temp/UI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

iter(g236): 新增 countdown 倒计时组件，秒级递减自动停表并带句柄控制（73 组件）

Browse Source
This commit is contained in:
HIsheR
2026-10-26 21:28:56 +08:00
parent 671c87456e
commit d50455318d
12 changed files with 176 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.ua/index.json
+40 -2
View File
@@ -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`，或带上小时位"
]
}
]
},
AGENTS.md
+1 -1
View File
@@ -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
ARCHITECTURE.md
+1 -1
View File
@@ -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，不发布）
README.md
+4 -4
View File
@@ -12,13 +12,13 @@ npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全
npm run changelog # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移）
```
## 组件（共 72 个）
## 组件（共 73 个）
<!-- ua:components -->
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
<!-- /ua:components -->
分组：表单（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 打包成单文件） |
apps/demo/main.ts
+15
View File
@@ -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<string[]>(['core']); // 多选树勾选集合（外部受控演示）
const treePick = signal('core'); // 树形选中节点 key
const transferKeys = signal<string[]>(['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',
'固钉',
llms-full.txt
+26 -1
View File
@@ -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
一行用法：
llms.txt
+1
View File
@@ -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 为回调
packages/skin/ui/src/countdown.ts
+27
View File
@@ -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 };
}
packages/skin/ui/src/index.ts
+1
View File
@@ -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';
packages/skin/ui/src/types.ts
+16
View File
@@ -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; // 主标题；缺省不渲染
packages/skin/ui/ua.manifest.json
+39 -1
View File
@@ -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`，或带上小时位"
]
}
]
}
packages/skin/ui/ui.css
+5
View File
@@ -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; /* 数字等宽：秒跳不抖动 */
}