快速开始

@fibrous/semi-ui-solid 是 Semi Design Next 的 Solid 组件库，服务端渲染见服务端渲染。

环境要求

peer 依赖：solid-js ^1.9.0。

安装

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

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

使用 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-* 变量。

// index.tsx，放在其他导入之前
import '@fibrous/semi-ui-solid/tokens';

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

使用组件

import { Button, Toast } from '@fibrous/semi-ui-solid';

export function App() {
    return <Button onClick={() => Toast.warning({ content: 'welcome' })}>Hello Semi</Button>;
}

也可以按目录深路径导入单个组件，路径写到 /index，如 import Button from '@fibrous/semi-ui-solid/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 重新预构建。

Solid 项目的构建配置有以下区别：

• Vite：开发服务器也需要 @fibrous/semi-vite-plugin，写成 plugins: [solid(), semi()]。vite-plugin-solid 把 Solid 包排除在预构建之外，foundation 的 CommonJS 依赖（如 style-to-js）原样进入浏览器，页面白屏，插件会把它们加入预构建。
• webpack 5、rspack 2：Semi 的 webpack、rspack 插件不处理 Solid 包，所以插件的选项（prefixCls、cssLayer: false、omitCss）对 Solid 包不起作用，只支持默认前缀与分层样式，不使用这两个插件。应用的 JSX 用 babel-loader 加 babel-preset-solid 编译（需要 @babel/core 7）；打包器不识别 solid 导出条件，取到 default 条件下已为 DOM 编译的 dist/*.js。样式由组件各自导入：webpack 用 css-loader 加 style-loader，rspack 用 type: 'css'。

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

整包样式

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

import '@fibrous/semi-ui-solid/styles.css';
// 使用 AI 组件时，在其后导入
import '@fibrous/semi-ai-solid/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。

图标与插画

import { IconHome } from '@fibrous/semi-icons-solid';

export function HomeIcon() {
    return <IconHome aria-label="首页" />;
}

插画从 @fibrous/semi-illustrations-solid 导入，如 IllustrationNoContent。

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

AI 组件

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

pnpm add @fibrous/semi-ai-solid

服务端渲染

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

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

export default defineConfig({
    plugins: [solidStart(), nitro(), semi({ omitCss: true })],
});

// src/app.tsx
import '@fibrous/semi-ui-solid/styles.css';

SolidStart 选整包样式，是因为它的 dev 服务端默认不收集 node_modules 内组件导入的 CSS：按组件路线在生产环境正常，dev 首屏无样式。给 solidStart() 传 css: { filter: { exclude: [/^(?!.*\/node_modules\/@fibrous\/semi-).*\/node_modules\//] } } 后 dev 也收集 Semi 包的组件 CSS，代价是多一处宿主配置，且 dev 首屏的样式略大于整包样式（约多 20%），分成数十个 <style>。

共同约定：

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