DateRangePicker 日期范围选择器

输入或者从日历中选择日期区间。

2026

值：2026-09-04 至 2026-09-12

'use client'

import { useState } from 'react'
import { DateRangePicker, Stack, Text, type DateRangeValue } from '@hina-ui/react'

export default function Demo() {
  const [range, setRange] = useState<DateRangeValue | null>({
    start: '2026-09-04',
    end: '2026-09-12',
  })
  return (
    <Stack gap="sm" align="start">
      <DateRangePicker
        value={range}
        onValueChange={setRange}
        clearable
        aria-label="活动期间"
        className="w-96"
      />
      <Text tone="muted" size="sm">
        值：{range ? `${range.start ?? '空'} 至 ${range.end ?? '空'}` : '空'}
      </Text>
    </Stack>
  )
}

tsx

用法

import { DateRangePicker } from '@hina-ui/react'

日期范围选择器把 DateRangeField 的分段输入面与 RangeCalendar 组合在一起：可以直接在各段里输入开始与结束日期，也可以点击末尾的按钮打开日历选择。value / onValueChange 绑定 { start, end } 对象，两个字段都是 YYYY-MM-DD 格式的 ISO 8601 字符串，与两者一致。未声明的属性都会传给包裹各段的组元素，请用 aria-label 或者 aria-labelledby 命名。

年

月

日

年

月

日

值：空

'use client'

import { useState } from 'react'
import { DateRangePicker, Stack, Text, type DateRangeValue } from '@hina-ui/react'

export default function Demo() {
  const [range, setRange] = useState<DateRangeValue | null>(null)
  return (
    <Stack gap="sm" align="start">
      <DateRangePicker
        value={range}
        onValueChange={setRange}
        aria-label="发售期间"
        className="w-96"
      />
      <Text tone="muted" size="sm">
        值：{range ? `${range.start ?? '空'} 至 ${range.end ?? '空'}` : '空'}
      </Text>
    </Stack>
  )
}

tsx

示例

范围与不可选的日期

min 与 max 同时约束输入与日历，unavailable 把某些日期标为不可选，maximumDays 限制区间最多包含的天数。

2026

'use client'

import { useState } from 'react'
import { DateRangePicker, type DateRangeValue } from '@hina-ui/react'

export default function Demo() {
  const [range, setRange] = useState<DateRangeValue | null>({
    start: '2026-09-08',
    end: '2026-09-11',
  })
  const weekend = (value: string) => [0, 6].includes(new Date(`${value}T00:00`).getDay())
  return (
    <DateRangePicker
      value={range}
      onValueChange={setRange}
      min="2026-09-01"
      max="2026-09-30"
      maximumDays={7}
      unavailable={weekend}
      aria-label="活动期间"
      className="w-96"
    />
  )
}

tsx

可清除

clearable 在各段之后加一个清除按钮，一次清空两侧，清空后值为 null。

2026

'use client'

import { useState } from 'react'
import { DateRangePicker, type DateRangeValue } from '@hina-ui/react'

export default function Demo() {
  const [range, setRange] = useState<DateRangeValue | null>({
    start: '2026-09-04',
    end: '2026-09-12',
  })
  return (
    <DateRangePicker
      value={range}
      onValueChange={setRange}
      clearable
      aria-label="活动期间"
      className="w-96"
    />
  )
}

tsx

尺寸

size 有 sm、md、lg 三档，与同档输入框等高，浮层里的日历使用同一档尺寸。

2026

import { DateRangePicker, Stack } from '@hina-ui/react'

export default function Demo() {
  const range = { start: '2026-09-04', end: '2026-09-12' }
  return (
    <Stack className="w-96">
      <DateRangePicker size="sm" value={range} aria-label="小号" />
      <DateRangePicker size="md" value={range} aria-label="中号" />
      <DateRangePicker size="lg" value={range} aria-label="大号" />
    </Stack>
  )
}

tsx

状态

invalid 给输入面加上警示色，disabled 禁用整组，readOnly 只读。variant="secondary" 是放在 surface 之内的扁平形态。

2026

import { DateRangePicker, Stack } from '@hina-ui/react'

