本文介绍一种零成本、无需付费 api 的方案，通过静态 json 数据 + 开源脚本，精准获取波斯历（shamsi/jalali）全年节假日，支持直接在 react 项目中使用，并可按年份结构化输出带描述的节日列表。
本文介绍一种零成本、无需付费 api 的方案，通过静态 json 数据 + 开源脚本，精准获取波斯历（shamsi/jalali）全年节假日，支持直接在 react 项目中使用，并可按年份结构化输出带描述的节日列表。
在开发面向伊朗用户或需兼容波斯文化场景的应用（如日程管理、本地化通知、政府服务类 Web App）时，准确呈现波斯历（Shamsi/Jalali）节假日是关键需求。由于官方无统一开放 API，且多数商业节假日服务仅覆盖公历（Gregorian）或主流国家，开发者常面临数据缺失、更新滞后、授权费用高等问题。本文提供一套经过验证的免费、离线优先、可嵌入 React 的解决方案，不依赖网络请求，规避 API 调用限制与隐私合规风险。
✅ 核心方案：静态节日数据 + 可维护脚本
推荐采用开源社区维护的 Persian Holidays Gist —— 该脚本由伊朗开发者基于伊朗政府公告（如伊朗内政部及文化遗产组织历年发布文件）整理，已持续更新至 1405 年（对应公历 2026–2027），涵盖所有法定节日（如诺鲁孜节、伊斯兰革命纪念日）、宗教节日（如阿舒拉日）及公共假日，并严格遵循波斯历闰年规则与官方调休安排。
该方案本质为 JSON 静态数据集 + 轻量级解析逻辑，而非实时 API，优势在于：
React 与 Next.js 性能优化指南，源自 Vercel 工程团队。适用于编写、审查或重构 React/Next.js 代码时使用。
- ✅ 完全免费，无调用频次或授权限制
- ✅ 数据离线可用，保障应用稳定性与加载速度
- ✅ 支持按年份精确查询（如 1402, 1403, 1404）
- ✅ 每条节日含标准格式字段：date（YYYY/MM/DD 波斯历格式）、description（波斯语节日名称）、部分版本还包含 en_name（英文名）与 type（法定/宗教/纪念）
? 在 React 中集成示例
-
安装依赖（可选）
若需在运行时动态转换公历日期为波斯历（用于比对），推荐轻量库 jalaali-js（仅 4KB，无依赖）：npm install jalaali-js
-
引入节日数据
将 Gist 中的 holidays.json 下载并置于 src/data/persian-holidays.json，内容结构如下：{ "1402": [ { "date": "1402/01/01", "description": "عید نوروز" }, { "date": "1402/01/02", "description": "عید نوروز" }, { "date": "1402/01/13", "description": "سیزده بدر" } ], "1403": [ ... ] } -
React Hook 封装查询逻辑
// hooks/usePersianHolidays.ts import holidaysData from '../data/persian-holidays.json'; export function usePersianHolidays(year: string) { return (holidaysData as Record<string, Array<{ date: string; description: string }>>)[year] || []; } // 使用示例 function HolidayList({ year = '1404' }) { const holidays = usePersianHolidays(year); return ( <ul> {holidays.map((h, i) => ( <li key={i}>{h.date} — {h.description}</li> ))} </ul> ); }
⚠️ 注意事项与最佳实践
- 数据时效性：静态 JSON 需每年手动更新（通常每年初由社区同步伊朗官方公告）。建议将 holidays.json 纳入 CI/CD 流程，在发布前校验最新年份数据。
- 地区适配：当前数据覆盖伊朗全国性节日；若需库尔德、俾路支等地方性节日，需额外补充区域字段（如 "region": "Kurdistan"）并扩展查询逻辑。
- 国际化增强：可结合 i18n 库（如 react-i18next）为 description 提供多语言映射，例如将 "عید نوروز" 映射为 "Nowruz Holiday"（英语）或 "诺鲁孜节"（中文）。
- 避免硬编码：切勿在组件中直接写死年份字符串，应通过 useEffect 或 URL 参数动态传入，提升复用性。
? 总结
对于 React 开发者而言，免费获取波斯历节假日并非必须依赖外部 API。借助社区维护的权威静态数据集，配合轻量解析工具与模块化封装，即可构建稳定、可维护、符合本地法规要求的节日系统。该方案已在多个伊朗政务类 PWA 和教育平台中落地验证，兼顾性能、合规性与开发效率——真正的“零成本”，始于一次可靠的 JSON 引入。
