@bingtang-rn/react-native-calendario for HarmonyOS

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

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 3.5.2 | 0.72+ | 否（js-only） | API17+ |

安装

npm install @bingtang-rn/react-native-calendario

使用

import { Calendar } from 'react-native-calendario';

// Range selection
<Calendar
  onPress={(date) => console.log(date)}
  startDate={new Date('2025-07-05')}
  endDate={new Date('2025-07-18')}
  startingMonth="2025-06-01"
  numberOfMonths={12}
  firstDayMonday
  theme={{ activeDayContainerStyle: { backgroundColor: '#6d95da' } }}
/>

// Single day selection
<Calendar
  onPress={(date) => console.log(date)}
  startDate={new Date()}
  disableRange
  startingMonth="2025-06-01"
/>

import 时使用原库名 'react-native-calendario'，而非鸿蒙包名。RNOH 通过 harmony.alias 自动映射。

平台差异：

• 本库为纯 JS 组件库，无原生模块依赖，HarmonyOS 上行为与其他平台一致。
• Platform.OS === 'web' 分支在鸿蒙端不会命中，走原生 FlatList 虚拟化路径。

权限要求：

• 无需任何系统权限。

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 否（js-only，无需原生注册） |

本库为 js-only 类型，无原生 TurboModule/Fabric 组件，无需原生 Package 注册。通过 harmony.alias 将 react-native-calendario 的 import 重定向到 @bingtang-rn/react-native-calendario，由 Metro bundler 在 JS 层完成映射。

说明：本库为 js-only 类型，无需原生 Package 注册。以下为确认 alias 配置正确。

确认 harmony.alias

在 ohos/package.json 中确认 harmony.alias 配置：

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

此配置由 scaffold 自动生成，确保 Metro 将 react-native-calendario 的 import 重定向到 @bingtang-rn/react-native-calendario。

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | Calendar | 日历月份滚动列表组件 | CalendarProps | JSX.Element | 完全支持 | | onPress | 日期点击回调 | date: Date | void | 完全支持 | | startDate | 选中起始日期 | Date | — | 完全支持 | | endDate | 选中结束日期 | Date | — | 完全支持 | | startingMonth | 首个渲染月份 | string | — | 完全支持 | | numberOfMonths | 渲染月份数 | number | — | 完全支持 | | minDate | 最小可选日期 | Date | — | 完全支持 | | maxDate | 最大可选日期 | Date | — | 完全支持 | | disableRange | 禁用范围选择 | boolean | — | 完全支持 | | firstDayMonday | 周一为每周第一天 | boolean | — | 完全支持 | | locale | 语言设置 | LocaleType | — | 完全支持 | | theme | 自定义样式 | ThemeType | — | 完全支持 | | monthHeight | 月份行高 | number | — | 完全支持 | | markedDays | 日期标记（多圆点） | MarkedDays | — | 完全支持 | | disabledDays | 禁用日期 | object | — | 完全支持 | | showWeekdays | 显示星期列 | boolean | — | 完全支持 | | showMonthTitle | 显示月份标题 | boolean | — | 完全支持 | | dayNames | 自定义星期名 | string[] | — | 完全支持 | | monthNames | 自定义月份名 | string[] | — | 完全支持 | | disableOffsetDays | 隐藏非当月日期 | boolean | — | 完全支持 | | renderDayContent | 自定义日期内容渲染 | function | — | 完全支持 | | renderAllMonths | Web 端渲染全部月份 | boolean | — | 部分支持（Web专用，鸿蒙端无效） | | calculateMonthHeightDynamically | 动态计算月份高度 | boolean | — | 完全支持 | | initialListSize | FlatList initialNumToRender | number | — | 完全支持 | | initialScrollIndex | 初始滚动位置 | number | — | 完全支持 | | viewableItemsChanged | 可见项变化回调 | function | — | 完全支持 | | viewableRangeOffset | 可见范围偏移量 | number | — | 完全支持 | | contentContainerStyle | FlatList 内容容器样式 | StyleProp | — | 完全支持 | | showsVerticalScrollIndicator | 显示垂直滚动条 | boolean | — | 完全支持 | | RangeType | 范围选择类型 | type | — | 完全支持 | | LocaleType | 语言枚举 | type | — | 完全支持 | | ThemeType | 主题类型 | type | — | 完全支持 | | DayType | 日期类型 | type | — | 完全支持 | | ViewableItemsType | 可见项类型 | type | — | 完全支持 | | CalendarProps | 组件 Props 类型 | type | — | 完全支持 |

平台差异

• renderAllMonths：Web 专用属性，在 HarmonyOS 上无效。鸿蒙端使用 FlatList 虚拟化列表渲染月份。
• Platform.OS 判断：源码中 Platform.OS === 'web' 在鸿蒙端不会命中，始终走原生 FlatList 路径（含 getItemLayout、removeClippedSubviews、initialScrollIndex）。

未实现功能

无。本库为纯 JS/TS React Native 组件库，所有公开能力均通过标准 RN 组件和 JS 逻辑实现，RNOH 完整支持。

使用限制

• 依赖 moment (2.30.1)：纯 JS 日期库，不使用 Intl API，在鸿蒙 Hermes 引擎上完全兼容。
• 依赖 react-native-month (1.6.3)：纯 JS/TS RN 组件库，使用标准 RN 组件，无原生代码，通过 RNOH 直接运行。
• 无需任何系统权限声明。

快速验证（运行 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

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 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

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

遗留问题

无

开源协议

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