@hxa-rn/react-native-modal-datetime-picker

v1.0.0

Published

9 days ago

react-native-modal-datetime-picker for HarmonyOS

0High
0Medium
0Low

react-native harmony harmonyos

react-native-modal-datetime-picker

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

项目介绍

react-native-modal-datetime-picker 是 React Native 日期与时间选择器的模态包装组件：它在选择器外提供统一的模态交互，并对外暴露确认、取消、变化和隐藏完成回调。适配后的实现支持日期、时间和日期时间三种选择流程，可直接用于 OpenHarmony 工程。

模态交互：以底部进入的模态承载选择器，支持点击遮罩取消，并在关闭动画完成后回调。
三种模式：date 选择日期，time 选择时间，datetime 先选日期再选时间，最终确认时才提交。
回调链：onChange、onConfirm、onCancel 与 onHide(didConfirm, date)。
选择范围与显示：minimumDate、maximumDate、is24Hour、display、minuteInterval、locale、timeZoneOffsetInMinutes。
包装层定制：按钮文案与文字颜色、自定义头部/确认按钮/取消按钮/选择器组件、五类样式属性，以及深色模式。
公开导出：默认与具名的 DateTimePickerModal、ConfirmButton、CancelButton、两个按钮样式对象和 10 个颜色/尺寸/字重常量。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/react-native-modal-datetime-picker

本包通过 peerDependencies 要求宿主工程提供 react-native >= 0.72。
本包通过 dependencies 自动安装 @react-native-ohos/[email protected]，由它提供 OpenHarmony 侧的原生日期时间选择能力，无需单独安装。
本包为纯 JavaScript 实现，宿主工程无需为本包执行额外的原生编译或源码集成步骤。

Autolinking

本包自身不包含 HarmonyOS 原生模块，无需为本包配置 Autolinking。原生选择能力来自依赖包 @react-native-ohos/datetimepicker，需由 RNOH Autolinking 注册到宿主工程：example/harmony/entry/src/main/ets/RNOHPackagesFactory.ets 由 RNOH Autolinking 生成并注册该依赖包，请勿手动修改。

导入

import DateTimePickerModal from '@hxa-rn/react-native-modal-datetime-picker';
import {
  DateTimePickerModal as NamedDateTimePickerModal,
  ConfirmButton,
  CancelButton,
  confirmButtonStyles,
  cancelButtonStyles,
  BACKGROUND_COLOR_LIGHT,
  BACKGROUND_COLOR_DARK,
  BORDER_COLOR,
  BORDER_COLOR_DARK,
  BORDER_RADIUS,
  BUTTON_FONT_WEIGHT,
  BUTTON_FONT_COLOR,
  BUTTON_FONT_SIZE,
  HIGHLIGHT_COLOR_DARK,
  HIGHLIGHT_COLOR_LIGHT,
} from '@hxa-rn/react-native-modal-datetime-picker';

ReactNativeModalDateTimePickerProps、ConfirmButtonPropTypes、CancelButtonPropTypes、CancelButtonStylePropTypes、ConfirmButtonStylePropTypes 等类型可从同一入口以 TypeScript 类型方式导入。

使用说明

基础用法

import React, { useState } from 'react';
import { Button, SafeAreaView, Text, View } from 'react-native';
import DateTimePickerModal from '@hxa-rn/react-native-modal-datetime-picker';

export default function App() {
  const [isVisible, setIsVisible] = useState(false);
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <SafeAreaView>
      <View>
        <Button title="选择日期" onPress={() => setIsVisible(true)} />
        <Text>当前值：{selectedDate.toISOString()}</Text>
      </View>
      <DateTimePickerModal
        isVisible={isVisible}
        mode="date"
        date={selectedDate}
        onChange={setSelectedDate}
        onConfirm={date => {
          setSelectedDate(date);
          setIsVisible(false);
        }}
        onCancel={() => setIsVisible(false)}
      />
    </SafeAreaView>
  );
}

mode 取 date、time 或 datetime；datetime 模式下确认按钮在日期步骤显示为下一步，进入时间步骤后才提交。
date 决定打开选择器时选中的初始值；传入无效日期时会回退到当前时间。
onChange 在选择值变化时回调当前 Date，onConfirm 在确认后回调最终 Date。
onCancel 在点击取消、点击遮罩或系统取消时调用；onHide 在关闭动画完成后回调确认状态与当前 Date，一次关闭只回调一次。
设置 minimumDate、maximumDate 可限制可选范围；设置 is24Hour 可切换时间显示制式。
传入 customHeaderIOS、customConfirmButtonIOS、customCancelButtonIOS 或 customPickerIOS 可替换对应区域；传入 isDarkModeEnabled 可强制深浅色，未传入时跟随系统主题。