export default function Demo() {
  const range = { start: '2026-09-04', end: '2026-09-12' }
  return (
    <Stack className="w-96">
      <DateRangePicker value={range} invalid aria-label="校验未通过" />
      <DateRangePicker value={range} disabled aria-label="已禁用" />
      <DateRangePicker value={range} readonly aria-label="只读" />
      <DateRangePicker value={range} variant="secondary" aria-label="扁平形态" />
    </Stack>
  )
}

tsx

在表单中

放进 FormField 后，标签关联到输入区，错误信息由字段渲染；校验规则与提交交给 Form。区间完整性的校验写在对象层，错误才会落到这个字段上。

'use client'

import { useState } from 'react'
import * as v from 'valibot'
import { Button, DateRangePicker, Form, FormField, Text, type DateRangeValue } from '@hina-ui/react'

const schema = v.object({
  trip: v.pipe(
    v.nullable(v.object({ start: v.nullable(v.string()), end: v.nullable(v.string()) })),
    v.check(value => !!value?.start && !!value?.end, '请选择完整的出行日期'),
  ),
})

export default function Demo() {
  const [values, setValues] = useState<{ trip: DateRangeValue | null }>({ trip: null })
  const [saved, setSaved] = useState('')

  async function save(data: unknown) {
    await new Promise(resolve => setTimeout(resolve, 600))
    setSaved(JSON.stringify(data))
  }

  return (
    <Form values={values} rules={schema} className="w-80" onSubmit={save}>
      {({ submitting }) => (
        <>
          <FormField name="trip" label="出行日期" required>
            <DateRangePicker value={values.trip} onValueChange={trip => setValues({ trip })} />
          </FormField>
          <Button type="submit" loading={submitting} className="self-start">
            保存
          </Button>
          {saved && (
            <Text tone="muted" size="sm">
              已保存：{saved}
            </Text>
          )}
        </>
      )}
    </Form>
  )
}

tsx

行为

点击末尾的按钮打开日历，焦点落在当前区间的开始日期。在日历里点第一个日期确定开始，此时值更新为开始日期加 null，日历保持打开；点第二个日期确定结束，值更新后关闭日历，焦点回到按钮。
日历是模态浮层：打开期间焦点保持在日历里，页面停止滚动，点击日历以外的任何地方都会关闭它，包括输入面本身。
Esc 关闭日历，焦点回到按钮。在日历的月份与年份视图里，Esc 先逐级返回。
日历在输入面下方展开，与输入面的左缘对齐。

API

Props

属性	类型	默认值	说明
`value`	`DateRangeValue \| null`	`null`	选中的区间，两端都是 `YYYY-MM-DD`
`open`	`boolean`	`false`	日历是否打开，`open / onOpenChange`
`placeholder`	`string`	今天	空值时各段与日历的起点
`min`	`string`	—	可选范围的下限
`max`	`string`	—	可选范围的上限
`maximumDays`	`number`	—	区间最多包含的天数
`unavailable`	`(date: string) => boolean`	—	判定某一天是否不可选
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	随语言	一周从周几开始
`weekdayFormat`	`'narrow' \| 'short'`	`'narrow'`	星期名称的格式
`fixedWeeks`	`boolean`	`true`	日历是否固定显示六周
`clearable`	`boolean`	`false`	是否显示清除按钮
`readOnly`	`boolean`	`false`	是否只读
`name`	`string`	—	表单字段名
`variant`	`'primary' \| 'secondary'`	`'primary'`	形态
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	尺寸
`disabled`	`boolean`	`false`	是否禁用
`invalid`	`boolean`	`false`	是否处于校验未通过状态
`className`	`string`	—	追加至根元素的类名

DateRangeValue 是 { start: string | null; end: string | null }，可以从包入口导入。

内容属性

属性	说明
`leading`	前置附属格的内容

回调

回调	参数	说明
`onValueChange`	`value: DateRangeValue \| null`	值变化
`onOpenChange`	`open: boolean`	日历开合变化
`onClear`	—	点击清除

用法

示例

范围与不可选的日期

可清除

尺寸

状态

在表单中

行为

无障碍

API

Props

内容属性

回调