企业官网建设流程全解析

• UI组件
• 前端

导读

arSA是 react-day-picker 项目中为**阿拉伯语（沙特阿拉伯）**定制的区域设置（locale）变量，它把 date-fns 的阿拉伯语环境与 DayPicker 特有的交互标签（如"上一个月""选择年份""周几"等）翻译合并为一份完整的DayPickerLocale对象。本文以 arSA 的 API 文档 为骨架，结合 ar-SA.ts 源码、DateLib 类型定义 以及 Hijri 日历文档 与 HijriEn 示例，为你讲清它的定义位置、字段结构、动态标签逻辑，以及如何在 Umm al-Qura 回历日历中实际使用它（含阿拉伯语 RTL 界面与拉丁数字两种场景）。

arSA 是什么：一份"扩展自 date-fns"的 DayPicker 区域设置

官方定义

API 文档对arSA的正式定义为：

constarSA:DayPickerLocale

并注明其定义位置为 packages/react-day-picker/src/locale/ar-SA.ts:8，说明它是一个编译期常量，类型为DayPickerLocale——即"Arabic (Saudi Arabia) locale extended with DayPicker-specific translations"（阿拉伯语（沙特阿拉伯）区域设置，扩展了 DayPicker 专属翻译）。

在 Hijri 包中的再导出

在回历专属包@daypicker/hijri中，arSA通过 packages/hijri/src/locale/ar-SA.ts 一行代码再导出：

export { arSA } from "@daypicker/react/locale";

因此无论是@daypicker/react还是@daypicker/hijri，都可以按需引入这份阿拉伯语区域设置；@daypicker/hijri的 API 索引文档 apps/website/docs/api/hijri/index.md 中与enUS一并列出的arSA变量，正是该再导出的结果。

DayPickerLocale 的类型结构

DayPickerLocale定义于 DateLib.ts，它继承自 date-fns 的DateFnsLocale，并追加了labels（可选）字段：

export type DayPickerLocaleLabels = { /* ... */ }; export interface DayPickerLocale extends DateFnsLocale { labels?: DayPickerLocaleLabels; }

这正是arSA源码中...dateFnsArSA展开操作的依据：date-fns 提供的arSA负责月份/星期名称、数字格式等基础本地化，而 DayPicker 专属的labels负责日历组件的无障碍（ARIA）标签翻译。

源码逐字段拆解：arSA 的完整结构

arSA的完整实现位于 packages/react-day-picker/src/locale/ar-SA.ts，其结构为：

import { arSA as dateFnsArSA } from "date-fns/locale"; // ... export const arSA: DayPickerLocale = { ...dateFnsArSA, // ① 继承 date-fns 阿拉伯语环境 labels: { // ② DayPicker 专属标签 labelDayButton: (...) => { ... }, labelMonthDropdown: "اختر الشهر", labelNext: "اذهب إلى الشهر التالي", labelPrevious: "اذهب إلى الشهر السابق", labelWeekNumber: (weekNumber) => `الأسبوع ${weekNumber}`, labelYearDropdown: "اختر السنة", labelGrid: (date, options, dateLib) => ..., labelGridcell: (date, modifiers, options, dateLib) => { ... }, labelNav: "شريط التنقل", labelWeekNumberHeader: "رقم الأسبوع", labelWeekday: (date, options, dateLib) => ..., }, };

逐项说明如下：

①...dateFnsArSA：复用 date-fns 的阿拉伯语环境

首行import { arSA as dateFnsArSA } from "date-fns/locale"引入 date-fns 的阿拉伯语（沙特阿拉伯）区域数据，再通过展开运算符合并进 DayPicker 的 locale 对象，使其自动获得：

• 月份、星期的本地化名称；
• 阿拉伯数字（如 ١٢٣٤٥）等 date-fns 约定；
• date-fns 各格式化函数所需的 locale 元数据。

DayPicker 内部所有日期格式化均通过 DateLib 类 完成，而DateLib的构造参数中就有locale字段（见 DateLib.ts 第 93 行附近），所以合并后的arSA会直接影响format、formatMonthYear等方法的输出。

②labels：DayPicker 专属翻译

注意：静态字符串标签（月份/年份下拉、导航按钮、导航区、周数表头）在组件渲染时原样用作aria-label；而labelDayButton、labelGridcell、labelWeekday、labelGrid等为函数标签，其行为取决于传入的参数，下面详析。

动态标签的运行时逻辑

labelDayButton与labelGridcell：按修饰器拼接语义

labelDayButton是日期按钮（day button）的无障碍标签，逻辑如下：

