快速开始

@fibrous/semi-ui-vue 是 Semi Design Next 的 Vue 组件库。

环境要求

peer 依赖：vue ^3.5.0。

安装

pnpm add @fibrous/semi-ui-vue @fibrous/semi-icons-vue

图标包 @fibrous/semi-icons-vue 是组件库的依赖，应用代码直接导入它时要在自己的 package.json 中声明，pnpm 不允许导入未声明的包。插画包 @fibrous/semi-illustrations-vue 不随组件库安装，用到时单独安装。

使用 npm 或 yarn 时换成对应的命令。

需要支持 Safari 17.4 以下时，另装 @fibrous/semi-polyfill，并在应用入口的第一行导入（早于任何 Semi 组件）。它只补齐 AbortSignal.any 与 Element.prototype.checkVisibility，浏览器已有原生实现时什么都不做；只用到其中一项时可以导入 @fibrous/semi-polyfill/abort-signal-any 或 @fibrous/semi-polyfill/check-visibility。

import '@fibrous/semi-polyfill';

引入 token

组件会自己导入主题 token（--semi-* CSS 变量）与 base 规则，不引入也能正常显示。首个组件懒加载时，token 要等该组件的 chunk 加载后才生效；在应用入口文件最先导入 tokens 入口，token 就随入口的 CSS 一起加载，首屏的应用样式也能用上 --semi-* 变量。

// main.ts，放在其他导入之前
import '@fibrous/semi-ui-vue/tokens';

tokens 入口是 JS 模块，导入的是组件所用的同一份 token，构建产物里只有一份，prefixCls 等构建插件选项对它同样生效。开启 omitCss 时它和组件样式一起被移除，token 由整包样式提供。

使用组件

<script setup lang="ts">
    import { Button, Toast } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Button @click="Toast.warning({ content: 'welcome' })">Hello Semi</Button>
</template>

也可以按目录深路径导入单个组件，路径写到 /index，如 import Button from '@fibrous/semi-ui-vue/button/index'。

样式与 token 随组件按需加载，只有用到的组件会被打包。Semi 自带 box-sizing: border-box 与滚动条基础样式，不需要 reset.css 一类的重置样式，额外的重置样式会改变组件尺寸。

构建插件

使用默认前缀 semi、分层样式且由组件各自导入样式时，webpack、rspack 不需要构建插件。组件导入的是预编译的 CSS，类名前缀为 semi，包在 @layer semi 中：需要有处理 .css 导入的规则，如 webpack 的 css-loader 加 style-loader（或 mini-css-extract-plugin 的 loader）、rspack 的 type: 'css'。Vite 的开发服务器可以不用插件，但 vite build 需要 @fibrous/semi-vite-plugin，原因见下。服务端渲染的宿主另见服务端渲染。

需要下列能力时，使用对应构建工具的插件：Vite 用 @fibrous/semi-vite-plugin，webpack 5 用 @fibrous/semi-webpack-plugin，rspack 2 用 @fibrous/semi-rspack-plugin。插件对组件库、图标包与 AI 包都生效。

// vite.config.ts
import { defineConfig } from 'vite';
import semi from '@fibrous/semi-vite-plugin';

export default defineConfig({
    plugins: [semi({ prefixCls: 'my' })],
});

// webpack.config.mjs
import SemiWebpackPlugin from '@fibrous/semi-webpack-plugin';

export default {
    plugins: [new SemiWebpackPlugin({ prefixCls: 'my' })],
};

// rspack.config.mjs，项目需要有把 .scss 当作 CSS 处理的规则
import { SemiRspackPlugin } from '@fibrous/semi-rspack-plugin';

export default {
    module: { rules: [{ test: /\.s?css$/, type: 'css' }] },
    plugins: [new SemiRspackPlugin({ prefixCls: 'my' })],
};

webpack 插件另有 extractCssOptions（如改用 mini-css-extract-plugin 的 loader）与 overrideStylesheetLoaders（在默认 loader 链上追加自己的 loader）。vite dev 中类名仍是 semi-* 时，预构建缓存来自修改前的配置，用 vite --force 重新预构建。

Semi 发布的 .scss 使用普通 Sass 无法解析的 semi: 地址，请通过构建插件或 @fibrous/semi-scss-compile 编译。

整包样式

需要一次性加载全部组件样式时，导入整包样式并开启构建插件的 omitCss，否则组件自带的样式导入会被再打包一份，同一组件的样式出现两次。整包样式已含 token 与图标样式，类名前缀为 semi，包在 @layer semi 中。

import '@fibrous/semi-ui-vue/styles.css';
// 使用 AI 组件时，在其后导入
import '@fibrous/semi-ai-vue/styles.css';

