diff --git a/.ua/index.json b/.ua/index.json index 19b5d63..7f6117d 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T13:25:25.456Z", + "generatedAt": "2026-10-26T13:28:41.290Z", "repoRoot": ".", "packages": [ { @@ -215,7 +215,8 @@ "commandPalette(props)：命令面板，⌘K / Ctrl+K 唤起，输入即过滤（主文案/说明/关键词三层），↑↓ 环形选择 + 回车执行 + Esc 收起，选中与关闭都归还焦点；返回 { el, open, close } 句柄", "timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起", "pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示", - "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand" + "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand", + "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset" ], "keyTypes": [ "ButtonProps", @@ -3937,6 +3938,43 @@ "label / copiedLabel 可改文案；variant / size 透传给内部 button，视觉与普通按钮完全一致", "非安全上下文（http）或旧浏览器自动降级为隐藏 textarea + execCommand，无需业务处理兼容" ] + }, + { + "id": "countdown", + "title": "倒计时 Countdown", + "demo": "sec-countdown", + "props": [ + { + "n": "seconds", + "t": "number", + "r": 1, + "d": "总时长（秒），> 0" + }, + { + "n": "running", + "t": "boolean", + "df": "true", + "d": "创建即开始倒数；传 false 用句柄 start 手动启动" + }, + { + "n": "format", + "t": "(seconds: number) => string", + "d": "展示格式化；缺省 mm:ss 两位补零" + }, + { + "n": "onFinish", + "t": "() => void", + "k": 1, + "d": "归零回调（自动停表后触发）" + } + ], + "example": "const cd = countdown({ seconds: 60, onFinish: () => console.log('结束') }); // cd.start / stop / reset", + "steps": [ + "传 seconds 即可用，缺省挂载即开始、mm:ss 展示；返回句柄 { el, start, stop, reset }", + "running: false 先摆好再手动 start，典型场景是「发送验证码」后才开始 60s 重发倒计时", + "归零自动停表并触发 onFinish；之后 start() 会重开一轮，reset() 复位到总时长", + "format 自定义展示：如只显示秒 (s) => `${s}s`，或带上小时位" + ] } ] }, diff --git a/AGENTS.md b/AGENTS.md index 463b2f1..a8c10fe 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）：72 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 +- `packages/skin/ui`（@ui-arch/ui）：73 个 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 5b5a616..d1ab00c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,7 +34,7 @@ ui-arch-mvp/ │ │ ├── table-core/ # 表格状态内核 │ │ └── frame/ # 信号 + hyperscript 微框架 │ ├── skin/ # 皮肤层（DOM 组件，可发布） -│ │ └── ui/ # 72 个组件 + ui.css +│ │ └── ui/ # 73 个组件 + ui.css │ ├── design/ # 资产层（可发布） │ │ └── tokens/ # --ua-* 设计令牌 │ └── tools/ # 工程层（private，不发布） diff --git a/README.md b/README.md index c4f048b..60f4803 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 可查漂移） ``` -## 组件（共 72 个） +## 组件（共 73 个） -accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark +accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark -分组：表单（button / copyButton / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。 +分组：表单（button / copyButton / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。 ## 可访问性约定 @@ -32,7 +32,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup |---|---| | `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：72 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | +| `packages/skin/ui` | @ui-arch/ui：73 个 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 bc468e4..90715b0 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -28,6 +28,7 @@ import { timePicker, commandPalette, copyButton, + countdown, dataTable, datePicker, transfer, @@ -251,6 +252,7 @@ const rangeTo = signal(''); // 区间终点 const acValue = signal(''); // 自动补全输入值（外部受控演示） const pinCode = signal(''); // 验证码输入值（外部受控演示） const pinMask = signal(''); // 密文验证码输入值（mask 演示） +const resendCd = countdown({ seconds: 90, running: false, format: (s) => `重发(${s}s)` }); // 重发倒计时（手动启动演示） const treeChecked = signal(['core']); // 多选树勾选集合（外部受控演示） const treePick = signal('core'); // 树形选中节点 key const transferKeys = signal(['a11y']); // 穿梭框右侧集合（外部受控演示） @@ -1106,6 +1108,19 @@ const content = h( copyButton({ text: '禁用态示例', disabled: true }), ), ), + section( + 'sec-countdown', + '倒计时', + 'countdown：秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示；句柄 start / stop / reset，验证码重发场景与 pinInput 搭配。', + h( + 'div', + { class: 'row' }, + countdown({ seconds: 10, onFinish: () => toast.info('倒计时结束') }).el, + resendCd.el, + button({ label: '重置 90s', variant: 'ghost', onClick: () => { resendCd.reset(); resendCd.start(); } }), + h('span', { class: 'out' }, '第二个示例初始暂停，点按钮重开'), + ), + ), section( 'sec-affix', '固钉', diff --git a/llms-full.txt b/llms-full.txt index cef99d8..671c952 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档（无图形版） -> 自动生成于 2026-10-26T13:25:25.456Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 +> 自动生成于 2026-10-26T13:28:41.290Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。 ## 快速上手 @@ -2073,6 +2073,30 @@ copyButton({ text: 'npm install @ui-arch/ui', onCopied: (t) => console.log(t) }) 现场演示：apps/docs/demo.html#sec-copybutton +### countdown — 倒计时 Countdown + +参数： + +- seconds（必填）：number —— 总时长（秒），> 0 +- running（默认 true）：boolean —— 创建即开始倒数；传 false 用句柄 start 手动启动 +- format：(seconds: number) => string —— 展示格式化；缺省 mm:ss 两位补零 +- onFinish（回调）：() => void —— 归零回调（自动停表后触发） + +示例： + +``` +const cd = countdown({ seconds: 60, onFinish: () => console.log('结束') }); // cd.start / stop / reset +``` + +手把手： + +1. 传 seconds 即可用，缺省挂载即开始、mm:ss 展示；返回句柄 { el, start, stop, reset } +2. running: false 先摆好再手动 start，典型场景是「发送验证码」后才开始 60s 重发倒计时 +3. 归零自动停表并触发 onFinish；之后 start() 会重开一轮，reset() 复位到总时长 +4. format 自定义展示：如只显示秒 (s) => `${s}s`，或带上小时位 + +现场演示：apps/docs/demo.html#sec-countdown + API 速览： - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交） @@ -2149,6 +2173,7 @@ API 速览： - timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起 - pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示 - copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand +- countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset 一行用法： diff --git a/llms.txt b/llms.txt index 4505e83..b416fbc 100644 --- a/llms.txt +++ b/llms.txt @@ -121,6 +121,7 @@ - timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起 - pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示 - copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand + - countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset - 用法: `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/countdown.ts b/packages/skin/ui/src/countdown.ts new file mode 100644 index 0000000..049ee09 --- /dev/null +++ b/packages/skin/ui/src/countdown.ts @@ -0,0 +1,27 @@ +import { h, signal } from '@ui-arch/frame'; +import type { CountdownHandle, CountdownProps } from './types.js'; + +/*** 倒计时：秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，句柄可 start / stop / reset ***/ +export function countdown(props: CountdownProps): CountdownHandle { + const remain = signal(props.seconds); // 剩余秒数（单一来源，h() 函数型子节点响应式刷新文本） + let timer = 0; // setInterval 句柄（0 表示停表中） + const fmt = props.format ?? ((s: number): string => `${String(Math.floor(s / 60)).padStart(2, '0')}:${String(s % 60).padStart(2, '0')}`); // 缺省 mm:ss 两位补零 + + const stop = (): void => { if (timer) { clearInterval(timer); timer = 0; } }; // 停表并清句柄，幂等 + + /*** 开始 / 续跑：重入先停旧表；已归零时视为重开一轮 ***/ + const start = (): void => { + stop(); + if (remain() <= 0) remain(props.seconds); + timer = window.setInterval(() => { + const next = Math.max(0, remain() - 1); + remain(next); + if (next <= 0) { stop(); if (props.onFinish) props.onFinish(); } // 归零即停表并回调，不留负数帧 + }, 1000); + }; + + const reset = (): void => { stop(); remain(props.seconds); }; // 复位到总时长并停表 + const el = h('span', { class: 'ua-countdown', role: 'timer' }, () => fmt(remain())) as HTMLSpanElement; + if (props.running ?? true) start(); // 缺省挂载即开始 + return { el, start, stop, reset }; +} diff --git a/packages/skin/ui/src/index.ts b/packages/skin/ui/src/index.ts index 32610cd..9a1fcf4 100644 --- a/packages/skin/ui/src/index.ts +++ b/packages/skin/ui/src/index.ts @@ -72,3 +72,4 @@ export { commandPalette } from './commandPalette.js'; export { timePicker } from './timePicker.js'; export { pinInput } from './pinInput.js'; export { copyButton } from './copyButton.js'; +export { countdown } from './countdown.js'; diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index 00c948b..890d769 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -265,6 +265,22 @@ export interface CopyButtonProps { onCopied?: (text: string) => void; // 复制成功回调（参数为实际写入的内容） } +/*** 倒计时入参 ***/ +export interface CountdownProps { + seconds: number; // 总时长（秒），> 0 + running?: boolean; // 创建即开始倒数；缺省 true + format?: (seconds: number) => string; // 展示格式化；缺省 mm:ss 两位补零 + onFinish?: () => void; // 归零回调（自动停表后触发） +} + +/*** 倒计时句柄 ***/ +export interface CountdownHandle { + el: HTMLSpanElement; // 根节点（role=timer，文本随剩余秒数响应式刷新） + start: () => void; // 开始 / 续跑（已归零则重开一轮） + stop: () => void; // 暂停（保留剩余秒数） + reset: () => void; // 复位到总时长并停表 +} + /*** 空状态入参 ***/ export interface EmptyProps { title?: string; // 主标题；缺省不渲染 diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index 05505e1..092dbf5 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -86,7 +86,8 @@ "commandPalette(props)：命令面板，⌘K / Ctrl+K 唤起，输入即过滤（主文案/说明/关键词三层），↑↓ 环形选择 + 回车执行 + Esc 收起，选中与关闭都归还焦点；返回 { el, open, close } 句柄", "timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起", "pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示", - "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand" + "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand", + "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset" ], "keyTypes": [ "ButtonProps", @@ -3808,6 +3809,43 @@ "label / copiedLabel 可改文案；variant / size 透传给内部 button，视觉与普通按钮完全一致", "非安全上下文（http）或旧浏览器自动降级为隐藏 textarea + execCommand，无需业务处理兼容" ] + }, + { + "id": "countdown", + "title": "倒计时 Countdown", + "demo": "sec-countdown", + "props": [ + { + "n": "seconds", + "t": "number", + "r": 1, + "d": "总时长（秒），> 0" + }, + { + "n": "running", + "t": "boolean", + "df": "true", + "d": "创建即开始倒数；传 false 用句柄 start 手动启动" + }, + { + "n": "format", + "t": "(seconds: number) => string", + "d": "展示格式化；缺省 mm:ss 两位补零" + }, + { + "n": "onFinish", + "t": "() => void", + "k": 1, + "d": "归零回调（自动停表后触发）" + } + ], + "example": "const cd = countdown({ seconds: 60, onFinish: () => console.log('结束') }); // cd.start / stop / reset", + "steps": [ + "传 seconds 即可用，缺省挂载即开始、mm:ss 展示；返回句柄 { el, start, stop, reset }", + "running: false 先摆好再手动 start，典型场景是「发送验证码」后才开始 60s 重发倒计时", + "归零自动停表并触发 onFinish；之后 start() 会重开一轮，reset() 复位到总时长", + "format 自定义展示：如只显示秒 (s) => `${s}s`，或带上小时位" + ] } ] } diff --git a/packages/skin/ui/ui.css b/packages/skin/ui/ui.css index bb05203..3846238 100644 --- a/packages/skin/ui/ui.css +++ b/packages/skin/ui/ui.css @@ -5197,3 +5197,8 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); } font-variant-numeric: tabular-nums; /* 数字等宽：换位不左右窜 */ caret-color: var(--ua-color-accent); } + +/* ---- 倒计时（countdown） ---- */ +.ua-countdown { + font-variant-numeric: tabular-nums; /* 数字等宽：秒跳不抖动 */ +}