@bingtang-rn/react-native-calendar-picker for HarmonyOS

本项目基于 react-native-calendar-picker 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 8.0.6 | 8.0.6 | 0.72+ | 是（harmony.alias） | API17+ |

安装

npm install @bingtang-rn/react-native-calendar-picker

使用

这是一个纯 JS 库（js_only），无需原生注册。通过 harmony.alias 机制，示例代码中 import CalendarPicker from 'react-native-calendar-picker' 会自动重定向到 @bingtang-rn/react-native-calendar-picker。

import React, { useState } from 'react';
import { View, Text, StyleSheet } from 'react-native';
import CalendarPicker from 'react-native-calendar-picker';

export default function App() {
  const [selectedDate, setSelectedDate] = useState<Date | null>(null);
  return (
    <View style={styles.container}>
      <CalendarPicker
        onDateChange={(date, type) => {
          if (type === 'START_DATE') {
            setSelectedDate(date);
          }
        }}
      />
      <Text>{selectedDate ? selectedDate.toString() : '未选择'}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
  },
});

注意：需安装 peer 依赖 date-fns >=3.0.0。

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 8.0.6 | 是（harmony.alias 自动重定向，无需手动注册） |

本模块为纯 JS 库，无需 C++ 或 ETS 侧 Package 注册。harmony.alias 配置在 ohos/package.json 中将原始包名 react-native-calendar-picker 重定向到 @bingtang-rn/react-native-calendar-picker，Metro 打包时自动处理。

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | onDateChange | 日期选择回调 | (date: Date, type: 'START_DATE'|'END_DATE') | void | ✅ | | onMonthChange | 月份切换回调 | (date: Date) | void | ✅ | | allowRangeSelection | 范围选择 | boolean | - | ✅ | | allowBackwardRangeSelect | 反向范围选择 | boolean | - | ✅ | | minRangeDuration | 最小范围天数 | number | Array | - | ✅ | | maxRangeDuration | 最大范围天数 | number | Array | - | ✅ | | minDate | 最小可选日期 | Date | - | ✅ | | maxDate | 最大可选日期 | Date | - | ✅ | | restrictMonthNavigation | 限制月份导航 | boolean | - | ✅ | | scrollable | 滚动模式 | boolean | - | ✅ | | horizontal | 滚动方向 | boolean | - | ✅ | | scrollDecelarationRate | 减速速率 | 'normal'|'fast'|number | - | ✅ | | enableDateChange | 允许选日期 | boolean | - | ✅ | | startFromMonday | 周一开始 | boolean | - | ✅ | | showDayStragglers | 跨月日填充 | boolean | - | ✅ | | firstDay | 起始日 | 0-6 | - | ✅ | | weekdays | 自定义星期标签 | Array(7) | - | ✅ | | months | 自定义月份名 | Array(12) | - | ✅ | | initialDate | 初始日期 | Date | - | ✅ | | initialView | 初始视图 | 'days'|'months'|'years' | - | ✅ | | customDatesStyles | 自定义日期样式 | Array | Func | - | ✅ | | customDayHeaderStyles | 自定义表头样式 | Func | - | ✅ | | disabledDates | 禁用日期 | Array | Func | - | ✅ | | disabledDatesTextStyle | 禁用日期文本样式 | TextStyle | - | ✅ | | selectedStartDate | 选中开始日期 | Date | - | ✅ | | selectedEndDate | 选中结束日期 | Date | - | ✅ | | selectedDayColor | 选中日背景色 | string | - | ✅ | | selectedDayTextColor | 选中日文本色 | string | - | ✅ | | selectedDayStyle | 选中日样式 | ViewStyle | - | ✅ | | selectedDayTextStyle | 选中日文本样式 | TextStyle | - | ✅ | | selectedRangeStartStyle | 范围起始样式 | ViewStyle | - | ✅ | | selectedRangeEndStyle | 范围结束样式 | ViewStyle | - | ✅ | | selectedRangeStyle | 范围内样式 | ViewStyle | - | ✅ | | selectedRangeStartTextStyle | 范围起始文本样式 | TextStyle | - | ✅ | | selectedRangeEndTextStyle | 范围结束文本样式 | TextStyle | - | ✅ | | selectedDisabledDatesTextStyle | 选中禁用日文本样式 | TextStyle | - | ✅ | | todayBackgroundColor | 今日背景色 | string | - | ✅ | | todayTextStyle | 今日文本样式 | TextStyle | - | ✅ | | textStyle | 全局文本样式 | TextStyle | - | ✅ | | dayShape | 日期形状 | 'circle'|'square' | - | ✅ | | scaleFactor | 缩放因子 | number | - | ✅ | | width | 容器宽度 | number | - | ✅ | | height | 容器高度 | number | - | ✅ | | headingLevel | 无障碍标题级别 | number | - | ✅（web 专属，鸿蒙无影响） | | selectMonthTitle | 月份选择标题 | string | - | ✅ | | selectYearTitle | 年份选择标题 | string | - | ✅ | | dayLabelsWrapper | 星期标签容器样式 | ViewStyle | - | ✅ | | monthYearHeaderWrapperStyle | 月年头部容器样式 | ViewStyle | - | ✅ | | headerWrapperStyle | 整个头部容器样式 | ViewStyle | - | ✅ | | monthTitleStyle | 月份标题样式 | TextStyle | - | ✅ | | yearTitleStyle | 年份标题样式 | TextStyle | - | ✅ | | previousTitle | 上月按钮文字 | string | - | ✅ | | nextTitle | 下月按钮文字 | string | - | ✅ | | previousTitleStyle | 上月按钮样式 | TextStyle | - | ✅ | | nextTitleStyle | 下月按钮样式 | TextStyle | - | ✅ | | previousComponent | 上月自定义组件 | ReactNode | - | ✅ | | nextComponent | 下月自定义组件 | ReactNode | - | ✅ | | fontScaling | 字体缩放 | boolean | - | ✅ | | goToDate (ref) | 编程式跳转日期 | (date, options?) | void | ✅ | | resetSelections (ref) | 清除选择 | () | void | ✅ |

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 17+ |

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包

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

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

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

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

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

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

已知差异

1. ScrollView 减速行为：鸿蒙平台 ScrollView 采用最小二乘法拟合瞬时速度，与 Android 有差异，scrollable 模式滚动手感可能略有不同。
2. Platform.OS === 'android' 分支：Scroller.js 中有一个 Android 专属的 bug 规避逻辑（首次选日期跳回上月），鸿蒙端不触发。如鸿蒙端出现类似问题，需在 Example 运行时验证。
3. Text.defaultProps 全局修改：库在构造函数中设置 Text.defaultProps.allowFontScaling，属已弃用模式，可能产生告警但不影响功能。
4. 属性命名：scrollDecelarationRate（原库拼写，应为 scrollDecelerationRate）保持与原库一致，不做修正。
5. goToDate 在 scrollable 模式下不支持：原库 index.js 中 goToDate 在 scrollable=true 时会 console.error 并直接返回（原库行为，非鸿蒙特有）。需调用 goToDate 时请先设置 scrollable=false，或使用 handleOnPressNext/handleOnPressPrevious 编程式翻月。

开源协议

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