记本博客集成 WebcoreUI 时遇到的坑

动机#

六月中旬，我在某短视频平台上发布了几篇 AI 生图的文章，收获了一些点赞和评论。评论大多是玩梗，但是也有一部分提出要取用我的原图。出于这项要求，我新建了《[AI 文生图] 提示词收集》一文，将提示词、参考图和生成图一并放入。

此时出现了一个问题：引用的图片默认宽度填满容器，而图片大多是竖版，就会出现一张图片几乎占满全屏的情况。如果并列放置多张图片，就会极度占用阅读空间。于是我开始寻找一个实现部分折叠的组件，将图片放入折叠，按钮控制开闭，就会节约空间。

与 DeepSeek 对话后，它给我抛出了一个解决方案——集成 WebcoreUI 到 Astro 博客中。

WebcoreUI 集成#

Webcore 是一个为 Astro 设计，基于 Sass 样式表的开源、可定制的 UI 组件库，且通过 API 提供 Svelte 和 React 支持。

将 WebcoreUI 集成到博客中，需要先安装对应库：

1
npm install sass typescript webcoreui

接下来，在根目录（与 astro.config.mjs 文件同级）新建配置文件 webcoreui.config.scss，暂时不要写内容。

在 Astro 组件 Layout.astro 的末尾加上 WebcoreUI 的加载函数：

1
<style lang="scss">
2
  @use 'webcoreui/styles' as *;
3

4
  @include setup((
5
    includeResets: false,   /* 非常重要，一会解释 */
6
    includeUtilities: true,
7
    includeTooltip: true,
8
    includeScrollbarStyles: false, /* 非常重要 */
9
    includeBreakpoints: true
10
  ));
11
</style>

接下来就可以在你的文章（需要 .mdx 文件格式）中引用组件。相关文档见此。

坑 默认样式冲突#

我刚刚集成 WebcoreUI 之后发现页面的样式出了问题。

主页部分，横幅下方的背景出现了意料之外的黑色块，右侧的滚动条也变成了黑色。

经过与正常、未集成 WebcoreUI 的网站比较，我发现我的网站 标签多出了一个 background: var(--w-color-primary-70) 的 CSS 声明，导致出现黑块。用 Everything 搜索源码发现它存在于 WebcoreUI 库的 resets.scss 文件里。

搜索文档，定位到 Resets 条目。文档中写道：

说明问题来源于这个 includeResets 字段。翻阅 Setup 条目 和 CSS Configurations 条目，我看到了 setup mixin 所支持的完整配置：

1
@use 'webcoreui/styles' as *;
2
@include setup((
3
    // Define paths for your fonts
4
    fontRegular: '/fonts/Inter-Regular.woff2',
5
    fontBold: '/fonts/Inter-Bold.woff2'
6

7
    // Optionally, define which styles you'd like to include
8
    includeResets: true,
9
    includeUtilities: true,
10
    includeTooltip: true,
11
    includeScrollbarStyles: true,
12
    includeBreakpoints: true
13
));

问题就明了了——我们要手动调用 setup，并将 includeResets 设为 false。鉴于滚动条的样式不合主题设计，也一并将 includeScrollbarStyles 设置为 false。同时我不想破坏已经设置好的博客字体，那么直接删去字体的引用。

为什么我先前没注意到？多半是因为在不手动调用 setup 的情况下，组件可以被正常引入和使用，就没有另外考虑相关的设置，忽略了这些选项。

在应用了这些配置后，黑块不再出现、滚动条样式恢复了正常。