react-native-ui-datepicker

本项目基于 farhoudshapouran/react-native-ui-datepicker 开发，并适配 React Native for OpenHarmony。 如果在使用过程中有任何问题，可以在 GitCode 提交 Issue，我们会及时跟进。

项目介绍

react-native-ui-datepicker 是一款可定制的 React Native 日期选择器组件，适配 React Native for OpenHarmony。以 JS-only 方式在 RNOH 上运行，无需原生模块即可使用。

主要能力包括：

• 日期单选：支持默认日期、最小 / 最大日期、启用 / 禁用日期与结果回调。
• 日期区间选择：支持起止日期、区间重置与跨度限制（min / max）。
• 日期多选：支持多日期增删、数量上限与连片区间展示（multiRangeMode）。
• 时间选择：支持日期与时间组合选择、12 / 24 小时制。
• 月份 / 年份浏览：支持月份、年份面板切换与受控 month / year 定位。
• 本地化能力：支持公历 / 波斯历（Jalali）、地区语言、时区和多种数字系统。
• 自定义外观：支持主题（useDefaultStyles）、样式表、class token 和组件插槽（components）。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/react-native-ui-datepicker

本库将 react 与 react-native（>= 0.72）作为 peer 依赖，安装时请确保宿主工程已包含相应版本。

Autolinking

本库为 JS-only 适配包，不包含原生实现：宿主工程安装依赖后即可直接使用，无需手动注册原生模块。

导入

import DateTimePicker, {
  useDefaultStyles,
  useDefaultClassNames,
  isTimeZoneSupported,
  convertToWallTime,
} from '@hxa-rn/react-native-ui-datepicker';

默认导出 DateTimePicker 组件；具名导出 useDefaultStyles、useDefaultClassNames 样式工具函数与 isTimeZoneSupported、convertToWallTime 时区工具函数，以及 DateType、CalendarMode、DatePickerBaseProps 等类型。

使用说明

基础用法

import { useState } from 'react';
import DateTimePicker from '@hxa-rn/react-native-ui-datepicker';

export default function App() {
  const [date, setDate] = useState();

  return (
    <DateTimePicker
      mode="single"
      date={date}
      onChange={(params) => setDate(params.date)}
    />
  );
}

mode 为必填项，决定组件使用的日期字段与回调参数结构：单选模式下 onChange 返回 { date }，区间模式返回 { startDate, endDate }，多选模式返回 { dates, datePressed, change }。

传入 timeZone 时，组件只改变日期的展示解释，不改变选中时刻本身：宿主传入的日期按该时区解释为墙上时间，用户点选的日期按目标时区口径处理，切换 timeZone 会重新触发一次 onChange，回写的是宿主传入的原始时刻。时区换算基于库自带的时区数据库，不依赖 Intl。

区间选择

import { useState } from 'react';
import DateTimePicker from '@hxa-rn/react-native-ui-datepicker';

export default function App() {
  const [startDate, setStartDate] = useState();
  const [endDate, setEndDate] = useState();

  return (
    <DateTimePicker
      mode="range"
      startDate={startDate}
      endDate={endDate}
      onChange={(params) => {
        setStartDate(params.startDate);
        setEndDate(params.endDate);
      }}
    />
  );
}

区间模式下 min / max 为起止日期之间的天数跨度限制；allowRangeReset 为 true 时，区间完整后再次点击任意日期会清空结束日期并以其作为新起点重新选择。

接口文档

以下 API 依据 src/index.ts 及相关类型定义整理。

DateTimePicker

日期选择器主组件，通过 mode 切换单选、区间、多选三种模式。

属性	类型	默认值	说明
instanceKey	string	未声明	组件实例标识，变化时重置内部状态。
mode	CalendarMode	single	选择模式。
calendar	CalendarType	gregory	历法类型：公历或波斯历。
locale	string	en	本地化语言标识。
numerals	Numerals	latn	数字系统。
timeZone	string	未声明	IANA 时区标识。
date	DateType	未声明	单选模式当前日期。
startDate	DateType	未声明	区间模式起始日期。
endDate	DateType	未声明	区间模式结束日期。
dates	DateType[]	未声明	多选模式日期集合。
min	number	未声明	区间 / 多选最小天数。
max	number	未声明	区间 / 多选最大天数。
onChange	SingleChange | RangeChange | MultiChange	未声明	选择结果回调，参数结构随 mode 变化。
allowRangeReset	boolean	false	区间完整后再次点击是否重置区间（区间模式）。
allowReverseRange	boolean	false	是否允许反向选择，即点击早于起点的日期时完成区间（区间模式）。
startYear	number	未声明	年份面板起始年份，当前实现未生效。
endYear	number	未声明	年份面板结束年份，当前实现未生效。
minDate	DateType	未声明	最小可选日期。
maxDate	DateType	未声明	最大可选日期。
enabledDates	DateType[] | ((date: DateType) => boolean)	未声明	日期白名单或启用判定函数。
disabledDates	DateType[] | ((date: DateType) => boolean)	未声明	日期黑名单或禁用判定函数。
firstDayOfWeek	number	0	周起始日，0 表示周日。
showOutsideDays	boolean	false	是否显示跨月日期。
timePicker	boolean	false	是否开启时间选择。
use12Hours	boolean	未声明	是否使用 12 小时制。
initialView	CalendarViews	day	初始视图。
containerHeight	number	300	容器高度。
containerStyle	ViewStyle	未声明	容器样式。
weekdaysHeight	number	25	星期行高度。
style	ViewStyle	{}	根样式。
className	string	''	根节点 class token。
styles	Styles	{}	逐键样式覆盖。
classNames	ClassNames	{}	逐键 class token 覆盖。
navigationPosition	NavigationPosition	around	导航按钮位置。
weekdaysFormat	WeekdayFormat	min	星期文案格式。
monthsFormat	MonthFormat	full	月份面板文案格式。
monthCaptionFormat	MonthFormat	full	月份标题格式。
multiRangeMode	boolean	未声明	多选日期是否按连片区间展示。
hideHeader	boolean	未声明	是否隐藏头部。
hideWeekdays	boolean	未声明	是否隐藏星期行。
showMonthSelector	boolean	未声明	是否显示月份选择器；未传时除年份视图外均显示。
disableMonthPicker	boolean	未声明	是否禁用月份选择器。
disableYearPicker	boolean	未声明	是否禁用年份选择器。
components	CalendarComponents	{}	自定义组件插槽。
month	number	未声明	受控浏览月份，0-11。
year	number	未声明	受控浏览年份。
onMonthChange	(month: number) => void	() => {}	浏览月份变化回调。
onYearChange	(year: number) => void	() => {}	浏览年份变化回调。