labelDayButton: (date, modifiers, options?, dateLib?) => { const lib = dateLib ?? new DateLib(options); // 优先复用外部注入的 DateLib let label = lib.format(date, "PPPP"); // 完整日期，如 "السبت، ١٥ ربيع الآخر ١٤٤٧" if (modifiers.today) label = `اليوم، ${label}`; // 今天 → 前缀"اليوم،"（今天，） if (modifiers.selected) label = `${label}، محدد`; // 选中 → 后缀"，محدد"（已选择） return label; };

关键点：

• dateLib ?? new DateLib(options)：允许调用方传入已配置好的DateLib实例（避免重复构造），否则基于options现场构造；options即 DateLibOptions，可携带locale、weekStartsOn、firstWeekContainsDate、useAdditionalDayOfYearTokens等配置。
• lib.format(date, "PPPP")：使用 date-fns 的PPPPtoken 输出完整长格式日期。
• modifiers.today/modifiers.selected：当该日期命中了"今天"或"选中"修饰器时，标签分别加上"اليوم，"（今天）前缀与"，محدد"（已选择）后缀——这样读屏软件用户无需进入格子即可知道今天是哪天、哪天已被选中。

labelGridcell与之类似，但只处理today前缀，不处理selected，且modifiers为可选参数。

labelGrid与labelWeekday：日期格式化复用

labelGrid: (date, options?, dateLib?) => (dateLib ?? new DateLib(options)).formatMonthYear(date),

labelGrid直接调用 DateLib.formatMonthYear 生成"年月"组合标签，作为整个月份网格的aria-label。

labelWeekday: (date, options?, dateLib?) => (dateLib ?? new DateLib(options)).format(date, "cccc"),

labelWeekday用cccctoken 输出星期全称（如 السبت/الأحد…）作为星期表头的标签。

labelWeekNumber：周数模板

labelWeekNumber: (weekNumber: number) => `الأسبوع ${weekNumber}`,

输入阿拉伯数字或拉丁数字的周数，输出"الأسبوع N"（第 N 周）。该标签在开启showWeekNumber时供周数列使用。

在 @daypicker/hijri 中实战使用 arSA

环境准备

arSA通常与回历（Hijri / Umm al-Qura）日历搭配使用。按 Hijri 日历文档 安装依赖：

npm install @daypicker/react @daypicker/hijri

从@daypicker/hijri引入DayPicker与arSA（enUS同样可用）：

import { DayPicker, arSA } from "@daypicker/hijri";

场景一：阿拉伯语标签、RTL 布局、阿拉伯-印度数字

不显式传locale时，@daypicker/hijri的DayPicker默认即使用arSA：界面呈现阿拉伯语标签、从右到左（RTL）布局与阿拉伯-印度数字（١٢٣）。参考 examples/Hijri.tsx：

import { DayPicker } from "@daypicker/hijri"; import React from "react"; export function Hijri() { return <DayPicker mode="single" />; }

场景二：英文标签、LTR 布局、拉丁数字

若想保留回历换算但改用英文标签与拉丁数字，可显式传入enUS并设置dir="ltr"与numerals="latn"。参考 examples/HijriEn.tsx：

import { DayPicker, enUS } from "@daypicker/hijri"; import React from "react"; export function HijriEn() { return ( <DayPicker showWeekNumber showOutsideDays locale={enUS} numerals="latn" /> ); }

与之等价地，@daypicker/hijri文档中的简写为：

<DayPicker locale={enUS} dir="ltr" numerals="latn" />;

参数说明：

• locale：传入arSA或enUS（二者均为DayPickerLocale），决定标签语言；
• dir="ltr"：显式覆盖默认的 RTL 方向，适合与英文标签搭配；
• numerals="latn"：将数字输出为拉丁数字（0-9），避免阿拉伯-印度数字；
• showWeekNumber：开启周数列，此时arSA中的labelWeekNumber/labelWeekNumberHeader即被使用；
• showOutsideDays：显示相邻月份的补白日期。

回历换算范围限制

需注意 Hijri 日历文档 中的说明：Hijri 构建基于 Umm al-Qura 换算表，支持的公历范围约为1924-08-01至2077-11-16，超出范围的日期属性会被钳制到该区间内。这也是使用arSA时日期格式化结果存在边界约束的原因。

相关资源索引

• API 定义文档：apps/website/docs/api/hijri/variables/arSA.md、apps/website/docs/api/hijri/variables/enUS.md
• 回历包 API 总览：apps/website/docs/api/hijri/index.md
• 区域设置类型定义：packages/react-day-picker/src/classes/DateLib.ts（含DayPickerLocale、DateLibOptions、formatMonthYear）
• 源码实现：packages/react-day-picker/src/locale/ar-SA.ts、packages/hijri/src/locale/ar-SA.ts
• 使用示例：examples/Hijri.tsx、examples/HijriEn.tsx
• 回历指南：apps/website/docs/localization/hijri.mdx

• UI组件
• 前端