diff --git a/.ua/index.json b/.ua/index.json index cea8fd7..9e01605 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T18:28:42.413Z", + "generatedAt": "2026-10-26T18:35:06.426Z", "repoRoot": ".", "packages": [ { @@ -2176,6 +2176,11 @@ "t": "(row: T) => unknown", "k": 1, "d": "传了才多一列展开钮:点开在该行下铺一条详情行(内容由这里给,展开态按 rowKey 记,筛选翻页不丢)" + }, + { + "n": "caption", + "t": "string", + "d": "表格可访问名:渲染成视觉隐藏的 ,读屏进表时靠它说清是哪一张表(纯图形上看不见,也不占位)" } ], "example": "dataTable({ data: users, selectable: true, columns: [{ key: 'name', header: '姓名', sortable: true }], pageSize: 5 })", diff --git a/apps/demo/main.ts b/apps/demo/main.ts index 4396a48..05905ef 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -1483,9 +1483,10 @@ const content = h( section( 'sec-table', '数据表格', - '粘性表头、斑马纹、行选择(全选三态 + 已选计数,选中行低视觉比重)、点表头或 Tab 聚焦后按 Enter/空格 排序(按住 Shift 点第二个表头即多列叠加,标记带优先级 ↑1 / ↓2)、定宽列表头右缘可拖拽或 ←→ 调列宽(双击复位)、工具栏筛选(0 行时按「有没有筛选词」分别提示「暂无数据」或「没有符合…的行」并给一键清除)、底部分页;工具栏「列」按钮勾选即可隐藏/恢复列(至少留一列,隐藏列不占表头也不进导出)、「导出 CSV」导的是筛选 + 排序后的全量行(不含勾选,与当前页无关)。', + '粘性表头、斑马纹、行选择(全选三态 + 已选计数,选中行低视觉比重)、点表头或 Tab 聚焦后按 Enter/空格 排序(按住 Shift 点第二个表头即多列叠加,标记带优先级 ↑1 / ↓2)、定宽列表头右缘可拖拽或 ←→ 调列宽(双击复位)、工具栏筛选(0 行时按「有没有筛选词」分别提示「暂无数据」或「没有符合…的行」并给一键清除)、底部分页;工具栏「列」按钮勾选即可隐藏/恢复列(至少留一列,隐藏列不占表头也不进导出)、「导出 CSV」导的是筛选 + 排序后的全量行(不含勾选,与当前页无关);caption 是表格的可访问名,视觉隐藏但读屏进表先念它。', card({ title: '用户表' }, dataTable({ data: users, + caption: '用户表:姓名 / 年龄 / 城市三列,可按列排序与筛选', // 可访问名:读屏进表先念这句 selectable: true, exportable: true, columnToggle: true, diff --git a/llms-full.txt b/llms-full.txt index 45acef3..bd7ae0a 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档(无图形版) -> 自动生成于 2026-10-26T18:28:42.413Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。 +> 自动生成于 2026-10-26T18:35:06.426Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。 > 组件 = 普通函数,传 props 返回 DOM;状态用 signal 双向绑定:读 signal() 写 signal(v)。 ## 快速上手 @@ -1046,6 +1046,7 @@ const name = signal(''); const f = form({ onSubmit: submit }, [formItem({ label: - columnToggle(默认 false):boolean —— 工具栏显示「列」按钮:弹层内勾选控制列显隐,至少保留一列(最后一列的勾选框锁死),缺省 false - hiddenColumns:Signal —— 受控隐藏列键集:与「列」面板双向同步,外部可据此持久化用户偏好;隐藏列不渲染、不进导出 - renderDetail(回调):(row: T) => unknown —— 传了才多一列展开钮:点开在该行下铺一条详情行(内容由这里给,展开态按 rowKey 记,筛选翻页不丢) +- caption:string —— 表格可访问名:渲染成视觉隐藏的 ,读屏进表时靠它说清是哪一张表(纯图形上看不见,也不占位) 示例: diff --git a/packages/skin/ui/src/dataTable.ts b/packages/skin/ui/src/dataTable.ts index 740ba33..c4b2efb 100644 --- a/packages/skin/ui/src/dataTable.ts +++ b/packages/skin/ui/src/dataTable.ts @@ -185,7 +185,7 @@ export function dataTable(props: DataTableProps): H props.columnToggle ? columnPicker({ columns: props.columns, hidden, disabled: busy }) : null, // 列显隐面板:勾选即重绘表头与单元格 props.exportable ? exportButton(table, () => shown(), props.exportName ?? 'table.csv') : null, // 导出筛选+排序后的全量行,列跟随当前可见列 ), - h('div', { class: 'ua-table-scroll' }, h('table', null, colgroup, thead, tbody)), + h('div', { class: 'ua-table-scroll' }, h('table', null, props.caption ? h('caption', { class: 'ua-visually-hidden' }, props.caption) : null, colgroup, thead, tbody)), // caption 视觉隐藏仍进无障碍树:表格才有名字 tablePager({ info, total: () => visible().total, diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index a2ccfb7..97f6ba1 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -80,6 +80,7 @@ export interface DataTableProps { columnToggle?: boolean; // 工具栏显示「列」按钮:弹层内勾选控制列显隐,至少保留一列;缺省 false hiddenColumns?: Signal; // 受控隐藏列键集:与「列」面板双向同步,供调用方记住用户偏好 onRowClick?: (row: T) => void; // 整行点击 / Enter / 空格的回调;传了行才可聚焦(未传时行不可交互) + caption?: string; // 表格可访问名(渲染成视觉隐藏的 ):读屏进表只念「表格」时,靠它说清是哪一张 } /*** 选项条目:select / radioGroup / tabs / segmented 共用的选项形状 ***/ diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index 038d1b1..c9171d4 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -314,13 +314,12 @@ "n": "password", "t": "boolean", "d": "密码框:原生打点渲染,内置「显示/隐藏」切换按钮(aria-label 同步);缺省普通文本" + }, + { + "n": "ariaLabel", + "t": "string", + "d": "无可见 label 时的可访问名(如「收件人」);缺省「文本输入」" } - , - { - "n": "ariaLabel", - "t": "string", - "d": "无可见 label 时的可访问名(如「收件人」);缺省「文本输入」" - } ], "example": "const name = signal(''); const el = textField({ value: name, placeholder: '输入名字…', onInput: (v) => console.log(v) })", "steps": [ @@ -388,13 +387,12 @@ "n": "size", "t": "'sm' | 'md' | 'lg'", "d": "高度档位:sm 紧凑 / md 默认 / lg 大触控目标,走 --ua-control-h-* 三档;缺省 md" + }, + { + "n": "ariaLabel", + "t": "string", + "d": "无可见 label 时的可访问名(如「数量」);缺省「数字输入」" } - , - { - "n": "ariaLabel", - "t": "string", - "d": "无可见 label 时的可访问名(如「数量」);缺省「数字输入」" - } ], "example": "const qty = signal(1); const el = inputNumber({ value: qty, min: 1, max: 99, onChange: (v) => console.log(v) })", "steps": [ @@ -456,13 +454,12 @@ "n": "autosize", "t": "boolean | { minRows?, maxRows? }", "d": "自适应内容高度:true 跟随内容涨落,对象态钳最小/最大行数,超出 maxRows 内部滚动;缺省固定行数" + }, + { + "n": "ariaLabel", + "t": "string", + "d": "无可见 label 时的可访问名(如「备注」);缺省「多行文本」" } - , - { - "n": "ariaLabel", - "t": "string", - "d": "无可见 label 时的可访问名(如「备注」);缺省「多行文本」" - } ], "example": "const bio = signal(''); textarea({ value: bio, rows: 4, placeholder: '一句话介绍…' })", "steps": [ @@ -539,13 +536,12 @@ "t": "(value: number) => void", "k": 1, "d": "拖动回调" + }, + { + "n": "ariaLabel", + "t": "string", + "d": "无可见 label 时的可访问名(如「音量」);缺省「数值」,区间模式自动带「下限 / 上限」" } - , - { - "n": "ariaLabel", - "t": "string", - "d": "无可见 label 时的可访问名(如「音量」);缺省「数值」,区间模式自动带「下限 / 上限」" - } ], "example": "const vol = signal(40); slider({ value: vol, min: 0, max: 100, step: 5, onChange: (v) => console.log(v) })", "steps": [ @@ -2050,6 +2046,11 @@ "t": "(row: T) => unknown", "k": 1, "d": "传了才多一列展开钮:点开在该行下铺一条详情行(内容由这里给,展开态按 rowKey 记,筛选翻页不丢)" + }, + { + "n": "caption", + "t": "string", + "d": "表格可访问名:渲染成视觉隐藏的 ,读屏进表时靠它说清是哪一张表(纯图形上看不见,也不占位)" } ], "example": "dataTable({ data: users, selectable: true, columns: [{ key: 'name', header: '姓名', sortable: true }], pageSize: 5 })", @@ -4674,13 +4675,46 @@ "title": "行内编辑 Editable", "demo": "sec-editable", "props": [ - { "n": "value", "t": "Signal", "r": 1, "d": "展示值,双向绑定:只有提交才写回,Esc 取消绝不落值" }, - { "n": "placeholder", "t": "string", "df": "'点击填写'", "d": "空值时的占位文案,颜色走辅助文字档" }, - { "n": "label", "t": "string", "df": "'编辑'", "d": "读屏用的字段名,作静止态按钮 aria-label 的前缀(如「标题:季度目标」)" }, - { "n": "multiline", "t": "boolean", "d": "多行模式(textarea):Enter 换行,Ctrl / Cmd + Enter 才提交;缺省单行" }, - { "n": "disabled", "t": "boolean | Signal", "d": "禁用只读,布尔与信号双口径;点了也不进编辑态" }, - { "n": "validate", "t": "(v: string) => string | null", "k": 1, "d": "提交校验:返回文案即拒绝提交、保持编辑态并标红(aria-invalid + role=alert),返回 null 表示通过" }, - { "n": "onCommit", "t": "(v: string) => void", "k": 1, "d": "提交回调,值已写回信号之后触发;取消不触发" } + { + "n": "value", + "t": "Signal", + "r": 1, + "d": "展示值,双向绑定:只有提交才写回,Esc 取消绝不落值" + }, + { + "n": "placeholder", + "t": "string", + "df": "'点击填写'", + "d": "空值时的占位文案,颜色走辅助文字档" + }, + { + "n": "label", + "t": "string", + "df": "'编辑'", + "d": "读屏用的字段名,作静止态按钮 aria-label 的前缀(如「标题:季度目标」)" + }, + { + "n": "multiline", + "t": "boolean", + "d": "多行模式(textarea):Enter 换行,Ctrl / Cmd + Enter 才提交;缺省单行" + }, + { + "n": "disabled", + "t": "boolean | Signal", + "d": "禁用只读,布尔与信号双口径;点了也不进编辑态" + }, + { + "n": "validate", + "t": "(v: string) => string | null", + "k": 1, + "d": "提交校验:返回文案即拒绝提交、保持编辑态并标红(aria-invalid + role=alert),返回 null 表示通过" + }, + { + "n": "onCommit", + "t": "(v: string) => void", + "k": 1, + "d": "提交回调,值已写回信号之后触发;取消不触发" + } ], "example": "const title = signal('季度目标'); editable({ value: title, label: '标题', validate: (v) => (v ? null : '标题不能为空'), onCommit: (v) => toast.success('已保存:' + v) })", "steps": [ @@ -4694,4 +4728,4 @@ } ] } -} \ No newline at end of file +} diff --git a/packages/tools/cli/bin/ua.js b/packages/tools/cli/bin/ua.js index 529518f..2d4bab1 100644 --- a/packages/tools/cli/bin/ua.js +++ b/packages/tools/cli/bin/ua.js @@ -1797,6 +1797,20 @@ function checkRoleNames(pkgs) { return issues; } +/*** 校验表格可访问名:没有 caption 的表格读屏只念「表格」,几张表同屏时分不清哪张是哪张 ***/ +function checkTableCaption(pkgs) { + const issues = []; + for (const pkg of pkgs) { + if (pkg.type !== 'skin-dom') continue; + const tablePath = path.join(ROOT, pkg.dir, 'src', 'dataTable.ts'); + if (!fs.existsSync(tablePath)) continue; + const src = fs.readFileSync(tablePath, 'utf8'); + if (!/props\.caption \? h\('caption'/.test(src)) issues.push(`${pkg.name}/src/dataTable.ts 没渲染 caption:表格缺可访问名,读屏只说「表格」`); + if (!/caption\?: string/.test(fs.readFileSync(path.join(ROOT, pkg.dir, 'src', 'types.ts'), 'utf8'))) issues.push(`${pkg.name}/src/types.ts 的 DataTableProps 缺 caption:没入口就永远命名不了`); + } + return issues; +} + /*** 校验同义词表:目标 id 必须真实存在(改名后残留会让回退指到空气),同一个词不得归两组(歧义会让结果随表序漂移) ***/ function checkSynonyms(ids) { const issues = []; @@ -1886,6 +1900,7 @@ function cmdVerify() { issues.push(...checkFormBusy(pkgs)); // 提交忙碌态必须有可见反馈 issues.push(...checkFormLabel(pkgs)); // 标签必须真正归属控件 issues.push(...checkRoleNames(pkgs)); // listbox / radiogroup 必须有名字 + issues.push(...checkTableCaption(pkgs)); // 表格必须有可访问名 issues.push(...checkSynonyms(new Set(pkgs.flatMap((p) => (p.docs?.components ?? []).map((c) => c.id))))); // 同义词表指向的组件必须真实存在 checkDarkTokens(issues); checkTokenParity(issues); @@ -1898,7 +1913,7 @@ function cmdVerify() { console.error(`${issues.length} violation(s)`); process.exit(1); } - console.log('verify OK (manifest ↔ docs ↔ demo 一致,文档 props ↔ 入参接口双向一致,皮肤无硬编码颜色与未定义令牌、暗色令牌齐全、tokens.json ↔ tokens.css 名字与值双源一致、@keyframes 无复制粘贴的重复帧、滚动容器全在细条规则内,README 组件清单与分组同步,backlog ↔ 留痕双向一致(编号严格递增、无重复 id、留痕时间线单调且带 +08:00,每个 iter 提交都有留痕),组合配方结构完整,MCP 工具清单三处一致,搜索同义词表目标存在且无歧义,combobox / slider / range 控件与 listbox / radiogroup 容器都有可访问名,toast 有 live 区域与 alert 抢占播报,表单错误文案被 aria-describedby 关联、标签归属控件(for / aria-labelledby)、重置真复位、错误环只在聚焦时亮、汇总条随校验重算、提交按钮有忙碌态,视觉回归抽查清单十九组件 × 五维度齐全)'); + console.log('verify OK (manifest ↔ docs ↔ demo 一致,文档 props ↔ 入参接口双向一致,皮肤无硬编码颜色与未定义令牌、暗色令牌齐全、tokens.json ↔ tokens.css 名字与值双源一致、@keyframes 无复制粘贴的重复帧、滚动容器全在细条规则内,README 组件清单与分组同步,backlog ↔ 留痕双向一致(编号严格递增、无重复 id、留痕时间线单调且带 +08:00,每个 iter 提交都有留痕),组合配方结构完整,MCP 工具清单三处一致,搜索同义词表目标存在且无歧义,combobox / slider / range 控件与 listbox / radiogroup 容器都有可访问名、表格有 caption,toast 有 live 区域与 alert 抢占播报,表单错误文案被 aria-describedby 关联、标签归属控件(for / aria-labelledby)、重置真复位、错误环只在聚焦时亮、汇总条随校验重算、提交按钮有忙碌态,视觉回归抽查清单十九组件 × 五维度齐全)'); } /*** 校验 git 提交信息是否符合 COMMITTING.md 规范(参数为 message 文件路径或直接 message 文本),违规退出码 1 ***/