react-native-datepicker

本项目基于 react-native-datepicker 开发。如果在使用过程中有任何问题，欢迎在 AtomGit 提交 Issue，会及时跟进。

项目介绍

@hxa-rn/react-native-datepicker 是 react-native-datepicker v1.7.2 的鸿蒙（OpenHarmony）适配版本，当前版本 1.7.3。

本模块为 js-only（纯 JS） 日期/时间选择器组件：点击输入框弹出底部 Modal 面板，通过自研 HarmonyDatePicker 列式滚轮完成选择，基于 Moment.js 解析与格式化日期字符串，支持 date / datetime / time 三种模式，以及范围限制、自定义样式、图标与回调等能力。

与原库差异简述：

• 原库 Android 端使用 DatePickerAndroid / TimePickerAndroid 系统对话框；鸿蒙端改为自研滚轮面板。
• 原库 iOS 端使用 DatePickerIOS；鸿蒙端以 HarmonyDatePicker（RN 核心 FlatList + snapToInterval）替代，交互语义（打开 → 滚轮选择 → 确认/取消）保持一致。

集成指南

安装鸿蒙适配包：

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

在宿主工程 package.json 中配置 harmony.alias，使业务代码仍可使用原库名 import：

{
  "harmony": {
    "alias": "react-native-datepicker"
  }
}

业务侧 import 示例：

import DatePicker from 'react-native-datepicker';

Peer 依赖：

依赖	版本要求
react-native	>= 0.72

运行时依赖（随包装载）： moment、prop-types。

本模块为 js-only，无需 Autolinking、HAR 编译或在 PackageProvider / CMakeLists.txt 中注册原生 Package。安装后直接 import 使用即可。发布产物为 JavaScript，不含 .d.ts；下面示例按 JS 编写。

使用说明

日期选择（mode="date"）

import React, { Component } from 'react';
import DatePicker from 'react-native-datepicker';

export default class MyDatePicker extends Component {
  state = { date: '2026-08-15' };

  render() {
    return (
      <DatePicker
        style={{ width: 200 }}
        date={this.state.date}
        mode="date"
        placeholder="请选择日期"
        format="YYYY-MM-DD"
        minDate="2020-01-01"
        maxDate="2030-12-31"
        confirmBtnText="确定"
        cancelBtnText="取消"
        onDateChange={(dateStr, date) => {
          this.setState({ date: dateStr });
        }}
      />
    );
  }
}

日期时间选择（mode="datetime"）

import React, { Component } from 'react';
import DatePicker from 'react-native-datepicker';

export default class MyDateTimePicker extends Component {
  state = { date: '2026-08-15 14:30' };

  render() {
    return (
      <DatePicker
        date={this.state.date}
        mode="datetime"
        format="YYYY-MM-DD HH:mm"
        onDateChange={(dateStr, date) => {
          this.setState({ date: dateStr });
        }}
      />
    );
  }
}

时间选择（mode="time"）

import React, { Component } from 'react';
import DatePicker from 'react-native-datepicker';

export default class MyTimePicker extends Component {
  state = { date: '14:30' };

  render() {
    return (
      <DatePicker
        date={this.state.date}
        mode="time"
        format="HH:mm"
        is24Hour={true}
        minuteInterval={5}
        onDateChange={(dateStr, date) => {
          this.setState({ date: dateStr });
        }}
      />
    );
  }
}

手动打开/关闭面板

组件为 class 组件，可通过 ref 调用实例方法 onPressDate() 手动打开面板：

import React, { Component, createRef } from 'react';
import DatePicker from 'react-native-datepicker';

export default class ManualOpenExample extends Component {
  datePickerRef = createRef();

  openPicker = () => {
    const picker = this.datePickerRef.current;
    if (picker) {
      picker.onPressDate();
    }
  };

  render() {
    return (
      <DatePicker
        ref={this.datePickerRef}
        date="2026-08-15"
        mode="date"
      />
    );
  }
}

面板打开后点击取消按钮或遮罩（未自定义 onPressMask 时）可关闭。

自定义样式

通过 customStyles 覆盖各部件样式，源码实际读取的 key 包括：dateTouchBody、dateInput、dateText、placeholderText、dateIcon、datePickerCon、datePicker、btnCancel、btnConfirm、btnTextCancel、btnTextConfirm、disabled。外层容器宽度/布局请用组件的 style，不会读取 customStyles.dateTouch。

