n-countdown 倒计时
用于活动截止、可暂停的相对时长与累计计时。时长输入统一为毫秒，天/时/分/秒可附加；截止日期优先。修改输入开始新一轮，修改显示格式或样式保留本轮进度。
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
API
属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| time | 初始毫秒数，与 day/hour/minute/second 相加；down 为剩余时长，up 为已累计时长 | number | 0 |
| day | 初始天数，与其他时长输入相加 | number | 0 |
| hour | 初始小时数，可超过 23 | number | 0 |
| minute | 初始分钟数，可超过 59 | number | 0 |
| second | 初始秒数，可包含小数 | number | 0 |
| datetime | 截止日期（Date 或带时区的日期字符串），非空时优先于时长输入；仅 down 使用 | Date / string / null | null |
| mode | down 倒计时，up 累计计时 | enum | down |
| max-time | 累计计时的毫秒上限，0 表示不限；仅 up 使用 | number | 0 |
| auto-start | 挂载或重置后自动开始；修改为 false 暂停，true 继续 | boolean | true |
| format | 显示格式：DD/HH/mm/ss/S/SS/SSS 或 {d}/{h}/{m}/{s}/{ms}；缺失高位单位累计至下一个显示单位 | string | HH:mm:ss |
| pad-zero | 天时分秒补足两位；毫秒按模板位数补零 | boolean | true |
| hide-zero | 隐藏前导零单位及其分隔符，最后一个单位始终保留 | boolean | false |
| millisecond | 以 30ms 刷新真实毫秒；关闭时按秒刷新并向上取整剩余秒数 | boolean | false |
| keep-alive | 组件销毁后进度不重置，重建时按真实时间补算，反复进出页面不再从初始值重跑（活动/秒杀倒计时）；无后台定时器 | boolean | false |
| keep-running | 进度保存到本地，杀进程重开或刷新后接着走而非重新计时（订单支付剩余时间）；存储失败派发 error | boolean | false |
| unique-key | 保留进度的键，未传时全部实例共用默认键；同页多实例需各自独立保留时传不同键（秒杀场次、订单号等） | string | n-countdown |
| item-style | 数字段容器行内样式（底色、边框、宽高）；宽度应能容纳超过两位的累计值 | string | |
| text-style | 数字段文字行内样式（颜色、字号）；固定盒内不要设置 line-height | string | |
| separator-style | 分隔符文字行内样式（颜色、字号） | string | |
| millisecond-style | 毫秒文字行内样式，在 textStyle 后应用 | string | |
| custom-class | 根节点额外类名，类须定义在组件样式表内 | string | |
| custom-style | 根节点行内样式 | string |
事件
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 初始化、重置与时间变化时触发，参数为 NCountdownData（total 为真实毫秒） | NCountdownData |
| start | 从未运行或暂停进入运行时触发，参数为 NCountdownData | NCountdownData |
| pause | 手动暂停运行时触发，参数为 NCountdownData；页面隐藏不触发 | NCountdownData |
| reset | 调用 reset 后触发，参数为 NCountdownData；自动开始时随后触发 start | NCountdownData |
| finish | 到达终点或主动 finish 时触发，每轮一次，参数为 NCountdownData | NCountdownData |
| error | 输入或保留状态错误时触发，参数为 NCountdownError；输入错误停止计时 | NCountdownError |
插槽
| 插槽名 | 说明 |
|---|---|
| default | 整体替换。参数 time: NCountdownData、items: NCountdownItem[]，另直接提供 days/hours/minutes/seconds/milliseconds 数值字段；字段为标准分解值，items 为格式模板的累计显示值 |
| item | 逐项替换。参数 item: NCountdownItem（value 格式化文字、unit 单位标识、isSeparator 是否分隔符）、index、time；保留数字块容器样式 |
方法与状态
| 名称 | 说明 |
|---|---|
| start() / resume() | 开始或继续：暂停后从原进度继续，完成后从初始值开启新一轮；运行中重复调用无效果 |
| pause() | 相对时长冻结；截止日期只暂停刷新，原截止时刻不延后 |
| reset() | 按当前 props 丢弃进度重新初始化，随后按 autoStart 决定是否开始 |
| finish() | 主动结束当前一轮，保留当前值并派发一次 finish；自然结束倒计时为 0，累计计时为上限 |
| isRunning | 是否处于运行状态；隐藏期间逻辑继续计时但不进行显示刷新 |
| current | 当前 NCountdownData（total、days、hours、minutes、seconds、milliseconds，全部为 number） |
格式与边界
- DD/HH/mm/ss/SSS 对应天/时/分/秒/三位毫秒，S/SS 对应十分之一秒/百分之一秒；{d}/{h}/{m}/{s}/{ms} 是等价占位符。模板中的其他内容作为分隔符原样显示，空格式为空展示。
- 未显示高位单位累计至下一显示单位：3661000ms 用 HH:mm:ss 显示 01:01:01，用 mm:ss 显示 61:01，用 ss 显示 3661。hideZero 仅隐藏前导零及分隔符，最后一单位仍显示零。
- 秒级倒计时向上取整显示，不会在剩余 999ms 时提前显示 0；millisecond 开启后显示真实毫秒，每约 30ms 刷新，调度周期不改变真实到期时刻。
- 时长输入非负且有限，毫秒取整数；非法数值、无效日期、up 配 datetime 均触发 error 并停止。默认零时长挂载不自动触发 finish；手动 start 或已过期截止日期触发一次 finish。
- 适合进度不能重置的场景：活动倒计时反复进出页面用 keep-alive，订单支付剩余时间跨重启用 keep-running；同页多实例需各自独立保留时用不同 unique-key 区分，单实例零配置即可。保存的进度恢复时校验计时配置，配置变化开始新一轮；暂停和已完成状态也保留，恢复后 start 从初始值重开；reset 明确覆盖保存的状态。存储读取、解析、写入失败通过 error 显式报告并从当前输入开始。
- 页面或应用隐藏时停止定时刷新，返回补算实际经过时间。没有后台唤醒能力，finish 在可执行回调时派发，业务有效期由服务端判定。设备系统时间变更会影响计时，应以业务提供的服务器校准截止时刻为准。
实现说明
| 机制 | 参考做法 | 本组件做法 | 分歧理由 |
|---|---|---|---|
| 输入 | 总时长、分单位时长、截止日期分别提供 | 全部保留，毫秒统一计算，日期优先 | 避免多套计值链路，输入优先级明确 |
| 计时 | 定时器逐秒递减或递增 | 时间值加时间戳锚点，定时器只触发刷新 | 调度延迟不会累计成误差，隐藏后无需逐次补帧 |
| 手动控制 | 开始、停止、续播、重置、结束 | start/pause/resume/reset/finish，暂停与完成分开，完成后 start 重开 | 防止暂停被当成结束事件，重复调用幂等，完成后再次开始对齐验证码重发等场景 |
| 格式与单位显隐 | 占位模板或独立单位开关，省略高位时累计 | 两种已有模板语法共用解析器，缺失单位累计 | 用模板表达单位选择，保留全部显示能力，避免多组开关相互冲突 |
| 毫秒 | 真实毫秒刷新或独立数字轮播装饰 | 30ms 刷新真实毫秒，S/SS/SSS 可选精度 | 避免视觉毫秒与实际时间脱节，不使用 CSS 关键帧或原生插件 |
| 隐藏零与补零 | 前导零隐藏、数值补零 | hideZero/padZero，最后一单位恒保留 | 结束状态仍可读，累计单位不截断 |
| 正向计时 | 独立累计计时器，初始值与上限 | mode=up 与 maxTime，共用同一时钟 | 功能来自累计计时参考，单一引擎覆盖两方向 |
| 销毁保留 | 销毁后继续、唯一键区分 | 状态快照与锚点，重建补算；本次运行与本地保存分别提供 | 销毁后不遗留定时器，恢复保留任务进度 |
| 插槽 | 整体作用域插槽或逐项插槽 | default 与 item 两级均保留 | 整体布局与局部换样式均可接管 |
| 样式 | 数字段、分隔符、毫秒独立尺寸颜色及底色边框 | 主题令牌、itemStyle/textStyle/separatorStyle/millisecondStyle | 遵循库内定制通道，原样式能力均有对应入口 |
| 结构更新 | 按显示列表渲染单位 | 根 key 仅依赖单位和分隔符结构，数值原地更新 | 保证 App 动态结构切换重绘，秒与帧刷新不重建 |
令牌：--n-countdown-item-width / padding-x / padding-y / background / border-width / border-color / radius / separator-margin / font-size / color / separator-size / separator-color。文字颜色默认显式引用主题文本色；数字块以最小宽度和内容自适应，允许累计小时、分钟与天数超过两位，不钉死文字高度与行高。