@hxa-rn/react-native-month-year-picker

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

项目介绍

这是一个为 React Native 提供月份和年份选择能力的组件，原项目面向 iOS 和 Android；当前仓库提供 React Native for OpenHarmony 适配实现。

当前适配实现支持以下能力：

• 设置初始月份和年份。
• 限制最小、最大可选月份。
• 处理确认、取消和中立按钮操作。
• 自定义确认、取消和中立按钮文案。
• 使用指定语言或设备当前系统语言显示月份。
• 支持 full、short、number、shortNumber 四种月份显示模式。
• 根据系统深浅色模式更新弹窗主题。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/react-native-month-year-picker

宿主工程需满足 react-native >=0.72 和 react >=16.11.0。

Autolinking

本包支持 HarmonyOS Autolinking。安装依赖后由宿主工程自动接入，无需手动注册。

导入

import MonthPicker, {
  ACTION_DATE_SET,
  ACTION_DISMISSED,
  ACTION_NEUTRAL,
} from '@hxa-rn/react-native-month-year-picker';

使用说明

基础用法

import React, {useCallback, useState} from 'react';
import {Text, TouchableOpacity, View} from 'react-native';
import MonthPicker, {
  ACTION_DATE_SET,
  ACTION_DISMISSED,
  ACTION_NEUTRAL,
} from '@hxa-rn/react-native-month-year-picker';

export default function MonthPickerExample() {
  const [visible, setVisible] = useState(false);
  const [date, setDate] = useState(new Date());

  const handleChange = useCallback((action: string, selectedDate?: Date) => {
    setVisible(false);

    if (action === ACTION_DISMISSED) {
      return;
    }

    if (
      (action === ACTION_DATE_SET || action === ACTION_NEUTRAL) &&
      selectedDate
    ) {
      setDate(selectedDate);
    }
  }, []);

  return (
    <View>
      <Text>{`${date.getFullYear()}-${date.getMonth() + 1}`}</Text>
      <TouchableOpacity onPress={() => setVisible(true)}>
        <Text>选择月份</Text>
      </TouchableOpacity>

      {visible && (
        <MonthPicker
          value={date}
          minimumDate={new Date(2020, 0)}
          maximumDate={new Date(2030, 11)}
          locale="zh"
          mode="full"
          okButton="确认"
          cancelButton="取消"
          neutralButton="清除"
          onChange={handleChange}
        />
      )}
    </View>
  );
}

MonthPicker 不渲染常驻视图，应在需要打开弹窗时条件渲染，并在 onChange 回调中将其关闭。value 必须是 Date；JavaScript Date 构造函数中的月份从 0 开始，例如 new Date(2020, 0) 表示 2020 年 1 月。未传入 locale 时，HarmonyOS 原生层会使用设备当前系统语言。

接口文档

以下 API 依据 src/index.js、src/index.d.ts 和 src/constants.js 整理。

MonthPicker

月份和年份选择组件。组件打开 HarmonyOS 原生月份年份选择弹窗，并通过 onChange 返回操作结果。

属性	类型	默认值	说明
value	Date	无	设置初始月份和年份；超出日期范围时会调整到最近的边界月份
onChange	(event: EventTypes, newDate: Date) => void	未声明	用户确认、取消、点击中立按钮或关闭弹窗后调用；取消或关闭时日期值为 undefined
locale	string	设备当前系统语言	设置月份文本使用的语言
mode	'full' | 'short' | 'number' | 'shortNumber'	'full'	控制月份显示为完整名称、缩写、两位数字或非补零数字
autoTheme	boolean	true	是否读取并监听系统颜色模式；设为 false 时使用浅色样式
maximumDate	Date	未声明	设置最大可选月份和年份
minimumDate	Date	未声明	设置最小可选月份和年份
okButton	string	'Done'	设置确认按钮文案
cancelButton	string	'Cancel'	设置取消按钮文案
neutralButton	string	null	设置中立按钮文案；未传入时不显示中立按钮

onChange action

以下常量由包入口导出：

导出常量	实际值	date	说明
ACTION_DATE_SET	'dateSetAction'	选中的 Date	点击确认按钮
ACTION_DISMISSED	'dismissedAction'	undefined	点击取消按钮、点击弹窗外区域或关闭弹窗
ACTION_NEUTRAL	'neutralAction'	选中的 Date	点击中立按钮

月份显示模式

mode	示例
full	January、七月、7월
short	Jan、7月、7월
number	01、02、...、12
shortNumber	1、2、...、12

快速验证（运行 Example）

前置条件

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

运行步骤

1. 获取开发分支源码：

   git clone -b react-native-month-year-picker_dev https://gitcode.com/hxa-rn/react-native-month-year-picker.git
   

2. 进入仓库根目录：

   cd react-native-month-year-picker
   

3. 安装根目录依赖：

   npm i
   

4. 生成供示例工程安装的本地安装包：

   npm pack
   

5. 进入 example 目录：

   cd example
   

6. 安装示例工程依赖：

   npm i
   

7. 生成 React Native JavaScript Bundle：

   npm run dev
   

8. 使用 DevEco Studio 打开 example/harmony，同步依赖、完成签名配置后构建并运行。

约束与限制

兼容性

依赖	要求
React Native for OpenHarmony	0.72.139（Example 验证基线；组件要求 React Native >=0.72）
HarmonyOS SDK	API 21+
Example 工程 compatibleSdkVersion	6.0.1(21)
Example 工程 targetSdkVersion	6.1.1(24)
Node.js	库工程 >=18；Example 工程 >=20

使用限制

• 同一时刻只能打开一个月份年份选择弹窗，重复打开会返回错误。
• minimumDate 不能晚于 maximumDate。
• minimumDate 和 maximumDate 按月份和年份限制可选范围；初始值超出范围时会调整到最近的边界月份。
• HarmonyOS 使用居中自定义弹窗，视觉布局与 iOS 的底部工具栏形式不同，但参数和回调语义保持一致。
• autoTheme 默认为 true，会读取并监听系统颜色模式；设为 false 时不监听系统颜色模式并使用浅色样式。

系统权限

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

开源 License

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

问题反馈渠道

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

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