57 lines
3.4 KiB
JSON
57 lines
3.4 KiB
JSON
{
|
||
"slug": "countdown",
|
||
"end": "vue3",
|
||
"curated": true,
|
||
"summary": "Vue 3 倒计时：传毫秒 target，内部每秒刷新，不足一天不显示天数段。",
|
||
"usage": [
|
||
"target 是 defineProps 里唯一的 prop，收毫秒时间戳，默认当前时间加一小时（Countdown.vue3.vue:15）；传秒级时间戳会算成很久以前，差值被截成 0 后四段全显示 00。",
|
||
"计时由组件自己维持：onMounted 里 setInterval 每秒刷新内部 ref now，onBeforeUnmount 里 clearInterval（第 18-19 行），外部不需要也不应该驱动刷新。",
|
||
"组件是 <script setup> 加单个 defineProps，只有一个 prop，没有 emit 也没有插槽，时分秒格式与冒号分隔符全写在模板里。",
|
||
"天数段由 v-if 判内部 computed d > 0 决定是否渲染（第 3 行），不足一天的倒计时不会渲染天这一格，总宽度会少一段。",
|
||
"剩余量经 Math.max(0, diff) 兜底（第 21 行）；diff 是依赖 props.target 与内部 ref now 的 computed，target 已过期时显示全 0 而不是负数。"
|
||
],
|
||
"bestPractices": [
|
||
"改 target 不需要重建组件：diff 是 computed，同时依赖 props.target 与内部 now，换值立即反映到四段显示上。",
|
||
"默认值是 () => Date.now() + 3600000 这样的工厂函数（第 15 行），每个实例各拿到自己的一小时；写成静态表达式会在组件定义时只求值一次。",
|
||
"组件只管显示不做回调：倒计时归零没有任何事件，需要在 0 点执行动作请按 target 在外部另设定时。",
|
||
"刷新用当前时间戳重算而不是每秒自减（第 16-18、21 行），标签页被挂起再回来时显示依然准确。"
|
||
],
|
||
"a11y": [
|
||
"数字每秒变化但容器 .kole-countdown 没有 aria-live 之类的播报属性，读屏器不会主动念出变化。",
|
||
"天/时/分/秒的单位是相邻 span 的可见文本（.kole-countdown-label），读屏器按 DOM 顺序念数字加单位，与视觉顺序一致。",
|
||
"数字是零填充的字符串（第 26 行 pad），读屏器念 08 时可能读成零八，对时间播报更友好的是不加前导零。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "Vue 3 端载体只有 defineProps 声明的一个 target（Number）；组件没有 emit 也没有插槽，显示形态由内部 computed 与写死的模板决定（frameworks/Countdown.vue3.vue:15-25）。",
|
||
"table": [
|
||
{
|
||
"name": "target",
|
||
"type": "Number",
|
||
"desc": "打开方式（frameworks/Countdown.vue3.vue:15）"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/Countdown.vue3.vue",
|
||
"kind": "Vue 3",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/Countdown.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"countdown-ex-1"
|
||
],
|
||
"notes": [
|
||
"唯一的 prop 声明见 frameworks/Countdown.vue3.vue:15，默认值是工厂函数形式的一小时后。",
|
||
"定时器生命周期见 frameworks/Countdown.vue3.vue:18-19：onMounted 起 setInterval，onBeforeUnmount 清理。",
|
||
"差值兜底与四段拆分见 frameworks/Countdown.vue3.vue:21-25，天数段的 v-if 见第 3 行。",
|
||
"契约声明的驱动维度 unit / size 属设计词汇层，未作为 prop 写入本页。"
|
||
]
|
||
}
|