日期时间组合、范围与区域化

import React, { useMemo, useState } from 'react';
import { SafeAreaView, Text } from 'react-native';
import DateTimePickerModal from '@hxa-rn/react-native-modal-datetime-picker';

export default function App() {
  const [isVisible, setIsVisible] = useState(false);
  const [value, setValue] = useState(new Date());

  const { minimumDate, maximumDate } = useMemo(() => {
    const min = new Date(value);
    min.setDate(min.getDate() - 7);
    const max = new Date(value);
    max.setDate(max.getDate() + 7);
    return { minimumDate: min, maximumDate: max };
  }, [value]);

  return (
    <SafeAreaView>
      <Text>当前值：{value.toISOString()}</Text>
      <DateTimePickerModal
        isVisible={isVisible}
        mode="datetime"
        date={value}
        minimumDate={minimumDate}
        maximumDate={maximumDate}
        is24Hour={false}
        locale="zh-CN"
        display="spinner"
        onChange={setValue}
        onConfirm={date => {
          setValue(date);
          setIsVisible(false);
        }}
        onCancel={() => setIsVisible(false)}
        onHide={(didConfirm, date) => console.log('关闭完成', didConfirm, date)}
      />
    </SafeAreaView>
  );
}

datetime 模式先进入日期步骤，确认后进入时间步骤，最终值由日期与时间合并得到，只有时间步骤的确认才触发 onConfirm。
minimumDate、maximumDate 在 JavaScript 层对选中值做边界钳制，越界值会被拉回最近的边界，并同步到原生选择器的显示。
locale 仅支持 zh-CN 与 en-US，未匹配时回退 en-US；生效时由自绘轮盘渲染本地化月名与年月日排列顺序。
minuteInterval 取有效间隔值时，时间步骤改用自绘分钟滚轮，只渲染该间隔的倍数。

接口文档

以下 API 依据 src/index.js、src/DateTimePickerModal.harmony.js 与 typings/index.d.ts 整理。

DateTimePickerModal

DateTimePickerModal 是本包默认导出与具名导出的模态日期时间选择器组件。

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | isVisible | boolean | false | 控制模态选择器是否显示。 | | date | Date | new Date() | 打开选择器时选中的初始日期时间；无效日期回退到当前时间。 | | mode | "date" \| "time" \| "datetime" | "date" | 选择日期、时间或日期时间组合。 | | onChange | (newDate: Date) => void | 未声明 | 选择值变化时回调当前日期。 | | onConfirm | (date: Date) => void | 必填 | 点击确认后回调最终日期。 | | onCancel | () => void | 必填 | 取消、点击遮罩或系统取消时回调。 | | onHide | (didConfirm: boolean, date: Date) => void | 未声明 | 关闭动画完成后回调确认状态与当前日期。 | | minimumDate | Date | 未声明 | 可选日期下限，在 JavaScript 层钳制选中值。 | | maximumDate | Date | 未声明 | 可选日期上限，在 JavaScript 层钳制选中值。 | | is24Hour | boolean | true | 设置时间是否为 24 小时制。 | | display | "default" \| "spinner" \| "compact" \| "inline" | "default" | 选择器外观；spinner 使用滚轮，inline/compact 使用系统日历控件。 | | minuteInterval | 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 10 \| 12 \| 15 \| 20 \| 30 | 未声明 | 分钟可选间隔；有效间隔会同时用于规范化初始分钟值与自绘分钟滚轮。 | | locale | string | 未声明 | 选择器使用的区域信息，支持 zh-CN 与 en-US。 | | timeZoneOffsetInMinutes | number | 未声明 | 强制使用的时区偏移（分钟）；未设置时使用设备时区。 | | isDarkModeEnabled | boolean | 未声明 | 强制深浅色样式；未设置时读取系统配色。 | | buttonTextColorIOS | string | 未声明 | 确认与取消按钮文字颜色；未设置时使用默认样式色 #007ff9。 | | cancelTextIOS | string | 'Cancel' | 取消按钮文案。 | | confirmTextIOS | string | 'Confirm' | 确认按钮文案。 | | customCancelButtonIOS | React.FunctionComponent<CustomCancelButtonPropTypes> | 未声明 | 自定义取消按钮组件。 | | customConfirmButtonIOS | React.FunctionComponent<CustomConfirmButtonPropTypes> | 未声明 | 自定义确认按钮组件。 | | customHeaderIOS | HeaderComponent | 未声明 | 自定义标题区域组件。 | | customPickerIOS | PickerComponent | 未声明 | 替换默认选择器组件。 | | backdropStyleIOS | ViewStyle | 未声明 | 遮罩样式。 | | modalStyleIOS | ViewStyle | 未声明 | 模态内容样式。 | | pickerContainerStyleIOS | ViewStyle | 未声明 | 选择器容器样式。 | | pickerStyleIOS | ViewStyle | 未声明 | 选择器样式。 | | pickerComponentStyleIOS | ViewStyle | 未声明 | 底层选择器组件样式。 | | modalPropsIOS | Object | 未声明 | 透传给底层 React Native Modal 的属性。 | | testID | string | 未声明 | 选择器视图的测试标识（见「使用限制」）。 | | cancelButtonTestID | string | 未声明 | 取消按钮的测试标识。 | | confirmButtonTestID | string | 未声明 | 确认按钮的测试标识。 |

