@h-ai/ui 1.0.0-beta.30 → 1.0.0-beta.31
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.en.md +10 -1183
- package/README.ja.md +9 -1182
- package/README.md +12 -1183
- package/auto-import.d.ts +4 -0
- package/auto-import.js +4 -0
- package/dist/components/compounds/Popover.svelte +1 -0
- package/dist/components/scenes/ai/AiDocumentEditor.svelte +73 -7
- package/dist/components/scenes/ai/document-download.js +49 -86
- package/dist/components/scenes/ai/document-parse.js +6 -28
- package/dist/components/scenes/ai/document-pdf-pages.d.ts +26 -0
- package/dist/components/scenes/ai/document-pdf-pages.js +111 -0
- package/dist/components/scenes/ai/document-pdf-worker.d.ts +11 -0
- package/dist/components/scenes/ai/document-pdf-worker.js +29 -0
- package/dist/components/scenes/ai/document-render-pool.d.ts +19 -0
- package/dist/components/scenes/ai/document-render-pool.js +20 -0
- package/dist/components/scenes/ai/document-render-worker.d.ts +13 -0
- package/dist/components/scenes/ai/document-render-worker.js +7 -0
- package/dist/components/scenes/ai/document-types.d.ts +2 -0
- package/dist/components/scenes/ai/index.d.ts +3 -0
- package/dist/components/scenes/ai/index.js +2 -0
- package/dist/components/scenes/ai/mind/AiMindMapEditor.svelte +519 -0
- package/dist/components/scenes/ai/mind/AiMindMapEditor.svelte.d.ts +8 -0
- package/dist/components/scenes/ai/mind/mind-adapter.d.ts +38 -0
- package/dist/components/scenes/ai/mind/mind-adapter.js +59 -0
- package/dist/components/scenes/ai/mind/mind-types.d.ts +116 -0
- package/dist/components/scenes/ai/mind/mind-types.js +1 -0
- package/dist/components/scenes/index.d.ts +1 -0
- package/dist/components/scenes/index.js +2 -0
- package/dist/components/scenes/tools/ArtifactWorkspace.svelte +561 -0
- package/dist/components/scenes/tools/ArtifactWorkspace.svelte.d.ts +17 -0
- package/dist/components/scenes/tools/ToolWorkspace.svelte +435 -0
- package/dist/components/scenes/tools/ToolWorkspace.svelte.d.ts +17 -0
- package/dist/components/scenes/tools/artifact-data.d.ts +35 -0
- package/dist/components/scenes/tools/artifact-data.js +127 -0
- package/dist/components/scenes/tools/artifact-markdown.d.ts +58 -0
- package/dist/components/scenes/tools/artifact-markdown.js +308 -0
- package/dist/components/scenes/tools/artifact-preview.d.ts +9 -0
- package/dist/components/scenes/tools/artifact-preview.js +31 -0
- package/dist/components/scenes/tools/index.d.ts +4 -0
- package/dist/components/scenes/tools/index.js +3 -0
- package/dist/components/scenes/tools/tool-form.d.ts +74 -0
- package/dist/components/scenes/tools/tool-form.js +179 -0
- package/dist/components/scenes/tools/workspace-types.d.ts +221 -0
- package/dist/components/scenes/tools/workspace-types.js +1 -0
- package/dist/messages/en-US.json +99 -1
- package/dist/messages/ja-JP.json +99 -1
- package/dist/messages/zh-CN.json +99 -1
- package/package.json +8 -2
package/README.md
CHANGED
|
@@ -12,1200 +12,29 @@ HTTP/UI 边界只对明确的有效 4xx 状态公开业务提示;错误缺少
|
|
|
12
12
|
|
|
13
13
|
## 快速开始
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
使用 pnpm 安装:`pnpm add @h-ai/ui`。
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
npm install @h-ai/ui @h-ai/core
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
Node 服务端工程将 UI 与 core 都列为生产依赖,确保适配器保留 core 的日志和原生依赖加载。
|
|
22
|
-
|
|
23
|
-
### 1. 配置 package.json 的应用导入
|
|
24
|
-
|
|
25
|
-
```json
|
|
26
|
-
{ "imports": { "#lib/*": "./src/lib/*" } }
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
### 2. 配置 vite.config.ts
|
|
30
|
-
|
|
31
|
-
SvelteKit 3 的预处理、编译器与适配器都在 Vite 插件中配置;纯 Svelte/Vite 工程才保留 svelte.config.js。
|
|
32
|
-
|
|
33
|
-
预处理顺序为 `vitePreprocess()` 或其他样式/模板语言转换在前、`autoImportHaiUi()` 在后。自动导入读取整份 Svelte AST,不直接接受尚未转换的 SCSS、Pug 等非标准语法;保留同步调用方式。
|
|
34
|
-
|
|
35
|
-
```ts
|
|
36
|
-
import { autoImportHaiUi } from '@h-ai/ui/auto-import'
|
|
37
|
-
import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
|
|
38
|
-
import adapter from '@sveltejs/adapter-node'
|
|
39
|
-
import { sveltekit } from '@sveltejs/kit/vite'
|
|
40
|
-
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
|
|
41
|
-
import tailwindcss from '@tailwindcss/vite'
|
|
42
|
-
import { defineConfig } from 'vite'
|
|
43
|
-
|
|
44
|
-
export default defineConfig({
|
|
45
|
-
plugins: [
|
|
46
|
-
sveltekit({
|
|
47
|
-
preprocess: [vitePreprocess(), autoImportHaiUi()],
|
|
48
|
-
compilerOptions: { runes: true },
|
|
49
|
-
adapter: adapter(),
|
|
50
|
-
paths: { relative: false },
|
|
51
|
-
}),
|
|
52
|
-
tailwindcss(),
|
|
53
|
-
],
|
|
54
|
-
optimizeDeps: { exclude: [...haiOptimizeExclude], include: [...haiPrebundledDeps] },
|
|
55
|
-
ssr: { noExternal: ['@h-ai/ui', '@h-ai/kit'], external: ['@h-ai/core', 'sm-crypto'] },
|
|
56
|
-
})
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
### 3. 配置 src/app.css
|
|
60
|
-
|
|
61
|
-
使用 Crypto 或依赖它的 Kit/IAM 时,应用生产依赖需包含 `sm-crypto@0.5.8`。CLI 已配好这一项;手工接入时运行 `pnpm add sm-crypto@0.5.8`。仅设置 external 不够,adapter-node 还需要直接生产依赖声明才能保留原包加载。
|
|
62
|
-
|
|
63
|
-
```css
|
|
64
|
-
@import 'tailwindcss';
|
|
65
|
-
@import '@h-ai/ui/styles/global.css';
|
|
66
|
-
@import '@h-ai/ui/styles/theme.css';
|
|
67
|
-
@source "../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
|
|
68
|
-
@source "../../../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
|
|
69
|
-
|
|
70
|
-
@plugin "daisyui" {
|
|
71
|
-
themes: light --default, dark --prefersdark, cupcake, emerald, corporate, nord, dracula, night;
|
|
72
|
-
}
|
|
73
|
-
|
|
74
|
-
/* 图标(可选) */
|
|
75
|
-
@plugin "@iconify/tailwind4" {
|
|
76
|
-
prefixes: tabler;
|
|
77
|
-
}
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
> `@source` 让 TailwindCSS 扫描 `@h-ai/ui` 组件中使用的 class 名,否则组件样式会丢失。嵌套应用位于 monorepo 中时,依赖包可能被提升到工作区根 `node_modules`,所以建议同时保留两条路径。
|
|
81
|
-
|
|
82
|
-
### 4. 使用组件
|
|
83
|
-
|
|
84
|
-
```svelte
|
|
85
|
-
<script>
|
|
86
|
-
import { Button, Input, Card } from '@h-ai/ui'
|
|
87
|
-
</script>
|
|
88
|
-
|
|
89
|
-
<Card title="示例表单">
|
|
90
|
-
<Input placeholder="请输入用户名" />
|
|
91
|
-
<Button variant="primary" onclick={handleSubmit}>提交</Button>
|
|
92
|
-
</Card>
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
启用自动导入后可直接在模板中使用,无需逐个 import:
|
|
96
|
-
|
|
97
|
-
```svelte
|
|
98
|
-
<!-- 无需 import { Button } from '@h-ai/ui' -->
|
|
99
|
-
<Button variant="primary">提交</Button>
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
> 除 `toast`、类型导入与 `Range`(会和 DOM `Range` 构造器冲突)外,其余公开 Svelte 组件都可通过 `@h-ai/ui/auto-import` 自动注入。
|
|
103
|
-
|
|
104
|
-
管理后台等只使用部分组件的页面,可直接使用公开组件目录入口;主题工具通过轻量 `@h-ai/ui/theme` 导入,避免主题消费加载根入口中的 AI、图表等组件。状态层的语言工具使用 `@h-ai/ui/i18n`,不加载组件与引导 CSS。组件路径以已安装版本的 exports 为准,不导入包内 `src/` 或 `dist/`。
|
|
105
|
-
|
|
106
|
-
自动导入器只为模板 AST 中实际使用的组件注入导入,注释、textarea 和脚本字符串中的示例不触发导入;脚本声明以及 each、await、snippet 等模板局部绑定优先。无分号、跨行及带别名的真实导入按语法树识别,已绑定的运行时组件名称不会重复注入。根入口 `@h-ai/ui` 的仅类型组件绑定按需提升为值;外部模块的同名类型无法安全合并时,构建错误会列出文件和组件名,请为类型设置别名,或用其他本地名显式导入组件。
|
|
107
|
-
|
|
108
|
-
```ts
|
|
109
|
-
import { Card } from '@h-ai/ui/components/compounds/index'
|
|
110
|
-
import { Button } from '@h-ai/ui/components/primitives/index'
|
|
111
|
-
import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
## 功能
|
|
115
|
-
|
|
116
|
-
### 用途、输入与输出
|
|
117
|
-
|
|
118
|
-
UI 无 init/close;以下片段在应用组件或浏览器交互上下文中使用,命名变量代表应用已提供的请求、Schema、资源定义或配置。完整步骤和失败处理见对应功能示例。`HaiResult` 先判断 `success`,异步项按签名 `await`。
|
|
119
|
-
|
|
120
|
-
| 入口 | 场景 | 输入 | 输出 | 调用片段 |
|
|
121
|
-
| --- | --- | --- | --- | --- |
|
|
122
|
-
| `autoImportHaiUi` | 自动导入 | `preprocessed Svelte source and filename through markup` | `PreprocessorGroup; synchronous { code }` | `autoImportHaiUi()` |
|
|
123
|
-
| `parseMarkdown` | 安全 Markdown | `Markdown source, MarkdownParseOptions?` | `HTML string; raw HTML escaped or allowlisted` | `parseMarkdown("# Hello", { allowHtmlTags: false })` |
|
|
124
|
-
| `renderMarkdownDocument` | 编辑器文档模型 | `Markdown source, MarkdownDocumentParseOptions?` | `MarkdownRenderResult with outline/codeBlocks/blocks` | `renderMarkdownDocument("# Report", { allowHtmlTags: false })` |
|
|
125
|
-
| `isLanguageSupported` | 检查高亮语言 | `language name` | `boolean` | `isLanguageSupported("typescript")` |
|
|
126
|
-
| `highlightCode` | 同步代码高亮 | `code text, supported language` | `escaped/highlighted HTML string` | `highlightCode("const total = 1", "typescript")` |
|
|
127
|
-
| `resolveDocumentMarkdownContent` | 代码内容加围栏 | `text, sourceKind?, language?` | `Markdown string with a safe fence length` | `resolveDocumentMarkdownContent("const x = 1", "code", "ts")` |
|
|
128
|
-
| `resolveDocumentDownloadActions` | 下载动作菜单 | `MarkdownToolbarDownloadAction[]?` | `AiDocumentResolvedDownloadAction[]` | `resolveDocumentDownloadActions([{ id: "markdown", label: "Markdown" }])` |
|
|
129
|
-
| `downloadAiDocument` | 下载已选格式 | `AiDocumentDownloadRequest` | `Promise<void>; browser failure rejects, SSR does nothing` | `downloadAiDocument({ actionId: "markdown", content: "# Report", filename: "report.md" })` |
|
|
130
|
-
| `createLocaleStore` | 组件树语言状态 | `{ defaultLocale?, supportedLocales?, detectBrowser?, persistKey? }` | `locale store with current/set/isSupported` | `createLocaleStore({ defaultLocale: "zh-CN", detectBrowser: false })` |
|
|
131
|
-
| `getGlobalLocale` | 读取当前语言 | `none` | `locale string from current context` | `getGlobalLocale()` |
|
|
132
|
-
| `setGlobalLocale` | 设置浏览器或启动语言 | `locale` | `void; use request context for SSR` | `setGlobalLocale("en-US")` |
|
|
133
|
-
| `detectBrowserLocale` | 识别浏览器语言 | `supportedLocales?` | `supported locale or null` | `detectBrowserLocale()` |
|
|
134
|
-
| `isLocaleSupported` | 校验支持语言 | `locale, supportedLocales?` | `boolean` | `isLocaleSupported("ja-JP")` |
|
|
135
|
-
| `resolveLocale` | 归一化语言 | `locale, supportedLocales?, fallback?` | `supported locale` | `resolveLocale("en")` |
|
|
136
|
-
| `interpolate` | 替换文案参数 | `template string, InterpolationParams` | `string` | `interpolate("Hello {name}", { name: "Ada" })` |
|
|
137
|
-
| `getThemeInfo` | 主题元数据 | `theme ID` | `ThemeInfo or undefined` | `getThemeInfo("light")` |
|
|
138
|
-
| `isDarkTheme` | 识别暗色主题 | `theme ID` | `boolean` | `isDarkTheme("dark")` |
|
|
139
|
-
| `normalizeThemeId` | 归一化主题 | `candidate theme ID, fallback?` | `supported theme ID` | `normalizeThemeId("unknown", "light")` |
|
|
140
|
-
| `normalizeHexColor` | 归一化颜色 | `string or null/undefined` | `six-digit lowercase hex string or null` | `normalizeHexColor("#5765F0")` |
|
|
141
|
-
| `resolveThemeTone` | 主题亮暗语义 | `theme ID` | `light or dark` | `resolveThemeTone("light")` |
|
|
142
|
-
| `createThemeBootstrapScript` | 防首屏主题闪烁 | `ThemeBootstrapScriptOptions from trusted host config` | `script string for the application HTML shell` | `createThemeBootstrapScript({ storageKey: "theme", defaultThemeId: "light" })` |
|
|
143
|
-
| `getThemeInitScript` | 默认主题启动脚本 | `none` | `script string` | `getThemeInitScript()` |
|
|
144
|
-
| `applyTheme` | 切换页面主题 | `theme ID, persist? (default true)` | `void; updates DOM/browser preference` | `applyTheme("dark")` |
|
|
145
|
-
| `getCurrentTheme` | 读取页面主题 | `none` | `theme ID string` | `getCurrentTheme()` |
|
|
146
|
-
| `getSavedTheme` | 读取主题偏好 | `fallback theme ID?` | `theme ID string` | `getSavedTheme("light")` |
|
|
147
|
-
| `createGuide` | 引导控制器 | `GuideOptions: tours, articles?, nav?, persistence?, persistKey?` | `GuideController; no init/close` | `createGuide({ tours: [], persistence: "memory" })` |
|
|
148
|
-
| `resolveGuideText` | 延迟翻译引导文案 | `string or translation callback?` | `string` | `resolveGuideText(() => m.help())` |
|
|
149
|
-
| `matchPermission` | 前端权限显示 | `required permission, userPermissions[]` | `boolean; not server authorization` | `matchPermission("orders:read", ["orders:*"])` |
|
|
150
|
-
| `setPermissionContext` | 提供组件权限上下文 | `() => current permissions; component initialization only` | `void` | `setPermissionContext(() => user.permissions)` |
|
|
151
|
-
| `usePermission` | 消费组件权限 | `none; component initialization only` | `PermissionContext with hasPerm/hasAnyPerm/hasAllPerms` | `usePermission()` |
|
|
152
|
-
| `createSensitiveActions` | 敏感操作确认 | `standard auth actions providing reauthenticate/publicConfig?` | `SensitiveActions: configure/authorize/submit/cancel` | `createSensitiveActions(actions)` |
|
|
153
|
-
| `createSessionRecovery` | 原地恢复会话 | `none; configure public config and current user afterward` | `SessionRecovery controller` | `createSessionRecovery()` |
|
|
154
|
-
| `defineCrud` | 声明列表表单 | `CrudResource with fields/API callbacks` | `CrudDef for CrudPage` | `defineCrud(resourceDefinition)` |
|
|
155
|
-
| `createCrudController` | 托管列表状态 | `CrudDef, { autoLoad? }?` | `controller data/nav/loading/loaded/error/load/reload` | `createCrudController(crud, { autoLoad: false })` |
|
|
156
|
-
| `mapPaginated` | 映射分页条目 | `PaginatedResult<T>, (item,index) => R` | `PaginatedResult<R> retaining total/page/pageSize` | `mapPaginated(page, item => ({ ...item, selected: false }))` |
|
|
157
|
-
| `createBrowserNavAdapter` | 接入普通浏览器导航 | `none` | `NavAdapter` | `createBrowserNavAdapter()` |
|
|
158
|
-
| `registerClipboardHostWriter` | 注册 WebView 剪贴板 | `async text => boolean or null to unregister` | `void` | `registerClipboardHostWriter(null)` |
|
|
159
|
-
| `writeTextToClipboard` | 复制并核对结果 | `text: string` | `Promise<boolean>; true only when write succeeds` | `writeTextToClipboard("trace-001")` |
|
|
160
|
-
| `cn` | 合并类名 | `...string\|boolean\|null\|undefined values` | `string` | `cn("flex", active && "text-primary")` |
|
|
161
|
-
| `getDataAttributes` | 只透传 data 属性 | `props record` | `ForwardedDataAttributes` | `getDataAttributes({ "data-testid": "save" })` |
|
|
162
|
-
| `generateId` | 生成 UI 标识 | `prefix?; not a security token generator` | `string` | `generateId("field")` |
|
|
163
|
-
| `portal` | 将节点挂到宿主 | `HTMLElement, target HTMLElement or selector?` | `Svelte action result with cleanup` | `portal(node, document.body)` |
|
|
164
|
-
| `detectPlatform` | 检测终端类型 | `none` | `Platform` | `detectPlatform()` |
|
|
165
|
-
| `isMobile` | 检查移动端 | `none` | `boolean` | `isMobile()` |
|
|
166
|
-
| `isNativeApp` | 检查原生壳 | `none` | `boolean` | `isNativeApp()` |
|
|
167
|
-
| `usePlatform` | 响应式终端视图 | `none; component initialization` | `{ current, isMobile, isApp }` | `usePlatform()` |
|
|
168
|
-
| `getVariantClass` | 映射主题样式 | `Variant, prefix?` | `string class name` | `getVariantClass("primary", "btn")` |
|
|
169
|
-
| `getSizeClass` | 映射主题样式 | `Size, prefix?` | `string class name` | `getSizeClass("sm", "btn")` |
|
|
170
|
-
| `getInputSizeClass` | 映射主题样式 | `Size` | `string class name` | `getInputSizeClass("sm")` |
|
|
171
|
-
| `getBadgeVariantClass` | 映射主题样式 | `Variant` | `string class name` | `getBadgeVariantClass("info")` |
|
|
172
|
-
| `getBadgeSizeClass` | 映射主题样式 | `Size` | `string class name` | `getBadgeSizeClass("sm")` |
|
|
173
|
-
| `getAlertVariantClass` | 映射主题样式 | `Variant` | `string class name` | `getAlertVariantClass("info")` |
|
|
174
|
-
| `getProgressVariantClass` | 映射主题样式 | `Variant` | `string class name` | `getProgressVariantClass("primary")` |
|
|
175
|
-
| `useToastFeedback` | 操作结果提示 | `() => safely localized message, variant?` | `void; source-owned toast lifecycle` | `useToastFeedback(() => errorMessage(error))` |
|
|
176
|
-
| `notifySuccess` | 操作结果提示 | `localized message, duration?` | `toast ID string` | `notifySuccess(m.saved())` |
|
|
177
|
-
| `notifyInfo` | 操作结果提示 | `localized message, duration?` | `toast ID string` | `notifyInfo(m.loading())` |
|
|
178
|
-
| `notifyWarning` | 操作结果提示 | `localized message, duration?` | `toast ID string` | `notifyWarning(m.warning())` |
|
|
179
|
-
| `notifyError` | 操作结果提示 | `unknown error, safe fallback?, duration?` | `toast ID string; internal exception text hidden` | `notifyError(error, m.retry())` |
|
|
180
|
-
| `errorMessage` | 操作结果提示 | `unknown error, safe fallback?` | `safe localized string` | `errorMessage(error, m.retry())` |
|
|
181
|
-
| `toast.add` | 共享提示队列 | `localized options/message` | `string item ID` | `toast.add({ message: m.saved(), variant: "success" })` |
|
|
182
|
-
| `toast.success` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `toast.success(m.result())` |
|
|
183
|
-
| `toast.info` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `toast.info(m.result())` |
|
|
184
|
-
| `toast.warning` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `toast.warning(m.result())` |
|
|
185
|
-
| `toast.error` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `toast.error(m.result())` |
|
|
186
|
-
| `toast.remove` | 共享提示队列 | `item ID` | `void` | `toast.remove(id)` |
|
|
187
|
-
| `toast.clear` | 共享提示队列 | `none` | `void` | `toast.clear()` |
|
|
188
|
-
| `message.add` | 共享提示队列 | `localized options/message` | `string item ID` | `message.add({ message: m.saved(), type: "success" })` |
|
|
189
|
-
| `message.success` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `message.success(m.result())` |
|
|
190
|
-
| `message.info` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `message.info(m.result())` |
|
|
191
|
-
| `message.warning` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `message.warning(m.result())` |
|
|
192
|
-
| `message.error` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `message.error(m.result())` |
|
|
193
|
-
| `message.remove` | 共享提示队列 | `item ID` | `void` | `message.remove(id)` |
|
|
194
|
-
| `message.clear` | 共享提示队列 | `none` | `void` | `message.clear()` |
|
|
195
|
-
| `toast.pause` | 提示计时 | `toast ID` | `void` | `toast.pause(id)` |
|
|
196
|
-
| `toast.resume` | 提示计时 | `toast ID` | `void` | `toast.resume(id)` |
|
|
197
|
-
| `messageBox.confirm` | 异步确认弹窗 | `localized string or MessageBoxOptions` | `Promise<boolean>; host handles confirmation/cancellation` | `messageBox.confirm({ message: m.confirm() })` |
|
|
198
|
-
| `messageBox.alert` | 异步确认弹窗 | `localized string or MessageBoxOptions` | `Promise<boolean>; host handles confirmation/cancellation` | `messageBox.alert({ message: m.confirm() })` |
|
|
199
|
-
|
|
200
|
-
- 表单、表格、弹窗、导航、图表与业务场景组件。
|
|
201
|
-
- 认证、CRUD、AI 内容展示、新手引导和帮助中心。
|
|
202
|
-
- Svelte 5、主题切换、响应式布局及中英日文组件文案。
|
|
203
|
-
|
|
204
|
-
Markdown 下划线与高亮支持转义,未闭合标记按文本处理;Toast 和文档下载在异常长文本输入下保持可用,追踪编号仍默认收起。
|
|
205
|
-
|
|
206
|
-
### data-* 属性透传
|
|
207
|
-
|
|
208
|
-
公开 Svelte 组件支持把调用方传入的 `data-*` 属性透传到组件根节点或主交互节点,便于测试选择器、埋点和自动化标记。普通未知属性不会被透传。
|
|
209
|
-
|
|
210
|
-
```svelte
|
|
211
|
-
<Button data-testid='save-button' data-analytics-id='settings.save'>保存</Button>
|
|
212
|
-
<Input data-testid='username-input' bind:value={username} />
|
|
213
|
-
<Modal data-testid='confirm-modal' bind:open={open}>...</Modal>
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
无需再为了 `data-testid` 单独封装按钮、输入框或弹层组件。
|
|
217
|
-
|
|
218
|
-
### 组件族的输入、事件与输出
|
|
219
|
-
|
|
220
|
-
下表覆盖组件清单中的交互类别;变量 m、rows、user、controllers 和回调由业务应用提供。静态展示组件输出 DOM,交互组件通过绑定和回调向应用报告变化,均不自动取得业务授权。更完整的组合步骤见本页“使用示例”、对应组件清单说明及 UI skill;其余 Props 由实际导出的 Props 类型约束。
|
|
221
|
-
|
|
222
|
-
| 组件族 | 输入 | 输出/事件 | 使用片段 |
|
|
223
|
-
| --- | --- | --- | --- |
|
|
224
|
-
| Button / IconButton / BareButton | variant, size, loading, disabled; icon/snippet; onclick | click event; loading/disabled block repeated action | `<Button loading={saving} onclick={save}>{m.save()}</Button>` |
|
|
225
|
-
| Input / BareInput / Textarea / PasswordInput | type, value, label/validation props | bind:value; input/change/focus events; file input exposes FileList | `<Input bind:value={draft} required />` |
|
|
226
|
-
| Select / Radio / Range / Rating / Combobox | options or min/max/step, current value | bound selected value and selection callbacks | `<Select options={options} bind:value={selected} />` |
|
|
227
|
-
| Checkbox / Switch / ToggleCheckbox / ToggleInput / ToggleRadio | checked/name/label, disabled | bind:checked and change events | `<Checkbox bind:checked={enabled} label={m.enabled()} />` |
|
|
228
|
-
| Form / FormLayout / FormField / TagInput | columns, labels, error/hint, tags, submit callback | validated submit event, tag changes, accessible field association | `<Form onsubmit={save}><FormField label={m.name()}><Input bind:value={name} /></FormField></Form>` |
|
|
229
|
-
| Modal / Drawer / Popover / Dropdown / Tooltip / Calendar | open, trigger/content snippets, dimensions, selected value | bound open/selection; focus handling and close actions | `<Modal bind:open={open} title={m.details()}>{m.content()}</Modal>` |
|
|
230
|
-
| DataTable / TableToolbar / Pagination / FilterBar | rows, columns, total/page, draft search/filter, loading | row/sort/page/query callbacks; host performs the request | `<DataTable {columns} data={rows} sortKey={sortKey} sortDir={sortDir} onsort={sortRows} />` |
|
|
231
|
-
| Tabs / Breadcrumb / Steps / BottomNav / AppBar | items/current key, links, titles and action snippets | selected key/navigation callbacks; host owns routing | `<Tabs {items} bind:active={activeTab} />` |
|
|
232
|
-
| Alert / Badge / Avatar / Tag / Spinner / Progress / Skeleton / Empty / Result | status/variant/value/text/image and state props | presentational DOM; tag/alert close callbacks when enabled | `<Progress value={completed} max={total} />` |
|
|
233
|
-
| WorkspaceLayout / PageHeader / SettingsLayout / SettingsModal | title, sections, active key, leading/actions/footer/children | layout DOM; selection/open callbacks; no business writes | `<WorkspaceLayout title={m.title()}>{m.content()}</WorkspaceLayout>` |
|
|
234
|
-
| FileUpload / ImageUpload / AvatarUpload / FileList | accept/size limits, File values, uploadHandler, files | selected files/progress/result URL and delete/download callbacks | `<ImageUpload bind:value={imageUrl} uploadHandler={uploadImage} />` |
|
|
235
|
-
| AuthPanel / AuthShell / LoginForm / RegisterForm / password forms / PermGuard | public IAM config, standard actions, errors, permission context | authenticated/submit/reset callbacks; server still authorizes | `<AuthPanel {config} {actions} />` |
|
|
236
|
-
| UserProfile / SensitiveOperationsForm / ReauthenticationDialog / SessionRecoveryDialog | profile or operations, async submit, current controller/state | UserProfile closes only on true; other confirmations report explicit completion | `<UserProfile {user} editable onsubmit={saveProfile} />` |
|
|
237
|
-
| CrudPage / CrudFilterBar / CrudEditPanel / CrudDetailPanel / CrudDeleteConfirm | CrudDef, data/nav, loading/error/permissions, API callbacks | resource-bound query/edit/delete callbacks; server enforces resource access | `<CrudPage {crud} data={controller.data} nav={controller.nav} />` |
|
|
238
|
-
| MarkdownRenderer / AiDocumentEditor / AiTableEditor / AiDocumentDownloadMenu | content or columns/rows, action callbacks, safe HTML options | Markdown HTML, content/cell changes and explicit download/run requests | `<MarkdownRenderer content={markdown} allowHtmlTags={false} />` |
|
|
239
|
-
| EncryptedInput / HashDisplay / SignatureDisplay | plaintext/hash/signature, algorithm label, real onencrypt callback | display DOM; bound encryptedValue only after current request succeeds | `<EncryptedInput bind:value={plain} bind:encryptedValue={cipher} onencrypt={encrypt} />` |
|
|
240
|
-
| FeedbackModal / FeedbackForm / FeedbackList / FeedbackDetail / FeedbackScreenshot | prepared evidence, attachments, rows/report, permissions and actions | submission/query/status/export/retry/annotation callbacks | `<FeedbackForm attachments={attachments} onsubmit={submitFeedback} />` |
|
|
241
|
-
| Chart / DashboardGrid / MetricCard / ReportCard | chart data/preset and raw chart props; metrics and loading state | rendered chart/dashboard; native chart callbacks pass through | `<MetricCard title={m.revenue()} value={revenue} trend={growth} />` |
|
|
242
|
-
| GuideHost / HelpCenter | GuideController, locale/scope, articles/tours | onboarding/help UI; start/close callbacks and nonsensitive preferences | `<GuideHost {guide} scope={user.id} locale={locale} />` |
|
|
243
|
-
|
|
244
|
-
### 组件架构
|
|
245
|
-
|
|
246
|
-
组件按三层划分(primitives → compounds → scenes):
|
|
247
|
-
|
|
248
|
-
```
|
|
249
|
-
components/
|
|
250
|
-
├── primitives/ # 原子组件(不可再分的基础 UI 单元)
|
|
251
|
-
├── compounds/ # 组合组件(由原子组件 + Bits UI headless 组合而成)
|
|
252
|
-
└── scenes/ # 场景组件(面向具体业务场景的完整 UI 流程)
|
|
253
|
-
├── ai/ # AI 文档 / 表格 / Markdown 预览
|
|
254
|
-
├── app/ # 应用级(设置/反馈/主题/语言切换)
|
|
255
|
-
├── crud/ # CRUD 页面 / 抽屉 / 过滤 / 删除确认
|
|
256
|
-
├── iam/ # 身份认证
|
|
257
|
-
├── storage/ # 存储管理
|
|
258
|
-
└── crypto/ # 加密展示
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
### 组件清单
|
|
262
|
-
|
|
263
|
-
#### 原子组件 Primitives
|
|
264
|
-
|
|
265
|
-
| 组件 | 描述 | 主要属性 |
|
|
266
|
-
| ---------------- | ------------ | ------------------------------------------------------------------ |
|
|
267
|
-
| `Button` | 按钮 | `variant`, `size`, `loading`, `disabled`, `outline`, `circle` |
|
|
268
|
-
| `IconButton` | 图标按钮 | `icon: trusted SVG string \| Snippet`, `variant`, `size`, `tooltip`, `loading` |
|
|
269
|
-
| `BareButton` | 无样式按钮 | `class`, `ariaLabel`, `role`, `tabindex` |
|
|
270
|
-
| `Input` | 输入框 | `type`, `value`, `size`, `error`, `validationMessage` |
|
|
271
|
-
| `BareInput` | 无样式输入框 | `type`, `class`, `accept`, `multiple` |
|
|
272
|
-
| `Textarea` | 文本域 | `value`, `rows`, `size`, `autoResize`, `error` |
|
|
273
|
-
| `Select` | 下拉选择 | `options`, `value`, `placeholder`, `size`, `clearable`, `filterable` |
|
|
274
|
-
| `Checkbox` | 复选框 | `checked`, `label`, `size`, `indeterminate` |
|
|
275
|
-
| `Switch` | 开关 | `checked`, `label`, `size` |
|
|
276
|
-
| `Radio` | 单选组 | `options`, `value`, `direction`, `size` |
|
|
277
|
-
| `ToggleCheckbox` | 原生开关输入 | `checked`, `name`, `onchange` |
|
|
278
|
-
| `ToggleInput` | 原生切换输入 | `checked`, `name` |
|
|
279
|
-
| `ToggleRadio` | 原生单选输入 | `checked`, `name`, `onchange` |
|
|
280
|
-
| `Range` | 滑块 | `value`, `min`, `max`, `step` |
|
|
281
|
-
| `Rating` | 评分 | `value`, `max` |
|
|
282
|
-
| `Badge` | 徽章 | `variant`, `size`, `outline` |
|
|
283
|
-
| `Avatar` | 头像 | `src`, `name`, `size`, `shape`, `ring` |
|
|
284
|
-
| `Tag` | 标签 | `text`, `variant`, `size`, `closable` |
|
|
285
|
-
| `Spinner` | 加载动画 | `size`, `variant` |
|
|
286
|
-
| `Progress` | 进度条 | `value`, `max`, `variant`, `striped`, `animated` |
|
|
287
|
-
|
|
288
|
-
`Checkbox`、`Switch` 和 `Radio` 默认使用主题主色,选中态跟随当前 DaisyUI 主题;`Checkbox` 可用 `checkbox-*` 类名覆盖颜色。
|
|
289
|
-
|
|
290
|
-
`BareInput` 的 `file` 类型通过 `onchange` 读取 `event.currentTarget.files`,不绑定文件路径 `value`;其他输入类型可使用 `bind:value`。
|
|
291
|
-
|
|
292
|
-
#### 组合组件 Compounds
|
|
293
|
-
|
|
294
|
-
##### 表单
|
|
295
|
-
|
|
296
|
-
| 组件 | 描述 | 主要属性 |
|
|
297
|
-
| ----------- | -------- | -------------------------------------------- |
|
|
298
|
-
| `Form` | 表单容器 | `columns`, `labelPosition`, `labelWidth`, `loading`, `disabled`, `onsubmit` |
|
|
299
|
-
| `FormField` | 表单字段 | `label`, `for`, `colSpan`, `labelPosition`, `error`, `hint`, `required` |
|
|
300
|
-
| `FormLayout` | 表单布局 | `columns`, `labelPosition`, `labelWidth` |
|
|
301
|
-
| `TagInput` | 标签输入 | `tags`, `maxTags`, `allowDuplicates`, `size` |
|
|
302
|
-
|
|
303
|
-
##### 表单布局与校验
|
|
304
|
-
|
|
305
|
-
`Form` 和可嵌入原生 `<form>` 的 `FormLayout` 共用 `columns={1 | 2}`、`labelPosition="top" | "left"`、`labelWidth`(默认 `8rem`)。默认单列、标签独立成行;双列在容器不足 `36rem` 时收为单列,同行标签在容器不足 `28rem` 时改为上下排列。
|
|
306
|
-
|
|
307
|
-
`FormField.colSpan` 默认 `'auto'`:多行文本、文件/图片上传、TagInput 和多选 Combobox 自动占两列;`1` / `2` 显式覆盖。自定义宽控件标注 `data-form-wide`。标题、错误摘要、按钮及其他非 FormField 内容自动独占一行。字段可单独覆盖 `labelPosition` / `labelWidth`。
|
|
308
|
-
|
|
309
|
-
标签自动关联内部 UI 控件;已有控件 ID 或原生控件使用 `<FormField for="control-id">`。错误/提示通过 `aria-describedby` 关联,错误控件带 `aria-invalid`,只显示一份字段提示。`label` / `error` / `hint` 支持字符串或延迟翻译函数。
|
|
310
|
-
|
|
311
|
-
`Input`、`Textarea`、`Select` 和 `PasswordInput` 的原生校验使用内置中英日文提示;`validationMessage` 只覆盖失败提示,不让有效输入一直无效。应用通过 UI 的 `setGlobalLocale` / `createLocaleStore` 同步语言,已显示的校验错误即时更新。`Textarea` 支持 `minlength` / `maxlength`,`Select` 支持 `name`、必填校验和 FormData 序列化。
|
|
312
|
-
|
|
313
|
-
字段错误统一通过 Toast 展示。即使上一条提示已关闭或自动消失,再次提交相同的无效输入仍会重新提示;修正输入后清除过期通知。控件保留错误边框、`aria-invalid` 和读屏关联说明。
|
|
314
|
-
|
|
315
|
-
文本控件输入后失焦显示前端校验错误,修正输入时即时更新;未输入的空字段留到提交时校验,避免默认焦点离开时挤动操作。CRUD 新增/编辑同样在输入后失焦或提交时校验,支持自定义校验文案,关闭重开清空校验状态。`Select` 在焦点离开触发器和选项后校验。`PasswordInput.minLength` 同时约束长度并用于强度计算;省略时不限制登录密码长度,强度计算仍以 8 位为基准。
|
|
316
|
-
|
|
317
|
-
`UserProfile.fieldConstraints` 按字段接收 `required`、`minlength`、`maxlength`、`pattern` 和 `validationMessage`(`pattern` 用于单行输入),让应用的用户名等业务规则复用失焦校验;`validationMessage` 支持延迟翻译函数。
|
|
318
|
-
|
|
319
|
-
`UserProfile.onsubmit` 必须返回 `true` 确认保存成功,返回 `false` 时保留编辑器和草稿;抛错也保留草稿并通过统一 Toast 提示。取消编辑恢复 `user` 中已保存的值。
|
|
320
|
-
|
|
321
|
-
`CrudEditPanel.onsubmit` 只接收表单声明的可写字段,编辑时排除 `readonly` 字段;新建时仍可填写该字段。主键、关联展示值和审计时间不从整行记录自动回传,空值、`false` 和 `0` 保持原值。服务端继续使用严格 schema 校验。
|
|
322
|
-
|
|
323
|
-
`LoginForm`、`RegisterForm`、`ChangePasswordForm`、`ForgotPasswordForm`、`ResetPasswordForm`、`AuthPanel`、`UserProfile` 和 `FeedbackModal` 接受同一组布局参数。`CrudPage` 通过 `form` 传入;`CrudEditPanel` 直接接收。CRUD 字段支持 `colSpan`,`validation.message` 支持翻译函数;按钮与回车均先校验,修正后错误消失,客户端校验不能替代服务端校验。
|
|
324
|
-
|
|
325
|
-
```svelte
|
|
326
|
-
<!-- m、save、name、notes 为应用自己的翻译、提交回调和状态 -->
|
|
327
|
-
<Form columns={2} labelPosition="left" labelWidth="6rem" onsubmit={save}>
|
|
328
|
-
<FormField label={() => m.name()} required>
|
|
329
|
-
<Input name="name" bind:value={name} required />
|
|
330
|
-
</FormField>
|
|
331
|
-
<FormField label={() => m.notes()}>
|
|
332
|
-
<Textarea name="notes" bind:value={notes} />
|
|
333
|
-
</FormField>
|
|
334
|
-
<Button type="submit">{m.save()}</Button>
|
|
335
|
-
</Form>
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
##### 反馈
|
|
339
|
-
|
|
340
|
-
| 组件 | 描述 | 主要属性 |
|
|
341
|
-
| ---------------- | -------- | --------------------------------- |
|
|
342
|
-
| `Alert` | 警告框 | `variant`, `title`, `dismissible` |
|
|
343
|
-
| `ToastContainer` | 通知容器 | 全局放置,配合 `toast` 单例使用 |
|
|
344
|
-
|
|
345
|
-
##### 弹层
|
|
346
|
-
|
|
347
|
-
| 组件 | 描述 | 主要属性 |
|
|
348
|
-
| --------- | ------ | ------------------------------------------------------- |
|
|
349
|
-
| `Modal` | 模态框(语义标签、焦点约束与恢复) | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose` |
|
|
350
|
-
| `Drawer` | 抽屉 | `open`, `position`, `title`, `size`, `width`, `resizable`, `widthStorageKey` |
|
|
351
|
-
| `Confirm` | 确认框 | `open`, `title`, `message`, `variant`, `onconfirm` |
|
|
352
|
-
| `Popover` | 弹出层 | `open`, `position`, `trigger`, `offset`, `portal` |
|
|
353
|
-
|
|
354
|
-
`Popover` 默认挂载到 `body`。在 `click` 模式下按 Enter 或空格打开后,焦点进入面板,按 Escape 关闭并返回触发控件。需要内联挂载时使用 `portal={false}`。
|
|
355
|
-
|
|
356
|
-
在 Modal/Drawer 内,Popover 的 portal 内容参与所属弹窗的 Tab 与 Shift+Tab 顺序,保持在模态边界内;关闭后撤销登记并恢复触发位置。
|
|
357
|
-
|
|
358
|
-
##### 数据展示
|
|
359
|
-
|
|
360
|
-
| 组件 | 描述 | 主要属性 |
|
|
361
|
-
| ----------- | -------- | ---------------------------------------- |
|
|
362
|
-
| `Card` | 卡片容器 | `title`, `bordered`, `shadow`, `padding` |
|
|
363
|
-
| `JsonViewer` | JSON 树查看器 | `value`, `defaultExpandedDepth`, `maxScalarLength`, `showCopy`, `onCopy`;循环引用自动替换为占位符 |
|
|
364
|
-
| `DataTable` | 数据表格 | `data`, `columns`, `keyField`, `loading`, `sortKey`, `sortDir`, `onsort`,`cell` 单元格插槽、`onrowclick`(列 `sortable` 可排序) |
|
|
365
|
-
| `Accordion` | 手风琴 | `items: AccordionItem[]` |
|
|
366
|
-
| `Timeline` | 时间线 | `items: TimelineItem[]` |
|
|
367
|
-
|
|
368
|
-
##### Bits UI headless 交互
|
|
369
|
-
|
|
370
|
-
| 组件 | 描述 | 主要属性 |
|
|
371
|
-
| ------------ | --------------------------- | ----------------------------------------------------------- |
|
|
372
|
-
| `Combobox` | 可搜索下拉选择(单选/多选) | `options`, `value`, `multiple`, `placeholder`, `size` |
|
|
373
|
-
| `Calendar` | 独立日历 | `value: DateValue`, `minValue`, `maxValue` |
|
|
374
|
-
| `DatePicker` | 日期输入+弹出 | `value: DateValue`, `minValue`, `maxValue`, `error`, `size` |
|
|
375
|
-
|
|
376
|
-
> 日期值使用 `@internationalized/date` 的 `DateValue` / `CalendarDate` 类型。
|
|
377
|
-
|
|
378
|
-
##### 移动端 / 增强交互
|
|
379
|
-
|
|
380
|
-
| 组件 | 描述 | 主要属性 |
|
|
381
|
-
| ---------------- | ------------ | --------------------------------------------------- |
|
|
382
|
-
| `ActionSheet` | 底部操作面板 | `open`, `title`, `items`, `cancelText`, `onselect` |
|
|
383
|
-
| `AppBar` | 顶部导航栏 | `title`, `backHref`, `onback`, `fixed`, `safeArea` |
|
|
384
|
-
| `BottomNav` | 底部导航栏 | `items`, `active`, `centered`, `maxWidth` |
|
|
385
|
-
| `InfiniteScroll` | 无限滚动 | `loading`, `finished`, `threshold`, `onload` |
|
|
386
|
-
| `PullRefresh` | 下拉刷新 | `refreshing`, `threshold`, `onrefresh` |
|
|
387
|
-
| `SafeArea` | 安全区域容器 | `top`, `bottom`, `left`, `right` |
|
|
388
|
-
| `SwipeCell` | 滑动操作单元 | `leftActions`, `rightActions`, `threshold`, `onaction` |
|
|
389
|
-
|
|
390
|
-
##### 导航
|
|
391
|
-
|
|
392
|
-
| 组件 | 描述 | 主要属性 |
|
|
393
|
-
| ------------ | -------- | -------------------------------------------- |
|
|
394
|
-
| `Tabs` | 标签页 | `items`, `active`, `type`, `size`, `lazy`, `onactivate` |
|
|
395
|
-
| `Pagination` | 分页(统一 table 风格) | `page`, `total`, `pageSize`, `showTotal`, `showJumper`, `showSizeChanger`, `showPageInfo`, `showFirstLast` |
|
|
396
|
-
| `Breadcrumb` | 面包屑 | `items`, `separator` |
|
|
397
|
-
| `Steps` | 步骤条 | `items`, `current`, `direction`, `clickable` |
|
|
398
|
-
| `Dropdown` | 下拉菜单 | `items`, `trigger`, `triggerClass`, `position` |
|
|
399
|
-
| `Tooltip` | 提示 | `content`, `position`, `delay`, `portal`(裁剪容器内使用) |
|
|
400
|
-
|
|
401
|
-
`Dropdown` 的 `click` 和 `hover` 模式将菜单挂载到 `body`。在 `manual` 模式下,调用方通过 `class` 切换 `dropdown-open` 来控制内联菜单。
|
|
402
|
-
|
|
403
|
-
##### 状态占位
|
|
404
|
-
|
|
405
|
-
| 组件 | 描述 | 主要属性 |
|
|
406
|
-
| ---------- | ------ | ------------------------------------- |
|
|
407
|
-
| `Skeleton` | 骨架屏 | `variant`, `width`, `height`, `count` |
|
|
408
|
-
| `Empty` | 空状态 | `title`, `description`, `icon` |
|
|
409
|
-
| `Result` | 结果页 | `status`, `title`, `description` |
|
|
410
|
-
|
|
411
|
-
##### 页面级
|
|
412
|
-
|
|
413
|
-
| 组件 | 描述 | 主要属性 |
|
|
414
|
-
| ------------ | -------- | ------------------------------------------- |
|
|
415
|
-
| `PageHeader` | 页面头部 | `title`, `description`,支持 `actions` 插槽 |
|
|
416
|
-
|
|
417
|
-
#### 场景组件 Scenes
|
|
418
|
-
|
|
419
|
-
##### 代码工作区
|
|
420
|
-
|
|
421
|
-
用 `CodeWorkspace` 浏览只读源码。最小接入只需提供目录列表和文件内容。目录回调收到 `null` 时返回根节点。打开文件即创建标签,标签按文件 ID 和版本复用,切换时恢复近期查看过的文件的光标与滚动位置。
|
|
422
|
-
|
|
423
|
-
```svelte
|
|
424
|
-
<script lang="ts">
|
|
425
|
-
import type { CodeWorkspaceSource } from '@h-ai/ui/components/scenes/code/index'
|
|
426
|
-
import { CodeWorkspace } from '@h-ai/ui/components/scenes/code/index'
|
|
427
|
-
|
|
428
|
-
const source: CodeWorkspaceSource = {
|
|
429
|
-
listChildren: () => [{ kind: 'file', id: 'readme', name: 'README.md' }],
|
|
430
|
-
readFile: () => ({ text: '# Hello', language: 'markdown' }),
|
|
431
|
-
}
|
|
432
|
-
</script>
|
|
433
|
-
|
|
434
|
-
<CodeWorkspace {source} />
|
|
435
|
-
```
|
|
436
|
-
|
|
437
|
-
传入 `source.search` 启用文件名和工作区内容搜索,返回 `nextCursor` 时可继续加载。文件或目录上的 `markers` 展示风险和 Git 状态,`readFile` 返回的 `annotations` 可标记行或范围。传入 `inspector` 和 `selectionActions` snippet 连接右侧检查区及选区浮动操作。更多用法见[代码工作区接入](../../docs/usage/development/ui.md#代码工作区)。
|
|
438
|
-
|
|
439
|
-
Monaco 和同源 worker 由 Vite 在浏览器按需加载。主题默认跟随 Hai,可选预设或传自定义配色。同页 Monaco 编辑器共享主题。移动端和编辑器加载失败时提供纯文本浏览。
|
|
440
|
-
|
|
441
|
-
行前图标由 `annotationIcon` Snippet 自定义。悬停时优先显示标注的 `hoverText`,否则使用 `annotationHover` Snippet,支持交互组件。按 Enter 可进入浮层,按 Escape 关闭。
|
|
442
|
-
|
|
443
|
-
##### Guide 引导与帮助
|
|
444
|
-
|
|
445
|
-
| 组件 | 描述 | 主要属性 |
|
|
446
|
-
| --- | --- | --- |
|
|
447
|
-
| `GuideHost` | 首次邀请、页面导览与帮助弹窗宿主 | `guide`, `locale`, `scope`, `autoStart` |
|
|
448
|
-
| `HelpCenter` | 可独立使用的帮助中心 | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
|
|
449
|
-
|
|
450
|
-
##### App 应用级
|
|
451
|
-
|
|
452
|
-
| 组件 | 描述 | 主要属性 |
|
|
453
|
-
| ---------------- | ---------------- | ------------------ |
|
|
454
|
-
| `FeedbackModal` | 反馈模态框 | `open`, `onsubmit` |
|
|
455
|
-
| `FeedbackForm` | 独立反馈表单 | `attachments`, `evidenceSummary`, `onsubmit`, `onfileschange` |
|
|
456
|
-
| `FeedbackList` | 服务端分页、筛选与处理操作 | `data`, `query`, `permissions`, `onquerychange`, `onstatus` |
|
|
457
|
-
| `FeedbackDetail` | 诊断材料、处理历史与导出 | `report`, `evidence`, `attachments`, `history`, `webhook`, `onretry`, `onexport` |
|
|
458
|
-
| `FeedbackScreenshot` | 图片预览、圈选与遮挡 | `attachment`, `onannotate` |
|
|
459
|
-
| `SettingsModal` | 设置模态框 | `open`, `onclose` |
|
|
460
|
-
| `SettingsLayout` | 设置页布局(分区导航 + 内容区) | `title`, `description`, `sections`, `active`, `onselect` |
|
|
461
|
-
| `LanguageSwitch` | 语言切换 | 无需 Props |
|
|
462
|
-
| `ThemeColorPicker` | 主题色选择器 | `value`, `presets`, `onchange` |
|
|
463
|
-
| `ThemeSelector` | 完整主题选择面板 | 无需 Props |
|
|
464
|
-
| `ThemeToggle` | 明/暗主题切换 | 无需 Props |
|
|
465
|
-
|
|
466
|
-
将详情 jobs 中 type: webhook 的任务传给 FeedbackDetail.webhook,显示状态、尝试次数及安全错误码;onretry 负责调用受权 retry API。业务异步证据在“业务信息”页签分页查询 kind: business,压缩附件在“操作现场”下载。
|
|
467
|
-
|
|
468
|
-
反馈说明可为空;宿主先用 `@h-ai/feedback/client` 的 `prepare()` 固定现场,再打开弹窗。表单通过 `onfileschange` 准备主动附件、通过 `onannotate` 将标注烧录到图片;受理失败保留输入并可本地导出。列表展示说明或服务端事实摘要,以 `onquerychange` 取得分页数据;界面权限不代替服务端授权。完整接入与离线工具见 [feedback 模块](../feedback/README.md)。
|
|
469
|
-
|
|
470
|
-
##### IAM 身份认证
|
|
471
|
-
|
|
472
|
-
| 组件 | 描述 | 主要属性 |
|
|
473
|
-
| -------------------- | ---------- | ----------------------------------------------------- |
|
|
474
|
-
| `AuthPanel` | 配置驱动认证页 | `config`, `actions`, `loginHeader/loginFields/loginFooter`, `registerHeader/registerFields/registerFooter` |
|
|
475
|
-
| `AuthShell` | 认证页布局(居中卡片 / 左右分栏) | `variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `illustration`, `description`, `highlights` |
|
|
476
|
-
| `LoginForm` | 登录表单 | `loading`, `errors`, `showForgotPassword`, `onsubmit` |
|
|
477
|
-
| `RegisterForm` | 注册表单 | `loading`, `errors`, `fields`, `onsubmit` |
|
|
478
|
-
| `ForgotPasswordForm` | 忘记密码 | `mode`, `loading`, `errors`, `onsubmit` |
|
|
479
|
-
| `ResetPasswordForm` | 重置密码 | `loading`, `errors`, `showCode`, `onsubmit` |
|
|
480
|
-
| `ChangePasswordForm` | 修改密码 | `loading`, `errors`, `requireOldPassword`, `onsubmit` |
|
|
481
|
-
| `PasswordInput` | 密码输入框 | `value`, `showToggle`, `showStrength`, `minLength` |
|
|
482
|
-
| `ReauthenticationDialog` | 敏感操作再认证 | `open`, `loading`, `error`, `onsubmit`, `onclose` |
|
|
483
|
-
| `PermGuard` | 权限守卫 | `permissions`, `mode`, `fallback` |
|
|
484
|
-
| `UserProfile` | 用户资料 | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint`, `onsubmit` |
|
|
485
|
-
| `SessionRecoveryDialog` | 原地会话恢复 | `recovery`, `actions` |
|
|
486
|
-
| `SensitiveOperationsForm` | 权限敏感操作编辑 | `operations`, `onsubmit`, `ondone` |
|
|
487
|
-
|
|
488
|
-
##### Storage 存储
|
|
489
|
-
|
|
490
|
-
| 组件 | 描述 | 主要属性 |
|
|
491
|
-
| -------------- | -------- | -------------------------------------------------------- |
|
|
492
|
-
| `FileUpload` | 文件上传 | `accept`, `maxSize`, `maxFiles`, `multiple`, `uploadHandler` |
|
|
493
|
-
| `ImageUpload` | 图片上传 | `value`, `accept`, `maxSize`, `aspectRatio`, `uploadHandler` |
|
|
494
|
-
| `AvatarUpload` | 头像上传 | `value`, `size`, `maxSize`, `fallback`, `uploadHandler` |
|
|
495
|
-
| `FileList` | 文件列表 | `files`, `layout`, `showDelete`, `showDownload` |
|
|
496
|
-
|
|
497
|
-
上传组件不内置 presign、请求头或 PUT/POST 协议。应用层通过 `uploadHandler(file, { signal, onProgress })` 调用自己的 service,并返回 `{ url?, response? }`;图片和头像上传需要返回可展示的 `url`。未提供 handler 时,`FileUpload` 只选择文件,图片/头像组件只生成本地预览。
|
|
498
|
-
|
|
499
|
-
##### Crypto 加密展示
|
|
500
|
-
|
|
501
|
-
输入变化立即清空 `encryptedValue`,只有当前输入的成功结果会回填;清空、回调替换和卸载均使旧请求失效。失败显示内置错误提示且密文保持为空;表单应仅在当前密文非空时提交需要加密的输入。
|
|
502
|
-
|
|
503
|
-
`EncryptedInput` 必须由调用方通过 `onencrypt` 接入真实加密服务,`algorithm` 仅用于说明该服务所用算法。未配置回调时组件明确提示不可用,不生成密文;没有 Base64 等编码回退。
|
|
504
|
-
|
|
505
|
-
| 组件 | 描述 | 主要属性 |
|
|
506
|
-
| ------------------ | -------- | ------------------------------------------------------- |
|
|
507
|
-
| `EncryptedInput` | 加密输入 | `value`, `encryptedValue`, `algorithm`, `showEncrypted` |
|
|
508
|
-
| `HashDisplay` | 哈希展示 | `value`, `algorithm`, `copyable`, `truncate` |
|
|
509
|
-
| `SignatureDisplay` | 签名展示 | `signature`, `publicKey`, `algorithm`, `verified` |
|
|
510
|
-
|
|
511
|
-
默认算法与 `@h-ai/crypto` 对齐:加密输入使用 `SM4`,哈希展示使用 `SM3`,签名展示使用 `SM2`。
|
|
512
|
-
|
|
513
|
-
##### AI 文档与表格
|
|
514
|
-
|
|
515
|
-
| 组件 | 描述 | 主要属性 / 能力 |
|
|
516
|
-
| ------------------------ | ---------------- | ---------------- |
|
|
517
|
-
| `MarkdownRenderer` | Markdown 渲染器 | `content`, `fontSize`, `allowHtmlTags`, `showCopyButton`, `enableHighlight` |
|
|
518
|
-
| `AiDocumentDownloadMenu` | 文档下载菜单 | `actions`, `ondownload` |
|
|
519
|
-
| `AiDocumentEditor` | AI 文档编辑器 | `content`, `fontSize`, `allowHtmlTags`, `showRunButton`, `showCodePreviewToggle`, `allowUnsafeCodePreview` |
|
|
520
|
-
| `AiTableEditor` | AI 表格编辑器 | `columns`, `rows`, `editable`, `ondownload` |
|
|
521
|
-
|
|
522
|
-
> `AiDocumentEditor` 默认只允许 Markdown 内置预览。HTML / JS / CSS 等高风险预览需要显式设置 `allowUnsafeCodePreview`,或通过 `oncoderun` 返回受控的预览结果。
|
|
523
|
-
>
|
|
524
|
-
> Mermaid 图表开箱即用:文档(`sourceKind='document'`)里的 ```` ```mermaid ```` 代码块在阅读态自动渲染为图表;code 模式(`sourceKind='code'` + `showCodePreviewToggle`)下可在「代码 / 预览」间切换。Mermaid 以 `securityLevel: 'strict'` 渲染为消毒后的 SVG,无需开启 `allowUnsafeCodePreview`。
|
|
525
|
-
>
|
|
526
|
-
> `MarkdownRenderer` 与 `AiDocumentEditor` 还支持展示层配置:
|
|
527
|
-
> - `fontSize` 支持 `number`(按 px 解释)或任意 CSS 长度字符串(如 `1.125rem`)
|
|
528
|
-
> - `allowHtmlTags` 默认关闭;开启后会按安全白名单解析 `<b>` / `<i>` / `<u>` / `<mark>` 等 HTML 标签,危险标签与属性仍会被消毒
|
|
529
|
-
> - 安全 HTML 文本中的引号、比较符和 `&` 实体只保留一层含义,配置代码不会显示为实体编号;编码后的标签保持文字,不会重新作为标签执行。
|
|
530
|
-
> - HTML 中的 `<pre><code class="language-yaml">` 等代码块也会安全重建高亮和复制按钮,不保留输入的任意样式或事件。支持 YAML、TypeScript、Shell、PowerShell、dotenv、Nginx、Dockerfile 和 Svelte 等常用语言。
|
|
531
|
-
> - 原始 `<img>` 可保留 `width` / `height`(1–99999 的正整数像素值),用于在图片延迟加载前预留空间,减少文档布局和锚点位置跳变;百分比、负数、小数、事件及任意 `style` 不保留。
|
|
532
|
-
|
|
533
|
-
```svelte
|
|
534
|
-
<MarkdownRenderer content={markdown} fontSize='1.125rem' allowHtmlTags />
|
|
535
|
-
|
|
536
|
-
<AiDocumentEditor
|
|
537
|
-
title='方案文档'
|
|
538
|
-
content={documentMarkdown}
|
|
539
|
-
fontSize={18}
|
|
540
|
-
allowHtmlTags
|
|
541
|
-
showToolbar
|
|
542
|
-
showOutline={false}
|
|
543
|
-
/>
|
|
544
|
-
```
|
|
545
|
-
|
|
546
|
-
##### Charts 图表
|
|
547
|
-
|
|
548
|
-
轻量看板由 `MetricCard`(数值、单位、百分比变化)、`ReportCard`(标题、操作、内容、加载/空态)和 `DashboardGrid`(按容器宽度收拢为一/二/多列)组成。指标卡自身不加载图形引擎;`trend={12.8}` 表示 +12.8%,`trendTone` 独立表达业务好坏,下降也可以是 success。缺失或非有限数显示“—”,零值正常显示。
|
|
549
|
-
|
|
550
|
-
`Chart.preset` 支持:`grouped-bar`、`stacked-bar`、`stacked-area`、`donut`、`sparkline`。预设补默认图形类型和配置,显式 `type` 及原生属性优先;例如 `innerRadius={0.8}` 覆盖环形默认半径。其他 LayerChart 属性与 snippet 继续透传。
|
|
551
|
-
|
|
552
|
-
按类型动态加载渲染器;SSR 保留高度并显示加载占位,浏览器挂载后绘制。加载态和空数据不加载渲染器。只需要看板组件时优先使用公开 charts 入口。高级图形通过 `ReportCard` 的 children 使用原生 LayerChart,不受 Chart 的五种类型限制;应用需显式依赖兼容的 `layerchart`,按需使用 `layerchart/svg`、`layerchart/hierarchy` 等实际公开入口。用动态组件加载控制高级图形的加载时机,见 admin 的原生 ArcChart 示例。
|
|
553
|
-
|
|
554
|
-
```svelte
|
|
555
|
-
<script lang="ts">
|
|
556
|
-
import { Chart, DashboardGrid, MetricCard, ReportCard } from '@h-ai/ui/components/scenes/charts/index'
|
|
557
|
-
const data = [{ month: 'Jan', revenue: 42, cost: 24 }, { month: 'Feb', revenue: 58, cost: 31 }]
|
|
558
|
-
</script>
|
|
559
|
-
|
|
560
|
-
<DashboardGrid label="Key metrics" columns={4}>
|
|
561
|
-
<MetricCard title="Revenue" value="128,430" unit="CNY" trend={12.8} trendTone="success" trendLabel="vs previous month" />
|
|
562
|
-
</DashboardGrid>
|
|
563
|
-
<ReportCard title="Revenue and cost">
|
|
564
|
-
<Chart preset="grouped-bar" {data} x="month" y={['revenue', 'cost']} />
|
|
565
|
-
</ReportCard>
|
|
566
|
-
```
|
|
567
|
-
|
|
568
|
-
`Chart type='line'` 默认透传 LayerChart 原生折线图;需要监控看板常见的“分段线 + 圆点 + 最近点 hover + 竖向参考线”时,使用 `lineVariant='segmented-point'`:
|
|
569
|
-
|
|
570
|
-
```svelte
|
|
571
|
-
<Chart
|
|
572
|
-
type='line'
|
|
573
|
-
data={trendData}
|
|
574
|
-
x='label'
|
|
575
|
-
y={['rateLimit', 'circuitBreak']}
|
|
576
|
-
series={trendSeries}
|
|
577
|
-
lineVariant='segmented-point'
|
|
578
|
-
tooltipMode='nearest'
|
|
579
|
-
showCrosshair
|
|
580
|
-
legend
|
|
581
|
-
grid
|
|
582
|
-
/>
|
|
583
|
-
```
|
|
584
|
-
|
|
585
|
-
##### CRUD 场景
|
|
586
|
-
|
|
587
|
-
| 组件 | 描述 | 主要属性 / 能力 |
|
|
588
|
-
| -------------------- | ------------ | ---------------- |
|
|
589
|
-
| `CrudPage` | CRUD 主页面 | `crud`, `data`, `permissions`, `form`, `pagination`, `density`, `detailColumns`, `showHeader`, `toolbarLeading`, `toolbarActions`, `card`, `tableCell`, `onrowclick`, `sortableColumns`, `nav`, `loading`, `loaded`, `error`, `onRetry`, `keepPreviousData` |
|
|
590
|
-
| `CrudFilterBar` | 过滤工具栏(搜索 + 多类型过滤 + 重置) | `filterFields`, `searchValue`, `onsearch`, `onfilterchange`, `onreset` |
|
|
591
|
-
| `CrudDetailPanel` | 详情面板(抽屉/弹窗) | `open`, `item`, `fields`, `variant`, `drawerWidth`, `modalSize` |
|
|
592
|
-
| `CrudEditPanel` | 编辑面板(抽屉/弹窗) | `open`, `fields`, `variant`, `drawerWidth`, `modalSize`, `onsubmit` |
|
|
593
|
-
| `CrudDeleteConfirm` | 删除确认框 | `open`, `loading`, `onconfirm` |
|
|
594
|
-
|
|
595
|
-
> `CrudPage`、`FeedbackList` 统一使用卡片内的查询栏、独立滚动表格和底部分页。搜索、查询、重置始终可见,扩展筛选默认收起且保留输入;点击查询或 Enter 一次提交全部条件,修改字段不自动查询。翻页和排序沿用已提交条件;重置清空搜索、筛选和排序并回到第一页。排序按钮只在支持排序的列头显示,`sortableColumns` 应只列出后端支持的字段。`detailColumns` 配置详情入口,`toolbarLeading` / `toolbarActions` 配置卡片上方的说明和业务操作;`card` 与 `tableCell` 保留自定义内容。过滤字段支持 `select`、`boolean`、`number`、`date`、`date-range`、`text`。 未提供 `sortableColumns` 时不显示排序按钮,避免把当前页排序当成服务端排序。
|
|
596
|
-
>
|
|
597
|
-
> 页面根容器会占满父级可用高度。表格无论是否有数据都会撑满剩余空间,仅数据区域滚动;表头固定在数据区顶部,分页栏固定在列表卡片底部。
|
|
598
|
-
> 宿主从视口外壳到内容区须逐层传递剩余高度(例如 `flex flex-1 min-h-0 flex-col`),中间包装层不能仅按内容自动计算高度。空表、少量数据和长列表均沿用底部分页。
|
|
599
|
-
>
|
|
600
|
-
> 表格列会优先压缩到 7rem 并截断超长文本;列总宽度仍超过容器时才显示横向滚动条。操作列固定在右侧,横向滚动时保持可见。
|
|
601
|
-
|
|
602
|
-
##### 错误页场景
|
|
603
|
-
|
|
604
|
-
| 组件 | 描述 | 主要属性 / 能力 |
|
|
605
|
-
| ----------- | ------------ | ---------------- |
|
|
606
|
-
| `ErrorPage` | 通用错误页(内置 401/403/404/500/503 预设) | `status`, `code`, `title`, `description`, `homeUrl`, `onhome`, `onback` |
|
|
607
|
-
|
|
608
|
-
> `CrudPage` 通过 `form` 配置新建/编辑的展示形式: 未提供 `sortableColumns` 时不显示排序按钮,避免把当前页排序当成服务端排序。
|
|
609
|
-
>
|
|
610
|
-
> - `form.variant`:`'drawer'`(抽屉,默认)或 `'modal'`(弹出窗口)。
|
|
611
|
-
> - 抽屉:`form.drawerSize` 选预设尺寸,`form.drawerWidth` 传任意 CSS 宽度(优先级更高);默认可拖动左侧边缘调整宽度,并按资源记忆,`form.drawerResizable=false` 可关闭。
|
|
612
|
-
> - 弹窗:`form.modalSize` 选预设尺寸,`form.modalWidth` / `form.modalHeight` 传任意 CSS 尺寸。
|
|
613
|
-
>
|
|
614
|
-
> `pagination` 配置分页栏(始终显示):`showSizeChanger`、`pageSizeOptions`、`showJumper`、`showTotal` 默认开启;紧凑视图可用 `showPageInfo` 关闭页码文案、`showFirstLast` 关闭首页 / 末页按钮。
|
|
615
|
-
>
|
|
616
|
-
> `density` 配置列表密度:`'normal'`(默认)或 `'compact'`(紧凑)。它只影响列表行、行内操作、分页与创建/编辑/详情表单元素,不影响页头与筛选栏。
|
|
617
|
-
>
|
|
618
|
-
> `CrudPage` 受控加载态:`loading` / `loaded` / `error` / `onRetry` / `keepPreviousData`。仅当 `loaded && total === 0` 时才展示空状态(避免首次请求未回时误显“暂无数据”);首次查询展示“查询中”;失败且无可用数据时展示错误与重试(`onRetry`);`keepPreviousData`(默认 true)在刷新/失败时保留旧数据。 未提供 `sortableColumns` 时不显示排序按钮,避免把当前页排序当成服务端排序。
|
|
619
|
-
>
|
|
620
|
-
> 纯客户端(无 SvelteKit SSR)可用框架级 `defineCrud` + `createCrudController` 托管 `data` 与 `nav`,自带 latest-wins(seq + AbortSignal)、失败保留旧数据、惰性加载与并发去重:
|
|
621
|
-
>
|
|
622
|
-
> ```svelte
|
|
623
|
-
> <script>
|
|
624
|
-
> import { CrudPage, createCrudController, defineCrud } from '@h-ai/ui'
|
|
625
|
-
> const crud = defineCrud({ name: 'user', label: '用户', fields: [/* ... */], api: { list: params => listUsers(params) } })
|
|
626
|
-
> const c = createCrudController(crud) // 惰性页签传 { autoLoad: false },首次激活时 c.load()
|
|
627
|
-
> </script>
|
|
628
|
-
> <CrudPage {crud} data={c.data} nav={c.nav} loading={c.loading} loaded={c.loaded} error={c.error} onRetry={c.reload} />
|
|
629
|
-
> ```
|
|
630
|
-
>
|
|
631
|
-
> `Tabs` 支持惰性页签:`lazy` 开启后未激活过的页签内容不渲染(`children` 提供 `isActivated(key)` 判断),`onactivate(key)` 在页签首次激活时触发一次,适合配合 `createCrudController({ autoLoad: false })` 在首次可见时才加载。
|
|
632
|
-
|
|
633
|
-
### 使用示例
|
|
634
|
-
|
|
635
|
-
#### Toast 通知
|
|
636
|
-
|
|
637
|
-
```svelte
|
|
638
|
-
<script>
|
|
639
|
-
import { toast, ToastContainer } from '@h-ai/ui'
|
|
640
|
-
|
|
641
|
-
function notify() {
|
|
642
|
-
toast.success('操作成功')
|
|
643
|
-
toast.error('操作失败')
|
|
644
|
-
toast.warning('请注意')
|
|
645
|
-
toast.info('提示信息', 5000) // 自定义持续时间
|
|
646
|
-
}
|
|
647
|
-
</script>
|
|
648
|
-
|
|
649
|
-
<button onclick={notify}>通知</button>
|
|
650
|
-
<ToastContainer />
|
|
651
|
-
```
|
|
652
|
-
|
|
653
|
-
默认在右下角浮动显示,不占页面布局;由 UI 模块统一使用提示蓝、成功绿、警告黄、错误红等主题语义色,以浅色底、细色边和对应图标区分,并保留轻阴影,支持手工关闭。多个提示进入同一 FIFO 队列,逐条展示,每条从展示时开始计时(默认 3 秒,`duration: 0` 等待手工关闭)。根布局只挂载一次 `<ToastContainer />`。用 `toast.add({ message: m.saved(), variant: 'success', position: 'bottom-center' })` 指定方位;`m.saved()` 是应用自身的翻译函数。可选 `bottom-right`(默认)、`top-right`、`bottom-center`、`top-center`、`bottom-left`、`top-left`。登录、改密、保存、删除、上传等操作成功或失败均使用 Toast;所有警告和错误(包括字段校验)统一由 ToastContainer 展示。字段保留错误标记与读屏关联,持续业务状态和恢复操作留在原位;`Alert` 只支持 info/success。
|
|
654
|
-
|
|
655
|
-
按 F8 聚焦当前提示,再按 F8 返回原控件;提示获得焦点后,Escape 关闭可关闭的提示并恢复焦点,Enter 激活关闭按钮。Modal 内同样可用,关闭提示不会关闭弹窗。不可关闭的提示仍可聚焦阅读并返回;自动消失也会恢复焦点。
|
|
656
|
-
|
|
657
|
-
> 已内置 `notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning`,无需应用自建工具:`notifyError(err, fallback?)` 隐藏普通 `Error` 的内部原文,显示兜底文案并保留 traceId;字符串参数必须是已本地化的安全文案,不能传入未知 `err.message`。默认成功 3s / 失败 5s。
|
|
658
|
-
|
|
659
|
-
需要把 HaiResult 失败交给使用 Promise 的组件时,使用 `throw new Error(result.error.message, { cause: result.error })` 保留完整错误。`errorMessage` / `notifyError` 会从 Error.cause 链读取安全的业务原因和 traceId;5xx 和未知异常仍使用安全兜底。异常链有深度限制并防止循环,不能直接显示底层异常文本。
|
|
660
|
-
|
|
661
|
-
响应式组件可在初始化时调用 `useToastFeedback(() => error)`,传入已完成安全映射和本地化的操作消息;队列中相同类型、相同消息合并,通知独立于来源组件生命周期。来源消息更新或清空时替换或移除该来源的旧通知;重复比较同时包含 traceId。`message` 入口也共用此队列、样式和关闭行为;`MessageContainer` 复用 `ToastContainer`,根布局只选择一个容器。
|
|
662
|
-
|
|
663
|
-
状态层可从轻量入口 `@h-ai/ui/toast` 导入 `toast`、`useToastFeedback`、`notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning` 和 `errorMessage`,不会连带加载组件及引导 CSS;`ToastContainer` 仍从组件入口导入并在根布局挂载。
|
|
664
|
-
|
|
665
|
-
默认不显示 traceId。可以传 `toast.add({ message: m.retry(), variant: 'warning', traceId })`;已有安全文案中的 `(traceId: …)` 也会自动分离。小图标展开“问题追踪编号”、复制按钮及联系客户支持或开发人员时提供编号的说明。复制失败时可手动选择编号。悬停、聚焦或展开时暂停计时,结束后继续剩余时间;也可调用 `toast.pause(id)` / `toast.resume(id)`。warning/error 使用 Toast;字段的可见错误文案也由 Toast 统一展示,保留 aria-invalid、读屏描述和原位恢复操作。
|
|
666
|
-
|
|
667
|
-
#### 指定提示方位
|
|
668
|
-
|
|
669
|
-
下例 `m.saved()` 由应用自己的 i18n 提供;不同方位也共用同一个队列,按顺序展示。
|
|
670
|
-
|
|
671
|
-
```ts
|
|
672
|
-
import { toast } from '@h-ai/ui/toast'
|
|
673
|
-
|
|
674
|
-
toast.add({ message: m.saved(), variant: 'success', position: 'top-right' })
|
|
675
|
-
toast.add({ message: m.saved(), position: 'bottom-center' })
|
|
676
|
-
```
|
|
677
|
-
|
|
678
|
-
#### 典型 CRUD 页面
|
|
679
|
-
|
|
680
|
-
```svelte
|
|
681
|
-
<script>
|
|
682
|
-
import {
|
|
683
|
-
PageHeader, Card, DataTable, Button,
|
|
684
|
-
Modal, Input, Select, toast, ToastContainer,
|
|
685
|
-
} from '@h-ai/ui'
|
|
686
|
-
|
|
687
|
-
let items = $state([])
|
|
688
|
-
let showModal = $state(false)
|
|
689
|
-
let loading = $state(false)
|
|
690
|
-
let formData = $state({ name: '', type: '' })
|
|
691
|
-
|
|
692
|
-
const columns = [
|
|
693
|
-
{ key: 'name', label: '名称' },
|
|
694
|
-
{ key: 'type', label: '类型' },
|
|
695
|
-
{ key: 'createdAt', label: '创建时间' },
|
|
696
|
-
]
|
|
697
|
-
|
|
698
|
-
async function handleCreate() {
|
|
699
|
-
loading = true
|
|
700
|
-
try {
|
|
701
|
-
await fetch('/api/items', { method: 'POST', body: JSON.stringify(formData) })
|
|
702
|
-
showModal = false
|
|
703
|
-
toast.success('创建成功')
|
|
704
|
-
} finally {
|
|
705
|
-
loading = false
|
|
706
|
-
}
|
|
707
|
-
}
|
|
708
|
-
</script>
|
|
709
|
-
|
|
710
|
-
<PageHeader title="项目管理" description="管理所有项目">
|
|
711
|
-
{#snippet actions()}
|
|
712
|
-
<Button onclick={() => showModal = true}>新建</Button>
|
|
713
|
-
{/snippet}
|
|
714
|
-
</PageHeader>
|
|
715
|
-
|
|
716
|
-
<Card>
|
|
717
|
-
<DataTable data={items} {columns} keyField="id" {loading}>
|
|
718
|
-
{#snippet actions(item)}
|
|
719
|
-
<Button size="xs">编辑</Button>
|
|
720
|
-
<Button size="xs" variant="error">删除</Button>
|
|
721
|
-
{/snippet}
|
|
722
|
-
</DataTable>
|
|
723
|
-
</Card>
|
|
724
|
-
|
|
725
|
-
<Modal bind:open={showModal} title="新建项目">
|
|
726
|
-
<form onsubmit={(e) => { e.preventDefault(); handleCreate() }} class="space-y-4">
|
|
727
|
-
<Input placeholder="名称" bind:value={formData.name} required />
|
|
728
|
-
<Select
|
|
729
|
-
placeholder="选择类型"
|
|
730
|
-
bind:value={formData.type}
|
|
731
|
-
options={[
|
|
732
|
-
{ value: 'a', label: '类型 A' },
|
|
733
|
-
{ value: 'b', label: '类型 B' },
|
|
734
|
-
]}
|
|
735
|
-
/>
|
|
736
|
-
</form>
|
|
737
|
-
{#snippet footer()}
|
|
738
|
-
<Button variant="ghost" onclick={() => showModal = false}>取消</Button>
|
|
739
|
-
<Button {loading} onclick={handleCreate}>创建</Button>
|
|
740
|
-
{/snippet}
|
|
741
|
-
</Modal>
|
|
742
|
-
|
|
743
|
-
<ToastContainer />
|
|
744
|
-
```
|
|
745
|
-
|
|
746
|
-
`Modal` 不传 `title` / `header` 时会保留右上角关闭按钮,但不额外渲染整条头部。需要调整圆角时可传 `radius="1.4rem"`,内部下拉等浮层需要越界显示时可传 `bodyOverflow="visible"`。
|
|
747
|
-
|
|
748
|
-
#### 声明式 CRUD 页面(CrudPage)
|
|
749
|
-
|
|
750
|
-
```svelte
|
|
751
|
-
<script lang='ts'>
|
|
752
|
-
import { createSvelteKitNavAdapter } from '@h-ai/kit/client'
|
|
753
|
-
import { CrudPage } from '@h-ai/ui'
|
|
754
|
-
|
|
755
|
-
let { data } = $props()
|
|
756
|
-
const nav = createSvelteKitNavAdapter()
|
|
757
|
-
</script>
|
|
758
|
-
|
|
759
|
-
<CrudPage
|
|
760
|
-
crud={roleCrud}
|
|
761
|
-
{data}
|
|
762
|
-
permissions={{ create: true, update: true, delete: true }}
|
|
763
|
-
form={{ variant: 'modal', modalSize: '3xl', columns: 2, labelPosition: 'top' }}
|
|
764
|
-
pagination={{ showSizeChanger: true, showJumper: true, pageSizeOptions: [10, 20, 50] }}
|
|
765
|
-
density='compact'
|
|
766
|
-
detailColumns={['name']}
|
|
767
|
-
sortableColumns={[{ key: 'createdAt', label: '创建时间' }]}
|
|
768
|
-
{nav}
|
|
769
|
-
/>
|
|
770
|
-
```
|
|
771
|
-
|
|
772
|
-
> 抽屉形式可改用 `form={{ variant: 'drawer', drawerWidth: '40rem' }}`;用户拖动后的宽度会覆盖初始宽度并按资源记忆。
|
|
773
|
-
|
|
774
|
-
#### 登录页面
|
|
775
|
-
|
|
776
|
-
```svelte
|
|
777
|
-
<script>
|
|
778
|
-
import { LoginForm } from '@h-ai/ui'
|
|
779
|
-
|
|
780
|
-
let loading = $state(false)
|
|
781
|
-
let errors = $state({})
|
|
782
|
-
|
|
783
|
-
async function handleLogin(data) {
|
|
784
|
-
loading = true
|
|
785
|
-
errors = {}
|
|
786
|
-
try {
|
|
787
|
-
await fetch('/api/login', { method: 'POST', body: JSON.stringify(data) })
|
|
788
|
-
} catch {
|
|
789
|
-
errors = { general: '登录失败,请检查用户名和密码' }
|
|
790
|
-
} finally {
|
|
791
|
-
loading = false
|
|
792
|
-
}
|
|
793
|
-
}
|
|
794
|
-
</script>
|
|
795
|
-
|
|
796
|
-
<!-- 场景组件内置 i18n,无需传入翻译 props -->
|
|
797
|
-
<LoginForm {loading} {errors} onsubmit={handleLogin} showRegisterLink />
|
|
798
|
-
```
|
|
799
|
-
|
|
800
|
-
#### PasswordInput 受控模式
|
|
801
|
-
|
|
802
|
-
```svelte
|
|
803
|
-
<script>
|
|
804
|
-
import { PasswordInput } from '@h-ai/ui'
|
|
805
|
-
|
|
806
|
-
let password = $state('')
|
|
807
|
-
</script>
|
|
808
|
-
|
|
809
|
-
<PasswordInput
|
|
810
|
-
value={password}
|
|
811
|
-
oninput={(e) => { password = e.currentTarget.value }}
|
|
812
|
-
placeholder="请输入密码"
|
|
813
|
-
showStrength
|
|
814
|
-
/>
|
|
815
|
-
```
|
|
816
|
-
|
|
817
|
-
### 反馈现场与交付检查
|
|
818
|
-
|
|
819
|
-
反馈的 `evidence` 显示实际已脱敏材料;`oncapture(id?)` 支持隐藏弹窗后跨页补图或替换。接入 `onfileschange` 后提供浏览器原生无声短录屏,停止后作为 WebM/MP4 附件预览或删除(最多 60 秒 / 5 MiB,录屏不自动脱敏)。`FeedbackDetail.onreplay` 按需返回完整页面事件,在“页面回放”播放和定位;日志/环境仍分页读取。
|
|
820
|
-
|
|
821
|
-
反馈表单的材料内容独立滚动,底部按钮始终可见,展开内容不会穿过操作栏。`FeedbackList` 保留无障碍名称,页面标题由宿主显示,避免管理页重复标题。
|
|
822
|
-
|
|
823
|
-
### 样式依赖
|
|
824
|
-
|
|
825
|
-
组件基于 TailwindCSS v4 + DaisyUI。应用层 `app.css` 需要以下配置:
|
|
826
|
-
|
|
827
|
-
```css
|
|
828
|
-
/* 必须 */
|
|
829
|
-
@import 'tailwindcss';
|
|
830
|
-
@import '@h-ai/ui/styles/global.css'; /* 基础重置、滚动条、焦点样式 */
|
|
831
|
-
@import '@h-ai/ui/styles/theme.css'; /* Tailwind v4 @theme Token(品牌色/阴影/动效) */
|
|
832
|
-
@source "../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
|
|
833
|
-
@source "../../../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
|
|
834
|
-
|
|
835
|
-
/* 移动端项目追加(可选) */
|
|
836
|
-
@import '@h-ai/ui/styles/design-tokens.css'; /* CSS 自定义属性 */
|
|
837
|
-
@import '@h-ai/ui/styles/mobile.css'; /* 安全区域/触摸优化 */
|
|
838
|
-
|
|
839
|
-
/* DaisyUI 主题 */
|
|
840
|
-
@plugin "daisyui" {
|
|
841
|
-
themes: light --default, dark --prefersdark, cupcake, emerald, corporate, nord, dracula, night;
|
|
842
|
-
}
|
|
843
|
-
```
|
|
844
|
-
|
|
845
|
-
- `global.css`:基础 HTML 重置、滚动条美化、表单焦点环
|
|
846
|
-
- `theme.css`:Tailwind v4 `@theme` 块,包含品牌色、阴影层级、动效曲线、字体特性
|
|
847
|
-
- `design-tokens.css`:CSS 自定义属性(间距/圆角/z-index/过渡),移动端推荐
|
|
848
|
-
- `mobile.css`:安全区域 padding、momentum 滚动、虚拟键盘适配、移动端 App 壳布局工具(`hai-mobile-viewport` / `hai-mobile-shell` / `hai-mobile-main`)
|
|
849
|
-
|
|
850
|
-
移动端页面推荐让 `BottomNav` 与页面壳宽度一致,避免桌面预览时底栏横跨整个视口:
|
|
851
|
-
|
|
852
|
-
```svelte
|
|
853
|
-
<div class="hai-mobile-viewport">
|
|
854
|
-
<div class="hai-mobile-shell max-w-lg">
|
|
855
|
-
<AppBar title="Home" fixed={false} safeArea />
|
|
856
|
-
<main class="hai-mobile-main">...</main>
|
|
857
|
-
<BottomNav items={items} active="home" centered maxWidth="lg" safeArea />
|
|
858
|
-
</div>
|
|
859
|
-
</div>
|
|
860
|
-
```
|
|
861
|
-
|
|
862
|
-
`BottomNav` 的导航按钮与 `ThemeSelector` 的主题按钮在客户端挂载后启用,确保点击时事件已绑定。
|
|
863
|
-
|
|
864
|
-
#### 图标
|
|
865
|
-
|
|
866
|
-
组件使用 Iconify (Tabler Icons):
|
|
867
|
-
|
|
868
|
-
```bash
|
|
869
|
-
npm install -D @iconify/tailwind4 @iconify-json/tabler
|
|
870
|
-
```
|
|
871
|
-
|
|
872
|
-
```css
|
|
873
|
-
/* app.css 中追加 */
|
|
874
|
-
@plugin "@iconify/tailwind4" {
|
|
875
|
-
prefixes: tabler;
|
|
876
|
-
}
|
|
877
|
-
```
|
|
878
|
-
|
|
879
|
-
#### 主题切换
|
|
880
|
-
|
|
881
|
-
使用内置的主题工具函数管理 15 个精选 DaisyUI 主题、高对比、直角商务及护眼主题:
|
|
882
|
-
|
|
883
|
-
`high-contrast` 随共享 theme.css 提供:黑底亮字、清晰边框/焦点、增强次要文字及占位符对比度。ThemeSelector 提供三语名称;示例与默认生成工程可选择,fullstack 的显式 themes 列表仍由宿主决定。配色按普通文字 7:1 的目标验收,不代表任意业务内容已通过整站无障碍认证。
|
|
884
|
-
|
|
885
|
-
`eye-care` 随共享 theme.css 提供暖绿色背景、深色正文、可读占位符与清晰焦点。主题选择器显示“护眼”,示例及默认模板可直接选择,刷新后保留偏好;现有默认主题及 fullstack 显式 themes 白名单不变。
|
|
886
|
-
|
|
887
|
-
`formal` 提供直角的商务外观,按钮、输入框、卡片与弹窗不使用装饰性圆角;主题选择器提供三语名称,示例和默认模板可选择。Button 的 submitHint 仅在 type=submit 时显示原生 Enter 提示,不绑定全局快捷键;LoginForm 默认在桌面首次就绪且页面无焦点时聚焦标识,autoFocus=false 可关闭。筛选 Enter 即时查询且忽略输入法确认;主题菜单支持方向键/Home/End、Enter/Space 及 Esc 恢复焦点;确认框默认聚焦取消,Esc 同步取消状态。
|
|
888
|
-
|
|
889
|
-
```ts
|
|
890
|
-
import {
|
|
891
|
-
applyTheme, // 应用主题(自动持久化到 localStorage)
|
|
892
|
-
createThemeBootstrapScript, // 生成可注入 app.html 的首屏主题恢复脚本
|
|
893
|
-
getCurrentTheme, // 获取当前主题
|
|
894
|
-
getSavedTheme, // 读取安全缓存,可传入应用配置的默认主题
|
|
895
|
-
getThemeInitScript, // 返回可注入到 HTML shell 的防闪烁脚本文本
|
|
896
|
-
isDarkTheme, // 检查是否暗色主题
|
|
897
|
-
normalizeHexColor, // 归一化 #RGB / #RRGGBB 主题色
|
|
898
|
-
normalizeThemeId, // 校验主题 ID 并自动回退
|
|
899
|
-
THEME_GROUPS, // 按亮色/暗色分组
|
|
900
|
-
THEMES, // ThemeInfo[] — 18 个主题元数据
|
|
901
|
-
} from '@h-ai/ui/theme'
|
|
902
|
-
```
|
|
903
|
-
|
|
904
|
-
简单场景可以直接使用 `getThemeInitScript()`;如果应用有自定义存储 key、主题色 CSS 变量或语言偏好,推荐在服务端通过 `createThemeBootstrapScript()` 生成脚本后再注入 `app.html`。
|
|
905
|
-
|
|
906
|
-
在 SvelteKit 的 `app.html` 中,可以先放一个占位符:
|
|
907
|
-
|
|
908
|
-
```html
|
|
909
|
-
<head>
|
|
910
|
-
<script>%theme_bootstrap%</script>
|
|
911
|
-
</head>
|
|
912
|
-
```
|
|
913
|
-
|
|
914
|
-
然后在 `hooks.server.ts` 里注入:
|
|
915
|
-
|
|
916
|
-
```ts
|
|
917
|
-
import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui/theme'
|
|
918
|
-
|
|
919
|
-
const themeBootstrapScript = createThemeBootstrapScript({
|
|
920
|
-
storageKey: 'hai-demo-preferences',
|
|
921
|
-
defaultThemeColor: '#5765f0',
|
|
922
|
-
colorCssVar: DEFAULT_THEME_COLOR_CSS_VAR,
|
|
923
|
-
})
|
|
924
|
-
|
|
925
|
-
transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstrapScript)
|
|
926
|
-
```
|
|
927
|
-
|
|
928
|
-
### 国际化 (i18n)
|
|
929
|
-
|
|
930
|
-
@h-ai/ui 采用**组件内置翻译**模式:
|
|
931
|
-
|
|
932
|
-
- 场景组件(`scenes/`)内置中英日文翻译(zh-CN / en-US / ja-JP),开箱即用
|
|
933
|
-
- 组件自动响应全局 locale 变化(通过 `@h-ai/core` 同步)
|
|
934
|
-
- 应用层只需处理**页面级文本**,组件内部文本由 @h-ai/ui 统一管理
|
|
935
|
-
- 如需覆盖特定文本,通过 `submitText`、`labels` 等 props 传入
|
|
936
|
-
|
|
937
|
-
#### createLocaleStore
|
|
938
|
-
|
|
939
|
-
用于客户端 locale 状态管理,自动同步到 `@h-ai/core` 全局 locale 管理器:
|
|
940
|
-
|
|
941
|
-
```svelte
|
|
942
|
-
<script>
|
|
943
|
-
import { createLocaleStore, setGlobalLocale } from '@h-ai/ui/i18n'
|
|
944
|
-
import { setLocale } from '#lib/paraglide/runtime.js'
|
|
945
|
-
|
|
946
|
-
const localeStore = createLocaleStore()
|
|
947
|
-
|
|
948
|
-
function changeLocale(code) {
|
|
949
|
-
localeStore.set(code) // 更新 UI store + 同步到 @h-ai/core
|
|
950
|
-
setLocale(code) // 同步到 Paraglide(应用层)
|
|
951
|
-
}
|
|
952
|
-
</script>
|
|
953
|
-
|
|
954
|
-
<select value={localeStore.current} onchange={(e) => changeLocale(e.currentTarget.value)}>
|
|
955
|
-
{#each localeStore.supported as l}
|
|
956
|
-
<option value={l.code}>{l.label}</option>
|
|
957
|
-
{/each}
|
|
958
|
-
</select>
|
|
959
|
-
```
|
|
960
|
-
|
|
961
|
-
`@h-ai/ui/i18n` 的 `createLocaleStore` 按“可解析的持久化值 → 完整 navigator.languages(再检查 navigator.language)→ defaultLocale → 支持列表首项”选择语言;首个不支持的候选不触发默认回退。匹配大小写、语言简写及逐级区域/脚本回退,返回 supportedLocales 中的配置代码;同语言多个变体按列表顺序选择。detectBrowserLocale 无实际命中返回 null,不插入框架默认值;空支持列表最终保留调用方默认值。SSR 不读取浏览器候选或修改全局语言。应用若使用 Paraglide,仍需用该项目的 setLocale 同步应用翻译;内置 UI 字典的覆盖范围不因自定义 store 列表而自动增加。
|
|
962
|
-
|
|
963
|
-
#### 导出的 i18n 工具
|
|
964
|
-
|
|
965
|
-
```ts
|
|
966
|
-
import {
|
|
967
|
-
createLocaleStore, // Svelte 响应式 locale store
|
|
968
|
-
DEFAULT_LOCALE, // 默认 locale: 'zh-CN'
|
|
969
|
-
DEFAULT_LOCALES, // 支持的 locale 列表
|
|
970
|
-
detectBrowserLocale, // 检测浏览器语言
|
|
971
|
-
getGlobalLocale, // 获取当前全局 locale
|
|
972
|
-
interpolate, // 字符串插值(如 "Hello {name}")
|
|
973
|
-
isLocaleSupported, // 检查 locale 是否支持
|
|
974
|
-
resolveLocale, // 解析 locale(支持回退)
|
|
975
|
-
setGlobalLocale, // 设置全局 locale(同步 @h-ai/core)
|
|
976
|
-
} from '@h-ai/ui/i18n'
|
|
977
|
-
```
|
|
978
|
-
|
|
979
|
-
协议在 Modal 内显示并保留表单输入;使用 URL 时,协议页面须允许 iframe 嵌入,组件禁用其脚本,另提供新窗口查看入口。登录/注册表单使用 `header/extraFields/footer` snippet,AuthPanel 透传 `loginHeader/loginFields/loginFooter` 和 `registerHeader/registerFields/registerFooter`,底部保留内置导航。自定义字段由应用绑定状态和提交,不会隐式写入 IAM 用户模型。
|
|
980
|
-
|
|
981
|
-
```svelte
|
|
982
|
-
<!-- config 来自 IAM 公开配置,actions 来自 Kit/API client;m 为应用翻译。 -->
|
|
983
|
-
<AuthPanel {config} {actions}>
|
|
984
|
-
{#snippet loginHeader()}
|
|
985
|
-
<p>{m.loginHelp()}</p>
|
|
986
|
-
{/snippet}
|
|
987
|
-
{#snippet registerFields()}
|
|
988
|
-
<label><input type='checkbox' bind:checked={subscribe} />{m.subscribe()}</label>
|
|
989
|
-
{/snippet}
|
|
990
|
-
</AuthPanel>
|
|
991
|
-
```
|
|
992
|
-
|
|
993
|
-
上例的 subscribe 为应用自身的 $state,应用包装 register 动作校验/提交扩展业务数据;如需单独组合表单,使用 `<RegisterForm> {#snippet extraFields()}...{/snippet} </RegisterForm>`。扩展里的按钮须为 `type="button"`,避免误提交。
|
|
994
|
-
|
|
995
|
-
### 配置驱动认证页面
|
|
996
|
-
|
|
997
|
-
状态层通过轻量入口 `@h-ai/ui/i18n` 导入 `authErrorMessage`,复用相同映射且无需加载场景组件。管理台个人改密、移动/桌面示例与生成模板均沿用此提示规则。
|
|
998
|
-
|
|
999
|
-
密码登录只提交 `identifier` 和 `password`;`AuthPanel` 将 `LoginForm` 的 `username` 映射为 `identifier`。会话有效期由服务端 `session.maxAge` / `session.refreshTokenMaxAge` 配置决定,登录表单不提供按次登录的持久会话选项。
|
|
1000
|
-
|
|
1001
|
-
协议支持 `agreements.userAgreementMarkdown` 与 `privacyPolicyMarkdown` 直接从配置加载;YAML 的 `|` 保留 Markdown 段落和换行。弹窗复用安全 MarkdownRenderer,关闭原始 HTML、脚本和代码复制工具。同主题同时提供正文与 URL 时优先正文,URL 可作为额外查看入口;只有 URL 时使用隔离 iframe。
|
|
1002
|
-
|
|
1003
|
-
```yaml
|
|
1004
|
-
agreements:
|
|
1005
|
-
showOnRegister: true
|
|
1006
|
-
showOnLogin: false
|
|
1007
|
-
userAgreementMarkdown: |
|
|
1008
|
-
# 用户协议
|
|
1009
|
-
|
|
1010
|
-
**账户使用条款**
|
|
1011
|
-
|
|
1012
|
-
- 请妥善保管账户凭据。
|
|
1013
|
-
privacyPolicyMarkdown: |
|
|
1014
|
-
# 隐私政策
|
|
1015
|
-
|
|
1016
|
-
注册资料用于账户管理,会话信息用于身份认证。
|
|
1017
|
-
# 可选 URL;同主题同时配置 Markdown 和 URL 时,弹窗优先显示 Markdown。
|
|
1018
|
-
# userAgreementUrl: https://example.com/terms
|
|
1019
|
-
# privacyPolicyUrl: https://example.com/privacy
|
|
1020
|
-
```
|
|
1021
|
-
|
|
1022
|
-
AuthPanel 直接接收 IAM 白名单配置和 actions,内置登录(密码/LDAP/邮件/短信)、注册、找回、重置及协议展示。使用 `config.ui` 配置卡片/分栏、标题、品牌、Logo 和配图。`LoginForm` 提供 methods、onsendotp、otpLength、resendInterval;密码表单接受 passwordPolicy。组件只渲染与交互,网络和 Token 存储通过 actions 注入。
|
|
1023
|
-
|
|
1024
|
-
认证错误统一使用 `authErrorMessage(error)`(从 `@h-ai/ui/components/scenes/iam/index` 导入):按公开错误码显示当前 UI 语言,凭据错误统一为“用户名或密码不正确”,未知错误及服务异常不显示原文,保留有效 `traceId`。AuthPanel、验证码发送、敏感操作确认与 fullstack 改密共用此映射。首次改密、密码过期、当前密码复用(`hai:iam:034`)和会话上限各有操作指引;操作成功和错误均使用统一 Toast。确认密码与服务端一样逐字符比较,不归一化 Unicode 或裁剪空白,输入不一致时由 Toast 提示,并保留字段关联。Kit 和 API Client 确认的时间窗口错误会在认证提示中显示服务器 UTC 时间及校时建议。
|
|
1025
|
-
|
|
1026
|
-
AuthPanel 在 SSR 阶段禁用原生表单控件,客户端挂载并绑定事件后自动开放输入,避免接管时丢失早到的输入。应用无需额外的就绪适配;E2E 等待控件可编辑,并覆盖客户端脚本延迟加载的场景。
|
|
1027
|
-
|
|
1028
|
-
认证链接指向当前完整 URL 时,AuthPanel 只切换场景并阻止重复导航,返回登录后可立即输入。路径、查询串或 hash 不同时交给应用路由处理;Ctrl/Cmd 等修改键点击保留浏览器行为。
|
|
1029
|
-
|
|
1030
|
-
`createSensitiveActions` 可利用标准 actions 的 `publicConfig()` 在操作前更新数据库规则。`SensitiveOperationsForm` 复用逐行输入、去重、校验与错误状态;传入 `operations`、异步 `onsubmit(operations)`(返回 HaiResult),`ondone` 只在保存成功后调用。数据库规则与文件规则取并集,表单清空不能取消文件规则。
|
|
1031
|
-
|
|
1032
|
-
会话过期后的重新登录使用 `createSessionRecovery()` + `SessionRecoveryDialog`。根布局通过 `configure(publicConfig, { id, username })` 绑定原用户,把 `recovery.recover` 传给 Kit/API client 的 `recoverSession`;弹窗传入同一份 controller 和标准 actions,布局卸载时 `cancel()`。UI 不保存密码或业务请求,不切换页面。登录携带 `expectedUserId`,服务端在发会话前限制原主体;验证码、锁定、登录限制和改密流程仍按正常登录执行。取消保留当前输入并结束本次续接;真实网络失败不重放写入。整页刷新/关闭后的内存输入无法恢复。
|
|
1033
|
-
|
|
1034
|
-
`createSensitiveActions(actions)` 复用 Kit/API client 的认证动作,统一管理已登录用户的二次确认、取消、错误重试、重复提交与迟到响应。每个应用根布局创建一份,用 `configure(公开策略)` 更新清单;布局卸载时 `cancel()`。`authorize(operation)` 返回 undefined 表示不需确认、null 表示取消/忙、字符串为本次操作凭据;取消时不要发业务请求。有凭据时只传给本次请求,不放全局 header 或持久存储。`ReauthenticationDialog` 绑定控制器的 `open/loading/error/submit/cancel`,不会增加权限。`Input` 支持 `datetime-local`,其值为浏览器本地时间,服务层转换为明确时间戳后提交。
|
|
1035
|
-
|
|
1036
|
-
```svelte
|
|
1037
|
-
<!-- actions 为 Kit/API client 的标准认证动作;policy 为 IAM 公开再认证策略。 -->
|
|
1038
|
-
<script lang='ts'>
|
|
1039
|
-
import type { SensitiveActionsOptions } from '@h-ai/ui'
|
|
1040
|
-
import { createSensitiveActions, ReauthenticationDialog } from '@h-ai/ui'
|
|
1041
|
-
|
|
1042
|
-
const { actions, policy }: { actions: SensitiveActionsOptions, policy: { enabled: boolean, operations: string[] } } = $props()
|
|
1043
|
-
const confirmation = createSensitiveActions(actions)
|
|
1044
|
-
$effect(() => {
|
|
1045
|
-
confirmation.configure(policy)
|
|
1046
|
-
return () => confirmation.cancel()
|
|
1047
|
-
})
|
|
1048
|
-
// 业务动作 await confirmation.authorize(operation);null 时中止该动作。
|
|
1049
|
-
</script>
|
|
1050
|
-
<ReauthenticationDialog
|
|
1051
|
-
open={confirmation.open}
|
|
1052
|
-
loading={confirmation.loading}
|
|
1053
|
-
error={confirmation.error}
|
|
1054
|
-
onsubmit={password => confirmation.submit(password)}
|
|
1055
|
-
onclose={() => confirmation.cancel()}
|
|
1056
|
-
/>
|
|
1057
|
-
```
|
|
1058
|
-
|
|
1059
|
-
[完整 IAM 配置 / IAM configuration](../iam/README.md)
|
|
1060
|
-
|
|
1061
|
-
### 新手引导与帮助中心
|
|
1062
|
-
|
|
1063
|
-
`@h-ai/ui/guide` 提供 `createGuide`、`GuideHost`、`HelpCenter` 和相关类型。无需 init/close;引擎在开始导览时按需加载,浮层复用当前主题。组件内置中英日文按钮、进度和错误提示,业务内容使用应用 i18n。
|
|
1064
|
-
|
|
1065
|
-
同一入口的 `resolveGuideText(text?)` 可解析字符串或 i18n 回调;宿主组件已自动解析文案。
|
|
1066
|
-
|
|
1067
|
-
下例放在应用布局中;`nav` 是应用现有 NavAdapter,`locale`、`user` 与翻译函数 `m` 来自应用,翻译 key 需在应用消息中定义。目标按钮放在 `/users` 页面。
|
|
1068
|
-
|
|
1069
|
-
```svelte
|
|
1070
|
-
<script lang='ts'>
|
|
1071
|
-
import { createGuide, GuideHost } from '@h-ai/ui/guide'
|
|
1072
|
-
|
|
1073
|
-
const guide = createGuide({
|
|
1074
|
-
nav,
|
|
1075
|
-
persistKey: 'my-app-guide',
|
|
1076
|
-
tours: [{
|
|
1077
|
-
id: 'users',
|
|
1078
|
-
version: 1,
|
|
1079
|
-
route: '/users',
|
|
1080
|
-
title: () => m.guide_users_title(),
|
|
1081
|
-
description: () => m.guide_users_description(),
|
|
1082
|
-
steps: [{
|
|
1083
|
-
target: 'users-create',
|
|
1084
|
-
title: () => m.guide_create_title(),
|
|
1085
|
-
description: () => m.guide_create_description(),
|
|
1086
|
-
}],
|
|
1087
|
-
}],
|
|
1088
|
-
articles: [{
|
|
1089
|
-
id: 'users-help',
|
|
1090
|
-
title: () => m.guide_users_title(),
|
|
1091
|
-
content: () => m.guide_users_markdown(),
|
|
1092
|
-
tourId: 'users',
|
|
1093
|
-
}],
|
|
1094
|
-
})
|
|
1095
|
-
</script>
|
|
1096
|
-
|
|
1097
|
-
<GuideHost {guide} {locale} scope={user.id} autoStart='users' />
|
|
1098
|
-
<Button onclick={() => guide.openHelp()}>{m.help()}</Button>
|
|
1099
|
-
<!-- 在目标页面为现有按钮添加锚点,无需额外包装。 -->
|
|
1100
|
-
<Button data-guide='users-create' onclick={createUser}>{m.create_user()}</Button>
|
|
1101
|
-
```
|
|
1102
|
-
|
|
1103
|
-
- `start(id)` 返回 `Promise<boolean>`,允许手动重看;失败返回 false 并设置 `error`。`startIfNeeded(id)` 返回 boolean 并显示首次邀请,通常由 autoStart 处理。
|
|
1104
|
-
- `openHelp(articleId?)` 打开帮助,`stop()` 取消导览,`reset(id)` 删除当前用户的偏好。完成、稍后和不再提醒分别记录;稍后暂缓一天,Cookie 默认保存一年。
|
|
1105
|
-
- 关闭按钮、Escape 和遮罩点击在首帧定位期间也会取消等待、清除 `busy`;启动中的 `start()` 返回 false,不记录完成。
|
|
1106
|
-
- `persistence` 支持 cookie(默认)、localStorage、memory;受限存储回退到实例内存。scope 使用非敏感用户标识,version 变化会重新提示。
|
|
1107
|
-
- 通过已有 NavAdapter 接入 SvelteKit、SPA 或原生 WebView;默认完整导航使用 sessionStorage 保存短期启动记录。宿主只在浏览器挂载后读取记录,SSR 实例不得跨用户共享。
|
|
1108
|
-
- 目标等待默认 3000ms,可用 waitTimeout 调整。before(signal) 可展开页签/抽屉;必要元素缺失停止,可选步骤使用 optional 跳过。引导不会自动提交业务表单。
|
|
1109
|
-
- 业务文案用函数延迟求值,并传入当前 locale。步骤内容按纯文本显示;帮助正文复用安全 MarkdownRenderer,原始 HTML 关闭。
|
|
1110
|
-
- HelpCenter 可独立放入帮助页面,props 为 articles、tours(可选)、locale、selectedId 和 onstart;支持类别标签、标题/正文搜索和关联导览。
|
|
1111
|
-
|
|
1112
|
-
admin-console 示例和 CLI fullstack Web/App/Desktop 默认包含帮助入口、首次邀请及个人资料导览。完整配置和验证场景见 [引导指南](../cli/templates/skills/hai-ui/guide.md)。
|
|
1113
|
-
|
|
1114
|
-
### 其他导出
|
|
1115
|
-
|
|
1116
|
-
```ts
|
|
1117
|
-
// 类型
|
|
1118
|
-
import type { ButtonProps, InputProps, ModalProps } from '@h-ai/ui'
|
|
1119
|
-
```
|
|
1120
|
-
|
|
1121
|
-
```ts
|
|
1122
|
-
// 样式工具
|
|
1123
|
-
import { cn, generateId, getSizeClass, getVariantClass } from '@h-ai/ui'
|
|
1124
|
-
```
|
|
1125
|
-
|
|
1126
|
-
```ts
|
|
1127
|
-
// Toast 单例
|
|
1128
|
-
import { toast } from '@h-ai/ui'
|
|
1129
|
-
```
|
|
1130
|
-
|
|
1131
|
-
组件子路径只开放 package.exports 明确列出的 barrel,例如 `@h-ai/ui/components/primitives/index`;不开放任意组件实现或内部存储辅助函数。宿主剪贴板注册仍是公开能力。
|
|
1132
|
-
|
|
1133
|
-
### 请求语言隔离
|
|
1134
|
-
|
|
1135
|
-
Node 请求与 SSR 使用 `core.i18n.runWithLocale(locale, () => handleRequest())`;SvelteKit 可使用 `kit.i18n.runWithLocale(locale, () => resolve(event))`,serv 自动按请求头建立上下文。异步子任务继承请求语言,优先级为显式 `MessageOptions.locale`、请求语言、进程启动默认语言。`setGlobalLocale` 在请求上下文中只更新当前请求;上下文外仅用于启动默认值,不能在请求 hook 中调用它修改默认值。
|
|
1136
|
-
|
|
1137
|
-
浏览器继续使用应用级 `setGlobalLocale` / `createLocaleStore`。SSR 的 UI store 初始化和 setter 只修改自身状态,不写全局语言;UI 消息从请求上下文读取。`runWithLocale` 仅支持 Node 入口,浏览器通过显式 locale 或应用状态翻译。
|
|
1138
|
-
|
|
1139
|
-
### 输入约束与 HTTP 能力
|
|
1140
|
-
|
|
1141
|
-
存储 key 按 UTF-8 最多 1024 字节,并拒绝绝对路径、反斜线、控制字符及点路径段;公开 HTTP 批量删除每次 1–1000 项。`@h-ai/storage/schemas` 提供浏览器安全的共同规则。预签名有效期为整数 1–604800 秒(Node 默认 3600,HTTP 默认 900);HTTP 上传仅接受 key/contentType/expiresIn,不支持 contentLength/maxSize/metadata/checksum。无效输入返回 HTTP 400,typed client 映射 VALIDATION_FAILED。FileUpload 的大小/类型限制仅为前端体验,实际对象须由应用服务端复核。Node 流式读写/checksum/条件写等没有默认 HTTP 端点。完整映射与授权边界见 [存储 API 能力](../storage/README.md#存储输入约束与跨端能力)。
|
|
1142
|
-
|
|
1143
|
-
### 紧凑工作区与可收起筛选
|
|
1144
|
-
|
|
1145
|
-
`WorkspaceLayout` 统一导航、内容区和可选页脚:顶栏采用紧凑高度,主内容使用 12/16px 内边距;没有页脚时不预留高度。通过 `title` 提供导航中的页面标题,`leading/actions/footer` 为 snippet,`data-*` 透传内容 main。父布局需传递剩余高度及 min-height: 0。
|
|
1146
|
-
|
|
1147
|
-
同名 `PageHeader` 自动省略重复标题,保留说明和操作;`SettingsLayout` 复用该行为。工作区中的 `CrudPage` 默认不重复显示页面标题,操作并入工具栏;独立使用仍显示标题,可用 `showHeader` 显式覆盖。
|
|
1148
|
-
|
|
1149
|
-
`FilterBar` 的 leading 和 actions 保持可见,children 默认收起,`bind:expanded` 控制展开,`activeCount` 提示已启用条件,`onreset` 提供内置三语重置按钮。收起保留控件和值;重置和请求逻辑由宿主回调处理。`TableToolbar` 复用该布局并提供原生查询表单,`CrudFilterBar` 复用相同实现;`onsearch` 在提交时读取当前绑定的搜索和筛选草稿,`onfilterchange` 只通知草稿变化。`onreset`(TableToolbar 使用 `onclearfilters`)必须同步清空宿主已提交条件并重新查询。列表排序使用 DataTable 的 `sortKey`、`sortDir`、`onsort`。 扩展筛选按容器宽度自适应为 1/2/4/6 列,字段横向间距 20px、纵向间距 16px,标签和控件分别对齐;日期范围占两列,窄屏占整行。
|
|
1150
|
-
|
|
1151
|
-
下例的 m、statusOptions、clearFilters 和 loadRows 由业务应用提供;清空回调须重置搜索及全部条件。
|
|
1152
|
-
|
|
1153
|
-
```svelte
|
|
1154
|
-
<script lang="ts">
|
|
1155
|
-
import { Button, FilterBar, Input, Select, WorkspaceLayout } from '@h-ai/ui'
|
|
1156
|
-
let search = $state('')
|
|
1157
|
-
let status = $state('')
|
|
1158
|
-
</script>
|
|
1159
|
-
|
|
1160
|
-
<div class="flex h-dvh min-h-0">
|
|
1161
|
-
<WorkspaceLayout title={m.page_title()}>
|
|
1162
|
-
<FilterBar activeCount={status ? 1 : 0} onreset={clearFilters}>
|
|
1163
|
-
{#snippet leading()}<Input size="sm" bind:value={search} placeholder={m.search()} />{/snippet}
|
|
1164
|
-
{#snippet actions()}<Button size="sm" onclick={loadRows}>{m.search()}</Button>{/snippet}
|
|
1165
|
-
<div class="w-40"><Select size="sm" bind:value={status} options={statusOptions} /></div>
|
|
1166
|
-
</FilterBar>
|
|
1167
|
-
</WorkspaceLayout>
|
|
1168
|
-
</div>
|
|
1169
|
-
```
|
|
1170
|
-
|
|
1171
|
-
### 设计与交互验收
|
|
1172
|
-
|
|
1173
|
-
页面设计使用 [hai-ui-design](../cli/templates/skills/hai-ui-design/SKILL.md),组件实现使用 [hai-ui](../cli/templates/skills/hai-ui/SKILL.md),真实界面走查使用 [hai-ui-review](../cli/templates/skills/hai-ui-review/SKILL.md)。[设计约定](../../.agents/instructions/ui-design.md) 说明布局、状态和示例。
|
|
1174
|
-
|
|
1175
|
-
Tabs 支持方向键/Home/End、禁用项跳过和单一 Tab 入口;表格提供排序与加载状态和行键盘操作;分页导航/输入名称跟随语言,外部页码同步跳页输入;筛选展开遵循文档焦点顺序,视图按钮提供选中状态。Empty/Alert 支持长内容换行。theme.css 引入共享 tokens,焦点跟随当前主题,global.css 响应减少动态效果。应用仍需接入实际筛选、排序、分页与失败恢复。
|
|
1176
|
-
|
|
1177
|
-
### 可选交互挑战
|
|
1178
|
-
|
|
1179
|
-
AuthPanel 在 config.captcha.enabled 时通过 actions.createCaptcha 自动生成并异步求解自托管 ALTCHA,按 login/register/sendOtp/passwordReset/renewPassword 用途提交单用证明;关闭时不加载求解器。createAuthActions 已提供动作,自定义动作须保留 captcha,缺少动作时不放行。证明仅存在当前请求内存,服务端始终校验与消费。
|
|
1180
|
-
|
|
1181
|
-
策略、默认值和恢复边界见 [IAM](../iam/README.md)。
|
|
17
|
+
[跟着最小示例完成接入](../../docs/usage/function/ui.md#quick-start)。
|
|
1182
18
|
|
|
1183
|
-
##
|
|
19
|
+
## 配置清单
|
|
1184
20
|
|
|
1185
|
-
|
|
21
|
+
本模块没有独立的运行配置文件。文件归属见[配置说明](../../docs/usage/configuration/ui.md),调用参数或响应结构见[参考页](../../docs/usage/function/ui.md#call-options)。
|
|
1186
22
|
|
|
1187
|
-
|
|
1188
|
-
| --- | --- | --- | --- | --- |
|
|
1189
|
-
| `Component Props` | 控制渲染与交互 | typed props, bound values, callbacks, children snippets | DOM, bindings and callback events | `<Input bind:value={draft} />` |
|
|
1190
|
-
| `Theme` | 主题与颜色 | supported theme ID, color values, preference key | DOM theme/CSS variables; nonsensitive browser preference | `applyTheme("light")` |
|
|
1191
|
-
| `Locale` | 界面语言 | supportedLocales, defaultLocale, persistKey, detectBrowser | component-tree locale; isolated SSR state | `createLocaleStore({ defaultLocale: "ja-JP", detectBrowser: false })` |
|
|
1192
|
-
| `Guide` | 帮助与首次引导 | tours, articles, nonsecret scope/version, nav adapter | guide/help state and nonsensitive progress | `createGuide({ tours: [], persistence: "memory" })` |
|
|
1193
|
-
| `CRUD` | 资源字段与 API | CrudResource fields/API callbacks and controller options | resource view model; API must implement authorization | `createCrudController(crud, { autoLoad: false })` |
|
|
1194
|
-
| `Authentication` | 公开认证配置 | IAM-whitelisted config and standard actions | AuthPanel submits to host actions; no secret persistence | `<AuthPanel {config} {actions} />` |
|
|
23
|
+
## 功能说明
|
|
1195
24
|
|
|
1196
|
-
|
|
25
|
+
[查 API 清单](../../docs/usage/function/ui.md#api-reference),包含调用入口、输入、返回值和用法。
|
|
1197
26
|
|
|
1198
|
-
|
|
27
|
+
[工具与产物工作台](../../docs/usage/function/ui.md#工具与产物工作台)提供参数表单、示例、任务进度、文档编辑、版本冲突与媒体预览;应用只需连接已授权的读写和执行回调。
|
|
1199
28
|
|
|
1200
|
-
|
|
29
|
+
<a id="代码工作区"></a>
|
|
1201
30
|
|
|
1202
|
-
|
|
31
|
+
[代码工作区](../../docs/usage/function/ui.md#代码工作区)
|
|
1203
32
|
|
|
1204
|
-
|
|
33
|
+
## 数据结构
|
|
1205
34
|
|
|
1206
|
-
|
|
35
|
+
模块没有自建数据库表。
|
|
1207
36
|
|
|
1208
|
-
|
|
37
|
+
查看[数据结构](../../docs/usage/data/ui.md),查阅主题、语言和引导进度保存在浏览器的什么位置。
|
|
1209
38
|
|
|
1210
39
|
## 开发测试
|
|
1211
40
|
|