From e54fdb6f22a1e76b3558622feed6e4e3215a23b1 Mon Sep 17 00:00:00 2001 From: HIsheR Date: Mon, 26 Oct 2026 12:19:23 +0800 Subject: [PATCH] =?UTF-8?q?iter(g55):=20=E6=96=B0=E5=A2=9E=20checkboxGroup?= =?UTF-8?q?=20=E5=A4=9A=E9=80=89=E7=BB=84=E7=BB=84=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .ua/index.json | 60 ++++++++++++++++++++++++++- AGENTS.md | 2 +- ARCHITECTURE.md | 2 +- README.md | 8 ++-- apps/demo/main.ts | 27 ++++++++++++ llms-full.txt | 31 +++++++++++++- llms.txt | 1 + packages/skin/ui/src/checkboxGroup.ts | 60 +++++++++++++++++++++++++++ packages/skin/ui/src/index.ts | 1 + packages/skin/ui/src/types.ts | 19 +++++++++ packages/skin/ui/ua.manifest.json | 58 +++++++++++++++++++++++++- packages/skin/ui/ui.css | 11 +++++ 12 files changed, 270 insertions(+), 10 deletions(-) create mode 100644 packages/skin/ui/src/checkboxGroup.ts diff --git a/.ua/index.json b/.ua/index.json index ae44533..31e8fc1 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T04:18:05.467Z", + "generatedAt": "2026-10-26T04:19:05.352Z", "repoRoot": ".", "packages": [ { @@ -196,7 +196,8 @@ "backTop(props):返回顶部悬浮按钮,越过阈值才浮现,外环 conic-gradient 显示已滚比例,点击平滑回顶", "colorPicker(props):颜色选择,预设色板(缺省语义令牌色)+ 原生取色器 + 手输 CSS 颜色串,value 为颜色串信号", "tour(props):引导漫游,返回 { el, start, close } 句柄;聚光框按 target 选择器定位,卡片自动选方位,Esc / 跳过走 onClose", - "watermark(props, ...children):内容容器 + 平铺水印覆盖层,canvas 生成单元、颜色取自令牌,覆盖层不挡交互" + "watermark(props, ...children):内容容器 + 平铺水印覆盖层,canvas 生成单元、颜色取自令牌,覆盖层不挡交互", + "checkboxGroup(props):多选组,value 为数组信号,min/max 用禁用边界项实现(不抛错),checkAll 支持半选且只统计未禁用项" ], "keyTypes": [ "ButtonProps", @@ -2461,6 +2462,61 @@ "color 传 var(--ua-*) 时会先解析成计算值(canvas 不认 CSS 变量),所以暗色主题下颜色会自动跟随", "覆盖层为 pointer-events:none,下方按钮/输入框照常可点;watermark 根节点自带圆角与裁剪" ] + }, + { + "id": "checkboxGroup", + "title": "多选组 CheckboxGroup", + "demo": "sec-checkgroup", + "props": [ + { + "n": "options", + "t": "CheckOption[]", + "r": 1, + "d": "选项集合:value / label / 可选 disabled" + }, + { + "n": "value", + "t": "Signal", + "d": "选中值数组信号;不传则内部维护" + }, + { + "n": "min", + "t": "number", + "d": "最少选几项:到下限后已选项禁用,防止取消" + }, + { + "n": "max", + "t": "number", + "d": "最多选几项:到上限后未选项禁用" + }, + { + "n": "checkAll", + "t": "boolean", + "d": "是否显示全选行(含半选);缺省 false" + }, + { + "n": "direction", + "t": "'horizontal' | 'vertical'", + "d": "排列方向;缺省 horizontal" + }, + { + "n": "disabled", + "t": "boolean | Signal", + "d": "整组禁用" + }, + { + "n": "onChange", + "t": "(values: string[]) => void", + "d": "变更回调(传副本)" + } + ], + "example": "checkboxGroup({ value: permPick, min: 1, max: 3, checkAll: true, options: [{ value: 'read', label: '读取' }, { value: 'write', label: '写入' }] })", + "steps": [ + "options 顺序即渲染顺序;勾选后把整份数组写回 value 信号并触发 onChange", + "max 生效时未选项自动禁用,min 生效时已选项自动禁用——用禁用表达边界,不抛错也不静默回滚", + "checkAll 行的选中/半选只统计未禁用项,禁用项不计入基数", + "direction 传 vertical 改为纵向排列;disabled 支持信号,整组响应式禁用" + ] } ] }, diff --git a/AGENTS.md b/AGENTS.md index 0a1fcbe..2e4f086 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):53 个 DOM 组件(表单 / 反馈 / 浮层 / 导航 / 表格),样式只消费令牌 +- `packages/skin/ui`(@ui-arch/ui):54 个 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 7c6fadb..e12061e 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,7 +34,7 @@ ui-arch-mvp/ │ │ ├── table-core/ # 表格状态内核 │ │ └── frame/ # 信号 + hyperscript 微框架 │ ├── skin/ # 皮肤层(DOM 组件,可发布) -│ │ └── ui/ # 53 个组件 + ui.css +│ │ └── ui/ # 54 个组件 + ui.css │ ├── design/ # 资产层(可发布) │ │ └── tokens/ # --ua-* 设计令牌 │ └── tools/ # 工程层(private,不发布) diff --git a/README.md b/README.md index fac3cf0..6afe25d 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 ``` -## 组件(共 53 个) +## 组件(共 54 个) -accordion · alert · autoComplete · avatar · backTop · badge · breadcrumb · button · carousel · card · cascader · checkbox · colorPicker · dataTable · datePicker · 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 · tour · transfer · tree · upload · watermark +accordion · alert · autoComplete · avatar · backTop · badge · breadcrumb · button · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · dataTable · datePicker · 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 · tour · transfer · tree · upload · watermark -分组:表单(button / textField / inputNumber / textarea / checkbox / colorPicker / switchButton / select / radioGroup / slider / rate / autoComplete / datePicker / 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 / backTop / tour / watermark)。 +分组:表单(button / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / radioGroup / slider / rate / autoComplete / datePicker / 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 / backTop / tour / watermark)。 ## 可访问性约定 @@ -31,7 +31,7 @@ accordion · alert · autoComplete · avatar · backTop · badge · breadcrumb |---|---| | `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:53 个 DOM 组件 + ui.css(只消费 `--ua-*` 令牌) | +| `packages/skin/ui` | @ui-arch/ui:54 个 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 541c8f0..1c6bde2 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -19,6 +19,7 @@ import { card, cascader, checkbox, + checkboxGroup, colorPicker, dataTable, datePicker, @@ -191,6 +192,7 @@ const listPick = signal(''); // 列表点击选中的条目标题 const slideIndex = signal(0); // 轮播当前下标(外部受控演示) const cascaderPath = signal(['east', 'sh']); // 级联选择路径(外部受控演示) const splitSizes = signal([35, 65]); // 分栏比例(外部受控演示) +const permPick = signal(['read']); // 多选组选中值(外部受控演示) const colorVal = signal('var(--ua-color-accent)'); // 颜色选择值(外部受控演示) const dateVal = signal('2026-10-26'); // 日期选择值(外部受控演示) const acValue = signal(''); // 自动补全输入值(外部受控演示) @@ -690,6 +692,31 @@ const content = h( button({ label: '错误(可关)', variant: 'danger', onClick: () => notification({ title: '保存失败', description: '服务端返回 500,请稍后重试', variant: 'danger' }) }), ), ), + section( + 'sec-checkgroup', + '多选组', + 'checkboxGroup:数组信号双向绑定,min/max 用「禁用边界项」代替报错,checkAll 带半选,只统计未禁用项。', + h( + 'div', + { class: 'col' }, + checkboxGroup({ + value: permPick, + min: 1, + max: 3, + checkAll: true, + onChange: (v) => toast.info(`已选 ${v.length} 项`), + options: [ + { value: 'read', label: '读取' }, + { value: 'write', label: '写入' }, + { value: 'delete', label: '删除' }, + { value: 'share', label: '分享' }, + { value: 'audit', label: '审计日志(不可授予)', disabled: true }, + ], + }), + checkboxGroup({ direction: 'vertical', options: [{ value: 'a', label: '纵向 A' }, { value: 'b', label: '纵向 B' }] }), + h('span', { class: 'out' }, () => `已选:${permPick().join(' / ') || '无'}(下限 1、上限 3)`), + ), + ), section( 'sec-watermark', '水印', diff --git a/llms-full.txt b/llms-full.txt index 695233a..31783a7 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档(无图形版) -> 自动生成于 2026-10-26T04:18:05.467Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。 +> 自动生成于 2026-10-26T04:19:05.352Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。 > 组件 = 普通函数,传 props 返回 DOM;状态用 signal 双向绑定:读 signal() 写 signal(v)。 ## 快速上手 @@ -1412,6 +1412,34 @@ watermark({ text: '内部资料\n仅限内网', gap: 160 }, card({ title: '受 现场演示:apps/docs/demo.html#sec-watermark +### checkboxGroup — 多选组 CheckboxGroup + +参数: + +- options(必填):CheckOption[] —— 选项集合:value / label / 可选 disabled +- value:Signal —— 选中值数组信号;不传则内部维护 +- min:number —— 最少选几项:到下限后已选项禁用,防止取消 +- max:number —— 最多选几项:到上限后未选项禁用 +- checkAll:boolean —— 是否显示全选行(含半选);缺省 false +- direction:'horizontal' | 'vertical' —— 排列方向;缺省 horizontal +- disabled:boolean | Signal —— 整组禁用 +- onChange:(values: string[]) => void —— 变更回调(传副本) + +示例: + +``` +checkboxGroup({ value: permPick, min: 1, max: 3, checkAll: true, options: [{ value: 'read', label: '读取' }, { value: 'write', label: '写入' }] }) +``` + +手把手: + +1. options 顺序即渲染顺序;勾选后把整份数组写回 value 信号并触发 onChange +2. max 生效时未选项自动禁用,min 生效时已选项自动禁用——用禁用表达边界,不抛错也不静默回滚 +3. checkAll 行的选中/半选只统计未禁用项,禁用项不计入基数 +4. direction 传 vertical 改为纵向排列;disabled 支持信号,整组响应式禁用 + +现场演示:apps/docs/demo.html#sec-checkgroup + API 速览: - button(props):按钮,variant = primary | ghost | danger,disabled 支持布尔或信号禁用;type 缺省 button(表单内不隐式提交) @@ -1469,6 +1497,7 @@ API 速览: - colorPicker(props):颜色选择,预设色板(缺省语义令牌色)+ 原生取色器 + 手输 CSS 颜色串,value 为颜色串信号 - tour(props):引导漫游,返回 { el, start, close } 句柄;聚光框按 target 选择器定位,卡片自动选方位,Esc / 跳过走 onClose - watermark(props, ...children):内容容器 + 平铺水印覆盖层,canvas 生成单元、颜色取自令牌,覆盖层不挡交互 +- checkboxGroup(props):多选组,value 为数组信号,min/max 用禁用边界项实现(不抛错),checkAll 支持半选且只统计未禁用项 一行用法: diff --git a/llms.txt b/llms.txt index 1cd9df2..5bd6c4b 100644 --- a/llms.txt +++ b/llms.txt @@ -102,6 +102,7 @@ - colorPicker(props):颜色选择,预设色板(缺省语义令牌色)+ 原生取色器 + 手输 CSS 颜色串,value 为颜色串信号 - tour(props):引导漫游,返回 { el, start, close } 句柄;聚光框按 target 选择器定位,卡片自动选方位,Esc / 跳过走 onClose - watermark(props, ...children):内容容器 + 平铺水印覆盖层,canvas 生成单元、颜色取自令牌,覆盖层不挡交互 + - checkboxGroup(props):多选组,value 为数组信号,min/max 用禁用边界项实现(不抛错),checkAll 支持半选且只统计未禁用项 - 用法: `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/checkboxGroup.ts b/packages/skin/ui/src/checkboxGroup.ts new file mode 100644 index 0000000..a2e66ea --- /dev/null +++ b/packages/skin/ui/src/checkboxGroup.ts @@ -0,0 +1,60 @@ +import { effect, h, signal } from '@ui-arch/frame'; +import type { Signal } from '@ui-arch/frame'; +import type { CheckboxGroupProps } from './types.js'; + +/*** 多选组:value 数组信号双向绑定,min/max 用「禁用边界」而非报错,可选全选行(含半选) ***/ +export function checkboxGroup(props: CheckboxGroupProps): HTMLElement { + // —— 状态集中声明 —— + const value: Signal = props.value ?? signal([]); // 选中值 + const inputs: HTMLInputElement[] = []; // 各选项勾选框 + const dir = props.direction ?? 'horizontal'; // 排列方向 + const usable = props.options.filter((o) => !o.disabled); // 可勾选项(全选基数) + + /*** 整组禁用:布尔直接取,信号在此读取以纳入 effect 依赖 ***/ + const groupOff = (): boolean => (typeof props.disabled === 'function' ? props.disabled() : props.disabled === true); + + /*** 变更落库:写信号 + 回调,边界不在此处拒绝——由 sync 提前禁用越界选项 ***/ + const update = (next: string[]): void => { + value(next); + props.onChange?.([...next]); + }; + + const all = h('input', { type: 'checkbox', class: 'ua-checkbox', 'aria-label': '全选' }) as HTMLInputElement; + all.addEventListener('change', () => { + update(all.checked ? usable.map((o) => o.value) : []); // 全选只覆盖未禁用项 + }); + + const rows = props.options.map((opt) => { + const input = h('input', { type: 'checkbox', class: 'ua-checkbox' }) as HTMLInputElement; + input.value = opt.value; + input.addEventListener('change', () => { + const cur = new Set(value()); + input.checked ? cur.add(opt.value) : cur.delete(opt.value); // 用户操作写回 + update([...cur]); + }); + inputs.push(input); + return h('label', { class: 'ua-check-row' }, input, opt.label); + }); + + /*** 同步勾选与可见可用性:到上限禁用未选项、到下限禁用已选项(不改值只锁操作) ***/ + const sync = (): void => { + const cur = value(); + const off = groupOff(); + const atMax = props.max != null && cur.length >= props.max; + const atMin = props.min != null && cur.length <= props.min; + props.options.forEach((opt, i) => { + const input = inputs[i]; + const on = cur.includes(opt.value); + input.checked = on; + input.disabled = off || opt.disabled === true || (on ? atMin : atMax); // 边界项锁死,避免越界 + }); + const picked = usable.filter((o) => cur.includes(o.value)).length; + all.checked = picked > 0 && picked === usable.length; + all.indeterminate = picked > 0 && picked < usable.length; // 半选:部分已选 + all.disabled = off || (picked === usable.length && atMin); // 全选行同样受边界约束 + }; + + effect(sync); + const body = h('div', { class: `ua-check-group ua-check-group-${dir}` }, ...(props.checkAll ? [h('label', { class: 'ua-check-row' }, all, '全选')] : []), ...rows); + return h('div', { class: 'ua-checkbox-group', role: 'group' }, body) as HTMLElement; +} diff --git a/packages/skin/ui/src/index.ts b/packages/skin/ui/src/index.ts index 91b512b..a74a7e4 100644 --- a/packages/skin/ui/src/index.ts +++ b/packages/skin/ui/src/index.ts @@ -5,6 +5,7 @@ export { inputNumber } from './inputNumber.js'; export { textarea } from './textarea.js'; export { slider } from './slider.js'; export { checkbox } from './checkbox.js'; +export { checkboxGroup } from './checkboxGroup.js'; export { switchButton } from './switch.js'; export { select } from './select.js'; export { menu } from './menu.js'; diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index 2d48905..70756e0 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -600,4 +600,23 @@ export interface WatermarkProps { color?: string; // 颜色(CSS 串或令牌名);缺省取 --ua-color-text-muted 的实色 } +/*** 多选组选项 ***/ +export interface CheckOption { + value: string; // 选项值 + label: string; // 显示文案 + disabled?: boolean; // 单项禁用:不可勾选,也不计入全选 +} + +/*** 多选组入参 ***/ +export interface CheckboxGroupProps { + options: CheckOption[]; // 选项集合 + value?: Signal; // 选中值数组信号;不传则内部维护 + min?: number; // 最少选几项:到下限后已选项禁用,防止取消 + max?: number; // 最多选几项:到上限后未选项禁用 + checkAll?: boolean; // 是否显示全选行(含半选);缺省 false + direction?: 'horizontal' | 'vertical'; // 排列方向;缺省 horizontal + disabled?: boolean | Signal; // 整组禁用 + onChange?: (values: string[]) => void; // 变更回调(传副本) +} + export type { ColumnDef, RowKey }; // 再导出常用内核类型,方便调用方 diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index bbbfe00..935f484 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -67,7 +67,8 @@ "backTop(props):返回顶部悬浮按钮,越过阈值才浮现,外环 conic-gradient 显示已滚比例,点击平滑回顶", "colorPicker(props):颜色选择,预设色板(缺省语义令牌色)+ 原生取色器 + 手输 CSS 颜色串,value 为颜色串信号", "tour(props):引导漫游,返回 { el, start, close } 句柄;聚光框按 target 选择器定位,卡片自动选方位,Esc / 跳过走 onClose", - "watermark(props, ...children):内容容器 + 平铺水印覆盖层,canvas 生成单元、颜色取自令牌,覆盖层不挡交互" + "watermark(props, ...children):内容容器 + 平铺水印覆盖层,canvas 生成单元、颜色取自令牌,覆盖层不挡交互", + "checkboxGroup(props):多选组,value 为数组信号,min/max 用禁用边界项实现(不抛错),checkAll 支持半选且只统计未禁用项" ], "keyTypes": [ "ButtonProps", @@ -2332,6 +2333,61 @@ "color 传 var(--ua-*) 时会先解析成计算值(canvas 不认 CSS 变量),所以暗色主题下颜色会自动跟随", "覆盖层为 pointer-events:none,下方按钮/输入框照常可点;watermark 根节点自带圆角与裁剪" ] + }, + { + "id": "checkboxGroup", + "title": "多选组 CheckboxGroup", + "demo": "sec-checkgroup", + "props": [ + { + "n": "options", + "t": "CheckOption[]", + "r": 1, + "d": "选项集合:value / label / 可选 disabled" + }, + { + "n": "value", + "t": "Signal", + "d": "选中值数组信号;不传则内部维护" + }, + { + "n": "min", + "t": "number", + "d": "最少选几项:到下限后已选项禁用,防止取消" + }, + { + "n": "max", + "t": "number", + "d": "最多选几项:到上限后未选项禁用" + }, + { + "n": "checkAll", + "t": "boolean", + "d": "是否显示全选行(含半选);缺省 false" + }, + { + "n": "direction", + "t": "'horizontal' | 'vertical'", + "d": "排列方向;缺省 horizontal" + }, + { + "n": "disabled", + "t": "boolean | Signal", + "d": "整组禁用" + }, + { + "n": "onChange", + "t": "(values: string[]) => void", + "d": "变更回调(传副本)" + } + ], + "example": "checkboxGroup({ value: permPick, min: 1, max: 3, checkAll: true, options: [{ value: 'read', label: '读取' }, { value: 'write', label: '写入' }] })", + "steps": [ + "options 顺序即渲染顺序;勾选后把整份数组写回 value 信号并触发 onChange", + "max 生效时未选项自动禁用,min 生效时已选项自动禁用——用禁用表达边界,不抛错也不静默回滚", + "checkAll 行的选中/半选只统计未禁用项,禁用项不计入基数", + "direction 传 vertical 改为纵向排列;disabled 支持信号,整组响应式禁用" + ] } ] } diff --git a/packages/skin/ui/ui.css b/packages/skin/ui/ui.css index 22bb11d..8d4b30e 100644 --- a/packages/skin/ui/ui.css +++ b/packages/skin/ui/ui.css @@ -3239,3 +3239,14 @@ button.ua-step-dot:hover { background-repeat: repeat; background-position: 0 0; } +.ua-check-group { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: var(--ua-space-2); +} +.ua-check-group-vertical { + flex-direction: column; + align-items: flex-start; + gap: var(--ua-space-1); +}