97 lines
5.2 KiB
JSON
97 lines
5.2 KiB
JSON
{
|
||
"slug": "timepicker",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端时间选择：value 受控、onChange 回传字符串，label 文案由 children 提供，控件是原生 time 输入。",
|
||
"usage": [
|
||
"入参解构为 { value = '09:30', format = 'HH:mm', children, onChange, ... }，默认值就是上午九点半（TimePicker.jsx:4）。",
|
||
"受控写法固定为 value 加 onChange：value={value}、onChange={(e) => onChange && onChange(e.target.value)}，组件不保存内部状态（TimePicker.jsx:8）。",
|
||
"label 文字来自 children：示例传「执行时间」，源码把它渲染在 <label> 里与 input 同行；不传 children 时组件里还有一个写死的「执行时间」兜底（TimePicker.jsx:8 与示例 timepicker-ex-1 的差异见 notes）。",
|
||
"format 在签名里有默认值 'HH:mm'，但组件体内没有引用，改变它不会影响原生控件的呈现（TimePicker.jsx:4,8）。",
|
||
"控件是原生 <input type=\"time\">，外层套 .kole-timepicker-root 与 .kole-timepicker kole-timepicker-item 两层类名（TimePicker.jsx:7-8）。",
|
||
"onChange 载荷是事件里的字符串（如 '09:30'），直接 useState 的 setter 就能用，无需再取 e.target（TimePicker.jsx:8；示例 timepicker-ex-1）。"
|
||
],
|
||
"bestPractices": [
|
||
"format 目前是空转参数：要实现秒级（HH:mm:ss）需要自己给原生 input 加 step=\"1\"，插件本身不处理（TimePicker.jsx:4,8）。",
|
||
"签名里的 children 与 onClick/onClose/onSubmit/onLoadMore 都没有绑定点，传了不生效；示例把 label 文案写在 children 里只是沿用，源码中的 label 文本是固定的（TimePicker.jsx:4,8）。",
|
||
"不接 onChange 时输入框无法改值（受控且值不变），表现为「敲不进字」，这是受控组件最常见的坑（TimePicker.jsx:8）。",
|
||
"取值是字符串，不做合法性校验；空值时浏览器会给出 ''，业务侧需要考虑空字符串与默认值 '09:30' 的区分（TimePicker.jsx:4,8）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端被消费的 props 只有两个：value 是受控值（默认 '09:30'），onChange 回传字符串；format 与 children 声明在签名中但不参与渲染，另有三个未绑定回调；控件本体是原生 time input，无 ref 句柄。",
|
||
"table": [
|
||
{
|
||
"name": "value",
|
||
"type": "string，默认 '09:30'",
|
||
"desc": "受控时间字符串，直接写到原生 input 的 value"
|
||
},
|
||
{
|
||
"name": "onChange",
|
||
"type": "(value: string) => void",
|
||
"desc": "输入变化时调用，载荷为 e.target.value 字符串"
|
||
},
|
||
{
|
||
"name": "format",
|
||
"type": "string，默认 'HH:mm'",
|
||
"desc": "声明为时间格式，实现里未被引用，不改变控件行为"
|
||
},
|
||
{
|
||
"name": "children",
|
||
"type": "ReactNode",
|
||
"desc": "签名中声明，实现里未被渲染，传入无效"
|
||
},
|
||
{
|
||
"name": "kole-timepicker-root",
|
||
"type": "className",
|
||
"desc": "最外层容器类名（本端专有，CSS 中无同名规则）"
|
||
},
|
||
{
|
||
"name": "kole-timepicker",
|
||
"type": "className",
|
||
"desc": "作用域与 label 行共用的类名，与 item 同节点"
|
||
},
|
||
{
|
||
"name": "kole-timepicker-item",
|
||
"type": "className",
|
||
"desc": "label 行类名，提供 inline-flex 布局与最小高度"
|
||
},
|
||
{
|
||
"name": "kole-timepicker-control",
|
||
"type": "className",
|
||
"desc": "原生 time 输入框的类名"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"文字在 <label> 内且与 input 同层，控件可访问名称来自 label 文本（示例传的「执行时间」），无需 id 关联（TimePicker.jsx:8）。",
|
||
"使用原生 <input type=\"time\">，Tab 聚焦与键盘调时由浏览器提供，不依赖自建键盘事件（TimePicker.jsx:8）。",
|
||
"示例一里没有为输入框加 aria-label，说明依赖 label 文本；若把 label 文字清空，控件将失去可读名称（TimePicker.jsx:8；示例 timepicker-ex-1）。",
|
||
"组件不渲染任何提示文本节点，也没有 aria-describedby 之类的描述关联（TimePicker.jsx:7-8）。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/TimePicker.jsx",
|
||
"kind": "React 组件",
|
||
"desc": "TimePicker.jsx —— React 实现：value/onChange 受控对、原生 time input 与两层类名容器"
|
||
},
|
||
{
|
||
"file": "frameworks/TimePicker.css",
|
||
"kind": "样式文件",
|
||
"desc": "TimePicker.css —— 组件 import 的 .kole-timepicker 系列样式"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"timepicker-ex-1",
|
||
"timepicker-ex-2"
|
||
],
|
||
"notes": [
|
||
"props 解构与默认值：frameworks/TimePicker.jsx:4",
|
||
"受控输入与 onChange 载荷：frameworks/TimePicker.jsx:8",
|
||
"类名三层：frameworks/TimePicker.jsx:7-8",
|
||
"样式定义：frameworks/TimePicker.css:16-17,2-3",
|
||
"示例 timepicker-ex-1 把「执行时间」写在 children 上，但源码渲染的是 <label> 内写死的「执行时间」文本（frameworks/TimePicker.jsx:8），children 未参与渲染；按实现记录该落差。",
|
||
"consumedApi.emits 里的 onClick/onClose/onSubmit/onLoadMore 均无绑定点，已在 table 中标注。"
|
||
]
|
||
}
|