v3.0.0-beta.7

新增 4 个组件（Calendar、RangeCalendar、DatePicker、DateRangePicker）以及多项 API 改进。

2026 年 2 月 19 日

本次发布新增 4 个组件：Calendar、RangeCalendar、DatePicker 与 DateRangePicker。同时还引入了 Switch.Content，用于将 label 与 description 组合到 Switch 控件旁边；以及 Tabs.Separator，用于在 Tab 之间按需添加分隔线。

⚠️ 破坏性变更：从 Tabs 中移除了 hideSeparator；DateInputGroup 与 ColorInputGroup 已分别合并到 DateField.Group、TimeField.Group 与 ColorField.Group 之下。

安装

升级到最新版本：

1npm i @lenso/tokens@beta @lenso/ui@beta

正在使用 AI 助手？ 只需对它说一句「Hey Cursor，把 HeroUI 升级到最新版本」，AI 助手就会自动对比版本并应用必要的变更。了解更多请参阅 HeroUI MCP 服务器。

新增功能

日期与时间体系

日期与时间 —— Calendar、DatePicker、RangeCalendar 与 DateRangePicker 均基于 React Aria 的日期基元构建。支持国际化、时区，以及完整的键盘导航与 ARIA 无障碍能力。

主要特性：

历法系统：公历、佛历、波斯历等
年份选择器：用于快速跳转年份的浮层
单元格指示器：在单元格上展示事件、可用状态或状态点
范围选择：日期范围带有视觉高亮
无障碍：键盘导航、屏幕阅读器、ARIA 全部支持

所有日期值都使用 @internationalized/date 提供的类型（CalendarDate、CalendarDateTime、ZonedDateTime）。可以用 I18nProvider 覆盖区域设置，并通过 useLocale 读取它。

新组件

Calendar：单日期选择，支持年份选择器、指示器与多月份显示。（文档）
RangeCalendar：日期范围选择，支持范围高亮与多月份显示。（文档）
DatePicker：日期输入框 + popover 日历。（文档）
DateRangePicker：两个日期输入框 + popover 范围日历。（文档）

Calendar

支持单日期选择的日历，包含年份选择器、单元格指示器、多月份视图以及国际化历法。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */4import { Calendar } from "@lenso/ui";5
6export function Basic() {7  return (8    <Calendar aria-label="Event date">9      <Calendar.Header>10        <Calendar.Heading />11        <Calendar.NavButton slot="previous" />12        <Calendar.NavButton slot="next" />13      </Calendar.Header>14      <Calendar.Grid>15        <Calendar.GridHeader>16          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}17        </Calendar.GridHeader>18        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>19      </Calendar.Grid>20    </Calendar>21  );22}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

年份选择器：

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */3import { Calendar } from "@lenso/ui";4
5export function YearPicker() {6  return (7    <Calendar aria-label="Event date">8      <Calendar.Header>9        <Calendar.YearPickerTrigger>10          <Calendar.YearPickerTriggerHeading />11          <Calendar.YearPickerTriggerIndicator />12        </Calendar.YearPickerTrigger>13        <Calendar.NavButton slot="previous" />14        <Calendar.NavButton slot="next" />15      </Calendar.Header>16      <Calendar.Grid>17        <Calendar.GridHeader>18          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}19        </Calendar.GridHeader>20        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>21      </Calendar.Grid>22      <Calendar.YearPickerGrid>23        <Calendar.YearPickerGridBody>24          {({ year }) => <Calendar.YearPickerCell year={year} />}25        </Calendar.YearPickerGridBody>26      </Calendar.YearPickerGrid>27    </Calendar>28  );29}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

国际化历法：

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */3import { Calendar } from "@lenso/ui";4import { getLocalTimeZone, today } from "@internationalized/date";5import { I18nProvider } from "react-aria-components/I18nProvider";6
7export function InternationalCalendar() {8  return (9    <I18nProvider locale="hi-IN-u-ca-indian">10      <Calendar aria-label="Event date" defaultValue={today(getLocalTimeZone())}>11        <Calendar.Header>12          <Calendar.YearPickerTrigger>13            <Calendar.YearPickerTriggerHeading />14            <Calendar.YearPickerTriggerIndicator />15          </Calendar.YearPickerTrigger>16          <Calendar.NavButton slot="previous" />17          <Calendar.NavButton slot="next" />18        </Calendar.Header>19        <Calendar.Grid>20          <Calendar.GridHeader>21            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}22          </Calendar.GridHeader>23          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>24        </Calendar.Grid>25        <Calendar.YearPickerGrid>26          <Calendar.YearPickerGridBody>27            {({ year }) => <Calendar.YearPickerCell year={year} />}28          </Calendar.YearPickerGridBody>29        </Calendar.YearPickerGrid>30      </Calendar>31    </I18nProvider>32  );33}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

