@reglow/reui-mcp 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +204 -0
- package/catalog.mjs +158 -0
- package/cli-utils.mjs +29 -0
- package/index.mjs +169 -0
- package/integrations.mjs +273 -0
- package/knowledge.mjs +923 -0
- package/package.json +46 -0
- package/server.mjs +710 -0
- package/setup.mjs +400 -0
- package/site.mjs +155 -0
- package/skills/reui-components/BEST_PRACTICES.md +219 -0
- package/skills/reui-components/COMPONENTS.md +141 -0
- package/skills/reui-components/SKILL.md +172 -0
- package/skills/reui-components/WORKFLOWS.md +264 -0
- package/skills.mjs +197 -0
- package/tar.mjs +115 -0
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
# ReUI 最佳实践与陷阱（BEST_PRACTICES）
|
|
2
|
+
|
|
3
|
+
> 面向使用 `@reglow/reui` 写业务的 AI 与开发者。每条结论都标注来源文件，未在仓库中核实的做法不写入本文件。
|
|
4
|
+
> 核心来源：`reui/guide.md`、`reui/README.md`、`reui/package.json`、`reui/theme/index.ts`、`reui/i18n/index.ts`、`reglow-docs/content/components-library/1.reui/`。
|
|
5
|
+
|
|
6
|
+
## 1. 安装与依赖
|
|
7
|
+
|
|
8
|
+
| 事项 | 正确做法 | 来源 |
|
|
9
|
+
| ---------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
10
|
+
| 安装 | `npm install @reglow/reui` | `README.md` |
|
|
11
|
+
| 环境 | Vue >= 3.5；Tailwind CSS 4 | `package.json` peerDependencies、`reglow-docs` 安装页 |
|
|
12
|
+
| 无需手动装 | `reka-ui`、`lucide-vue-next`、`dayjs`、`@vueuse/core`、`@tiptap/*`、`@tanstack/vue-table` 等随包自动安装 | `package.json` dependencies |
|
|
13
|
+
| 构建产物 | `dist/index.js` + `dist/style.css` + `dist/components.css` + 子路径目录（`preserveModules`，每个组件单独 chunk） | `guide.md` §3 |
|
|
14
|
+
|
|
15
|
+
**不要**把 `vue` 装成两个版本：Nuxt/file: 安装时用 `vite.resolve.dedupe: ["vue"]`（`guide.md` §7）。
|
|
16
|
+
|
|
17
|
+
## 2. 样式引入
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
// ✅ 应用入口引入一次（含主题 reset + 组件样式）
|
|
21
|
+
import "@reglow/reui/style.css";
|
|
22
|
+
|
|
23
|
+
// ✅ 宿主已有 Tailwind / 主题变量时，避免 reset 冲突
|
|
24
|
+
import "@reglow/reui/components.css";
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- 两份 CSS 都由 Tailwind CSS 4 构建产物提供，`sideEffects: ["**/*.css"]` 保证不被 tree-shake。
|
|
28
|
+
- 样式只引一次；不要在多个组件里重复 `import`。
|
|
29
|
+
|
|
30
|
+
## 3. Tailwind 消费方：必须 `@source` 扫描库产物
|
|
31
|
+
|
|
32
|
+
ReUI 组件内部存在**动态拼装的类名**，依赖消费方 Tailwind 静态扫描命中；否则工具类不会生成。
|
|
33
|
+
|
|
34
|
+
```css
|
|
35
|
+
/* 消费方主 CSS */
|
|
36
|
+
@import "tailwindcss";
|
|
37
|
+
/* 扫描库构建产物中的 class 名，生成对应 utility */
|
|
38
|
+
@source "../../../node_modules/@reglow/reui/dist/components";
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
来源实测：
|
|
42
|
+
|
|
43
|
+
- `reglow-admin-*/frontend-admin/src/assets/css/main.css`、`reglow-design/src/assets/css/main.css` 均为该写法。
|
|
44
|
+
- 官方文档站用源码目录：`@source '../../../reui/components'`（`reglow-docs/assets/css/tailwind.css`）。
|
|
45
|
+
- 文档页面示例：`@source "../node_modules/@reglow/reui/dist"`（`reglow-docs/.../2.usage-vue.md`）。
|
|
46
|
+
|
|
47
|
+
**陷阱**：只写 `@import "@reglow/reui/style.css"` 而不加 `@source`，在宿主自己也要用语义 token（`bg-muted` 等）时可能缺类；两者选择其一，别指望"引了 style.css 就万事大吉"。
|
|
48
|
+
|
|
49
|
+
## 4. 引入方式与 tree-shaking
|
|
50
|
+
|
|
51
|
+
| 方式 | 写法 | 适用 |
|
|
52
|
+
| ---------- | --------------------------------------------------------------------------------- | ------------------------------- |
|
|
53
|
+
| 主入口按需 | `import { Button, PageTable } from "@reglow/reui"` | 通用推荐（构建器可 tree-shake） |
|
|
54
|
+
| 子路径 | `import { Splitter } from "@reglow/reui/reui/splitter"`、`@reglow/reui/ui/button` | 想显式控制粒度 |
|
|
55
|
+
| 全局注册 | `app.use(Reui)` / `app.use(createReui({...}))` | 页面里不想逐个 import |
|
|
56
|
+
| Nuxt | `modules: ["@reglow/reui/nuxt"]` 自动注册 | Nuxt 项目 |
|
|
57
|
+
|
|
58
|
+
**命名冲突要当心**：`ui` 与 `reui` 有同名组件（`Input`、`Textarea`、`Table`、`Tabs`、`Card`、`Alert`、`Calendar`、`Collapsible`）。
|
|
59
|
+
|
|
60
|
+
- 聚合规则：主入口 `export *` 两侧，**同名 reui 优先**，`ui` 只导出独有内容（`guide.md` §3）。
|
|
61
|
+
- `ui/input`、`ui/textarea`、`ui/avatar` 已标记 `@deprecated`，内部转发到 `reui` 版本——新代码统一从 `@reglow/reui` 或 `/reui/*` 取（头像组请用 `reui/avatar` 的 `AvatarGroup`）。
|
|
62
|
+
- 注意命名差异：表格组件导出名是 **`PageTable`**（目录名 `table`）；`ui/table` 导出的是 `Table/TableHeader/TableBody/...` 基础表格。
|
|
63
|
+
|
|
64
|
+
## 5. 主题
|
|
65
|
+
|
|
66
|
+
### 5.1 首选 ConfigProvider（推荐）
|
|
67
|
+
|
|
68
|
+
```vue
|
|
69
|
+
<ConfigProvider
|
|
70
|
+
locale="zh-TW"
|
|
71
|
+
:theme="{ mode: 'dark', primaryColor: 'emerald', radius: '0.5' }"
|
|
72
|
+
>
|
|
73
|
+
<App />
|
|
74
|
+
</ConfigProvider>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
- `theme` prop 被 deep watch → `applyTheme({ ...DEFAULT_THEME, ...theme })`（`guide.md` §4.4）。
|
|
78
|
+
- 支持嵌套，内层覆盖外层同名属性（`config-provider/README.md`）。
|
|
79
|
+
|
|
80
|
+
### 5.2 命令式 API
|
|
81
|
+
|
|
82
|
+
| API | 用途 | 注意 |
|
|
83
|
+
| --------------------- | ------------------------------------------------- | ---------------------------------------------- |
|
|
84
|
+
| `applyTheme(theme)` | 仅当前会话生效 | 必须在浏览器环境（内部判断 `typeof document`） |
|
|
85
|
+
| `saveTheme(theme)` | 写 `localStorage("reui_theme_config")` + 立即应用 | 用户主动切换主题时用 |
|
|
86
|
+
| `loadAndApplyTheme()` | 启动恢复 | 放在 `main.ts` 的 `mount` 之前，避免白屏闪烁 |
|
|
87
|
+
|
|
88
|
+
### 5.3 主题引擎行为（`theme/index.ts`）
|
|
89
|
+
|
|
90
|
+
- 暗色 = `<html>` 上的 **`.dark`** class；`mode: "auto"` 读 `prefers-color-scheme`。
|
|
91
|
+
- 注入的 CSS 变量：`--primary`/`--primary-foreground`/`--ring`、`--background`/`--foreground`、`--card*`、`--popover*`、`--secondary*`、`--muted*`、`--accent*`、`--border`、`--input`、`--radius`、`--font-body`（`--font-heading` 仅在标题字体与正文字体不一致时注入）。
|
|
92
|
+
- 色值全部为 **oklch**；主色 17 种、中性色 7 种（`neutral/stone/zinc/mauve/olive/mist/taupe`）、圆角取值 `"0" / "0.3" / "0.5" / "0.75" / "1.0"`。
|
|
93
|
+
- 字体 9 种（`system/inter/manrope/geist/harmonyos/oppo/misans/alibaba/noto`），Web 字体按需注入 Google Fonts `<link>`。
|
|
94
|
+
|
|
95
|
+
### 5.4 自定义样式怎么写
|
|
96
|
+
|
|
97
|
+
```vue
|
|
98
|
+
<!-- ✅ 语义 token -->
|
|
99
|
+
<div
|
|
100
|
+
class="bg-card text-card-foreground border border-border rounded-[var(--radius)]"
|
|
101
|
+
/>
|
|
102
|
+
<!-- ❌ 固定色值，切主题不跟随 -->
|
|
103
|
+
<div class="bg-blue-500 text-white" />
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
组件内部统一用 `cn()`（`clsx` + `tailwind-merge`）合并类名（`lib/utils.ts`），业务侧覆盖样式也用 `cn()` 或直接传 `class`。
|
|
107
|
+
|
|
108
|
+
## 6. i18n
|
|
109
|
+
|
|
110
|
+
### 6.1 铁律清单
|
|
111
|
+
|
|
112
|
+
| # | 规则 | 反例 |
|
|
113
|
+
| --- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
114
|
+
| 1 | `t()/tm()` 只能在模板 / `computed` / 函数体内调用 | `withDefaults(defineProps<...>(), { placeholder: t("reui.x.y") })` |
|
|
115
|
+
| 2 | 不要在模块顶层调用 | `const title = t("common.confirm")` |
|
|
116
|
+
| 3 | 数组消息用 `computed(() => tm<string[]>(...))` 保持响应式 | `const days = tm("reui.calendar.weekDays")` |
|
|
117
|
+
| 4 | 文案类 prop 组件内不设中文默认值，使用处写 `props.xxx \|\| t("reui.xxx.yyy")` | 硬编码 `"请选择日期"` |
|
|
118
|
+
| 5 | 新增 key 必须三语言同步（`zh-CN` 基准全集，`zh-TW`/`en-US` 镜像） | 只加 `zh-CN` |
|
|
119
|
+
|
|
120
|
+
来源：`guide.md` §4.3，实测代码 `i18n/index.ts`、`DatePicker.vue`。
|
|
121
|
+
|
|
122
|
+
### 6.2 业务侧用法
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import {
|
|
126
|
+
setLocale,
|
|
127
|
+
getCurrentLocale,
|
|
128
|
+
addLocale,
|
|
129
|
+
t,
|
|
130
|
+
tm,
|
|
131
|
+
useI18n,
|
|
132
|
+
} from "@reglow/reui";
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
- 语言标识自动归一化：`zh-HK`/`zh-Hant` → `zh-TW`，`en`/`en-GB` → `en-US`（`i18n/index.ts`）。
|
|
136
|
+
- `setLocale` 会写 `localStorage("locale")` 并同步 `document.documentElement.lang`。
|
|
137
|
+
- `addLocale(locale, msgs)` 对已有语言做**深合并**（不会丢其它 key），对新语言则追加到 `supportedLocales`。
|
|
138
|
+
- 组件级覆盖优先于 i18n：`<DatePicker placeholder="Pick a date" />`、`<Transfer :title-text="['Source', 'Target']" />`。
|
|
139
|
+
- 消息 key 两层：`common.*` + `reui.<component>.*`（如 `reui.datePicker.weekText`、`reui.calendar.weekDays`）。
|
|
140
|
+
|
|
141
|
+
## 7. ConfigProvider 深入用法
|
|
142
|
+
|
|
143
|
+
```vue
|
|
144
|
+
<ConfigProvider
|
|
145
|
+
locale="zh-CN"
|
|
146
|
+
direction="ltr"
|
|
147
|
+
component-size="default"
|
|
148
|
+
:theme="{ mode: 'light', primaryColor: 'blue', radius: '0.5' }"
|
|
149
|
+
namespace="re"
|
|
150
|
+
:get-popup-container="
|
|
151
|
+
(triggerNode) => triggerNode?.parentElement || document.body
|
|
152
|
+
"
|
|
153
|
+
:component-config="{ Button: { type: 'primary' }, Table: { bordered: true } }"
|
|
154
|
+
:empty="{ description: '暂无数据' }"
|
|
155
|
+
:pagination="{ pageSizeOptions: [10, 20, 50], showSizeChanger: true }"
|
|
156
|
+
>
|
|
157
|
+
<App />
|
|
158
|
+
</ConfigProvider>
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
- 消费侧 composable：`useConfigProvider()`（完整上下文）、`useComponentConfig("Table")`（组件级配置）、`useComponentSize(props.size)`（组件 prop > ConfigProvider > 默认值）。
|
|
162
|
+
- DOM 副作用：同步 `documentElement.dir` / `lang` / `.dark` class（`config-provider/README.md`）。
|
|
163
|
+
- **弹层挂载**：`getPopupContainer` 统一控制 Popover / Select / Dropdown 等的挂载容器——层级异常（弹层被裁剪、z-index 错乱）优先检查这里。
|
|
164
|
+
|
|
165
|
+
## 8. Nuxt 接入
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
export default defineNuxtConfig({
|
|
169
|
+
modules: ["@reglow/reui/nuxt"],
|
|
170
|
+
reui: {
|
|
171
|
+
prefix: "R",
|
|
172
|
+
locale: "zh-CN",
|
|
173
|
+
theme: { primaryColor: "blue" },
|
|
174
|
+
injectStyles: true,
|
|
175
|
+
},
|
|
176
|
+
vite: { resolve: { dedupe: ["vue"] } },
|
|
177
|
+
});
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
| 坑 | 说明与对策 |
|
|
181
|
+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
182
|
+
| 组件重名 | 用 `prefix: "R"` → `<RButton>`（官方 docs 站即此配置） |
|
|
183
|
+
| reset 冲突 | 宿主已有 Tailwind 时 `injectStyles: false`，并自行 `@source` 扫描组件源码/产物 |
|
|
184
|
+
| vue 双实例 | file:/软链安装必须 `vite.resolve.dedupe: ["vue"]`（`guide.md` §7） |
|
|
185
|
+
| 组件清单不更新 | `nuxt/components.mjs` 由 `scripts/gen-nuxt-components.mjs` 自动生成，**增删组件后重新 `npm run build`** |
|
|
186
|
+
| SSR | 组件默认有服务端守卫；`Cropper`/`SlideCaptcha`/`QRCode`/`AudioPlayer`/`VideoPlayer`/`Editor`/`Tour`/`Affix`/`BackTop`/`Watermark`/`MasonryGrid` 服务端渲染占位 |
|
|
187
|
+
| 命令式 API | `Modal.info/success/error/warning/confirm`、`useNotification`、`useToast` **只能在客户端**（事件回调 / `onMounted`）调用，勿在 `setup` 顶层调用 |
|
|
188
|
+
| 纯浏览器逻辑 | 需要 `localStorage` 或浏览器 SDK 的区域用 `<ClientOnly>` 包裹 |
|
|
189
|
+
|
|
190
|
+
## 9. 新增 / 修改组件（库内开发）
|
|
191
|
+
|
|
192
|
+
1. 目录：`components/reui/<name>/` → `Xxx.vue` + `index.ts` + `README.md` + `__tests__/Xxx.test.ts`。
|
|
193
|
+
2. `index.ts` 用 `export { default as Xxx } from "./Xxx.vue"`，并导出类型；同步 `components/reui/index.ts` 加 `export * from "./<name>"`。
|
|
194
|
+
3. i18n 三语言同步；遵守 §6.1 的响应式铁律。
|
|
195
|
+
4. 样式用语义 token + `cn()`；结构化节点加 `data-slot="xxx"` 便于测试与定制。
|
|
196
|
+
5. 单测：Vitest + `@vue/test-utils`（`vitest.config.ts` + `test/setup.ts` 已补齐 `ResizeObserver`/`IntersectionObserver`/Pointer Capture）。
|
|
197
|
+
6. 验证命令：
|
|
198
|
+
```bash
|
|
199
|
+
cd D:\Huolidev\reglow_project\reui
|
|
200
|
+
npx vitest run # 全量（组件多时用 --maxWorkers=2）
|
|
201
|
+
npx vue-tsc --noEmit -p tsconfig.json # 等价 npm run typecheck
|
|
202
|
+
npm run build # build:nuxt + vite build --mode lib + build:css + merge-css
|
|
203
|
+
```
|
|
204
|
+
7. **组件目录会被外部流程整体更新**：改完务必回查 `components/reui/index.ts` 聚合导出是否完整、是否与 `ui` 层产生命名冲突（`guide.md` §8）。
|
|
205
|
+
8. **组件库不得 import 应用层模块**（如 `@/stores/auth`）；需要业务能力时改为 prop 或全局配置（如 `PageTable` 的 `buttonPermissionMode`，`lib/config.ts`）。
|
|
206
|
+
9. 批量重构后用 grep 验证是否真的落盘（`rg "@/i18n" components/`）。
|
|
207
|
+
|
|
208
|
+
## 10. 常见错误速查表
|
|
209
|
+
|
|
210
|
+
| 症状 | 根因 | 修复 |
|
|
211
|
+
| ---------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------- |
|
|
212
|
+
| 组件样式错乱 / 无样式 | 未引 `style.css`，或宿主 Tailwind 未 `@source` 扫描库产物 | 引样式 + 加 `@source`（见 §2、§3） |
|
|
213
|
+
| 切语言后组件文案不更新 | `t()` 写在 `withDefaults` 默认值或模块顶层 | 挪到模板 / `computed` / 函数体 |
|
|
214
|
+
| 暗色模式只亮一半 | 自定义样式用了固定色值，未用语义 token | 改 `bg-background` / `text-muted-foreground` 等 |
|
|
215
|
+
| 弹层被父容器裁剪 | 挂载容器不对 | 用 `ConfigProvider` 的 `getPopupContainer` |
|
|
216
|
+
| TS 报 `ThemeConfig` 类型冲突 | `config-provider` 与 `theme` 同名类型 | 类型从 `@reglow/reui` 主入口取（已显式以 `theme` 为准，`guide.md` §5） |
|
|
217
|
+
| 首屏主题闪烁 | 未在 mount 前 `loadAndApplyTheme()` | 在 `main.ts` 入口调用 |
|
|
218
|
+
| Nuxt 下 `Modal.confirm` 报错 | 服务端调用了命令式 API | 移到客户端事件回调 |
|
|
219
|
+
| 组件不存在 / 文档查不到 | 版本差异或未收录 | 用 `search_reui_docs` 复核；确认后再下结论，不要臆造组件名 |
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# ReUI 组件选型清单（COMPONENTS）
|
|
2
|
+
|
|
3
|
+
> 分类与文档链接取自官网组件总览 https://reglow.huoli.tech/components-library/reui （同源仓库文件：`reglow-docs/content/components-library/1.reui/1.index.md`）。
|
|
4
|
+
> 导入符号已逐一核对各组件目录的 `index.ts`（`reui/components/reui/*/index.ts`、`reui/components/ui/*/index.ts`）。
|
|
5
|
+
> 版本基线：`@reglow/reui` 0.2.0（`reui/package.json`）。
|
|
6
|
+
|
|
7
|
+
## 使用方式
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
// 主入口（推荐）
|
|
11
|
+
import { Splitter, PageTable, ConfigProvider } from "@reglow/reui";
|
|
12
|
+
|
|
13
|
+
// 按需子路径（等价，粒度更细）
|
|
14
|
+
import { Splitter, SplitterPanel } from "@reglow/reui/reui/splitter";
|
|
15
|
+
import { Button } from "@reglow/reui/ui/button";
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- 文档链接形如 `https://reglow.huoli.tech/components-library/reui/components/<category>/<name>`。
|
|
19
|
+
- `子路径` 列中的 `ui/*` 表示基础组件层，`reui/*` 表示高级组件层；主入口同名组件以 `reui` 为准（`guide.md` §3）。
|
|
20
|
+
|
|
21
|
+
## 通用 general
|
|
22
|
+
|
|
23
|
+
| 组件 | 中文名 | 说明 | 导入符号 | 子路径 |
|
|
24
|
+
| --------------------------------------------------------------------------------------- | ------ | ------------------ | --------- | -------------- |
|
|
25
|
+
| [button](https://reglow.huoli.tech/components-library/reui/components/general/button) | 按钮 | 触发操作的基础按钮 | `Button` | `ui/button` |
|
|
26
|
+
| [divider](https://reglow.huoli.tech/components-library/reui/components/general/divider) | 分割线 | 分隔内容区域 | `Divider` | `reui/divider` |
|
|
27
|
+
| [label](https://reglow.huoli.tech/components-library/reui/components/general/label) | 标签 | 表单字段文本标签 | `Label` | `ui/label` |
|
|
28
|
+
| [spinner](https://reglow.huoli.tech/components-library/reui/components/general/spinner) | 加载圈 | 基础加载指示 | `Spinner` | `ui/spinner` |
|
|
29
|
+
| [toggle](https://reglow.huoli.tech/components-library/reui/components/general/toggle) | 开关 | 简单布尔值开关 | `Toggle` | `ui/toggle` |
|
|
30
|
+
|
|
31
|
+
## 布局 layout
|
|
32
|
+
|
|
33
|
+
| 组件 | 中文名 | 说明 | 导入符号 | 子路径 |
|
|
34
|
+
| ------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------ | ---------------------------- | ------------------- |
|
|
35
|
+
| [border-beam](https://reglow.huoli.tech/components-library/reui/components/layout/border-beam) | 边框光束 | 边框发光动画 | `BorderBeam` | `reui/border-beam` |
|
|
36
|
+
| [masonry-grid](https://reglow.huoli.tech/components-library/reui/components/layout/masonry-grid) | 瀑布流 | 瀑布流布局 | `MasonryGrid` | `reui/masonry-grid` |
|
|
37
|
+
| [splitter](https://reglow.huoli.tech/components-library/reui/components/layout/splitter) | 面板分割 | 可拖拽分割面板（支持折叠、受控、延迟渲染） | `Splitter` / `SplitterPanel` | `reui/splitter` |
|
|
38
|
+
|
|
39
|
+
## 导航 navigation
|
|
40
|
+
|
|
41
|
+
| 组件 | 中文名 | 说明 | 导入符号 | 子路径 |
|
|
42
|
+
| ------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------- |
|
|
43
|
+
| [affix](https://reglow.huoli.tech/components-library/reui/components/navigation/affix) | 固钉 | 滚动时固定元素位置 | `Affix` | `reui/affix` |
|
|
44
|
+
| [breadcrumb](https://reglow.huoli.tech/components-library/reui/components/navigation/breadcrumb) | 面包屑 | 显示页面层级路径 | `Breadcrumb` | `reui/breadcrumb` |
|
|
45
|
+
| [dropdown-menu](https://reglow.huoli.tech/components-library/reui/components/navigation/dropdown-menu) | 下拉菜单 | 下拉操作菜单（reka-ui 透传） | `DropdownMenu` / `DropdownMenuTrigger` / `DropdownMenuContent` / `DropdownMenuItem` / `DropdownMenuSub` … | `reui/dropdown-menu` |
|
|
46
|
+
| [tabs](https://reglow.huoli.tech/components-library/reui/components/navigation/tabs) | 标签页 | 多标签内容切换（配置式 / 复合式，6 种样式） | `Tabs` / `TabsList` / `TabsTrigger` / `TabsContent` | `reui/tabs` |
|
|
47
|
+
|
|
48
|
+
## 数据录入 data-entry
|
|
49
|
+
|
|
50
|
+
| 组件 | 中文名 | 说明 | 导入符号 | 子路径 |
|
|
51
|
+
| -------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
|
52
|
+
| [autocomplete](https://reglow.huoli.tech/components-library/reui/components/data-entry/autocomplete) | 自动完成 | 输入时自动补全（远程搜索/回显） | `AutoComplete` | `reui/autocomplete` |
|
|
53
|
+
| [cascader](https://reglow.huoli.tech/components-library/reui/components/data-entry/cascader) | 级联选择 | 多级联动选择 | `Cascader` | `reui/cascader` |
|
|
54
|
+
| [checkbox](https://reglow.huoli.tech/components-library/reui/components/data-entry/checkbox) | 多选框 | 多项选择（含不确定态） | `Checkbox` / `CheckboxGroup` | `reui/checkbox` |
|
|
55
|
+
| [code-editor](https://reglow.huoli.tech/components-library/reui/components/data-entry/code-editor) | 代码编辑器 | 零依赖语法高亮 + 可编辑（Python/TS/Java/Rust） | `CodeEditor`（`highlightCode` / `tokenizeLines`） | `reui/code-editor` |
|
|
56
|
+
| [combobox](https://reglow.huoli.tech/components-library/reui/components/data-entry/combobox) | 组合框 | 可搜索选择框 | `Combobox` / `EditableCombobox` | `ui/combobox` |
|
|
57
|
+
| [command](https://reglow.huoli.tech/components-library/reui/components/data-entry/command) | 命令面板 | 命令式菜单 | `Command` / `CommandDialog` / `CommandInput` / `CommandList` / `CommandItem` / `CommandEmpty` / `CommandGroup` / `CommandSeparator` / `CommandShortcut` | `ui/command` |
|
|
58
|
+
| [date-picker](https://reglow.huoli.tech/components-library/reui/components/data-entry/date-picker) | 日期选择 | 选择日期 / 日期范围 / 日期时间 | `DatePicker` / `DateRangePicker` / `CalendarPanel` | `reui/date-picker` |
|
|
59
|
+
| [editor](https://reglow.huoli.tech/components-library/reui/components/data-entry/editor) | 富文本 | 富文本编辑器（Tiptap） | `Editor` / `EditorToolbar` / `EditorBubbleMenu` / `EditorDragHandle` / `EditorSuggestionMenu` / `EditorMentionMenu` / `EditorEmojiMenu` | `reui/editor` |
|
|
60
|
+
| [input](https://reglow.huoli.tech/components-library/reui/components/data-entry/input) | 输入框 | 基础文本输入（含 variant / status） | `Input` | `reui/input` |
|
|
61
|
+
| [input-password](https://reglow.huoli.tech/components-library/reui/components/data-entry/input-password) | 密码输入框 | 掩码显示与显隐切换 | `InputPassword` | `reui/input-password` |
|
|
62
|
+
| [input-select](https://reglow.huoli.tech/components-library/reui/components/data-entry/input-select) | 输入选择 | 输入与下拉结合 | `InputSelect` | `reui/input-select` |
|
|
63
|
+
| [native-select](https://reglow.huoli.tech/components-library/reui/components/data-entry/native-select) | 原生选择 | 原生下拉框 | `NativeSelect` / `NativeSelectOptGroup` / `NativeSelectOption` | `ui/native-select` |
|
|
64
|
+
| [radio](https://reglow.huoli.tech/components-library/reui/components/data-entry/radio) | 单选框 | 单项选择（含按钮组） | `RadioGroup` / `RadioGroupItem` / `RadioGroupSingle` / `RadioSingle` | `reui/radio` |
|
|
65
|
+
| [rate](https://reglow.huoli.tech/components-library/reui/components/data-entry/rate) | 评分 | 星级评分 | `Rate` | `reui/rate` |
|
|
66
|
+
| [segmented](https://reglow.huoli.tech/components-library/reui/components/data-entry/segmented) | 分段控制 | 分段选择 | `Segmented` | `reui/segmented` |
|
|
67
|
+
| [select](https://reglow.huoli.tech/components-library/reui/components/data-entry/select) | 选择器 | 下拉选择（reka-ui 透传） | `Select` / `SelectTrigger` / `SelectContent` / `SelectItem` / `SelectValue` / `SelectGroup` / `SelectLabel` … | `reui/select` |
|
|
68
|
+
| [slide-captcha](https://reglow.huoli.tech/components-library/reui/components/data-entry/slide-captcha) | 滑块验证 | 滑块验证码 | `SlideCaptcha` | `reui/slide-captcha` |
|
|
69
|
+
| [switch](https://reglow.huoli.tech/components-library/reui/components/data-entry/switch) | 开关 | 受控开关 | `Switch` | `ui/switch` |
|
|
70
|
+
| [tags-input](https://reglow.huoli.tech/components-library/reui/components/data-entry/tags-input) | 标签输入 | 标签式输入 | `TagsInput` / `TagsInputInput` / `TagsInputItem` / `TagsInputItemText` / `TagsInputItemDelete` | `ui/tags-input` |
|
|
71
|
+
| [textarea](https://reglow.huoli.tech/components-library/reui/components/data-entry/textarea) | 多行文本 | 多行文本输入 | `Textarea` | `reui/textarea` |
|
|
72
|
+
| [time-picker](https://reglow.huoli.tech/components-library/reui/components/data-entry/time-picker) | 时间选择 | 选择时间 | `TimePicker` | `reui/time-picker` |
|
|
73
|
+
| [transfer](https://reglow.huoli.tech/components-library/reui/components/data-entry/transfer) | 穿梭框 | 双栏数据穿梭 | `Transfer` | `reui/transfer` |
|
|
74
|
+
| [treeselect](https://reglow.huoli.tech/components-library/reui/components/data-entry/treeselect) | 树选择 | 树形下拉选择 | `TreeSelect` | `reui/treeselect` |
|
|
75
|
+
| [upload](https://reglow.huoli.tech/components-library/reui/components/data-entry/upload) | 上传 | 文件上传 | `Upload` | `reui/upload` |
|
|
76
|
+
|
|
77
|
+
## 数据展示 data-display
|
|
78
|
+
|
|
79
|
+
| 组件 | 中文名 | 说明 | 导入符号 | 子路径 |
|
|
80
|
+
| -------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
|
|
81
|
+
| [audio-player](https://reglow.huoli.tech/components-library/reui/components/data-display/audio-player) | 音频播放 | 音频播放器 | `AudioPlayer` | `reui/audio-player` |
|
|
82
|
+
| [avatar](https://reglow.huoli.tech/components-library/reui/components/data-display/avatar) | 头像 | 头像展示 | `Avatar` / `AvatarImage` / `AvatarFallback` / `AvatarGroup` | `reui/avatar` |
|
|
83
|
+
| [badge](https://reglow.huoli.tech/components-library/reui/components/data-display/badge) | 徽标 | 角标与状态点 | `Badge` / `BadgeRibbon` | `reui/badge` |
|
|
84
|
+
| [calendar](https://reglow.huoli.tech/components-library/reui/components/data-display/calendar) | 日历 | 日历展示 | `Calendar` | `reui/calendar` |
|
|
85
|
+
| [card](https://reglow.huoli.tech/components-library/reui/components/data-display/card) | 卡片 | 内容容器卡片 | `Card` / `CardHeader` / `CardTitle` / `CardDescription` / `CardContent` / `CardFooter` / `CardMeta` / `CardGroup` | `reui/card` |
|
|
86
|
+
| [carousel](https://reglow.huoli.tech/components-library/reui/components/data-display/carousel) | 轮播图 | 循环播放的内容切换（自动播放/淡入淡出/拖拽） | `Carousel` | `reui/carousel` |
|
|
87
|
+
| [chat](https://reglow.huoli.tech/components-library/reui/components/data-display/chat) | 对话 | 对话气泡组件 | `ChatMessage` / `ChatMessages` / `ChatPalette` / `ChatPrompt` / `ChatPromptSubmit` / `ChatReasoning` / `ChatShimmer` / `ChatTool` | `reui/chat` |
|
|
88
|
+
| [collapse](https://reglow.huoli.tech/components-library/reui/components/data-display/collapse) | 折叠面板 | 配置式 + 复合式、手风琴、ghost | `Collapse` / `CollapsePanel` | `reui/collapse` |
|
|
89
|
+
| [collapsible](https://reglow.huoli.tech/components-library/reui/components/data-display/collapsible) | 折叠面板 | 可折叠内容（配置式 + 复合式双模式） | `Collapsible` / `CollapsibleRoot` / `CollapsibleTrigger` / `CollapsibleContent` | `reui/collapsible` |
|
|
90
|
+
| [empty](https://reglow.huoli.tech/components-library/reui/components/data-display/empty) | 空状态 | 空数据占位 | `Empty` | `reui/empty` |
|
|
91
|
+
| [hover-card](https://reglow.huoli.tech/components-library/reui/components/data-display/hover-card) | 悬停卡片 | 悬停展示详情 | `HoverCard` / `HoverCardTrigger` / `HoverCardContent` | `reui/hover-card` |
|
|
92
|
+
| [image-viewer](https://reglow.huoli.tech/components-library/reui/components/data-display/image-viewer) | 图片预览 | 图片放大预览 | `Image` / `ImageViewer` / `PreviewGroup` | `reui/image-viewer` |
|
|
93
|
+
| [popover](https://reglow.huoli.tech/components-library/reui/components/data-display/popover) | 气泡卡片 | 悬浮气泡内容 | `Popover` / `PopoverTrigger` / `PopoverContent` | `reui/popover` |
|
|
94
|
+
| [pricing-table](https://reglow.huoli.tech/components-library/reui/components/data-display/pricing-table) | 价格表 | 定价方案对比 | `PricingTable` | `reui/pricing-table` |
|
|
95
|
+
| [qr-code](https://reglow.huoli.tech/components-library/reui/components/data-display/qr-code) | 二维码 | 二维码生成 | `QRCode` | `reui/qr-code` |
|
|
96
|
+
| [table](https://reglow.huoli.tech/components-library/reui/components/data-display/table) | 表格 | 通用表格（自动列/排序/行选择/展开行）+ 分页表格（搜索/分页/行操作/服务端排序） | `Table` / `TableRoot` / `TableHeader` / `TableBody` / `TableRow` / `TableHead` / `TableCell` / `PageTable` | `reui/table` |
|
|
97
|
+
| [tag](https://reglow.huoli.tech/components-library/reui/components/data-display/tag) | 标签 | 分类标签 | `Tag` / `CheckableTag` / `CheckableTagGroup` | `reui/tag` |
|
|
98
|
+
| [timeline](https://reglow.huoli.tech/components-library/reui/components/data-display/timeline) | 时间轴 | 时间线展示 | `Timeline` / `TimelineItem` | `reui/timeline` |
|
|
99
|
+
| [tooltip](https://reglow.huoli.tech/components-library/reui/components/data-display/tooltip) | 文字提示 | 悬浮文字提示 | `Tooltip` / `TooltipSingle` / `TooltipTrigger` / `TooltipContent` / `TooltipProvider` | `reui/tooltip` |
|
|
100
|
+
| [tree](https://reglow.huoli.tech/components-library/reui/components/data-display/tree) | 树形控件 | 树形结构展示 | `Tree` | `reui/tree` |
|
|
101
|
+
| [video-player](https://reglow.huoli.tech/components-library/reui/components/data-display/video-player) | 视频播放 | 视频播放器 | `VideoPlayer` | `reui/video-player` |
|
|
102
|
+
|
|
103
|
+
## 反馈 feedback
|
|
104
|
+
|
|
105
|
+
| 组件 | 中文名 | 说明 | 导入符号 | 子路径 |
|
|
106
|
+
| -------------------------------------------------------------------------------------------------- | ---------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
|
|
107
|
+
| [alert](https://reglow.huoli.tech/components-library/reui/components/feedback/alert) | 警告提示 | 页面级警告提示（5 种风格） | `Alert` | `reui/alert` |
|
|
108
|
+
| [alert-dialog](https://reglow.huoli.tech/components-library/reui/components/feedback/alert-dialog) | 警告对话框 | 强制确认对话框 | `AlertDialog` / `AlertDialogTrigger` … | `ui/alert-dialog` |
|
|
109
|
+
| [dialog](https://reglow.huoli.tech/components-library/reui/components/feedback/dialog) | 对话框 | 模态对话框 | `Dialog` / `DialogTrigger` / `DialogContent` / `DialogHeader` / `DialogTitle` / `DialogDescription` / `DialogFooter` / `DialogClose` | `reui/dialog` |
|
|
110
|
+
| [drawer](https://reglow.huoli.tech/components-library/reui/components/feedback/drawer) | 抽屉 | 侧边抽屉面板 | `Drawer` / `DrawerTrigger` / `DrawerContent` / `DrawerHeader` / `DrawerTitle` / `DrawerFooter` | `reui/drawer` |
|
|
111
|
+
| [feedback](https://reglow.huoli.tech/components-library/reui/components/feedback/feedback) | 反馈 | 用户反馈组件 | `Feedback` | `reui/feedback` |
|
|
112
|
+
| [modal](https://reglow.huoli.tech/components-library/reui/components/feedback/modal) | 模态框 | 模态窗口（含多种预设） | `Modal`（命令式 `useModal`） | `reui/modal` |
|
|
113
|
+
| [notification](https://reglow.huoli.tech/components-library/reui/components/feedback/notification) | 通知 | 全局通知 | `useNotification` / `NotificationContainer` / `NotificationItem` | `reui/notification` |
|
|
114
|
+
| [pop-confirm](https://reglow.huoli.tech/components-library/reui/components/feedback/pop-confirm) | 气泡确认 | 气泡确认框 | `PopConfirm` / `PopConfirmTrigger` / `PopConfirmContent` | `reui/pop-confirm` |
|
|
115
|
+
| [skeleton](https://reglow.huoli.tech/components-library/reui/components/feedback/skeleton) | 骨架屏 | 加载骨架占位 | `Skeleton` | `ui/skeleton` |
|
|
116
|
+
| [spin](https://reglow.huoli.tech/components-library/reui/components/feedback/spin) | 加载中 | 加载状态 | `Spin` | `reui/spin` |
|
|
117
|
+
| [toast](https://reglow.huoli.tech/components-library/reui/components/feedback/toast) | 轻提示 | 轻量提示 | `useToast` / `ToastContainer` / `ToastItem` | `reui/toast` |
|
|
118
|
+
|
|
119
|
+
## 其他 others
|
|
120
|
+
|
|
121
|
+
| 组件 | 中文名 | 说明 | 导入符号 | 子路径 |
|
|
122
|
+
| ------------------------------------------------------------------------------------------------------ | -------- | ------------------------------- | ----------------------------------------------------------------------------------- | ---------------------- |
|
|
123
|
+
| [backtop](https://reglow.huoli.tech/components-library/reui/components/others/backtop) | 回到顶部 | 一键回到顶部 | `BackTop` | `reui/backtop` |
|
|
124
|
+
| [config-provider](https://reglow.huoli.tech/components-library/reui/components/others/config-provider) | 全局配置 | 语言与主题配置 | `ConfigProvider`（`useConfigProvider` / `useComponentConfig` / `useComponentSize`） | `reui/config-provider` |
|
|
125
|
+
| [cropper](https://reglow.huoli.tech/components-library/reui/components/others/cropper) | 图片裁切 | 图片裁切 | `Cropper` | `reui/cropper` |
|
|
126
|
+
| [float-button](https://reglow.huoli.tech/components-library/reui/components/others/float-button) | 悬浮按钮 | 悬浮操作按钮（含分组/回到顶部） | `FloatButton` / `FloatButtonGroup` | `reui/float-button` |
|
|
127
|
+
| [overlay](https://reglow.huoli.tech/components-library/reui/components/others/overlay) | 浮层 | 浮层层级管理 | `OverlayProvider`（`useOverlayLayer`） | `reui/overlay` |
|
|
128
|
+
| [tour](https://reglow.huoli.tech/components-library/reui/components/others/tour) | 漫游引导 | 分步引导 | `Tour` | `reui/tour` |
|
|
129
|
+
| [watermark](https://reglow.huoli.tech/components-library/reui/components/others/watermark) | 水印 | 页面水印 | `Watermark` | `reui/watermark` |
|
|
130
|
+
|
|
131
|
+
## 常见选型对照
|
|
132
|
+
|
|
133
|
+
| 需求 | 选它 | 不要选 |
|
|
134
|
+
| ------------------------------ | --------------------------------------------------------- | ------------------------------------------------- |
|
|
135
|
+
| 带分页/搜索/行操作的数据列表 | `PageTable`（`reui/table`） | `Table`（通用表格，不含分页/搜索/列管理） |
|
|
136
|
+
| 通用表格（排序/行选择/展开行） | `Table`（`reui/table`） | `TableRoot` + 原子组件（无排序/选择，需完全自建） |
|
|
137
|
+
| 模态确认删除 | `Modal.confirm` / `PopConfirm` | `ui/alert-dialog`（reka-ui 风格，需自行组装） |
|
|
138
|
+
| 表单内日期输入 | `DatePicker` / `DateRangePicker`（`Dayjs` 值） | `Calendar`（面板形态，用于嵌入式日历） |
|
|
139
|
+
| 左右分栏可拖拽 | `Splitter` + `SplitterPanel` | `MasonryGrid`（瀑布流，不同场景） |
|
|
140
|
+
| 可折叠内容区 | `Collapse`（多面板、手风琴）/ `Collapsible`（单个折叠区） | — |
|
|
141
|
+
| 代码展示 / 编辑 | `CodeEditor`（`readonly` 作展示） | `Textarea`（无高亮） |
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: reui-components
|
|
3
|
+
description: ReUI（@reglow/reui）Vue 3 组件库的检索、选型、用法示例、主题定制、国际化与 Nuxt 接入技能。当用户提到 ReUI、@reglow/reui、reui 组件、reui-mcp，或需要为 Vue/Nuxt 后台项目挑选 reui 组件、查询组件 props/API、生成组件用法代码、配置主题（暗色/主色/圆角/字体）、接入 i18n 时使用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# ReUI 组件库技能（reui-components）
|
|
7
|
+
|
|
8
|
+
## 1. 技能定位
|
|
9
|
+
|
|
10
|
+
让 AI 在「用 ReUI 写代码」时**只依据真实文档与源码作答**，不凭记忆编造 props、events、slots 或导入路径。
|
|
11
|
+
|
|
12
|
+
- 组件库：`@reglow/reui`（Vue 3 + TypeScript + Tailwind CSS 4 + reka-ui，shadcn-vue 组织方式）
|
|
13
|
+
- 两层结构：`ui`（基础原子组件）+ `reui`（高级业务组件，覆盖后台管理系统场景）
|
|
14
|
+
- 事实来源优先级：**reui-mcp 工具 → 组件目录 `README.md` / 源码 → 官网文档站**
|
|
15
|
+
- 官网文档：https://reglow.huoli.tech/components-library/reui
|
|
16
|
+
- 仓库内文档：`reui/guide.md`（库级设计说明）、`reui/README.md`、`reui/COMPONENT_FUNCTIONALITY.md`（API 实现审计）
|
|
17
|
+
|
|
18
|
+
## 2. 触发场景
|
|
19
|
+
|
|
20
|
+
| 用户意图 | 走哪里 |
|
|
21
|
+
| ------------------------------------------- | ---------------------------------------------------------------------- |
|
|
22
|
+
| 「有没有 XX 组件 / 该用哪个组件」 | `get_reui_document`（不传 `component` 得总览）、本目录 `COMPONENTS.md` |
|
|
23
|
+
| 「XX 组件怎么用 / 有哪些 props」 | `get_reui_document` + `get_reui_code_examples` |
|
|
24
|
+
| 「给我一段可复制的示例代码」 | `get_reui_code_examples` |
|
|
25
|
+
| 「这个组件内部怎么实现的」 | `list_component_files` → `get_file_code` → `get_function_code` |
|
|
26
|
+
| 「哪里用到了 XX / 关键词排查」 | `search_reui_docs` |
|
|
27
|
+
| 安装、主题、i18n、Nuxt 接入、构建、项目约定 | `get_reui_guide` |
|
|
28
|
+
| 业务代码里引入组件、切主题、切语言 | 本目录 `BEST_PRACTICES.md` |
|
|
29
|
+
|
|
30
|
+
## 3. 核心工作流（配合 reui-mcp）
|
|
31
|
+
|
|
32
|
+
### 3.1 四步基础查询
|
|
33
|
+
|
|
34
|
+
1. **定位组件**：`get_reui_document`（可传 `category` 过滤）→ 拿到组件名与一句话说明。
|
|
35
|
+
2. **取完整文档**：`get_reui_document` 传 `component`（如 `component: "splitter"`）→ README 全文 + API 表格 + 示例说明。
|
|
36
|
+
3. **取可运行代码**：`get_reui_code_examples` 传同一个 `component` → 直接可复制的 Vue/TS 片段。
|
|
37
|
+
4. **确认不够再下钻**：`list_component_files` → `get_file_code`（指定行号区间）→ `get_function_code`（按符号名取实现）。
|
|
38
|
+
|
|
39
|
+
### 3.2 硬性规则
|
|
40
|
+
|
|
41
|
+
- **不猜 API**：任何 prop / event / slot 必须来自工具返回的文档或源码；工具查不到就明说「文档未提供」。
|
|
42
|
+
- **标明来源**：当工具命中兜底（返回官网文档站内容而非本地包内容）时，回复中必须写明「来源：官网文档站」与 `version`。
|
|
43
|
+
- **版本意识**：`version` 不传 = 当前项目本地已安装版本；跨版本对比或复现历史行为时才显式传版本号。
|
|
44
|
+
- **先读后写**：生成 reui 组件代码前，至少调用一次 `get_reui_document` 或 `get_reui_code_examples`。
|
|
45
|
+
|
|
46
|
+
## 4. 关键约定速查
|
|
47
|
+
|
|
48
|
+
### 4.1 安装与引入
|
|
49
|
+
|
|
50
|
+
| 事项 | 写法 | 来源 |
|
|
51
|
+
| -------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------- |
|
|
52
|
+
| 安装 | `npm i @reglow/reui` | `reui/README.md` |
|
|
53
|
+
| 主入口 | `import { Button, Splitter } from "@reglow/reui"` | `reui/package.json` exports `.` |
|
|
54
|
+
| 子路径（按需） | `import { Splitter } from "@reglow/reui/reui/splitter"`、`@reglow/reui/ui/button` | `reui/package.json` exports `./ui/*` `./reui/*` |
|
|
55
|
+
| 其他子路径 | `@reglow/reui/i18n`、`@reglow/reui/theme`、`@reglow/reui/nuxt` | 同上 |
|
|
56
|
+
| 样式（完整） | `import "@reglow/reui/style.css"` | `reui/package.json` exports `./style.css` |
|
|
57
|
+
| 样式（仅组件） | `import "@reglow/reui/components.css"`（宿主已有 Tailwind/主题变量，避免 reset 冲突） | `reui/README.md` |
|
|
58
|
+
|
|
59
|
+
### 4.2 Vue 用法
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
// main.ts
|
|
63
|
+
import { createApp } from "vue";
|
|
64
|
+
import { createReui } from "@reglow/reui";
|
|
65
|
+
import "@reglow/reui/style.css";
|
|
66
|
+
|
|
67
|
+
createApp(App)
|
|
68
|
+
.use(
|
|
69
|
+
createReui({
|
|
70
|
+
locale: "zh-CN",
|
|
71
|
+
theme: {
|
|
72
|
+
mode: "light",
|
|
73
|
+
baseColor: "zinc",
|
|
74
|
+
primaryColor: "blue",
|
|
75
|
+
radius: "0.5",
|
|
76
|
+
},
|
|
77
|
+
}),
|
|
78
|
+
)
|
|
79
|
+
.mount("#app");
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`createReui({ locale, theme, config })` 内部：装 i18n → `setLocale` → `applyTheme` → `setReuiConfig`
|
|
83
|
+
（`index.ts`）。不传配置可直接 `app.use(Reui)`（默认导出为无参 install）。
|
|
84
|
+
|
|
85
|
+
统一控制语言与主题：`<ConfigProvider locale="zh-TW" :theme="{ mode: 'dark' }">`（`guide.md` §4.4）。
|
|
86
|
+
|
|
87
|
+
### 4.3 Nuxt 用法
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
// nuxt.config.ts
|
|
91
|
+
export default defineNuxtConfig({
|
|
92
|
+
modules: ["@reglow/reui/nuxt"],
|
|
93
|
+
reui: {
|
|
94
|
+
locale: "zh-CN",
|
|
95
|
+
theme: { primaryColor: "blue" },
|
|
96
|
+
prefix: "R",
|
|
97
|
+
injectStyles: true,
|
|
98
|
+
},
|
|
99
|
+
vite: { resolve: { dedupe: ["vue"] } }, // 软链/file: 安装时避免 vue 双实例
|
|
100
|
+
});
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
- 自动注册组件（`prefix: "R"` → `<RButton>`）、注入样式与客户端 runtime plugin（`guide.md` §6）。
|
|
104
|
+
- `injectStyles: false` → 仅注入 `components.css`（宿主已有 Tailwind 时用，官方 docs 站即此配置，`reglow-docs/assets/css/tailwind.css`）。
|
|
105
|
+
|
|
106
|
+
### 4.4 主题
|
|
107
|
+
|
|
108
|
+
| API | 说明 |
|
|
109
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
110
|
+
| `applyTheme(theme)` | 切换 `<html>` 的 `.dark` + 注入 `--primary`/`--background`/`--radius`/`--font-body` 等 CSS 变量（`theme/index.ts`） |
|
|
111
|
+
| `saveTheme(theme)` | 写 `localStorage("reui_theme_config")` 并立即应用 |
|
|
112
|
+
| `loadAndApplyTheme()` | 启动时恢复，避免白屏闪烁 |
|
|
113
|
+
|
|
114
|
+
`ThemeConfig = { mode: "light" | "dark" | "auto", baseColor, primaryColor, radius, headingFont?, bodyFont? }`。
|
|
115
|
+
组件消费方式为 Tailwind 语义 token（`bg-primary` / `text-muted-foreground` / `border-border` 等），暗色靠 `.dark` class。
|
|
116
|
+
|
|
117
|
+
### 4.5 i18n
|
|
118
|
+
|
|
119
|
+
| API | 说明 |
|
|
120
|
+
| ------------------------------------------- | -------------------------------------------------------------- |
|
|
121
|
+
| `t(key, params?)` / `tm<T>(key, fallback?)` | 翻译文本 / 取数组·对象消息 |
|
|
122
|
+
| `setLocale(locale)` / `getCurrentLocale()` | 切换（写 `localStorage("locale")` + 同步 `<html lang>`）/ 读取 |
|
|
123
|
+
| `addLocale(locale, messages)` | 新增语言或深合并覆盖内置文案 |
|
|
124
|
+
| `useI18n()` | `{ locale, t, tm, setLocale, supportedLocales }` |
|
|
125
|
+
|
|
126
|
+
**铁律**：`t()/tm()` 只能在模板、`computed` 或函数体内调用，**绝不**写在 `withDefaults` 默认值或模块顶层；数组消息用 `computed(() => tm<string[]>(...))`；文案类 prop 优先于 i18n 默认值（`guide.md` §4.3）。
|
|
127
|
+
|
|
128
|
+
### 4.6 新增 / 修改组件时必须遵守
|
|
129
|
+
|
|
130
|
+
- 目录：`components/reui/<name>/`，含 `Xxx.vue` + `index.ts` + `README.md` + `__tests__/Xxx.test.ts`。
|
|
131
|
+
- 聚合导出：新增组件后同步 `components/reui/index.ts`（`export * from "./<name>"`）；同名组件 **reui 优先**（`guide.md` §3）。
|
|
132
|
+
- i18n：`zh-CN.ts` 为基准全集，`zh-TW.ts` / `en-US.ts` 必须镜像同样 key。
|
|
133
|
+
- 样式：统一用 `cn()` 合并类名 + 语义 token，不用硬编码色值；结构化元素加 `data-slot`。
|
|
134
|
+
- 验证：`npx vitest run`、`npx vue-tsc --noEmit -p tsconfig.json`（脚本别名 `npm run typecheck`）、`npm run build`。
|
|
135
|
+
|
|
136
|
+
> ⚠️ `components/reui/` 目录会被外部流程整体更新（曾出现 `index.ts` 被覆盖、新组件缺导出），改完后务必回查聚合入口与 `ui` 层命名冲突（`guide.md` §8）。
|
|
137
|
+
|
|
138
|
+
## 5. 文件导航（同目录）
|
|
139
|
+
|
|
140
|
+
| 文件 | 内容 | 何时读 |
|
|
141
|
+
| ------------------- | ----------------------------------------------------------------------- | -------------------------- |
|
|
142
|
+
| `WORKFLOWS.md` | reui-mcp 工具概览 + 四步查询流程 + 5 个完整任务示例（含参数与判断标准） | 需要查文档/示例代码前 |
|
|
143
|
+
| `BEST_PRACTICES.md` | 安装、样式、Tailwind `@source`、主题、i18n、Nuxt 的实践与陷阱 | 写业务代码前后对照 |
|
|
144
|
+
| `COMPONENTS.md` | 按分类的组件选型清单（说明 + 导入名 + 文档链接） | 组件选型、确认组件是否存在 |
|
|
145
|
+
|
|
146
|
+
## 6. 在 Trae / CodeBuddy / Qoder 中启用（MCP + Skills）
|
|
147
|
+
|
|
148
|
+
一条命令同时写好 MCP 配置并把本技能装进对应目录（默认就是这三个工具）：
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
npx -y -p @reglow/reui-mcp reui-setup --tools trae,codebuddy,qoder
|
|
152
|
+
# 可选：--scope user（用户级）｜--dry-run（仅预览）｜--force（覆盖已有 Skills）
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
| 工具 | Skills 目录（项目级） | MCP 配置（项目级） | 仍需手动完成 |
|
|
156
|
+
| --------- | --------------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
|
|
157
|
+
| Trae | `.trae/skills/` | `.trae/mcp.json` | 设置 → MCP 打开「启用项目级 MCP」开关 |
|
|
158
|
+
| CodeBuddy | `.codebuddy/skills/` | `.mcp.json` | IDE 需在对话面板 CodeBuddy Settings → MCP → Add MCP 粘贴同一条目；CLI 直接生效 |
|
|
159
|
+
| Qoder | `.qoder/skills/` | `.mcp.json`（或 `.qoder/settings.json`） | 项目级 MCP 默认需批准（或设 `mcp.enableAllProjectMcpServers: true`）；`/mcp reload` |
|
|
160
|
+
|
|
161
|
+
- MCP 条目：`{"command":"npx","args":["-y","@reglow/reui-mcp"]}`；CodeBuddy / Qoder 额外带 `type: "stdio"` 与 `description`。
|
|
162
|
+
- 排查：`npx -y @reglow/reui-mcp --check`（知识源与组件数）、`npx -y @reglow/reui-mcp --list-tools`（各工具路径）。
|
|
163
|
+
- 配置完成后重载 AI 工具（Qoder 还需 `/skills reload`），再让它「用 reui 组件写一个 XX 页面」验证工具被调用。
|
|
164
|
+
|
|
165
|
+
## 7. 常见红线
|
|
166
|
+
|
|
167
|
+
1. 不编造 props / events / slots / 导入路径。
|
|
168
|
+
2. 不在 `withDefaults` 或模块顶层调用 `t()` / `tm()`。
|
|
169
|
+
3. 不在 `setup` 顶层调用 `Modal.info/confirm`、`useToast`、`useNotification` 等命令式 API（仅在客户端事件回调/`onMounted` 中调用）。
|
|
170
|
+
4. 不用 `bg-blue-500` 这类固定色，改用语义 token。
|
|
171
|
+
5. 消费方 Tailwind v4 未加 `@source` 扫描 `node_modules/@reglow/reui` 时，类名可能缺失（`@source "../../../node_modules/@reglow/reui/dist/components"`）。
|
|
172
|
+
6. 不修改 `mcp/` 代码与 `package.json` 等非文档文件。
|