--- title: "Web" description: "在任何 Web 项目中使用 Tanrei 的 CSS 令牌和 Web Components。" url: "https://tanrei.chnotchy.com/zh-cn/getting-started/web/" last_updated: 2026-10-23T21:17:12.000Z --- # Web > 在任何 Web 项目中使用 Tanrei 的 CSS 令牌和 Web Components。 `@tanrei/web` 包含两样东西：一份以 CSS 自定义属性提供设计令牌的样式表，以及用 Lit 构建的、基于标准的自定义元素。它不要求使用任何框架。 > [!WARNING] > **预发布** > > `0.1.0-next.0` 已以 dist-tag `next` 发布到 npm：在 `0.1.0` 之前，请安装 `@tanrei/web@next`。在 0.x 预发布期间不保持向后兼容：任何一个预发布都可能破坏任何东西，事先没有弃用期，破坏了什么写在它的 changeset 里。 ## 安装 ### 从 npm ```sh npm install @tanrei/web ``` ### 从源码要在发布之前使用 `main` 上的源码，你需要 Git、Node 22.22 或更高版本，以及 pnpm 12（`corepack enable` 会给你仓库固定的那个版本）。在仓库的克隆中构建这个包并打包，再把打包出的文件安装到你的项目里： ```sh git clone https://github.com/chnotchy/tanrei.git cd tanrei pnpm install pnpm --filter @tanrei/web build pnpm --filter @tanrei/web pack --pack-destination ../tanrei-packages ``` ```sh # 在你的项目中：路径指向写入这些包的文件夹 npm install path/to/tanrei-packages/tanrei-web-*.tgz ``` 打包出的文件包含的正是发布时发布的内容，所以下面的一切用法都完全相同。要取用更新的源码，就拉取、重新构建并打包，然后安装新的文件。 ## 使用 1. 尽早加载一次样式表。它们都被包在级联层（`tanrei.*`）中，因此你自己的样式始终优先。 ```js import '@tanrei/web/tanrei.css'; ``` `tanrei.css` 把一切放进一个文件：页面的基础样式、令牌，以及不用元素绘制的部件（文本样式、表格、手风琴等）的样式表。只想加载用得到的部分，就加载令牌、需要的话再加上基础样式，然后按需加载那些样式表： ```js import '@tanrei/web/tokens.css'; import '@tanrei/web/base.css'; // 让页面使用系统的表面色、文字颜色和正文字体，并去掉 body 的外边距 ``` 基础样式让页面本身使用表面色，让你自己的文字使用 on-surface 颜色和正文字体，并去掉浏览器给 body 加的外边距。没有它，页面保持浏览器的默认样式。 2. 注册你的设计系统的组件，也可以只导入用到的元素。 ```js import '@tanrei/web'; // 使用预设时，改为导入它的入口：m3-like、m3-expressive-like 或 cupertino import '@tanrei/web/m3-like'; // 或者，一次导入一个元素： import '@tanrei/web/components/button'; ``` `@tanrei/web` 只注册默认系统包含的组件，所以基于它的产品接触不到系统没有的组件。预设的入口 `@tanrei/web/` 注册该预设包含的组件，`@tanrei/web/all` 注册包里的全部组件。只有预设才包含的组件，例如[分段按钮](https://tanrei.chnotchy.com/zh-cn/components/segmented-button/)，仍然可以有意地使用：在你的系统的层里引入它，并导入它自己的模块。 `@tanrei/web/…` 这类说明符是包的导出，由打包工具（Vite、webpack、esbuild）解析。没有打包工具时，浏览器无法解析 `` 或 ` ``` 3. 像使用其他 HTML 一样使用这些元素。 ```html 部署取消 ``` 4. 给出你的产品的文字。组件没有自己的文字：必填和选填小标签上的字、关闭按钮的名称等等，都是你的产品的。想先让每一个都用平实的英语，就导入一次英语文字包： ```js import '@tanrei/web/words/en'; ``` 要改其中任何一个，或者给出另一种语言的文字，就在它之后调用 `setWords()`。你给出的文字优先于包中的文字，写在元素上的文字又优先于这两者。 ```js import { setWords } from '@tanrei/web'; setWords({ requiredText: 'Mandatory' }); setWords({ requiredText: '必填', optionalText: '选填', closeLabel: '关闭' }, { lang: 'zh-cn' }); ``` 既没有这个包、也没有你的文字时，组件仍然可以工作，并在控制台里告诉你缺的是哪一个。参见[文字](https://tanrei.chnotchy.com/zh-cn/foundations/words/)。 ## 元素清单编辑器和编程代理从包的 [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest)（`@tanrei/web/custom-elements.json`）读取元素：每个元素的属性、特性、事件、插槽和部件，不包含产品无法访问的内容。`@tanrei/web/custom-elements/.json` 只包含系统 `` 提供的元素，所以在一个系统里工作的工具不会推荐别的元素。 ## 主题与对比度令牌的值使用了 `light-dark()`，因此会跟随所在元素的 `color-scheme`。开箱即用时，这意味着跟随操作系统的设置，并且在 `prefers-contrast: more` 时切换到高对比度方案。如果想自己控制，可以设置属性： ```html ``` > [!NOTE] > **注意** > > 这两个属性既可以用在 `` 上，也可以用在任意子树上。生成的样式表把整套令牌声明在 `:root, [data-tanrei-contrast]` 上，因此在嵌套元素上设置 `data-tanrei-contrast` 时，其中的组件令牌也会按该对比度级别重新解析，而不只是系统颜色。 ### 记住用户选择的主题如果用户可以在你的产品里选择主题，就要保存这个选择，并在页面第一次绘制之前把它放到 `` 上：如果由之后才运行的脚本来设置，页面会先用系统的主题显示一帧。`@tanrei/web/theme-script` 两件事都做。`themeScript()` 是一段要内联在 `` 里、写在样式表之前的小脚本，`saveTheme()` 保存一个选择并立即绘制它。 ```js import { loadTheme, saveTheme } from '@tanrei/web/theme-script'; saveTheme('dark'); // 'light'、'dark'，或者 'system'，重新跟随操作系统 loadTheme(); // 保存的内容：'light'、'dark' 或 'system' ``` 在 Next.js（App Router）中，把它内联在根布局里。加上 `suppressHydrationWarning`，是因为脚本会在 React 水合之前改变 `` 的一个属性。 ```tsx // app/layout.tsx import { themeScript } from '@tanrei/web/theme-script'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( ``` 这段脚本要写得小而朴素：每位访客的浏览器都会运行它，旧浏览器也不例外。如果用静态 `import`，浏览器会在这段脚本运行之前就加载应用，无法解析应用的旧浏览器根本走不到检测这一步；`import()` 则在检测之后才加载。 ## 测试 ### 在浏览器中运行 Tanrei 的元素建立在浏览器所实现的能力之上：shadow root、`ElementInternals`（表单控件的值与有效性、自定义状态）、Popover API、`