diff --git a/.ua/index.json b/.ua/index.json index 428d029..65ab171 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T07:21:05.139Z", + "generatedAt": "2026-10-26T07:22:32.759Z", "repoRoot": ".", "packages": [ { @@ -206,7 +206,8 @@ "calendar(props)：月历，整月网格内嵌页面（排期 / 值班 / 日程），每日可带 marker 标记文案，方向键漫游 + Enter 选中，翻月走 onMonthChange", "typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮", "grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列", - "floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label" + "floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label", + "mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value" ], "keyTypes": [ "ButtonProps", @@ -3262,6 +3263,56 @@ "右下角已被 backTop 占用，页面同时有返回顶部时用 position: 'left-bottom'", "纯展示 + 单回调，没有选中态与开合状态；需要多级操作请用 menu / popover 挂在 onClick 上" ] + }, + { + "id": "mentions", + "title": "@提及输入 Mentions", + "demo": "sec-mentions", + "props": [ + { + "n": "items", + "t": "MentionItem[]", + "r": 1, + "d": "候选池：每项含 name（插入正文的名字）、label（显示名）、description（说明）、keywords（只参与过滤的额外匹配词）" + }, + { + "n": "value", + "t": "Signal", + "d": "受控文本信号；不传则组件内部维护（拿不到外部读取时不要传）" + }, + { + "n": "rows", + "t": "number", + "df": "3", + "d": "输入框行数" + }, + { + "n": "placeholder", + "t": "string", + "d": "占位文案" + }, + { + "n": "onSelect", + "t": "(item: MentionItem) => void", + "k": 1, + "d": "选中某人后的回调（弹层已收起，正文已替换）" + }, + { + "n": "onInput", + "t": "(text: string) => void", + "k": 1, + "d": "每次输入的回调，参数为当前全文（已写回 value 信号）" + } + ], + "example": "const text = signal(''); mentions({ items: [{ name: 'zhangsan', label: '张三', description: '前端', keywords: ['zs'] }], value: text, placeholder: '输入 @ 叫人', onSelect: (it) => toast.info(it.label) })", + "steps": [ + "在输入框里键入 @ 触发弹层，继续打字按 name / keywords 过滤（拼音、工号放 keywords，不出现在候选行里）", + "键盘：↑↓ 环形移动高亮、Enter 或 Tab 选中、Esc 只收这一层弹层（stopPropagation，不会连带关掉外层弹窗）", + "选中后组件按光标位置把 @片段替换成「@名字 + 空格」，光标落在其后，可以接着打字", + "受控用法：传 value 信号并在 onSelect / onInput 里读最新全文；外部改信号会同步回输入框，别同时再手写 input 事件", + "弹层贴在输入框下沿而非跟随光标行（多行输入里更稳定，也不会被行高算错），需要跟随光标请自绘", + "要限制可选人范围就在 items 上做过滤，组件不做远程搜索；远程场景用 onInput 拉数据后重建 items" + ] } ] }, diff --git a/AGENTS.md b/AGENTS.md index 3dfd445..78265ef 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）：63 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 +- `packages/skin/ui`（@ui-arch/ui）：64 个 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 63baa62..29e0cef 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,7 +34,7 @@ ui-arch-mvp/ │ │ ├── table-core/ # 表格状态内核 │ │ └── frame/ # 信号 + hyperscript 微框架 │ ├── skin/ # 皮肤层（DOM 组件，可发布） -│ │ └── ui/ # 63 个组件 + ui.css +│ │ └── ui/ # 64 个组件 + ui.css │ ├── design/ # 资产层（可发布） │ │ └── tokens/ # --ua-* 设计令牌 │ └── tools/ # 工程层（private，不发布） diff --git a/README.md b/README.md index d46cf7e..1e52e5c 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,13 @@ npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全 npm run changelog # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移） ``` -## 组件（共 63 个） +## 组件（共 64 个） -accordion · affix · alert · anchor · autoComplete · avatar · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · list · menu · modal · multiSelect · notification · pagination · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · tour · transfer · tree · typography · upload · watermark +accordion · affix · alert · anchor · autoComplete · avatar · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · list · menu · modal · mentions · multiSelect · notification · pagination · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · tour · transfer · tree · typography · upload · watermark -分组：表单（button / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / popconfirm / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / anchor）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel / calendar / typography）、其他（floatButton / grid / space / divider / splitter / backTop / affix / tour / watermark）。 +分组：表单（button / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / popconfirm / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / anchor）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel / calendar / typography）、其他（floatButton / grid / space / divider / splitter / backTop / affix / tour / watermark）。 ## 可访问性约定 @@ -32,7 +32,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · backTop · ba |---|---| | `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：63 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | +| `packages/skin/ui` | @ui-arch/ui：64 个 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 6e45a96..617223a 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -46,6 +46,7 @@ import { watermark, menu, modal, + mentions, multiSelect, pagination, popconfirm, @@ -248,6 +249,15 @@ const range = signal('week'); // —— 时间线：false 时末尾显示「进行中」虚线节点，true 表示流程已结束 —— const flowDone = signal(false); +// —— @提及：受控文本信号，选中的人写进评论正文 —— +const comment = signal(''); +const teamMembers = [ + { name: 'zhangsan', label: '张三', description: '前端 · 组件库', keywords: ['zs', '1001'] }, + { name: 'lisi', label: '李四', description: '后端 · 订单服务', keywords: ['ls', '1002'] }, + { name: 'wangwu', label: '王五', description: '设计 · 交互', keywords: ['ww', '1003'] }, + { name: 'zhaoliu', label: '赵六', description: 'QA · 回归', keywords: ['zl', '1004'] }, +]; + const content = h( 'div', { class: 'page' }, @@ -1306,6 +1316,26 @@ const content = h( card({ title: zone }, typography({ content: '健康检查通过', type: 'success', variant: 'paragraph' }))), ), ), + section( + 'sec-mentions', + '@提及输入', + 'mentions 在 textarea 里键入 @ 就弹候选：↑↓ 环形移动、Enter/Tab 选中、Esc 只收这一层弹层；选中后按光标位置替换 @片段并写回 value 信号。输入拼音或工号也能命中（keywords 只参与过滤不显示）。', + grid({ min: '320px' }, + card({ title: '评论框' }, + mentions({ + items: teamMembers, + value: comment, + rows: 3, + placeholder: '输入 @ 叫人来评审……', + onSelect: (item) => toast.info(`已提及 ${item.label}`), + }), + ), + card({ title: '当前正文' }, + h('div', { class: 'out' }, () => comment() || '（还没写）'), + typography({ variant: 'paragraph', type: 'secondary', content: '值由 value 信号驱动，外部改信号输入框同步；这里就是同一个信号。' }), + ), + ), + ), section( 'sec-floatbutton', '悬浮操作按钮', diff --git a/llms-full.txt b/llms-full.txt index 8a79b8f..42fe4ed 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档（无图形版） -> 自动生成于 2026-10-26T07:21:05.139Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 +> 自动生成于 2026-10-26T07:22:32.759Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。 ## 快速上手 @@ -1758,6 +1758,34 @@ document.body.append(floatButton({ icon: '+', label: '新建工单', position: ' 现场演示：apps/docs/demo.html#sec-floatbutton +### mentions — @提及输入 Mentions + +参数： + +- items（必填）：MentionItem[] —— 候选池：每项含 name（插入正文的名字）、label（显示名）、description（说明）、keywords（只参与过滤的额外匹配词） +- value：Signal —— 受控文本信号；不传则组件内部维护（拿不到外部读取时不要传） +- rows（默认 3）：number —— 输入框行数 +- placeholder：string —— 占位文案 +- onSelect（回调）：(item: MentionItem) => void —— 选中某人后的回调（弹层已收起，正文已替换） +- onInput（回调）：(text: string) => void —— 每次输入的回调，参数为当前全文（已写回 value 信号） + +示例： + +``` +const text = signal(''); mentions({ items: [{ name: 'zhangsan', label: '张三', description: '前端', keywords: ['zs'] }], value: text, placeholder: '输入 @ 叫人', onSelect: (it) => toast.info(it.label) }) +``` + +手把手： + +1. 在输入框里键入 @ 触发弹层，继续打字按 name / keywords 过滤（拼音、工号放 keywords，不出现在候选行里） +2. 键盘：↑↓ 环形移动高亮、Enter 或 Tab 选中、Esc 只收这一层弹层（stopPropagation，不会连带关掉外层弹窗） +3. 选中后组件按光标位置把 @片段替换成「@名字 + 空格」，光标落在其后，可以接着打字 +4. 受控用法：传 value 信号并在 onSelect / onInput 里读最新全文；外部改信号会同步回输入框，别同时再手写 input 事件 +5. 弹层贴在输入框下沿而非跟随光标行（多行输入里更稳定，也不会被行高算错），需要跟随光标请自绘 +6. 要限制可选人范围就在 items 上做过滤，组件不做远程搜索；远程场景用 onInput 拉数据后重建 items + +现场演示：apps/docs/demo.html#sec-mentions + API 速览： - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交） @@ -1825,6 +1853,7 @@ API 速览： - typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮 - grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列 - floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label +- mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value 一行用法： diff --git a/llms.txt b/llms.txt index 1cd5bba..08f0175 100644 --- a/llms.txt +++ b/llms.txt @@ -112,6 +112,7 @@ - typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮 - grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列 - floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label + - mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value - 用法: `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/index.ts b/packages/skin/ui/src/index.ts index a32c991..b226737 100644 --- a/packages/skin/ui/src/index.ts +++ b/packages/skin/ui/src/index.ts @@ -63,3 +63,4 @@ export { calendar } from './calendar.js'; export { typography } from './typography.js'; export { grid } from './grid.js'; export { floatButton } from './floatButton.js'; +export { mentions } from './mentions.js'; diff --git a/packages/skin/ui/src/mentions.ts b/packages/skin/ui/src/mentions.ts new file mode 100644 index 0000000..60cf1b8 --- /dev/null +++ b/packages/skin/ui/src/mentions.ts @@ -0,0 +1,114 @@ +import { effect, h, signal } from '@ui-arch/frame'; +import type { MentionItem, MentionsProps } from './types.js'; + +// 每个实例的 listbox id 前缀，保证 aria-activedescendant 唯一 +let seq = 0; + +/*** 取光标前的 @ 触发词（不含 @ 本身）：没有未闭合的 @ 片段时返回 null ***/ +function tokenBefore(text: string, caret: number): string | null { + const match = /@([^\s@]*)$/.exec(text.slice(0, caret)); + return match ? match[1] : null; +} + +/*** 用选中的名字替换光标前的 @片段，返回替换后的全文与新光标位置 ***/ +function applyPick(text: string, caret: number, name: string): { text: string; caret: number } { + const head = text.slice(0, caret).replace(/@[^\s@]*$/, `@${name} `); + return { text: head + text.slice(caret), caret: head.length }; +} + +/*** @提及输入：textarea 内键入 @ 弹候选，↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层；弹层贴输入框下沿，选中按光标替换 @片段 ***/ +export function mentions(props: MentionsProps): HTMLElement { + const uid = `ua-mentions-${++seq}`; + const items = props.items; + const value = props.value ?? signal(''); + const open = signal(false); // 弹层开合 + const query = signal(''); // 当前 @ 后的过滤词 + const active = signal(0); // 高亮项下标 + const input = h('textarea', { + class: 'ua-mentions-input', + rows: String(props.rows ?? 3), + placeholder: props.placeholder ?? '', + 'aria-autocomplete': 'list', + 'aria-controls': uid, + 'aria-expanded': 'false', + }) as HTMLTextAreaElement; + input.value = value(); + const list = h('div', { class: 'ua-mentions-pop', role: 'listbox', id: uid }); + const wrap = h('div', { class: 'ua-mentions' }, input, list); + + // 候选：空过滤词给全量，否则按名字 / 关键词做包含匹配 + const filtered = (): MentionItem[] => (query() + ? items.filter((it) => it.name.includes(query()) || (it.keywords ?? []).some((k) => k.includes(query()))) + : items); + + /*** 重绘弹层：同步显隐、高亮项与 aria-activedescendant（无候选时不开层） ***/ + const paint = (): void => { + const shown = filtered(); + const visible = open() && shown.length > 0; + wrap.classList.toggle('is-open', visible); + input.setAttribute('aria-expanded', String(visible)); + list.replaceChildren(...shown.map((item, i) => h('div', { + class: `ua-mentions-item${i === active() ? ' is-active' : ''}`, + role: 'option', + id: `${uid}-${i}`, + 'aria-selected': i === active() ? 'true' : 'false', + onmousedown: (e: Event) => { e.preventDefault(); pick(item); }, // 阻止默认让 textarea 不失焦 + }, h('span', { class: 'ua-mentions-name' }, item.label), + item.description ? h('span', { class: 'ua-mentions-desc' }, item.description) : null))); + if (visible) input.setAttribute('aria-activedescendant', `${uid}-${active()}`); + else input.removeAttribute('aria-activedescendant'); + }; + + /*** 选中候选：替换光标前的 @片段、写回信号、光标落到插入文本之后 ***/ + const pick = (item: MentionItem): void => { + const caret = input.selectionStart ?? input.value.length; + const next = applyPick(input.value, caret, item.name); + input.value = next.text; + value(next.text); + input.setSelectionRange(next.caret, next.caret); + input.focus(); + open(false); + query(''); + paint(); + props.onSelect?.(item); + }; + + input.addEventListener('input', () => { + value(input.value); + props.onInput?.(input.value); + const token = tokenBefore(input.value, input.selectionStart ?? input.value.length); + query(token ?? ''); + active(0); // 每次输入重新从第一项开始高亮 + open(token !== null); + paint(); + }); + + input.addEventListener('keydown', (e) => { + if (!open()) return; // 未开层时所有按键交给浏览器 + const shown = filtered(); + if (e.key === 'Escape') { + e.preventDefault(); + e.stopPropagation(); // 只收本层，不连带外层弹层 + open(false); + paint(); + return; + } + if (e.key === 'ArrowDown' || e.key === 'ArrowUp') { + e.preventDefault(); + active((active() + (e.key === 'ArrowDown' ? 1 : -1) + shown.length) % shown.length); // 环形移动 + paint(); + return; + } + if ((e.key === 'Enter' || e.key === 'Tab') && shown.length) { + e.preventDefault(); + pick(shown[Math.min(active(), shown.length - 1)]); + } + }); + + input.addEventListener('blur', () => { open(false); paint(); }); // 失焦收起 + effect(() => { + const outer = value(); + if (outer !== input.value) input.value = outer; // 外部改信号时同步输入框 + }); + return wrap; +} diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index c627263..0a55bc1 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -777,4 +777,22 @@ export interface FloatButtonProps { onClick?: () => void; // 点击回调 } +/*** @提及候选项 ***/ +export interface MentionItem { + name: string; // 插入正文的名字（@ 之后的部分，如 zhangsan） + label: string; // 候选行显示名称（如 张三） + description?: string; // 候选行右侧说明（部门 / 邮箱） + keywords?: string[]; // 额外匹配词（拼音、工号），不显示只参与过滤 +} + +/*** @提及输入入参 ***/ +export interface MentionsProps { + items: MentionItem[]; // 候选池：键入 @ 后按名字 / 关键词过滤 + value?: Signal; // 受控文本信号；不传则内部维护 + rows?: number; // 输入框行数；缺省 3 + placeholder?: string; // 占位文案 + onSelect?: (item: MentionItem) => void; // 选中某人后的回调（弹层已收起） + onInput?: (text: string) => void; // 每次输入的回调，参数为当前全文 +} + export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方 diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index 5de257c..8db10ee 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -77,7 +77,8 @@ "calendar(props)：月历，整月网格内嵌页面（排期 / 值班 / 日程），每日可带 marker 标记文案，方向键漫游 + Enter 选中，翻月走 onMonthChange", "typography(props)：排版文本，variant 决定语义（标题出 h1-h5 / 段落出 p / 行内出 span），支持语义色、装饰位、对齐、多行截断与复制按钮", "grid(props, ...children)：栅格容器，columns 固定列数或 min 走 auto-fit 自适应列宽，gutter 统一列间距，窄屏自动降为单列", - "floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label" + "floatButton(props)：悬浮操作按钮，固定停靠左下 / 右下角，label 缺省为纯图标圆形，badge 走角标，tooltip 兼作 aria-label", + "mentions(props)：@提及输入，textarea 内键入 @ 弹候选（名字 / 关键词过滤），↑↓ 环形移动、Enter/Tab 选中、Esc 只收本层，选中按光标替换并写回 value" ], "keyTypes": [ "ButtonProps", @@ -3133,6 +3134,56 @@ "右下角已被 backTop 占用，页面同时有返回顶部时用 position: 'left-bottom'", "纯展示 + 单回调，没有选中态与开合状态；需要多级操作请用 menu / popover 挂在 onClick 上" ] + }, + { + "id": "mentions", + "title": "@提及输入 Mentions", + "demo": "sec-mentions", + "props": [ + { + "n": "items", + "t": "MentionItem[]", + "r": 1, + "d": "候选池：每项含 name（插入正文的名字）、label（显示名）、description（说明）、keywords（只参与过滤的额外匹配词）" + }, + { + "n": "value", + "t": "Signal", + "d": "受控文本信号；不传则组件内部维护（拿不到外部读取时不要传）" + }, + { + "n": "rows", + "t": "number", + "df": "3", + "d": "输入框行数" + }, + { + "n": "placeholder", + "t": "string", + "d": "占位文案" + }, + { + "n": "onSelect", + "t": "(item: MentionItem) => void", + "k": 1, + "d": "选中某人后的回调（弹层已收起，正文已替换）" + }, + { + "n": "onInput", + "t": "(text: string) => void", + "k": 1, + "d": "每次输入的回调，参数为当前全文（已写回 value 信号）" + } + ], + "example": "const text = signal(''); mentions({ items: [{ name: 'zhangsan', label: '张三', description: '前端', keywords: ['zs'] }], value: text, placeholder: '输入 @ 叫人', onSelect: (it) => toast.info(it.label) })", + "steps": [ + "在输入框里键入 @ 触发弹层，继续打字按 name / keywords 过滤（拼音、工号放 keywords，不出现在候选行里）", + "键盘：↑↓ 环形移动高亮、Enter 或 Tab 选中、Esc 只收这一层弹层（stopPropagation，不会连带关掉外层弹窗）", + "选中后组件按光标位置把 @片段替换成「@名字 + 空格」，光标落在其后，可以接着打字", + "受控用法：传 value 信号并在 onSelect / onInput 里读最新全文；外部改信号会同步回输入框，别同时再手写 input 事件", + "弹层贴在输入框下沿而非跟随光标行（多行输入里更稳定，也不会被行高算错），需要跟随光标请自绘", + "要限制可选人范围就在 items 上做过滤，组件不做远程搜索；远程场景用 onInput 拉数据后重建 items" + ] } ] } diff --git a/packages/skin/ui/ui.css b/packages/skin/ui/ui.css index 8ae8e6c..24072fd 100644 --- a/packages/skin/ui/ui.css +++ b/packages/skin/ui/ui.css @@ -4151,3 +4151,80 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); } transform: none; } } + +/* —— @提及输入：弹层贴输入框下沿，候选行高亮走淡色底 —— */ +.ua-mentions { + position: relative; + display: inline-block; + width: 100%; +} +.ua-mentions-input { + width: 100%; + box-sizing: border-box; + padding: var(--ua-space-2) var(--ua-space-3); + border: 1px solid var(--ua-color-border); + border-radius: var(--ua-radius-md); + background: var(--ua-color-surface); + color: var(--ua-color-text); + font: inherit; + font-size: var(--ua-font-size-md); + line-height: 1.6; + resize: vertical; + transition: border-color 0.15s ease, box-shadow 0.15s ease; +} +.ua-mentions-input:focus { + outline: none; + border-color: var(--ua-color-accent); + box-shadow: 0 0 0 3px color-mix(in srgb, var(--ua-color-accent) 22%, transparent); +} +.ua-mentions-pop { + position: absolute; + left: 0; + right: 0; + top: calc(100% + 4px); + z-index: 30; + display: none; + max-height: 220px; + overflow-y: auto; + padding: var(--ua-space-1); + border: 1px solid var(--ua-color-border); + border-radius: var(--ua-radius-md); + background: var(--ua-color-surface); + box-shadow: 0 12px 28px color-mix(in srgb, var(--ua-color-text) 16%, transparent); +} +.ua-mentions.is-open .ua-mentions-pop { + display: block; + animation: ua-mentions-in 0.15s ease; +} +.ua-mentions-item { + display: flex; + align-items: baseline; + gap: var(--ua-space-2); + padding: var(--ua-space-2) var(--ua-space-2); + border-radius: var(--ua-radius-sm); + cursor: pointer; + transition: background 0.15s ease; +} +.ua-mentions-item.is-active { + background: color-mix(in srgb, var(--ua-color-accent) 10%, transparent); /* 选中态低视觉比重 */ +} +.ua-mentions-name { + color: var(--ua-color-text); +} +.ua-mentions-desc { + color: var(--ua-color-text-muted); + font-size: var(--ua-font-size-sm); +} +@keyframes ua-mentions-in { + from { opacity: 0; transform: translateY(-4px); } + to { opacity: 1; transform: none; } +} +@media (prefers-reduced-motion: reduce) { + .ua-mentions.is-open .ua-mentions-pop { + animation: none; + } + .ua-mentions-input, + .ua-mentions-item { + transition: none; + } +}