# @dhis2/multi-calendar-dates 中文文档 规范地址：https://npmcn.com/package/%40dhis2/multi-calendar-dates/ 版本：3\.2\.1 npm 元数据更新时间：2026-10-20T09:05:48.204Z 中文译文更新时间：2026-11-12T06:16:07.975Z 软件包许可：BSD-3-Clause 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dhis2/multi-calendar-dates 原文对照：https://npmcn.com/package/%40dhis2/multi-calendar-dates/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2.6 MB，531 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：react \>=16\.8，react-dom \>=16\.8 - 首次发布：2023-01-09T18:26:40.832Z - 最新版本发布：2026-10-20T09:05:47.965Z - 近 30 天下载量：16985（2026-10-12 至 2026-11-10，npm 官方下载统计） - 已发布版本数：59（近 12 个月 11 个） ## 中文简介 [![codecov](https://codecov.io/github/dhis2/multi-calendar-dates/graph/badge.svg?token=VZBHOLXYP1)](https://codecov.io/github/dhis2/multi-calendar-dates) ## 安装 ```sh npm install @dhis2/multi-calendar-dates ``` 也可以使用：`pnpm add @dhis2/multi-calendar-dates`、`yarn add @dhis2/multi-calendar-dates`、`bun add @dhis2/multi-calendar-dates` ## README [![codecov](https://codecov.io/github/dhis2/multi-calendar-dates/graph/badge.svg?token=VZBHOLXYP1)](https://codecov.io/github/dhis2/multi-calendar-dates) # 多日历引擎 这个库用于在多卡路里系统(即. Ethiopic, Nepali等)跨DHIS-2应用. 它主要暴露两个 组件 : 1. 钩子喜欢 [使用日期选择器](https://github.com/dhis2/multi-calendar-dates/blob/multi-calendar-docs/src/hooks/useDatePicker.ts) 用于构建UI组件(部分为@dhis/ui),例如: [日历](https://ui.dhis2.nu/components/calendar) 财务报告和审定财务报表 [日历输入](https://ui.dhis2.nu/components/calendar-input) 组件. 2. 帮助方法,比如 `generateFixedPeriods` 财务报告和审定财务报表 `getNowInCalendar` 要处理 历代、日期操纵和计算 算计系统. 这个图书馆背后的想法是 抽象复杂的交易细节 在DHIS2中注明日期,并将其集中到一个地方供消费 不同的应用程序和图书馆. 内部,图书馆依靠 [时间 API 密码](https://tc39.es/proposal-temporal) 除其他外,旨在实现 目标,全力支持非希腊日历. 这个 [文档](https://docs.google.com/document/d/19zjyB45oBbqC5KeubaU8E7cw9fGhFc3tOXY0GkzZKqc/edit?userstoinvite=hendrik%40dhis2.org#heading=h.rjt0etsbsqh6) 对该项目有一些要求和设计决定. 这个 [吉拉史诗](https://dhis2.atlassian.net/browse/DHIS2-14051) 列出应用程序 移动到使用图书馆, 以及接下来会发生什么. # API 密码 下面的一切都是从 `@dhis2/multi-calendar-dates`。见 [API 和 实例](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md) 参数、返回值和示例. ## 帮助者 | 名称 | 说明 | | --- | --- | | [`getNowInCalendar`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#getnowincalendar) | 日历和时区的当前日期和时间 | | [`convertFromIso8601`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#convertfromiso8601-and-converttoiso8601) | 将 ISO 8601 (希腊语) 日期转换为日历 | | [`convertToIso8601`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#convertfromiso8601-and-converttoiso8601) | 将日历中的日期转换为 ISO 8601 (希腊语) | | [`addToCalendarDate`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#date-arithmetic-and-formatting) | 在日历中添加或减去年数、月数和日数,将日数夹到月底 | | [`formatCalendarDate`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#date-arithmetic-and-formatting) | 格式化日期为 `yyyy-MM-dd` 字符串 DHIS2 后端预期, 随时间而选择 | | [`getDaysInMonth`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#date-arithmetic-and-formatting) | 日历中一个月中的天数 | | `validateDateString` | 对照格式、分/最大范围以及日历规则验证日期字符串。 回返a `DateValidationResult` 无效时的代码 | ## 固定期间 由数据条目等应用程序和分析库生成 不同日历中的固定时段列表(日、周、月、.) 系统. | 名称 | 说明 | | --- | --- | | [`generateFixedPeriods`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#generatefixedperiods) | 一年中所有时期类型, 在给定日历和地区 | | [`getFixedPeriodByDate`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#getfixedperiodbydate) | 包含日期的周期类型 | | [`createFixedPeriodFromPeriodId`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#createfixedperiodfromperiodid) | 重建一个段从它的ID,例如. `202301` | | [`getAdjacentFixedPeriods`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#getadjacentfixedperiods) | N 期之前或之后 | ## 钩子等 钩被出口,但大多是内部使用的: `@dhis2/ui`是因为 [日历](https://ui.dhis2.nu/components/calendar) 财务报告和审定财务报表 [日历输入](https://ui.dhis2.nu/components/calendar-input)。大多数应用程序使用 这些部件,而不是直接的钩子. | 名称 | 说明 | | --- | --- | | [`useDatePicker`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/#readme-hooks-for-calendar-ui) | 返回日历拾取器的周网格、日标签和导航状态的钩 | | `useResolvedDirection` | 从语言中解析文本方向( LTR/ RTL) 的钩, 或明确覆盖 | | [`periodTypes`](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/api.md#periodtypes) | 所有支持的周期类型 IDs | | `constants.calendars` | 支持的日历 ID | | `constants.numberingSystems` | 支持的+R 编号系统代码 | | `DateValidationResult` | 密码 `validateDateString` 当日期无效时返回 | | `CalendarDate`, (中文(简体) ), `CalendarDateTime` (类型) | `{ year, month, day, eraYear? }`,同样加 `hour`, (中文(简体) ), `minute` 财务报告和审定财务报表 `second`。读取年份为 `eraYear ?? year` | ### 日历 UI 的钩 图书馆提供钩子 `useDatePicker` 被阴道所消耗 日历组件。 目前使用它有两个组件: - [日历](https://ui.dhis2.nu/components/calendar): 日历组件 支持非希腊日历 - [日历输入](https://ui.dhis2.nu/components/calendar-input): 包装 环绕日历组件支持最常用的 当我们想要在一个输入旁显示时,日历. `useDatePicker` 使用一个 [日期选择选项](https://github.com/dhis2/multi-calendar-dates/blob/multi-calendar-docs/src/hooks/useDatePicker.ts#L16) 对象,并返回 [使用日期选择器返回](https://github.com/dhis2/multi-calendar-dates/blob/multi-calendar-docs/src/hooks/useDatePicker.ts#LL28C13-L28C32) 包含使UI组件,即本地化的 日期名称,以及当前视图中的周数(月份). ```ts // the options passed to useDatePicker type DatePickerOptions = { date: string options: PickerOptions onDateSelect: (payload: OnDateSelectPayload) => void minDate?: string maxDate?: string format?: 'YYYY-MM-DD' | 'DD-MM-YYYY' strictValidation?: boolean } type OnDateSelectPayload = { calendarDateString: string } | null ``` ```ts // the return type of the hook type UseDatePickerReturn = UseNavigationReturnType & { weekDayLabels: string[] calendarWeekDays: { dateValue: string label: string | number onClick: () => void isSelected: boolean | undefined isToday: boolean isInCurrentMonth: boolean }[][] } ``` # 特殊情况和有时期逻辑的考虑 在计算期间时,有一些特殊的DHIS2-特定案例: 我们处理。 测试和黄瓜特征中记录了这些特征 文档。 其中包括: - 在埃塞俄比亚历法中处理第13个月:埃塞俄比亚人 日历有13个月:12个月30天,然后第13个月有5个或 6天取决于它是否是一个跳跃年. 生成时 双周或更短的期间(双周、周、日),然后是第13个 月份显示 。 但是,当我们产生月期或 更大的,我们不显示 第13个月。 后端就变成 决定将第13个月的任何数据列入何处,因此在这样做时 每月分析,第13个月 将与下一个月 数据. - 期间的ID由后端决定,它们使用Gregorian 月份名称,例如, `QuarterlyNov` 或者说 `QuarterlyApr`在 前端,在一个非希腊日历中, `Nov` 将被翻译为 目前历法系统的第11个月(Hamle in Ethiopic). 理想的是,我们 未来会有日历不可知的时期ID, 但是这个 暂时是解决之道. - 从前端角度来说,我们总是在日历中发送日期 系统。 格式化为类似ISO的格式(`yyyy-MM-dd`) (中文(简体) ). 没错 “ISO类似”,因为日期实际上在日历系统中而不是 gregorian ISO8601 日历。 所以,当一个系统设置到Ethiopic,发送 `2015-01-01` 到后端,表示2015年的Ethiopic(即 2022 in Gregorian (英语). 这是后端所期望的 如果有的话 需要转换,然后发生在后端. - 鉴于前端有临时物体 我们有能力 发送日期转换为Gregorian, 但这就是后端 期待现在. - 尼泊尔语作为自定义日历执行:见 [内帕利卡伦达尔](https://github.com/dhis2/multi-calendar-dates/blob/multi-calendar-docs/src/custom-calendars/nepaliCalendar.ts)。 。 。 . 尼泊尔历法是单索拉历法,这意味着月长可以 年复一年,情况不一。 Temperal的算术方式是 将一天转换为格勒戈里安,进行算术,然后转换 返回日历。 这导致了奇怪的情况 你这样做 `nepaliDate.add({month: 1})` 例如,结果仍然是 (因为这个月在格雷戈里安有30天,但在尼泊尔有32天) (例如,A/CN.9/WG.III/WP.III/WP.1号文件)。 为了绕过去,我们 [将一天设定为 第十四届](https://github.com/dhis2/multi-calendar-dates/blob/73057360c4720d995370779b02fe6e3784b326ab/src/period-calculation/getYearlyPeriods.ts#L23) 在算术之前(以时期生成为背景) 导致在DHIS2背景下产生有意义的结果. - 尼泊尔语在主要浏览器中也不作为地语支持. 所以我们依靠 用硬码地图定位它,意味着我们没有同样的 显示例如短或长的日或月名称的灵活性 与 `.toLocaleString`这意味着消费者只能使用其中的一种 `ne-NP` 或者说 `en-NP` (nepali 月和日译为英文) 一个带有尼泊尔日历的地块, 他们不能使用浏览器本地化 (因此他们无法以法语为例显示尼泊尔语月名) 如果有埃蒂奥皮克或伊斯兰日历,就能够这样做. - 在Ethiopic日历中,当消耗一个日期时使用 `.eraYear` 而不是说 `.year` 以获得一年的一部分约会。 目前正在讨论 决定哪个时代应该属于 默认,但它可能是依赖浏览器 结尾,所以它更安全 用于 `eraYear` 这是埃塞俄比亚用户期望看到的。 我们 在图书馆里抽象地看待这种区别,但是没有 很简单的解决方案. - 图书馆还收集了一些DHIS2与《公约》的具体不一致之处 后端可以方便图书馆的消费者. 例如,它已经 从 DHIS2 所用的日历标识转换成预期的标识的地图 图书馆: [dhis2 加仑达斯地图](https://github.com/dhis2/multi-calendar-dates/blob/multi-calendar-docs/src/constants/dhis2CalendarsMap.ts)。 。 。 . 这些地图是“thiopian”(在DHIS2中使用)到“ethiopic”,这是标准 JavaScript (在 [Unicode-%R 密码](https://cldr.unicode.org/)) (中文(简体) ). 这个 ưμ㼯A 在 JavaScript 上下文(即来自 `ar_SD` 改为 `ar-SD`) (中文(简体) ). # 结构决定记录 - [记录架构决定](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/architecture/decisions/0001-record-architecture-decisions.md) - [使用临时API作为支柱 引擎](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/architecture/decisions/0002-use-temporal-api-as-the-backbone-for-the-engine.md) - [将临时多填充器升级为0.5.x,不用自定义 日历](https://npmcn.com/package/%40dhis2/multi-calendar-dates/doc/architecture/decisions/0003-upgrade-temporal-polyfill-to-0-5-without-custom-calendars.md) (3.0.0分解变化) ## 常见问题 ### 如何安装 @dhis2/multi-calendar-dates？ 在项目目录运行 npm install @dhis2/multi-calendar-dates，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8）、react-dom（\>=16\.8）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @dhis2/multi-calendar-dates 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @dhis2/multi-calendar-dates 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @dhis2/multi-calendar-dates 可以商用吗？ @dhis2/multi-calendar-dates 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。 ### @dhis2/multi-calendar-dates 的下载量有多少？ 根据 npm 官方下载统计，@dhis2/multi-calendar-dates 在 2026/10/12 – 2026/11/10 这 30 天内被下载 16,985 次，日均约 566 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @dhis2/multi-calendar-dates 还在维护吗？ 最新版本 3\.2\.1 发布于 2026/10/20（22 天前）；至今共发布 59 个版本，其中过去 12 个月发布了 11 个；首次发布于 2023/01/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。