常见问题与故障排查

安装

界面没有颜色，并且使用的是系统字体

你还没有导入 CSS。在应用入口处添加一次即可：

import '@thl-ui/styles/thl-ui.css';

Angular：将 node_modules/@thl-ui/styles/dist/thl-ui.css 添加到 angular.json 的 styles 中。同时为 <body> 添加 thl-body 类，以获得字体和背景色。

npm install 报告 peer 依赖错误

thl-ui 要求 Vue ≥ 3.5.2、React ≥ 18 或 Angular ≥ 20。不支持更早的版本：Angular 19 无法编译该库，Vue < 3.5.2 会产生 TypeScript 类型错误。请升级你的框架；如果确实必要，可以使用 --legacy-peer-deps 安装（不推荐）。

TypeScript 找不到组件类型

在 tsconfig.json 中使用 "moduleResolution": "Bundler"（或 "NodeNext"）。旧的 "node" 模式无法读取包的 exports 字段。

需要 Bootstrap、jQuery 或 Google Fonts 吗？

不需要。thl-ui 的 CSS 完全从零编写，Open Sans 字体已打包在 @thl-ui/styles 中（自托管，没有外部请求）。

主题

修改品牌色

在导入 thl-ui.css 之后覆盖 CSS 变量：

:root {
  --thl-theme: #7c3aed;        /* 按钮、激活标签页等的背景色… */
  --thl-on-theme: #fff;        /* 放在该颜色之上的文字 */
  --thl-theme-text: #6d28d9;   /* 该颜色在白色背景上作为文字使用时 */
}

--thl-on-theme 与 --thl-theme 之间、--thl-theme-text 与白色之间的对比度应至少保持 4.5:1。参见 主题与暗色模式。

只修改某个区域的主题

<section data-thl-theme="red" data-thl-color-mode="dark">…</section>

我的 CSS 被库的 CSS 覆盖了（或者反过来）

所有类名都带有 thl- 前缀，默认链接颜色的优先级为零（:where(...)），因此你写的普通类选择器会胜出。如需修改前缀以避免冲突：在配置中设置 prefix: 'my'，并且使用 $prefix: my 重新构建 SCSS（@use "@thl-ui/styles/scss/index" with ($prefix: "my")）。

打包体积太大

• Vue：避免使用默认的 app.use(ThlUI)（它会注册所有组件）。使用 import { ThlUI } from '@thl-ui/vue' 进行配置，然后只导入你需要的组件。只使用 Button 时：约 120 KB，而不是约 230 KB。
• React 和 Angular：按需导入单个组件；打包工具会 tree-shake 掉其余部分。
• 按组件拆分的 CSS：@thl-ui/styles/components/button.css…（记得同时添加 @thl-ui/styles/tokens.css 和 @thl-ui/styles/fonts.css）。

行为

用户设置（语言、皮肤、暗色模式）没有被记住

在配置中启用 persist: true。数据保存在 localStorage 的 thl-ui-config key 下（如需重命名 key：persist: { key: 'my-app-ui' }）。注意，保存的值会在下次加载时覆盖配置中的值。

Toast 或 confirm() 没有显示

AppLayout 已经挂载了这些宿主组件。如果你不使用 AppLayout，请在应用根部放置一次：

<ThlToaster />
<ThlConfirmHost />

（React：<Toaster /> 和 <ConfirmHost />；Angular：<thl-toaster /> 和 <thl-confirm-host />。）没有 ConfirmHost 时，confirm() 会回退到浏览器的 window.confirm。

点击侧边栏菜单会重新加载整个页面

侧边栏默认使用 <a href>。传入 link 插槽（Vue）、renderLink prop（React）或 thlMenuLink 模板（Angular）即可使用路由链接。参见 教程 第 3 步。

表单错误没有显示

错误只会在首次提交之后出现。每个 ThlField 都需要 name、value 和 rules，并且必须位于带有 :values 的 ThlForm 内。如需显示服务端错误，向 ThlField 传入 error="…"。

校验信息仍然是英文

文案跟随当前语言。检查配置中的 locale，如果启用了 persist，还要检查 localStorage 中保存的值。没有翻译的语言会回退到 fallbackLocale（默认 en）。

添加新语言

app.use(ThlUI, {
  locales: ['vi', 'en', 'ko'],
  messages: { ko: { common: { ok: '확인', cancel: '취소' } /* … */ } },
});

未翻译的 key 会回退到 fallbackLocale。从右到左的语言（ar、he、fa、ur）会自动设置 dir="rtl"，布局会自动镜像。

无障碍

仅图标按钮

始终为屏幕阅读器提供标签：

<ThlButton icon="trash-2" aria-label="删除" />

没有可见标签的输入框

将它们包裹在 ThlField label="…" 中（标签会自动与输入框关联），或传入 aria-label。

仍然无法解决？

打开对应的 playground（npm run dev:vue / dev:react / dev:angular），并与 apps/playground-* 中的示例页面源码对比：每个组件在那里都有可运行的示例。