RangeCalendar

日期范围选择，支持范围高亮与多月份视图。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. */4import { RangeCalendar } from "@lenso/ui";5
6export function Basic() {7  return (8    <RangeCalendar aria-label="Trip dates" firstDayOfWeek="mon">9      <RangeCalendar.Header>10        <RangeCalendar.Heading />11        <RangeCalendar.NavButton slot="previous" />12        <RangeCalendar.NavButton slot="next" />13      </RangeCalendar.Header>14      <RangeCalendar.Grid>15        <RangeCalendar.GridHeader>16          {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}17        </RangeCalendar.GridHeader>18        <RangeCalendar.GridBody>19          {(date) => <RangeCalendar.Cell date={date} />}20        </RangeCalendar.GridBody>21      </RangeCalendar.Grid>22    </RangeCalendar>23  );24}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

多月份显示：

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 derived work. Copyright NextUI Inc. Apache-2.0. Modified for StyleX. */3import { RangeCalendar } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  root: { containerType: "normal", width: "100%", maxWidth: "none", overflowX: "auto" },7  months: { marginInline: "auto", display: "flex", width: "max-content", gap: 32 },8  month: { width: 256 },9  heading: { flex: "none" },10  spacer: { width: 24, height: 24 },11});12export function MultipleMonths() {13  return (14    <RangeCalendar aria-label="Trip dates" xstyle={styles.root} visibleDuration={{ months: 2 }}>15      <div {...stylex.props(styles.months)}>16        <div {...stylex.props(styles.month)}>17          <RangeCalendar.Header>18            <RangeCalendar.NavButton slot="previous" />19            <RangeCalendar.Heading xstyle={styles.heading} />20            <div {...stylex.props(styles.spacer)} />21          </RangeCalendar.Header>22          <RangeCalendar.Grid>23            <RangeCalendar.GridHeader>24              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}25            </RangeCalendar.GridHeader>26            <RangeCalendar.GridBody>27              {(date) => <RangeCalendar.Cell date={date} />}28            </RangeCalendar.GridBody>29          </RangeCalendar.Grid>30        </div>31        <div {...stylex.props(styles.month)}>32          <RangeCalendar.Header>33            <div {...stylex.props(styles.spacer)} />34            <RangeCalendar.Heading xstyle={styles.heading} offset={{ months: 1 }} />35            <RangeCalendar.NavButton slot="next" />36          </RangeCalendar.Header>37          <RangeCalendar.Grid offset={{ months: 1 }}>38            <RangeCalendar.GridHeader>39              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}40            </RangeCalendar.GridHeader>41            <RangeCalendar.GridBody>42              {(date) => <RangeCalendar.Cell date={date} />}43            </RangeCalendar.GridBody>44          </RangeCalendar.Grid>45        </div>46      </div>47    </RangeCalendar>48  );49}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

DatePicker

日期输入框 + popover 日历。支持格式选项、国际化、自定义指示器与表单校验。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3/** Adapted from the pinned HeroUI v3.2.6 basic.json. Copyright NextUI Inc. Apache-2.0. Local RAC label and StyleX replace source Label and utility classes. */4import { Calendar, DateField, DatePicker } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6
7const styles = stylex.create({ field: { width: 288 } });8export function Basic() {9  return (10    <DatePicker xstyle={styles.field} name="date">11      <DatePicker.Label>Date</DatePicker.Label>12      <DateField.Group fullWidth>13        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>14        <DateField.Suffix>15          <DatePicker.Trigger>16            <DatePicker.TriggerIndicator />17          </DatePicker.Trigger>18        </DateField.Suffix>19      </DateField.Group>20      <DatePicker.Popover>21        <Calendar aria-label="Event date">22          <Calendar.Header>23            <Calendar.YearPickerTrigger>24              <Calendar.YearPickerTriggerHeading />25              <Calendar.YearPickerTriggerIndicator />26            </Calendar.YearPickerTrigger>27            <Calendar.NavButton slot="previous" />28            <Calendar.NavButton slot="next" />29          </Calendar.Header>30          <Calendar.Grid>31            <Calendar.GridHeader>32              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}33            </Calendar.GridHeader>34            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>35          </Calendar.Grid>36          <Calendar.YearPickerGrid>37            <Calendar.YearPickerGridBody>38              {({ year }) => <Calendar.YearPickerCell year={year} />}39            </Calendar.YearPickerGridBody>40          </Calendar.YearPickerGrid>41        </Calendar>42      </DatePicker.Popover>43    </DatePicker>44  );45}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

