67 lines
3.4 KiB
JSON
67 lines
3.4 KiB
JSON
{
|
||
"slug": "rangequickpicker",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端日期范围快捷选择：预设区间一键填入，也可手改起止日期，确认后才回调。",
|
||
"usage": [
|
||
"modelValue 形状固定为 {start, end}，但 start 与 end 是各自独立的内部 state，初始值只在挂载时取自 modelValue。",
|
||
"与多数选择器不同，这里 preset 与自定义输入都不立即上报，只有点确定才走 confirm 调 onChange，取消或点外部只关闭弹层。",
|
||
"内部保存了 modelValue 与本地 start / end 两套值，触发器上显示的是 modelValue，自定义输入显示的是本地值，二者在未确认前可能不一致。",
|
||
"预设项高亮由 activeIndex 控制，选预设会把区间算好填进本地 start / end 并记下索引，手动改日期则清掉高亮。",
|
||
"关闭行为集中在 useEffect 里的 document click：点到组件外部就收起弹层并把 activeIndex 复位为 -1。",
|
||
"预设来自 presets prop，默认是内置的今天、近 7 天、本月等区间，算区间只依赖本地时间函数。"
|
||
],
|
||
"bestPractices": [
|
||
"点确定只回调 onChange，不会自持最终值，受控方必须把新区间写回 modelValue，否则触发器文案不会变。",
|
||
"弹层开合、预设高亮、草稿区间三者都是内部状态，外部无法命令式关闭，需要关闭得靠用户点击外部区域。",
|
||
"取消按钮只关弹层、不还原草稿值，再次打开时自定义输入里仍是上次改到一半的值。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端 3 个 props 加 onChange；弹层开合 open、草稿区间 start / end、预设高亮 activeIndex 均为内部 state，确认前不对外通信。",
|
||
"table": [
|
||
{
|
||
"name": "modelValue",
|
||
"type": "Object，{start, end}",
|
||
"desc": "已确认的区间，用于初始化草稿值并驱动触发器显示"
|
||
},
|
||
{
|
||
"name": "presets",
|
||
"type": "Array<Object>",
|
||
"desc": "预设区间列表，默认内置今天与近 7 天等，元素含 label 与区间规则"
|
||
},
|
||
{
|
||
"name": "onChange",
|
||
"type": "(range) => void",
|
||
"desc": "点确定后回调，参数为最终区间对象"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"触发器是 div 加 onClick，没有 tabindex、role 与 aria-expanded，键盘无法展开。",
|
||
"预设项是原生 button，键盘可聚焦触发，是本面板里唯一键盘可用的部分。",
|
||
"弹层没有 role=dialog，打开时焦点也不移入，读屏器不会播报弹层出现。",
|
||
"起止用的是原生 date 输入，键盘可编辑，但没有 label 说明哪个是开始、哪个是结束。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/RangeQuickPicker.jsx",
|
||
"kind": "React 实现",
|
||
"desc": "RangeQuickPicker.jsx —— 本端实现全文（结构、事件与状态逻辑）"
|
||
},
|
||
{
|
||
"file": "frameworks/RangeQuickPicker.css",
|
||
"kind": "样式文件",
|
||
"desc": "frameworks/RangeQuickPicker.css —— 本端 kole-* 类名与 is-* 状态类的样式定义"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"rangequickpicker-ex-1"
|
||
],
|
||
"notes": [
|
||
"props 与默认区间见 frameworks/RangeQuickPicker.jsx:33，草稿与高亮 state 见第 35-38 行。",
|
||
"点外部关闭见 frameworks/RangeQuickPicker.jsx:40-49，预设填充见第 51-56 行。",
|
||
"仅确认才回调见 frameworks/RangeQuickPicker.jsx:57-61。"
|
||
]
|
||
}
|