按钮与样式导出

| 导出项 | 类型 | 说明 | | --- | --- | --- | | ConfirmButton | React.FunctionComponent<ConfirmButtonPropTypes> | 默认确认按钮组件。 | | CancelButton | React.FunctionComponent<CancelButtonPropTypes> | 默认取消按钮组件。 | | confirmButtonStyles | ConfirmButtonStylePropTypes | 确认按钮默认样式对象。 | | cancelButtonStyles | CancelButtonStylePropTypes | 取消按钮默认样式对象。 | | BACKGROUND_COLOR_LIGHT、BACKGROUND_COLOR_DARK、BORDER_COLOR、BORDER_COLOR_DARK、BORDER_RADIUS、BUTTON_FONT_WEIGHT、BUTTON_FONT_COLOR、BUTTON_FONT_SIZE、HIGHLIGHT_COLOR_DARK、HIGHLIGHT_COLOR_LIGHT | string \| number | 公开颜色、尺寸与字重常量。 | | ReactNativeModalDateTimePickerProps | TypeScript 类型 | 组件 Props 类型。 | | ConfirmButtonPropTypes、CancelButtonPropTypes、CancelButtonStylePropTypes、ConfirmButtonStylePropTypes、CustomCancelButtonPropTypes、CustomConfirmButtonPropTypes、HeaderComponent、PickerComponent | TypeScript 类型 | 按钮、自定义组件与样式类型。 |

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | | :-- | --- | | Node.js | >=20 | | React Native for OpenHarmony | @react-native-oh/[email protected] | | HarmonyOS SDK | API 21+ |

运行步骤

在仓库根目录生成供示例工程安装的本地安装包：
```
npm pack
```
进入 example 目录：
```
cd example
```
安装示例工程依赖：
```
npm install
```
生成 React Native JavaScript Bundle：
```
npm run dev
```
使用 DevEco Studio 打开 example/harmony，同步依赖，完成本地签名配置后构建并运行。

约束与限制

兼容性

| 依赖 | 要求 | | --- | --- | | React Native for OpenHarmony | @react-native-oh/[email protected] | | HarmonyOS SDK | API 21+；适配范围为 API 21–24。 | | Example 工程 compatibleSdkVersion | 6.0.1(21) | | Example 工程 targetSdkVersion | 6.1.1(24) | | Node.js | 本库 >=18；Example 工程 >=20。 |

使用限制

datetime 模式分为日期与时间两个步骤，只有最终确认后才回调 onConfirm。
minimumDate、maximumDate 在 JavaScript 层对选中值做边界钳制，越界时会把显示同步回边界值；底层 OpenHarmony 系统日历控件本身无法表达起止范围。
minuteInterval 取有效间隔值时，时间模式改用自绘分钟滚轮显示有效分钟项，系统时间选择器本身不会按间隔隐藏分钟项。
locale 由自绘轮盘执行区域化（仅支持 zh-CN 与 en-US，月名与年月日排列顺序），底层原生选择器不支持该属性；当同时设置了 minimumDate 或 maximumDate 时，日期步骤不使用自绘轮盘，locale 在该步骤不生效。
display 为 spinner 时使用滚轮外观，inline/compact 使用系统日历控件，其余取值按底层默认外观处理。
本版 React Native for OpenHarmony 未桥接 testID 与 accessibilityRole：无法通过 testID 在真机 UI 树中定位节点，按钮的可访问角色由系统推断；accessibilityLabel 会映射为系统无障碍文本。
timePickerModeAndroid 为 Android 专属属性，在 OpenHarmony 上不适用。
customHeaderIOS、customPickerIOS、modalPropsIOS 与 *IOS 样式属性源自 iOS 实现，不保证在 OpenHarmony 上呈现完全等价的视觉效果。
日期时间选择能力依赖 @react-native-ohos/[email protected] 提供的 OpenHarmony 原生实现。

系统权限

本库不依赖额外的 HarmonyOS 系统权限，也无需动态申请权限。

开源 License

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

问题反馈渠道

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

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