日期与时间（搭配 TimeField）：

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** Adapted from HeroUI v3.2.6 format-options.json. Copyright NextUI Inc. Apache-2.0. */3import { DatePicker, TimeField } from "@lenso/ui";4import {5  getLocalTimeZone,6  parseDate,7  parseZonedDateTime,8  type DateValue,9} from "@internationalized/date";10import { useMemo, useState } from "react";11import * as stylex from "@stylexjs/stylex";12import { PickerCalendar, PickerInput } from "./parts";13import { FormatControls, formatStyles, type Granularity, type HourCycle } from "./format-controls";14
15export function FormatOptions() {16  const [granularity, setGranularity] = useState<Granularity>("minute");17  const [hourCycle, setHourCycle] = useState<HourCycle>(12);18  const [hideTimeZone, setHideTimeZone] = useState(false);19  const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false);20  const timeGranularity = granularity !== "day" ? granularity : undefined;21  const defaultValue = useMemo<DateValue>(22    () =>23      granularity === "day"24        ? parseDate("2026-02-03")25        : parseZonedDateTime(`2026-02-03T08:45:00[${getLocalTimeZone()}]`),26    [granularity],27  );28  return (29    <div {...stylex.props(formatStyles.stack)}>30      <DatePicker31        key={granularity}32        xstyle={formatStyles.field}33        defaultValue={defaultValue}34        granularity={granularity}35        hourCycle={hourCycle}36        hideTimeZone={hideTimeZone}37        shouldForceLeadingZeros={shouldForceLeadingZeros}38        name="date"39      >40        {({ state }) => (41          <>42            <DatePicker.Label>Date and time</DatePicker.Label>43            <PickerInput />44            <DatePicker.Popover xstyle={formatStyles.popover}>45              <PickerCalendar />46              {timeGranularity && (47                <div {...stylex.props(formatStyles.timeRow)}>48                  <span {...stylex.props(formatStyles.label)}>Time</span>49                  <TimeField50                    aria-label="Time"51                    granularity={timeGranularity}52                    hourCycle={hourCycle}53                    hideTimeZone={hideTimeZone}54                    name="time"55                    shouldForceLeadingZeros={shouldForceLeadingZeros}56                    value={state.timeValue}57                    onChange={(value) => {58                      if (value) state.setTimeValue(value);59                    }}60                  >61                    <TimeField.Group variant="secondary">62                      <TimeField.Input>63                        {(segment) => <TimeField.Segment segment={segment} />}64                      </TimeField.Input>65                    </TimeField.Group>66                  </TimeField>67                </div>68              )}69            </DatePicker.Popover>70          </>71        )}72      </DatePicker>73      <FormatControls74        {...{75          granularity,76          setGranularity,77          hourCycle,78          setHourCycle,79          hideTimeZone,80          setHideTimeZone,81          shouldForceLeadingZeros,82          setShouldForceLeadingZeros,83        }}84      />85    </div>86  );87}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

DateRangePicker

