RangePicker
日期范围选择器，双面板（两个月并排，右面板=左面板+1）序列选择（点起始→点结束，自动排序、起止可跨面板、hover 跨面板预览区间），受控/非受控；显示与星期/月份均经 Intl.DateTimeFormat 本地化。type=dateTimeRange 时在双日期面板右侧各挂一组时/分/秒时间列（复用 DatePicker dateTime 列逻辑），起止各自携带时分秒；needConfirm（dateTimeRange 默认 true）时选择进 pending 缓冲，点确定才提交。支持 showSecond/disabledTime/disabledTimePicker/hideDisabledOptions（语义与 DatePicker dateTime 一致）。type=monthRange（对齐 Semi）时改用双「月份」面板（各 12 个月格，头部年份 + 左右切年、左右面板相邻两年）选起止月，value=[起始月, 结束月]（Date 落在该月 1 号），区间高亮/hover 预览按月粒度；不含时间列，maxRange 不适用。
如何引入
import { RangePicker } from '@chenzy-design/svelte';基础用法
支持日期、日期时间、月份、年份类型，含范围选择、快捷预设、禁用时间。
基础日期选择
单日期选择与范围选择器的基础用法。
日期类型
type 切换日期时间、月份、年份选择。
范围选择
RangePicker 配合 disabledDate 与 maxRange 限制可选区间。
禁用日期与快捷预设
disabledDate 禁用周末，presets/presetPosition 提供快捷选项。
自定义格式与外观
format 自定义解析格式，size/status/disabled 控制外观状态。
带时间范围选择
RangePicker type=dateTimeRange 双面板 + 起止时/分/秒列 + 确认提交，支持 showSecond、disabledTime。
月份范围选择
RangePicker type=monthRange 双月份面板（头部年份 + 左右切年）选起止月，value 为 [起始月, 结束月]。
面板内嵌输入
insetInput 在面板顶部渲染可编辑输入框（date 日期框；dateTime 日期框+时间框），键盘可直接键入，与面板选择双向同步。
年月滚轮快速跳转
点头部年月标题展开年 + 月滚轮列（复用 ScrollList），快速跳转任意年月；yearAndMonthOpts 控制循环滚动。
多选日期
multiple 多选（仅 type=date），value 为 Date[]，max 限制数量。
时区显示
timeZone 按 IANA 时区显示同一时刻（格式化层注入，底层绝对时刻不变）。
确认选择
needConfirm 使 dateTime 需点击确认才写入值，配合 onConfirm 回调。
面板插槽与自定义日期
topSlot/bottomSlot 面板额外区域，renderDate 自定义日期单元格内容。
自定义触发器
triggerRender 完全自定义触发器外观。
范围快捷区间
RangePicker presets 提供最近 7 天等快捷区间，presetPosition 控制位置。
周选择
RangePicker startDateOffset/endDateOffset 单击任意日期即选中整周。
API 参考
RangePicker
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
type | dateRange 纯日期范围 / dateTimeRange 带时间范围（每端时/分/秒列 + 确认）/ monthRange 月份范围（双月份面板选起止月） | 'dateRange'|'dateTimeRange'|'monthRange' | 'dateRange' |
value | — | [Date|null, Date|null] | null | undefined |
defaultValue | — | [Date|null, Date|null] | null | null |
open | — | boolean | undefined |
defaultOpen | — | boolean | false |
startPlaceholder | — | string | '开始日期' |
endPlaceholder | — | string | '结束日期' |
size | — | 'small'|'default'|'large' | 'default' |
status | — | 'default'|'warning'|'error' | 'default' |
disabled | — | boolean | false |
clearable | — | boolean | true |
disabledDate | — | (date: Date) => boolean | undefined |
disabledTime | dateTimeRange：按日期返回各时间列禁用值（分/秒列联动已选时/分） | (date: Date) => { disabledHours?: () => number[]; disabledMinutes?: (hour: number) => number[]; disabledSeconds?: (hour: number, minute: number) => number[] } | undefined |
showSecond | dateTimeRange：是否显示秒列 | boolean | true |
hideDisabledOptions | dateTimeRange：隐藏被禁用的时间选项（默认仅置灰） | boolean | false |
disabledTimePicker | dateTimeRange：禁止时间列（只保留日期面板 + 确认） | boolean | false |
needConfirm | 需点击确认才提交（dateTimeRange 默认 true，dateRange 默认 false） | boolean | undefined |
maxRange | — | number | undefined |
startDateOffset | 单击范围选择：与 endDateOffset 同时提供后，单击某日即选定 [startDateOffset(clicked), endDateOffset(clicked)]（如周选择），一步完成不进两步；仅 dateRange/dateTimeRange 生效 | (date: Date) => Date | undefined |
endDateOffset | 单击范围选择的结束偏移；与 startDateOffset 同时提供才生效 | (date: Date) => Date | undefined |
weekStart | — | 0 | 1 | 0 |
locale | — | string | 'zh-CN' |
presets | 快捷区间列表：点击直接选定整段 [start, end]（惰性 value 即时求值、自动排序）；needConfirm 时进 pending 缓冲否则直接提交并关面板；monthRange 时 value 落每月 1 号 | { label: string; value: [Date, Date] | (() => [Date, Date]) }[] | undefined |
presetPosition | 快捷区间列表位置（left/right 竖排并列于面板侧，top/bottom 横排于面板上/下） | 'left' | 'right' | 'top' | 'bottom' | 'bottom' |
onChange | — | (v: [Date|null,Date|null] | null) => void | undefined |
onOpenChange | — | (open: boolean) => void | undefined |
onPanelChange | — | (e: { panelDate: Date }) => void | undefined |
onClear | — | (e: {}) => void | undefined |
onPresetClick | 点击快捷区间选项 | (e: { preset: { label: string; value: [Date, Date] | (() => [Date, Date]) } }) => void | undefined |
onConfirm | 点击确认按钮（needConfirm） | (e: { value: [Date|null,Date|null] | null }) => void | undefined |
onCancel | 点击取消按钮（needConfirm） | (e: { value: [Date|null,Date|null] | null }) => void | undefined |
onFocus | — | (e: FocusEvent) => void | undefined |
onBlur | — | (e: FocusEvent) => void | undefined |
ariaLabel | — | string | undefined |
position | 浮层弹出位置 | string | 'bottomLeft' |
autoAdjustOverflow | 浮层自动调整位置防溢出 | boolean | true |
spacing | 触发器与浮层间距（px） | number | undefined |
getPopupContainer | 浮层挂载容器 | () => HTMLElement | undefined |
dropdownMargin | 浮层相对触发器的额外偏移 | number | { x?: number; y?: number } | undefined |
class | 根节点自定义类名（对齐 Semi className） | string | '' |
style | 根节点内联样式 | string | undefined |
Methods
| 属性 | 类型 | 说明 |
|---|---|---|
open() | — | 命令式展开面板（对齐 Semi） |
close() | — | 命令式关闭面板（对齐 Semi） |
focus(focusType?: 'rangeStart'|'rangeEnd') | — | 命令式聚焦触发器（单触发器结构下 focusType 退化为聚焦整体，签名对齐 Semi） |
blur() | — | 命令式移除触发器焦点（对齐 Semi） |
Accessibility
| ARIA role | dialog |
- 触发器 button aria-haspopup=dialog、aria-expanded、aria-controls 指向面板
- 面板 role=dialog；左右各一 role=grid（aria-label 为各自月份），单元格 role=gridcell + aria-selected（端点）
- 双面板并排显示相邻两月：最左「上一月」、最右「下一月」整体翻页；第一次点击设起始、第二次设结束并自动排序，起止可跨面板；hover 跨面板实时预览区间
- maxRange：选定起始后，离起点超过 maxRange 天的日期 aria-disabled 置灰、点击/hover 无效（daysBetween 纯函数判定）
- startDateOffset/endDateOffset（单击范围选择，如周选择）：两者都提供时单击某日即选定整个区间 [startDateOffset(clicked), endDateOffset(clicked)]，不进「点起始→点结束」两步；悬停整段预览高亮；仅 dateRange/dateTimeRange 生效
- 触发器 Enter/Space/↓ 打开、Esc 关闭
- type=dateTimeRange：面板右侧挂起/止两组时/分/秒列 role=listbox + option；时间列作用于当前激活端 activeEnd（选起始日/点左侧列=start，选结束日/点右侧列=end），激活端有 --active 底色标示
- dateTimeRange 默认 needConfirm=true：选择进 pending 缓冲，footer「确定」提交、「取消」回退并关闭
- disabledTime：dateTimeRange 时/分/秒列被禁用值 aria-disabled、点击/键盘无效（分/秒列联动激活端已选时/分）
- type=monthRange：左右各一 role=grid 的 12 月格（3 列大格），头部显示年份 + 左右按钮切年（左右面板相邻两年）；点起始月→点结束月自动排序、起止可跨面板、hover 跨面板预览区间；单元格 role=gridcell + aria-selected（端点）。选完即提交 onChange（无确认、无时间列）
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--cd-transition-date-picker-range-input | background-color .16s ease-in-out |