From cb8a9ea357b3f13f749705543904b9b5295fb2f0 Mon Sep 17 00:00:00 2001 From: HIsheR Date: Mon, 26 Oct 2026 12:12:52 +0800 Subject: [PATCH] =?UTF-8?q?iter(g49):=20=E6=96=B0=E5=A2=9E=20autoComplete?= =?UTF-8?q?=20=E8=87=AA=E5=8A=A8=E8=A1=A5=E5=85=A8=E7=BB=84=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .ua/index.json | 61 +++++++++++++- AGENTS.md | 2 +- ARCHITECTURE.md | 2 +- README.md | 8 +- apps/demo/main.ts | 27 +++++++ llms-full.txt | 32 +++++++- llms.txt | 1 + packages/skin/ui/src/autoComplete.ts | 116 +++++++++++++++++++++++++++ packages/skin/ui/src/index.ts | 1 + packages/skin/ui/src/types.ts | 18 +++++ packages/skin/ui/ua.manifest.json | 59 +++++++++++++- packages/skin/ui/ui.css | 88 ++++++++++++++++++++ 12 files changed, 405 insertions(+), 10 deletions(-) create mode 100644 packages/skin/ui/src/autoComplete.ts diff --git a/.ua/index.json b/.ua/index.json index 6458199..d33306d 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T04:11:34.965Z", + "generatedAt": "2026-10-26T04:12:36.698Z", "repoRoot": ".", "packages": [ { @@ -190,7 +190,8 @@ "result(props)：结果页，status 四档语义色 + 标题 + 说明 + 操作区，用于提交完成/校验失败等终态", "transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选", "cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作", - "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号" + "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号", + "autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想" ], "keyTypes": [ "ButtonProps", @@ -2195,6 +2196,62 @@ "direction 传 vertical 变为上下分栏，键盘方向键与光标同步切换", "传入 sizes 信号即受控，外部写入可做「预设布局」切换（如 1:1 / 2:1）" ] + }, + { + "id": "autoComplete", + "title": "自动补全 AutoComplete", + "demo": "sec-autocomplete", + "props": [ + { + "n": "options", + "t": "AutoCompleteOption[] | ((q: string) => AutoCompleteOption[])", + "r": 1, + "d": "候选项：静态列表或按关键字计算的函数（可远程联想）" + }, + { + "n": "value", + "t": "Signal", + "d": "输入值信号；不传则内部维护，传了即外部受控" + }, + { + "n": "placeholder", + "t": "string", + "d": "占位文案，同时作为无障碍名称" + }, + { + "n": "emptyText", + "t": "string", + "d": "无匹配时的提示文案；缺省「无匹配项」" + }, + { + "n": "maxItems", + "t": "number", + "d": "最多展示条数；缺省 8" + }, + { + "n": "disabled", + "t": "boolean | Signal", + "d": "禁用输入与弹层" + }, + { + "n": "onInput", + "t": "(query: string) => void", + "d": "每次输入回调，适合触发远程请求" + }, + { + "n": "onSelect", + "t": "(option: AutoCompleteOption) => void", + "d": "选中回调（点击或 Enter）" + } + ], + "example": "autoComplete({ value: acValue, placeholder: '输入组件名', options: [{ value: 'dataTable', hint: '表格' }], onSelect: (o) => toast.success(o.value) })", + "steps": [ + "输入任何字符即按包含匹配（忽略大小写）过滤候选，空串时弹层不展开", + "↑↓ 在候选间环形移动并高亮，Enter 选中，Esc 收起，Tab 失焦也会收起", + "候选行支持右侧 hint（分类 / 拼音），选中后值写回输入框并触发 onSelect", + "options 传函数时每次输入都会用当前关键字调用，可在此发起远程请求并返回新数组", + "value 传信号即受控：外部写入会同步回填输入框内容" + ] } ] }, diff --git a/AGENTS.md b/AGENTS.md index 370e510..0682caa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架 -- `packages/skin/ui`（@ui-arch/ui）：47 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 +- `packages/skin/ui`（@ui-arch/ui）：48 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private） - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ff16a97..cf0d0cf 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,7 +34,7 @@ ui-arch-mvp/ │ │ ├── table-core/ # 表格状态内核 │ │ └── frame/ # 信号 + hyperscript 微框架 │ ├── skin/ # 皮肤层（DOM 组件，可发布） -│ │ └── ui/ # 47 个组件 + ui.css +│ │ └── ui/ # 48 个组件 + ui.css │ ├── design/ # 资产层（可发布） │ │ └── tokens/ # --ua-* 设计令牌 │ └── tools/ # 工程层（private，不发布） diff --git a/README.md b/README.md index eb60e44..e75ffa8 100644 --- a/README.md +++ b/README.md @@ -11,13 +11,13 @@ npm run demo # 打开演示：apps/demo/dist/demo.html npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全量文档 llms-full.txt ``` -## 组件（共 47 个） +## 组件（共 48 个） -accordion · alert · avatar · badge · breadcrumb · button · carousel · card · cascader · checkbox · dataTable · descriptions · divider · drawer · empty · form · image · inputNumber · list · menu · modal · notification · pagination · popover · progress · radioGroup · rate · result · segmented · select · skeleton · slider · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · transfer · tree · upload +accordion · alert · autoComplete · avatar · badge · breadcrumb · button · carousel · card · cascader · checkbox · dataTable · descriptions · divider · drawer · empty · form · image · inputNumber · list · menu · modal · notification · pagination · popover · progress · radioGroup · rate · result · segmented · select · skeleton · slider · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · transfer · tree · upload -分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel）、其他（divider / splitter）。 +分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / autoComplete / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel）、其他（divider / splitter）。 ## 可访问性约定 @@ -31,7 +31,7 @@ accordion · alert · avatar · badge · breadcrumb · button · carousel · car |---|---| | `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） | | `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） | -| `packages/skin/ui` | @ui-arch/ui：47 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | +| `packages/skin/ui` | @ui-arch/ui：48 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） | | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server | | `apps/demo` | 交互演示（esbuild 打包成单文件） | diff --git a/apps/demo/main.ts b/apps/demo/main.ts index 5876908..d1a8f5a 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -10,6 +10,7 @@ const IMG_DEMO = 'data:image/svg+xml;utf8,' + encodeURIComponent( import { accordion, alert, + autoComplete, avatar, badge, breadcrumb, @@ -185,6 +186,7 @@ const listPick = signal(''); // 列表点击选中的条目标题 const slideIndex = signal(0); // 轮播当前下标（外部受控演示） const cascaderPath = signal(['east', 'sh']); // 级联选择路径（外部受控演示） const splitSizes = signal([35, 65]); // 分栏比例（外部受控演示） +const acValue = signal(''); // 自动补全输入值（外部受控演示） const treePick = signal('core'); // 树形选中节点 key const transferKeys = signal(['a11y']); // 穿梭框右侧集合（外部受控演示） const cityPick = signal(''); // 可搜索下拉的选中城市 @@ -681,6 +683,31 @@ const content = h( button({ label: '错误（可关）', variant: 'danger', onClick: () => notification({ title: '保存失败', description: '服务端返回 500，请稍后重试', variant: 'danger' }) }), ), ), + section( + 'sec-autocomplete', + '自动补全', + 'autoComplete：输入即过滤候选，↑↓ 环形高亮 / Enter 选中 / Esc 收起；options 传函数可做远程联想，空结果给提示行。', + h( + 'div', + { class: 'row' }, + autoComplete({ + value: acValue, + placeholder: '输入组件名，如 table', + emptyText: '没有匹配的组件', + onSelect: (o) => toast.success(`已选 ${o.value}`), + options: [ + { value: 'dataTable', hint: '表格' }, + { value: 'transfer', hint: '穿梭框' }, + { value: 'cascader', hint: '级联' }, + { value: 'splitter', hint: '分栏' }, + { value: 'autoComplete', hint: '联想' }, + { value: 'pagination', hint: '分页' }, + ], + }), + autoComplete({ placeholder: '按关键字动态算候选', options: (q) => [{ value: `${q}-alpha` }, { value: `${q}-beta` }] }), + h('span', { class: 'out' }, () => (acValue() ? `输入框当前值：${acValue()}` : '未输入')), + ), + ), section( 'sec-splitter', '可拖拽分栏', diff --git a/llms-full.txt b/llms-full.txt index aa544c4..79411c2 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档（无图形版） -> 自动生成于 2026-10-26T04:11:34.965Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 +> 自动生成于 2026-10-26T04:12:36.698Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。 ## 快速上手 @@ -1255,6 +1255,35 @@ splitter({ sizes: ratio, min: 15, panes: [leftPanel, rightPanel], onChange: (s) 现场演示：apps/docs/demo.html#sec-splitter +### autoComplete — 自动补全 AutoComplete + +参数： + +- options（必填）：AutoCompleteOption[] | ((q: string) => AutoCompleteOption[]) —— 候选项：静态列表或按关键字计算的函数（可远程联想） +- value：Signal —— 输入值信号；不传则内部维护，传了即外部受控 +- placeholder：string —— 占位文案，同时作为无障碍名称 +- emptyText：string —— 无匹配时的提示文案；缺省「无匹配项」 +- maxItems：number —— 最多展示条数；缺省 8 +- disabled：boolean | Signal —— 禁用输入与弹层 +- onInput：(query: string) => void —— 每次输入回调，适合触发远程请求 +- onSelect：(option: AutoCompleteOption) => void —— 选中回调（点击或 Enter） + +示例： + +``` +autoComplete({ value: acValue, placeholder: '输入组件名', options: [{ value: 'dataTable', hint: '表格' }], onSelect: (o) => toast.success(o.value) }) +``` + +手把手： + +1. 输入任何字符即按包含匹配（忽略大小写）过滤候选，空串时弹层不展开 +2. ↑↓ 在候选间环形移动并高亮，Enter 选中，Esc 收起，Tab 失焦也会收起 +3. 候选行支持右侧 hint（分类 / 拼音），选中后值写回输入框并触发 onSelect +4. options 传函数时每次输入都会用当前关键字调用，可在此发起远程请求并返回新数组 +5. value 传信号即受控：外部写入会同步回填输入框内容 + +现场演示：apps/docs/demo.html#sec-autocomplete + API 速览： - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交） @@ -1306,6 +1335,7 @@ API 速览： - transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选 - cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作 - splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号 +- autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想 一行用法： diff --git a/llms.txt b/llms.txt index ce98d18..e500850 100644 --- a/llms.txt +++ b/llms.txt @@ -96,6 +96,7 @@ - transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选 - cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作 - splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号 + - autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')` - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调 diff --git a/packages/skin/ui/src/autoComplete.ts b/packages/skin/ui/src/autoComplete.ts new file mode 100644 index 0000000..48b8de9 --- /dev/null +++ b/packages/skin/ui/src/autoComplete.ts @@ -0,0 +1,116 @@ +import { effect, h, signal } from '@ui-arch/frame'; +import type { Signal } from '@ui-arch/frame'; +import { pushOverlay } from './overlay.js'; +import { flip } from './position.js'; +import type { AutoCompleteOption, AutoCompleteProps } from './types.js'; + +let seq = 0; // 实例序号：给弹层列表一个稳定 id，供 aria-controls 关联 + +/*** 自动补全：输入即过滤候选项，↑↓ 高亮 / Enter 选中 / Esc 收起，value 信号双向绑定 ***/ +export function autoComplete(props: AutoCompleteProps): HTMLElement { + // —— 状态集中声明 —— + const value: Signal = props.value ?? signal(''); // 输入值 + const open = signal(false); // 弹层开合 + const query = signal(''); // 当前过滤关键字（与 value 同步，独立信号便于受控写入） + const active = signal(-1); // 键盘高亮下标，-1 表示无高亮 + const place = signal<'top' | 'bottom'>('bottom'); // 实际方位 + let releaseEsc: (() => void) | null = null; // Esc 栈注销函数 + const max = props.maxItems ?? 8; + + /*** 按关键字取候选：函数式入参交给调用方计算（可远程联想），结果截断到 maxItems ***/ + const candidates = (): AutoCompleteOption[] => { + const all = typeof props.options === 'function' ? props.options(query()) : props.options; + const q = query().trim().toLowerCase(); + const hit = q ? all.filter((o) => o.value.toLowerCase().includes(q)) : all; // 包含匹配，大小写不敏感 + return hit.slice(0, max); + }; + + const input = h('input', { + type: 'text', + class: 'ua-autocomplete-input', + placeholder: props.placeholder ?? '', + 'aria-label': props.placeholder ?? '自动补全', + role: 'combobox', + 'aria-expanded': () => String(open()), + 'aria-autocomplete': 'list', + disabled: props.disabled, + value: () => value(), // 外部写入信号时回填输入框 + oninput: (e: Event) => { + const v = (e.target as HTMLInputElement).value; + value(v); + query(v); + active(-1); + open(v.trim().length > 0); // 空串收起，避免开屏就弹 + props.onInput?.(v); + }, + }) as HTMLInputElement; + + const list = h('ul', { class: 'ua-autocomplete-list', role: 'listbox', id: `ua-ac-${(seq += 1)}` }) as HTMLElement; + input.setAttribute('aria-controls', list.id); + const pop = h('div', { class: () => `ua-autocomplete-pop${open() ? ' ua-open' : ''}${place() === 'top' ? ' is-flip' : ''}` }, list) as HTMLElement; + const root = h('div', { class: 'ua-autocomplete' }, input, pop) as HTMLElement; + + /*** 选中候选：写值 + 收起 + 回调，焦点回到输入框便于继续输入 ***/ + const pick = (opt: AutoCompleteOption): void => { + value(opt.value); + query(opt.value); + open(false); + active(-1); + props.onSelect?.(opt); + input.focus(); + }; + + /*** 重绘候选行：高亮项由 active 决定，空结果渲染提示行 ***/ + const render = (): void => { + const opts = candidates(); + if (!opts.length) { + list.replaceChildren(h('li', { class: 'ua-autocomplete-empty' }, props.emptyText ?? '无匹配项')); + input.removeAttribute('aria-activedescendant'); + return; + } + const rows = opts.map((opt, i) => { + const row = h( + 'li', + { + class: () => `ua-autocomplete-opt${active() === i ? ' is-active' : ''}`, + role: 'option', + id: `${list.id}-${i}`, + 'aria-selected': String(active() === i), + onmousedown: (e: Event) => { e.preventDefault(); pick(opt); }, // 阻止默认：保住输入框焦点，blur 后仍能选中 + }, + h('span', { class: 'ua-autocomplete-value' }, opt.value), + opt.hint ? h('span', { class: 'ua-autocomplete-hint' }, opt.hint) : null, + ); + return row; + }); + list.replaceChildren(...rows); + const cur = rows[active()]; + if (cur) input.setAttribute('aria-activedescendant', cur.id); // 读屏跟随高亮 + else input.removeAttribute('aria-activedescendant'); + }; + + root.addEventListener('keydown', (e: KeyboardEvent) => { + const opts = candidates(); + if (e.key === 'ArrowDown' || e.key === 'ArrowUp') { + e.preventDefault(); // 阻止光标跳行 + if (!open() && opts.length) { open(true); active(0); return; } // 未展开：先展开并高亮首项 + const dir = e.key === 'ArrowDown' ? 1 : -1; + active((active() + dir + opts.length) % opts.length); // 环形移动 + return; + } + if (e.key === 'Enter' && open() && active() >= 0) { e.preventDefault(); pick(opts[active()]); return; } // 有高亮才回车选中 + if (e.key === 'Tab') { open(false); return; } // 失焦前收起，避免残留浮层 + }); + + document.addEventListener('click', (e) => { + if (root.contains(e.target as Node)) return; // 卫语句：组件内点击不处理 + open(false); + }); + effect(render); // 依赖 query / active / options，任一变化即重绘 + effect(() => { + if (open()) releaseEsc ??= pushOverlay(() => { open(false); input.focus(); }); // 入栈逐层关闭 + else { releaseEsc?.(); releaseEsc = null; } + }); + effect(() => { if (open()) place(flip(input, pop, 'bottom')); }); // 空间不足自动翻转 + return root; +} diff --git a/packages/skin/ui/src/index.ts b/packages/skin/ui/src/index.ts index 7e9dac3..9fa0cae 100644 --- a/packages/skin/ui/src/index.ts +++ b/packages/skin/ui/src/index.ts @@ -47,3 +47,4 @@ export { dataTable } from './dataTable.js'; export { transfer } from './transfer.js'; export { cascader } from './cascader.js'; export { splitter } from './splitter.js'; +export { autoComplete } from './autoComplete.js'; diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index 4de3793..a8fe1b0 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -523,4 +523,22 @@ export interface SplitterProps { onChange?: (sizes: number[]) => void; // 拖拽/键盘调整后回调（传副本） } +/*** 自动补全候选 ***/ +export interface AutoCompleteOption { + value: string; // 选中后写入输入框的值 + hint?: string; // 右侧补充说明（如分类 / 拼音）；缺省不渲染 +} + +/*** 自动补全入参 ***/ +export interface AutoCompleteProps { + options: AutoCompleteOption[] | ((query: string) => AutoCompleteOption[]); // 候选：静态列表或按关键字计算 + value?: Signal; // 输入值信号；不传则内部维护 + placeholder?: string; // 占位文案 + emptyText?: string; // 无匹配提示；缺省「无匹配项」 + maxItems?: number; // 最多展示条数；缺省 8 + disabled?: boolean | Signal; // 禁用输入与弹层 + onInput?: (query: string) => void; // 每次输入回调（可用于远程联想） + onSelect?: (option: AutoCompleteOption) => void; // 选中回调（点击或 Enter） +} + export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方 diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index 9a44789..16ac4fd 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -61,7 +61,8 @@ "result(props)：结果页，status 四档语义色 + 标题 + 说明 + 操作区，用于提交完成/校验失败等终态", "transfer(props)：穿梭框，左右两栏勾选后整体搬运，targetKeys 信号双向绑定，两栏各自搜索与全选（含半选），禁用条目不参与搬运也不可勾选", "cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作", - "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号" + "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号", + "autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想" ], "keyTypes": [ "ButtonProps", @@ -2066,6 +2067,62 @@ "direction 传 vertical 变为上下分栏，键盘方向键与光标同步切换", "传入 sizes 信号即受控，外部写入可做「预设布局」切换（如 1:1 / 2:1）" ] + }, + { + "id": "autoComplete", + "title": "自动补全 AutoComplete", + "demo": "sec-autocomplete", + "props": [ + { + "n": "options", + "t": "AutoCompleteOption[] | ((q: string) => AutoCompleteOption[])", + "r": 1, + "d": "候选项：静态列表或按关键字计算的函数（可远程联想）" + }, + { + "n": "value", + "t": "Signal", + "d": "输入值信号；不传则内部维护，传了即外部受控" + }, + { + "n": "placeholder", + "t": "string", + "d": "占位文案，同时作为无障碍名称" + }, + { + "n": "emptyText", + "t": "string", + "d": "无匹配时的提示文案；缺省「无匹配项」" + }, + { + "n": "maxItems", + "t": "number", + "d": "最多展示条数；缺省 8" + }, + { + "n": "disabled", + "t": "boolean | Signal", + "d": "禁用输入与弹层" + }, + { + "n": "onInput", + "t": "(query: string) => void", + "d": "每次输入回调，适合触发远程请求" + }, + { + "n": "onSelect", + "t": "(option: AutoCompleteOption) => void", + "d": "选中回调（点击或 Enter）" + } + ], + "example": "autoComplete({ value: acValue, placeholder: '输入组件名', options: [{ value: 'dataTable', hint: '表格' }], onSelect: (o) => toast.success(o.value) })", + "steps": [ + "输入任何字符即按包含匹配（忽略大小写）过滤候选，空串时弹层不展开", + "↑↓ 在候选间环形移动并高亮，Enter 选中，Esc 收起，Tab 失焦也会收起", + "候选行支持右侧 hint（分类 / 拼音），选中后值写回输入框并触发 onSelect", + "options 传函数时每次输入都会用当前关键字调用，可在此发起远程请求并返回新数组", + "value 传信号即受控：外部写入会同步回填输入框内容" + ] } ] } diff --git a/packages/skin/ui/ui.css b/packages/skin/ui/ui.css index 1b1cd44..be86f82 100644 --- a/packages/skin/ui/ui.css +++ b/packages/skin/ui/ui.css @@ -2721,3 +2721,91 @@ button.ua-step-dot:hover { transition: none; } } +.ua-autocomplete { + position: relative; + display: inline-block; + width: 100%; + max-width: 320px; +} +.ua-autocomplete-input { + width: 100%; + padding: 8px var(--ua-space-2); + font-size: var(--ua-font-size-sm); + color: var(--ua-color-text); + background: var(--ua-color-surface); + border: 1px solid var(--ua-color-border); + border-radius: var(--ua-radius-sm); + outline: none; + transition: border-color 0.15s ease, box-shadow 0.15s ease; +} +.ua-autocomplete-input:focus { + border-color: var(--ua-color-accent); + box-shadow: 0 0 0 3px color-mix(in srgb, var(--ua-color-accent) 18%, transparent); +} +.ua-autocomplete-input:disabled { + opacity: 0.5; + cursor: not-allowed; +} +.ua-autocomplete-pop { + position: absolute; + z-index: 40; + left: 0; + right: 0; + display: none; + margin-top: 4px; + border: 1px solid var(--ua-color-border); + border-radius: var(--ua-radius-md); + background: var(--ua-color-surface); + box-shadow: 0 12px 28px rgba(0, 0, 0, 0.18); + overflow: hidden; +} +.ua-autocomplete-pop.ua-open { + display: block; + animation: ua-ac-in 0.15s ease both; +} +.ua-autocomplete-pop.is-flip { + margin-top: 0; + margin-bottom: 4px; +} +.ua-autocomplete-list { + max-height: 220px; + margin: 0; + padding: var(--ua-space-1); + overflow: auto; + list-style: none; +} +.ua-autocomplete-opt { + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--ua-space-1); + padding: 6px var(--ua-space-1); + border-radius: var(--ua-radius-sm); + font-size: var(--ua-font-size-sm); + color: var(--ua-color-text); + cursor: pointer; + transition: background 0.15s ease; +} +.ua-autocomplete-opt.is-active, +.ua-autocomplete-opt:hover { + background: color-mix(in srgb, var(--ua-color-accent) 10%, transparent); +} +.ua-autocomplete-hint { + font-size: var(--ua-font-size-sm); + color: var(--ua-color-text-muted); +} +.ua-autocomplete-empty { + padding: var(--ua-space-2) 0; + text-align: center; + font-size: var(--ua-font-size-sm); + color: var(--ua-color-text-muted); +} +@keyframes ua-ac-in { + from { opacity: 0; transform: translateY(-4px); } + to { opacity: 1; transform: translateY(0); } +} +@media (prefers-reduced-motion: reduce) { + .ua-autocomplete-pop.ua-open { animation: none; } + .ua-autocomplete-input, + .ua-autocomplete-opt { transition: none; } +}