接口文档

导出默认组件 DatePicker（class 组件）。

Props

属性	类型	默认值	说明
mode	'date' | 'datetime' | 'time'	'date'	选择模式
date	string | Date	''	当前/初始日期；空时打开面板默认定位当前时间（并收敛到 min/max 范围）
format	string	随 mode：YYYY-MM-DD / YYYY-MM-DD HH:mm / HH:mm	Moment 格式化模板
minDate	string | Date	—	最小可选日期
maxDate	string | Date	—	最大可选日期
placeholder	string	''	日期为空时的占位文案
confirmBtnText	string	'确定'	确认按钮文案
cancelBtnText	string	'取消'	取消按钮文案
is24Hour	boolean	随 format 推断（含 h/a 时为 12 小时制）	是否 24 小时制
minuteInterval	number	—	分钟选项步进间隔
showIcon	boolean	true	是否显示日期图标
iconSource	number | {uri: string}	内置 date_icon.png	图标资源
iconComponent	element	—	自定义图标组件（优先于 iconSource）
disabled	boolean	false	禁用时点击不弹出面板
hideText	boolean	false	隐藏日期文本
allowFontScaling	boolean	true	日期文字是否随系统字体缩放
customStyles	object	{}	各部件自定义样式
TouchableComponent	Component	TouchableHighlight	底层触摸组件
getDateStr	(date: Date) => string	—	自定义日期字符串格式化函数
height	number	259	面板高度（px）
duration	number	300	面板弹出/收起动画时长（ms）
locale	string	—	会传给 HarmonyDatePicker，但当前实现未使用该值：滚轮列标签不本地化，getDateStr 也不会按 locale 调用 moment
androidMode	'clock' | 'calendar' | 'spinner' | 'default'	'default'	兼容字段，鸿蒙端无实际效果
modalAccessory	ReactNode	—	面板顶部附加内容

回调

回调	签名	说明
onDateChange	(dateStr: string, date: Date) => void	点击确认后触发；dateStr 为格式化字符串，date 为 Date 对象
onOpenModal	() => boolean | void	打开面板前触发；返回 false 时不打开面板
onCloseModal	() => void	面板关闭时触发（确认或取消后）
onPressMask	() => void	点击遮罩时触发；若传入该回调，组件不再自动执行默认取消关闭，需自行处理

实例方法

方法	说明
onPressDate()	手动打开选择面板（等效点击输入框）
onPressCancel()	取消当前选择并关闭面板（等效点击取消按钮）

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>= 18（运行 Example 建议 >= 20，见 example/package.json）
DevEco Studio	5.0+ / 6.0+
HarmonyOS SDK	API 13+（example/harmony 的 compatibleSdkVersion 为 5.0.1(13)）

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-datepicker.git
cd react-native-datepicker
git checkout main

2. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-datepicker@^1.7.3，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

4. 安装鸿蒙依赖

cd harmony
ohpm install

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 首次构建请在 File → Project Structure → Signing Configs 勾选 Automatically generate signature，Apply 后 Sync
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：本模块为 js-only，Example 无需 Autolinking、HAR 编译或原生 Package 注册。编 HAP 前必须先执行 npm run dev。

约束与限制

项	要求
React Native（RNOH）	0.72（peerDependencies >= 0.72）
HarmonyOS SDK	API 13+（example/harmony 的 compatibleSdkVersion 为 5.0.1(13)）
Node.js	>= 18（engines）；运行 Example 建议 >= 20
权限	纯 JS 组件，无额外系统权限
架构	js-only，无 HAR / 原生模块，无需 Autolinking
平台差异	鸿蒙端使用自研 HarmonyDatePicker 滚轮面板，不使用 DatePickerAndroid / TimePickerAndroid / DatePickerIOS
androidMode	兼容字段，鸿蒙端无实际效果
locale	当前实现未使用该值，滚轮列标签与 getDateStr 均不按 locale 本地化
其他	format 含 h/a 时默认 12 小时制；无效日期字符串不导致崩溃；滚轮对齐以真机为准

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

如在集成或使用过程中遇到问题，可通过以下渠道反馈：

• GitCode 仓库：https://gitcode.com/hxa-rn/react-native-datepicker
• Issue 提交：https://gitcode.com/hxa-rn/react-native-datepicker/issues