工具函数

接口	说明
useDefaultStyles(scheme?: 'dark' | 'light')	生成默认浅色或深色样式表，未指定时跟随系统深浅色。
useDefaultClassNames()	生成默认 class token 映射。
isTimeZoneSupported(timeZone?: string)	判断指定 IANA 时区是否可用，便于宿主预先校验配置。
convertToWallTime(date: Date, timeZone?: string)	把某个时刻换算为指定时区下的墙上时间，时区无效或换算失败时返回 undefined。

类型定义

类型	说明
DateType	string | number | Dayjs | Date | null | undefined，日期统一接收类型。
CalendarType	'gregory' | 'jalali'。
CalendarMode	'single' | 'range' | 'multiple'。
NavigationPosition	'around' | 'right' | 'left'。
WeekdayFormat	'min' | 'short' | 'full'。
MonthFormat	'short' | 'full'。
Numerals	支持的数字系统，含 'latn'、'arab'、'arabext'、'deva' 等。
CalendarComponents	组件插槽集合，可替换 Day、Month、Year、Weekday、IconPrev、IconNext、MonthSelector、YearSelector。
CalendarDay	日期单元格数据。
CalendarWeek	星期标题数据。
CalendarMonth	月份单元格数据。
CalendarYear	年份单元格数据。
CalendarMonthSelectorProps	月份选择器按钮属性。
CalendarYearSelectorProps	年份选择器按钮属性。
DatePickerBaseProps	DateTimePicker 的基础属性类型。
SingleChange	(params: { date: DateType }) => void。
RangeChange	(params: { startDate: DateType; endDate: DateType }) => void。
MultiChange	(params: { dates: DateType[]; datePressed?: DateType; change: 'added' | 'removed' | 'updated' }) => void。

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>=20
React Native for OpenHarmony	0.72.139
HarmonyOS SDK	API 21+

运行步骤

1. 获取开发分支源码：

   git clone -b react-native-ui-datepicker_dev https://gitcode.com/hxa-rn/react-native-ui-datepicker.git
   

2. 进入仓库根目录：

   cd react-native-ui-datepicker
   

3. 在仓库根目录安装依赖：

   npm i
   

4. 在仓库根目录生成供示例工程安装的本地安装包：

   npm pack
   

5. 进入 example 目录：

   cd example
   

6. 安装示例工程依赖：

   npm i
   

7. 生成 React Native JavaScript Bundle：

   npm run dev
   

   产物生成到 example/harmony/entry/src/main/resources/rawfile/bundle.harmony.js。

8. 使用 DevEco Studio 打开 example/harmony，等待 oh-package 依赖同步完成；在 File → Project Structure → Signing Configs 中完成签名配置后，选择 entry 模块与手机设备，构建并运行。

约束与限制

兼容性

依赖	要求
React Native for OpenHarmony	>= 0.72
HarmonyOS SDK	API 21+
Example 工程 compatibleSdkVersion	6.0.1(21)
Example 工程 targetSdkVersion	6.1.1(24)
Node.js	>= 18（示例工程要求 >= 20）

使用限制

• 组件为 JS-only 实现，在 RNOH 上运行，日期计算与本地化依赖 dayjs 及其插件。
• 时区换算基于 timezone-support 的时区数据库，不依赖 Intl；timeZone 无效时不做换算，可先用 isTimeZoneSupported 校验。
• initialView="time" 仅在单选模式下生效，区间 / 多选模式下会回退到日期视图。
• startYear / endYear 已在类型定义中声明，但当前实现未生效：年份面板按固定分页展示，暂不支持自定义起止年份。
• 示例工程 entry 模块当前仅声明 phone 设备类型。

系统权限

本库不依赖额外的 HarmonyOS 系统权限。

开源 License

本项目采用 MIT，与上游项目保持一致。

问题反馈渠道

如在使用过程中遇到问题，请在 GitCode 提交Issue，我们会及时跟进。

• 提交问题时建议附上项目版本、RN 版本、OpenHarmony SDK/API 版本、DevEco Studio 版本、设备信息、复现步骤及相关日志。
• 涉及签名、账号、密钥或用户数据时，请勿在 Issue 中上传敏感信息；可按组织安全流程提交脱敏日志。