两个日期输入框 + popover 范围日历。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3/** Adapted from the pinned HeroUI v3.2.6 basic.json. Copyright NextUI Inc. Apache-2.0. Local RAC label and StyleX replace source Label and utility classes. */4import { DateField, DateRangePicker, RangeCalendar } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6
7const styles = stylex.create({ field: { width: 320 } });8export function Basic() {9  return (10    <DateRangePicker xstyle={styles.field} endName="endDate" startName="startDate">11      <DateRangePicker.Label>Trip dates</DateRangePicker.Label>12      <DateField.Group fullWidth>13        <DateField.Input slot="start">14          {(segment) => <DateField.Segment segment={segment} />}15        </DateField.Input>16        <DateRangePicker.RangeSeparator />17        <DateField.Input slot="end">18          {(segment) => <DateField.Segment segment={segment} />}19        </DateField.Input>20        <DateField.Suffix>21          <DateRangePicker.Trigger>22            <DateRangePicker.TriggerIndicator />23          </DateRangePicker.Trigger>24        </DateField.Suffix>25      </DateField.Group>26      <DateRangePicker.Popover>27        <RangeCalendar aria-label="Trip dates">28          <RangeCalendar.Header>29            <RangeCalendar.YearPickerTrigger>30              <RangeCalendar.YearPickerTriggerHeading />31              <RangeCalendar.YearPickerTriggerIndicator />32            </RangeCalendar.YearPickerTrigger>33            <RangeCalendar.NavButton slot="previous" />34            <RangeCalendar.NavButton slot="next" />35          </RangeCalendar.Header>36          <RangeCalendar.Grid>37            <RangeCalendar.GridHeader>38              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}39            </RangeCalendar.GridHeader>40            <RangeCalendar.GridBody>41              {(date) => <RangeCalendar.Cell date={date} />}42            </RangeCalendar.GridBody>43          </RangeCalendar.Grid>44          <RangeCalendar.YearPickerGrid>45            <RangeCalendar.YearPickerGridBody>46              {({ year }) => <RangeCalendar.YearPickerCell year={year} />}47            </RangeCalendar.YearPickerGridBody>48          </RangeCalendar.YearPickerGrid>49        </RangeCalendar>50      </DateRangePicker.Popover>51    </DateRangePicker>52  );53}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

API 改进

Switch.Content

Switch.Content 用于将 label 与 description 组合到 Switch 控件旁边（#6240）。

之前：

1import { Switch, Label, Description } from '@lenso/ui';2
3<Switch>4  <Switch.Control>5    <Switch.Thumb />6  </Switch.Control>7  <Switch.Content>8    <Label>Email notifications</Label>9    <Description>Get notified when someone mentions you</Description>10  </Switch.Content>11</Switch>

Tabs.Separator

Tabs 组件现在新增了一个显式的 Tabs.Separator 子组件，用于在 Tab 之间添加视觉分隔线。它取代了之前自动生成的 CSS 伪元素分隔线以及 hideSeparator prop（#6243）。

分隔线现在改为 按需启用 —— 在希望出现分隔线的 <Tabs.Tab> 内部添加 <Tabs.Separator /> 即可。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2export { WithSeparator } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Field 子组件的合并

DateField、TimeField 与 ColorField 现在直接暴露各自的输入组子组件，不再需要单独引入 DateInputGroup 或 ColorInputGroup。具体的迁移方式请参阅破坏性变更。

Breadcrumbs 修复

传给 Breadcrumbs.Item 的 props 现在会正确转发到底层的 Link（#6233）。

样式修复

ListBox Item：将悬停背景色从 bg-default-hover 调整为 bg-default，以保持一致性
Date Input Group：将段（segment）文本从 tabular-nums 调整为 text-nowrap，优化布局
Date Input Group：改进 focus-within 样式，使其将日期选择器触发器排除在字段聚焦高亮之外

依赖更新

React Aria Components：从 1.14.0 升级到 1.15.0 —— 新增了 render prop，可用于自定义任何 React Aria 组件渲染的 DOM 元素（适用于路由链接、Motion 等动画库）
@react-aria/utils：从 3.32.0 升级到 3.33.0
@react-types/shared：从 3.32.1 升级到 3.33.0
@internationalized/date：从 3.10.1 升级到 3.11.0 —— 日期字段现在改为在失焦时进行约束，而不是在输入过程中实时约束
新增 @react-aria/i18n 与 @react-stately/utils，用于日历的国际化

⚠️ 破坏性变更

Tabs —— 移除 `hideSeparator` prop

hideSeparator prop 已从 Tabs 组件中移除。分隔线现在改为 按需启用，通过新增的 <Tabs.Separator /> 子组件来添加，而不再通过 CSS 伪元素自动生成（#6243）。

之前：