omitCss 时插件不再编译样式，cssLayer 不起作用，webpack、rspack 插件同时传入会报错。需要自定义前缀或不分层的整包样式时，用 @fibrous/semi-scss-compile 生成：--prefix 与插件的 prefixCls 一致，--no-layer 输出不分层的样式。-f、-i 可省略，缺省使用 @fibrous/semi-scss-compile 自己依赖的 foundation 与 icons-core，所以它的版本要与组件库一致；版本不一致时用 -f、-i 指向应用里安装的 @fibrous/semi-foundation、@fibrous/semi-icons-core 的 dist，pnpm 下这两个包要加为直接依赖。--ai 必须给出路径，指向 @fibrous/semi-ai-foundation 的 dist，pnpm 下要把它加为直接依赖，版本与组件库相同。

pnpm add -D @fibrous/semi-scss-compile
pnpm exec semi-build-scss -o src/semi.css --min --prefix my
# 使用 AI 组件时另生成一份，在上面那份之后导入（需再安装 @fibrous/semi-ai-foundation）
pnpm add -D @fibrous/semi-ai-foundation
pnpm exec semi-build-scss --ai node_modules/@fibrous/semi-ai-foundation/dist -o src/semi-ai.css --min --prefix my

定制样式

样式定制不需要构建插件：在应用的样式中覆写 --semi-* CSS 变量即可改变全局的颜色、圆角、字号、间距等，变量清单见设计变量，暗色模式的取值见暗色模式。Semi 的样式位于 @layer semi 中，应用中不分层的 CSS 规则总是优先，可以直接覆盖某个组件的具体样式，不需要 !important。

:root {
    --semi-color-primary: var(--semi-violet-5);
}

.my-toolbar .semi-button {
    border-radius: 0;
}

与 Tailwind 同用时，层的声明顺序与原子类中使用 Semi token 的方式见 Tailwind。

图标与插画

<script setup lang="ts">
    import { IconHome } from '@fibrous/semi-icons-vue';
</script>

<template>
    <IconHome aria-label="首页" />
</template>

自定义 SVG 使用 Icon 的默认插槽。插画从 @fibrous/semi-illustrations-vue 导入，如 IllustrationNoContent。

图标样式随图标组件加载。图标列表与用法见图标。

AI 组件

AIChatInput、AIChatDialogue、Chat、Sidebar 等 AI 组件在独立的 AI 包中，基于组件库，样式随组件加载；加载整包样式时，AI 包的整包样式在组件库的之后导入。能力介绍见 AI 组件。

pnpm add @fibrous/semi-ai-vue

服务端渲染

服务端渲染与 hydration 按下表配置宿主，多数宿主需要加上 Semi 的构建插件。默认按组件加载样式：组件 JS 自带样式导入，不导入 styles.css。整包样式是可选路线：构建插件开 omitCss，再导入一次 styles.css，见整包样式。两条路线不混用，混用时 CSS 体积约翻倍。

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ['@fibrous/semi-nuxt'],
});

模块不做组件自动导入，组件照常从 @fibrous/semi-ui-vue 导入。

@fibrous/semi-nuxt 在应用没有设置 features.inlineStyles 时把它设为 false，生产环境的 SSR 页面只用 <link> 加载样式。原因是 Nuxt 把页面 chunk 里的全部 CSS 都内联进该页的 HTML，而这份 CSS 同时仍以 <link> 加载：几个常用组件只被一个页面导入时，该页 HTML 从约 5KB 增至约 210KB。代价是应用自己的 SFC <style> 也不再内联。要保留 Nuxt 的内联，在 nuxt.config.ts 中显式设置，模块不覆盖：

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ['@fibrous/semi-nuxt'],
    features: { inlineStyles: true },
});

共同约定：

• 语言包从 UI 包的 locale/source/ 子路径导入（如 locale/source/en_US），不需要直接安装 @fibrous/semi-foundation。
• semiGlobal 只在应用启动时设置，按请求变化的配置用 ConfigProvider。
• 默认打开的弹层在 hydration 后出现。
• CodeHighlight 不内置语言：应用要直接安装 shiki（pnpm 不允许导入未声明的包），用 CodeHighlight.register 或 languages 传入 shiki/langs/* 的语言，见 CodeHighlight。

同一页面挂载多个 Vue app

组件内部的 id 由 Vue 的 useId 生成，按 app 计数。同一页面挂载多个 app（微前端、Astro island 等）时，给每个 app 设置不同的 app.config.idPrefix，否则各 app 生成相同的 id，aria-labelledby 等引用会指向其他 app 里的元素。

const app = createApp(App);
app.config.idPrefix = 'checkout';
app.mount('#checkout');