1{/* Separators shown by default, hidden via prop */}2<Tabs hideSeparator>3  <Tabs.List>4    <Tabs.Tab id="tab1">Tab 1<Tabs.Indicator /></Tabs.Tab>5    <Tabs.Tab id="tab2">Tab 2<Tabs.Indicator /></Tabs.Tab>6  </Tabs.List>7</Tabs>

之后：

1{/* No separators by default — explicitly add them where needed */}2<Tabs>3  <Tabs.List>4    <Tabs.Tab id="tab1"><Tabs.Indicator />Tab 1</Tabs.Tab>5    <Tabs.Tab id="tab2"><Tabs.Separator /><Tabs.Indicator />Tab 2</Tabs.Tab>6  </Tabs.List>7</Tabs>

CSS 变更：

Tab 的分隔线样式已从伪元素（.tabs__tab:not(:first-child):before）迁移到独立的 .tabs__separator 类
已移除 [data-hide-separator] 这一 data 属性

Field 子组件 API 变更

DateInputGroup 与 ColorInputGroup 不再从 @lenso/ui 直接导出。它们的子组件已分别合并到对应的 Field 组件之下（DateField、TimeField、ColorField）。

DateField 变更

之前：

1import {DateField, Label, DateInputGroup, Description} from '@lenso/ui';2
3<DateField>4  <Label>Date</Label>5  <DateInputGroup>6    <DateInputGroup.Prefix>...</DateInputGroup.Prefix>7    <DateInputGroup.Input>8      {(segment) => <DateInputGroup.Segment segment={segment} />}9    </DateInputGroup.Input>10    <DateInputGroup.Suffix>...</DateInputGroup.Suffix>11  </DateInputGroup>12  <Description>Pick a date</Description>13</DateField>

之后：

1import {DateField, Label, Description} from '@lenso/ui';2
3<DateField>4  <Label>Date</Label>5  <DateField.Group>6    <DateField.Prefix>...</DateField.Prefix>7    <DateField.Input>8      {(segment) => <DateField.Segment segment={segment} />}9    </DateField.Input>10    <DateField.Suffix>...</DateField.Suffix>11  </DateField.Group>12  <Description>Pick a date</Description>13</DateField>

TimeField 变更

模式与 DateField 相同：

之前	之后
`DateInputGroup`	`TimeField.Group`
`DateInputGroup.Input`	`TimeField.Input`
`DateInputGroup.Segment`	`TimeField.Segment`
`DateInputGroup.Prefix`	`TimeField.Prefix`
`DateInputGroup.Suffix`	`TimeField.Suffix`

ColorField 变更

之前	之后
`ColorInputGroup`	`ColorField.Group`
`ColorInputGroup.Input`	`ColorField.Input`
`ColorInputGroup.Prefix`	`ColorField.Prefix`
`ColorInputGroup.Suffix`	`ColorField.Suffix`

用法：

1import {ColorField, Label, ColorInputGroup, ColorSwatch} from '@lenso/ui';2
3<ColorField>4  <Label>Color</Label>5  <ColorInputGroup>6    <ColorInputGroup.Prefix>7      <ColorSwatch color="#000" />8    </ColorInputGroup.Prefix>9    <ColorInputGroup.Input />10  </ColorInputGroup>11</ColorField>

之后：

1import {ColorField, Label, ColorSwatch} from '@lenso/ui';2
3<ColorField>4  <Label>Color</Label>5  <ColorField.Group>6    <ColorField.Prefix>7      <ColorSwatch color="#000" />8    </ColorField.Prefix>9    <ColorField.Input />10  </ColorField.Group>11</ColorField>

说明： 底层的 CSS 类名（.date-input-group、.color-input-group 等）保持不变，仅 JavaScript 引入路径与组件名称发生了变化。

链接

贡献者

感谢每一位为本次发布做出贡献的开发者！

HeroUI contributors

v3.0.0-beta.7

安装

新增功能

日期与时间体系

新组件

Calendar

RangeCalendar

DatePicker

DateRangePicker

API 改进

Switch.Content

Tabs.Separator

Field 子组件的合并

Breadcrumbs 修复

样式修复

依赖更新

⚠️ 破坏性变更

Tabs —— 移除 hideSeparator prop

Field 子组件 API 变更

DateField 变更

TimeField 变更

ColorField 变更

链接

贡献者

Tabs —— 移除 `hideSeparator` prop