date-fns 葡萄牙语ptLocale 全解析format/parse 令牌快照与底层实现指南【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns导读本指南以 date-fns 仓库中 葡萄牙语 locale 快照文档 为骨架系统讲解ptlocale 在format、parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration六大 API 下的完整行为。你将掌握葡萄牙语序数1º、2º、月份/星期缩写、灵活时段da manhã、da madrugada等本地化令牌的输入输出规则并深入理解这些输出是如何由 localize/index.ts、match/index.ts、formatLong/index.ts 等源码实现的。一、pt Locale 的基本信息与加载方式葡萄牙语 locale 在仓库中的完整实现位于pkgs/core/src/locale/pt/通过 index.ts 导出export const pt: Locale { code: pt, formatDistance: formatDistance, formatLong: formatLong, formatRelative: formatRelative, localize: localize, match: match, options: { weekStartsOn: 0 /* Sunday */, firstWeekContainsDate: 4, }, };code: pt符合 ISO 639-1 的语言代码巴西葡萄牙语为独立的pt-BRlocale位于 pkgs/core/src/locale/pt-BR 同目录结构。options.weekStartsOn: 0一周从星期日开始这会直接影响formatRelative中 lastWeek/nextWeek 的判定边界。options.firstWeekContainsDate: 4一年中第一个包含 1 月 4 日的周为第 1 周这是葡萄牙语地区常用的周编号约定与部分国家使用的 1 月 1 日规则不同。这两项配置在 format/index.ts 中通过options?.locale?.options?.weekStartsOn等取值链路被实际消费。加载使用方式pt已被自动索引导出见 pkgs/core/src/locale/index.ts 的export * from ./pt/index.ts可直接从date-fns/locale导入import { pt } from date-fns/locale; import { format, parse, formatDistance } from date-fns; format(new Date(1987, 1, 11), PPPP, { locale: pt }); // quarta-feira, 11 de fevereiro de 1987快照表格中的时区基线所有示例日期均以T12:13:14.015Z等 UTC 时间戳给出测试在固定时区下运行format与parse结果均为确定性输出可用于回归验证。二、format 与 parse 令牌快照葡萄牙语序数与本地化文本快照文档的核心是一张覆盖全部令牌形态的对照表其输出由 localize/index.ts 定义解析侧由 match/index.ts 配合实现。以下按类别逐项解读。1. 序数令牌带o后缀葡萄牙语的序数规则非常统一任何数字后面直接追加º阳性序数符号。这一规则在源码中由ordinalNumber函数实现const ordinalNumber: LocalizeFnnumber (dirtyNumber, _options) { const number Number(dirtyNumber); return number º; };因此所有*o令牌年份、季度、月份、星期、时、分、秒、日的 format 结果都形如1º、11º、42º、365º令牌含义format 示例parse 回读yo日历年份1987º/5º1987-01-01/0005-01-01Yo本地周编号年份1987º/4º1987-01-04/0004-01-04Qo/qo季度格式化/独立1º/2º对应季度首日Mo/Lo月份格式化/独立1º~12º对应月份 1 日wo/Io本地周/ISO 周1º/49º周起始日do日1º/11º/28º对应日期Do年中的日42º/365º对应日期ho/Ho/Ko/ko小时1-12/0-23/0-11/1-2411º/23º对应时刻mo/so分 / 秒1º/55º对应时刻eo/io/co本地/ISO/独立星期几2º周一、6º周五对应日期注意Yo与yo的差异以0005-01-01为例Yo输出4º且 parse 回读为0004-01-04——这是因为本地周编号年份按firstWeekContainsDate: 4规则归入上一年度第 1 周。2. 月份三种宽度 × 两种上下文月份数据定义于 localize/index.tsconst monthValues { narrow: [j, f, m, a, m, j, j, a, s, o, n, d], abbreviated: [jan, fev, mar, abr, mai, jun, jul, ago, set, out, nov, dez], wide: [janeiro, fevereiro, março, abril, maio, junho, julho, agosto, setembro, outubro, novembro, dezembro], };令牌宽度format 示例MMMM/LLLLwidejaneiro、fevereiro、março、abril……dezembroMMM/LLLabbreviatedjan、fev、mar、abr、mai、jun、jul、ago、set、out、nov、dezMMMMM/LLLLLnarrowj、f、m、a、m、j、j、a、s、o、n、d窄宽度narrow的重要陷阱由于多个月份首字母相同MMMMM/LLLLL的 format 结果存在歧义——如2019-03-11与2019-05-11都输出m2019-06-11、2019-07-11都输出j。因此快照中这些行的parse 结果不可靠例如m被解析回2019-03-01、j被解析回2019-01-01实战中不要用窄宽度令牌做解析。对应地match/index.ts 的parseMonthPatterns中narrow与any两组正则正是这种有损匹配的来源any用^ja、^mar、^ab等更长的前缀消歧narrow只能靠首字母。3. 星期格式化与独立两种上下文localize/index.ts 定义了星期数据const dayValues { narrow: [d, s, t, q, q, s, s], short: [dom, seg, ter, qua, qui, sex, sáb], abbreviated: [dom, seg, ter, qua, qui, sex, sáb], wide: [domingo, segunda-feira, terça-feira, quarta-feira, quinta-feira, sexta-feira, sábado], };令牌宽度format 示例以周一2019-02-11为例EEEE/iiii/eeee/ccccwidesegunda-feiraE/EE/EEE/iii/eee/cccabbreviatedsegEEEEE/iiiii/eeeee/cccccnarrowsEEEEEE/iiiiii/eeeeee/ccccccshortsegio/eo/co序数ISO/本地/独立1º周一/2º本地周关键差异点E*格式化、i*ISO 星期、e*本地星期、c*独立星期四套令牌共用同一份本地化文本区别仅在编号体系与上下文。窄宽度EEEEE同样存在歧义周一与周五都输出s快照显示其 parse 回读都落在2019-02-11周一说明窄宽度星期不应作为唯一解析依据。本地星期序号eo中周一为2º因为weekStartsOn: 0星期日为 1ISO 序号io中周一为1º。4. 时段Day PeriodAM/PM、中午/午夜与灵活时段葡萄牙语对一天时段的划分是本地化最丰富的部分定义于 localize/index.tsa/b系列AM/PM、AM/PMnoon/midnightAM/PM或小写am/pmaaaaa/bbbbbnarrow只输出AM/PM且快照中对应parse 结果为Invalid Date——因为窄宽度无法被 match/index.ts 的matchDayPeriodPatterns唯一识别。B系列灵活时段这是葡萄牙语特色按一天 24 小时划分时段输入时刻format 结果parse 回读基准时刻da manhã早晨11:13da manhã04:00da tarde下午14:13da tarde12:00da noite晚上19:13da noite17:00da madrugada凌晨02:13da madrugada00:00注意B系列是格式化上下文formattingDayPeriodValues介词da与 morning/afternoon/evening/night 的阳阴性搭配由该映射表固定独立上下文standalone则使用不带介词的manhã、tarde、noite、madrugada。5. 本地化长日期/长时间令牌P、p 系列formatLong/index.ts 定义了这些组合令牌的底层格式const dateFormats { full: EEEE, d de MMMM de y, long: d de MMMM de y, medium: d de MMM de y, short: dd/MM/y, }; const timeFormats { full: HH:mm:ss zzzz, long: HH:mm:ss z, medium: HH:mm:ss, short: HH:mm, }; const dateTimeFormats { full: {{date}} às {{time}}, long: {{date}} às {{time}}, medium: {{date}}, {{time}}, short: {{date}}, {{time}}, };令牌format 示例1987-02-11说明P11/02/1987dd/MM/y日/月/年顺序PP11 de fev de 1987短月份 de连接词PPP11 de fevereiro de 1987全月名 de连接词PPPPquarta-feira, 11 de fevereiro de 1987星期 逗号 全月名p12:13HH:mmpp12:13:14HH:mm:ssppp/pppp12:13:14 GMT0/12:13:14 GMT00:00含时区名快照中parse 均为ErroredPp/PPpp/PPPppp/PPPPpppp日期 逗号/às 时间组合令牌两个实战要点de与às是字面量用单引号包裹PPPppp/PPPPpppp组合中日期与时间用às意为 at连接这是葡萄牙语自然语言的固定表达。ppp/pppp及其组合的 parse 结果在快照中全部标记为Errored——当timeFormats.full包含zzzz/z时区名时parse 无法解析GMT0这类时区表示。实战中解析长时间令牌时避免依赖时区名。三、formatDistance口语化距离表达快照## formatDistance节设定基准时刻为2000 年 1 月 1 日 00:00覆盖过去与未来两个方向。其文案与逻辑实现在 formatDistance/index.tsconst formatDistanceLocale { lessThanXSeconds: { one: menos de um segundo, other: menos de {{count}} segundos }, xSeconds: { one: 1 segundo, other: {{count}} segundos }, halfAMinute: meio minuto, lessThanXMinutes: { one: menos de um minuto, other: menos de {{count}} minutos }, xMinutes: { one: 1 minuto, other: {{count}} minutos }, aboutXHours: { one: aproximadamente 1 hora, other: aproximadamente {{count}} horas }, xHours: { one: 1 hora, other: {{count}} horas }, xDays: { one: 1 dia, other: {{count}} dias }, aboutXWeeks: { one: aproximadamente 1 semana, other: aproximadamente {{count}} semanas }, xWeeks: { one: 1 semana, other: {{count}} semanas }, aboutXMonths: { one: aproximadamente 1 mês, other: aproximadamente {{count}} meses }, xMonths: { one: 1 mês, other: {{count}} meses }, aboutXYears: { one: aproximadamente 1 ano, other: aproximadamente {{count}} anos }, xYears: { one: 1 ano, other: {{count}} anos }, overXYears: { one: mais de 1 ano, other: mais de {{count}} anos }, almostXYears: { one: quase 1 ano, other: quase {{count}} anos }, };单复数规则count 1用单数形式1 ano、1 mês、1 dia否则用复数anos、meses、dias。{{count}}由函数在运行时替换为数字export const formatDistance: FormatDistanceFn (token, count, options) { let result; const tokenValue formatDistanceLocale[token]; if (typeof tokenValue string) { result tokenValue; } else if (count 1) { result tokenValue.one; } else { result tokenValue.other.replace({{count}}, String(count)); } if (options?.addSuffix) { if (options.comparison options.comparison 0) { return daqui a result; // 未来 } else { return há result; // 过去 } } return result; };快照中的行为可归纳为未来方向addSuffix: true且comparison 0前缀daqui ain …如daqui a 6 anos、daqui a 30 minutos。过去方向前缀há… ago如há 2 dias、há aproximadamente 1 hora。includeSeconds: true当差值小于 1 分钟时细化秒级表达——menos de 5 segundos、menos de 10 segundos、menos de 20 segundos、meio minuto半分钟。约数词aproximadamente约、mais de超过、quase几乎分别对应aboutX*、overXYears、almostXYears令牌族。注意快照中2001-06-01输出mais de 1 anoover而2001-02-01输出aproximadamente 1 anoabout这是formatDistance内部按日差计算后选取不同令牌的结果。四、formatDistanceStrict精确距离与强制单位## formatDistanceStrict节输出的是不含约数的精确值并展示unit: hour强制单位的效果输入日期默认结果addSuffix: true强制hour单位2006-01-016 anosdaqui a 6 anos52608 horas2000-01-021 diadaqui a 1 dia24 horas2000-01-01T00:4545 minutosdaqui a 45 minutos1 hora2000-01-01T00:00:000 segundoshá 0 segundos0 horas1999-12-31T23:59:555 segundoshá 5 segundos0 horas与formatDistance的要点差异无约数差值 45 分钟直接输出45 minutosformatDistance会四舍五入为aproximadamente 1 hora。默认单位选择按跨度月/年/日/时/分/秒精确换算formatDistanceStrict内部实现见 pkgs/core/src/formatDistanceStrict/index.ts。强制单位时如unit: hour所有差值统一折算成小时取整6 anos ≈ 52608 horas含闰年 2004 的 366 天45 minutos折算后按取整规则输出1 hora不足 1 小时的15 minutos输出0 horas。后缀规则与 formatDistance 一致未来加daqui a过去加há如há 0 segundos。五、formatRelative相对日期表达## formatRelative节设定基准时刻为 2000-01-01 00:00输出由 formatRelative/index.ts 驱动const formatRelativeLocale { lastWeek: (date) { const weekday date.getDay(); const last weekday 0 || weekday 6 ? último : última; return last eeee às p; }, yesterday: ontem às p, today: hoje às p, tomorrow: amanhã às p, nextWeek: eeee às p, other: P, };快照对应关系输入日期相对关系结果2000-01-10超出下周10/01/2000other→P2000-01-05下周内quarta-feira às 00:002000-01-02明天amanhã às 00:002000-01-01今天hoje às 00:001999-12-31昨天ontem às 00:001999-12-27上周内última segunda-feira às 00:001999-12-21超出上周21/12/1999other→P两个语言细节值得注意lastWeek是函数而非字符串因为葡萄牙语的 上星期几 需要按名词性别变体——星期日domingo与星期六sábado是阳性名词用último其余星期几是阴性名词segunda-feira等以-feira结尾用última。这正是快照中出现última segunda-feira的原因。nextWeek不加定冠词直接输出quarta-feira às 00:00。六、formatDuration时长格式化## formatDuration节验证了Duration对象到葡萄牙语字符串的映射底层复用 formatDistance/index.ts 的xYears、xMonths、xWeeks、xDays、xHours、xMinutes、xSeconds令牌Duration结果{years: 0}/{years: 1}/{years: 2}0 anos/1 ano/2 anos{months: 0}/{months: 1}/{months: 2}0 meses/1 mês/2 meses{weeks: 0}/{weeks: 1}/{weeks: 2}0 semanas/1 semana/2 semanas{days: 0}/{days: 1}/{days: 2}0 dias/1 dia/2 dias{hours: 0}/{hours: 1}/{hours: 2}0 horas/1 hora/2 horas{minutes: 0}/{minutes: 1}/{minutes: 2}0 minutos/1 minuto/2 minutos{seconds: 0}/{seconds: 1}/{seconds: 2}0 segundos/1 segundo/2 segundos单复数规则贯穿始终数量为 1 时用单数1 mês、1 dia、1 hora其余含 0用复数meses、dias、horas。注意0与大于 1 的数字一样走复数分支。七、源码佐证pt 的数据结构、正则匹配与整体调用链1. 本地化数据的两种用途format 与 parse 各司其职ptlocale 内部以五个模块协作见 pkgs/core/src/locale/pt/index.ts 的导入localizelocalize/index.tsformat 侧负责把数值月份序号、星期序号等翻译成葡萄牙语文本所有值按narrow/abbreviated/wide三种宽度组织quarter还带有argumentCallback: (quarter) quarter - 1做数组下标偏移。matchmatch/index.tsparse 侧负责把葡萄牙语文本匹配回数值。每类单元都提供match*Patterns从文本到正则与parse*Patterns从正则到数值两组模式const matchMonthPatterns { narrow: /^[jfmasond]/i, abbreviated: /^(jan|fev|mar|abr|mai|jun|jul|ago|set|out|nov|dez)/i, wide: /^(janeiro|fevereiro|março|abril|maio|junho|julho|agosto|setembro|outubro|novembro|dezembro)/i, };formatLongformatLong/index.ts定义P/p系列组合令牌的底层格式串。formatDistance与formatRelative分别支撑口语化距离与相对时间表达。所有函数都通过通用构建器buildLocalizeFn、buildMatchFn、buildMatchPatternFn、buildFormatLongFn生成保证与 pkgs/core/src/locale/types.ts 中定义的Locale接口一致——该接口要求每个 locale 必须实现code、formatDistance、formatRelative、localize、formatLong、match六个成员。2. 配置项如何影响行为pt的optionsweekStartsOn: 0、firstWeekContainsDate: 4在核心函数中被读取。以 format/index.ts 为例options?.locale?.options?.firstWeekContainsDate ?? defaultOptions.locale?.options?.firstWeekContainsDate ?? /* 默认值 */, options?.locale?.options?.weekStartsOn ?? defaultOptions.locale?.options?.weekStartsOn ?? /* 默认值 */,这意味着weekStartsOn: 0决定了formatRelative中今天/昨天/上周/下周的边界划分firstWeekContainsDate: 4决定了Yo、wo等周编号令牌的分界如0005-01-01的Yo归入0004年第 1 周。如果显式传入的options中带weekStartsOn等覆盖值会优先于 locale 内置配置源码取值顺序为显式 options → locale options → 默认值。3. 与 pt-BR 的并列关系仓库中葡萄牙语存在两个独立 localept葡萄牙本土与pt-BR巴西二者目录并列于 pkgs/core/src/locale。快照所展示的pt使用1º序数、da manhã时段表达与PT地区周规则若目标用户为巴西应选择pt-BR两者在拼写如某些词汇差异与周起始约定上可能不同选错 locale 会直接影响format与formatDistance的输出。八、实战建议与快照使用场景做回归测试基准snapshot.md是 date-fns 为每个 locale 自动生成的确定性快照仓库中pkgs/core/src/locale/下每个语言目录均有同名文件。升级依赖或修改 locale 源码后可用快照表逐行比对 format/parse 输出是否漂移。解析输入规范化用户输入的葡萄牙语日期文本如11 de fevereiro de 1987可直接交给parse其内部会调用match模块的正则按wide宽度匹配全月名。避免窄宽度MMMMM/EEEEE的多义性多个月份/星期共享首字母会导致回读错误而aaaaa/bbbbb的 narrow AM/PM 甚至直接返回Invalid Date。时区名令牌慎用于 parseppp/pppp含GMT0在快照中 parse 均为Errored如需可解析的完整时间使用ppHH:mm:ss或自行附加时区处理。序数风格统一葡萄牙语所有序数统一追加º阳性质ordinalNumber实现简单直接不存在英语st/nd/rd/th那种按数字结尾变化的复杂性。距离表达的语义选择需要口语化约数用formatDistance会产出aproximadamente/mais de/quase需要精确数值用formatDistanceStrict可按unit强制折算为单一单位。总结ptlocale 快照文档pkgs/core/src/locale/pt/snapshot.md完整覆盖了 date-fns 六大格式化 API 在葡萄牙语下的行为*o序数统一追加º、月份/星期三档宽度、da manhã/da madrugada等灵活时段、de/às连接词的长日期表达、daqui a/há后缀的距离句式以及último/última按星期名词性别变化的相对时间。这些输出与 localize、match、formatLong、formatDistance、formatRelative 五个实现模块一一对应并受weekStartsOn: 0、firstWeekContainsDate: 4两个选项约束。理解快照与源码的映射关系既能让你准确预测任何日期在ptlocale 下的格式化结果也能在遇到 parse 回读异常窄宽度歧义、时区名无法解析时快速定位根因。【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
date-fns 葡萄牙语ptLocale 全解析format/parse 令牌快照与底层实现指南【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns导读本指南以 date-fns 仓库中 葡萄牙语 locale 快照文档 为骨架系统讲解ptlocale 在format、parse、formatDistance、formatDistanceStrict、formatRelative、formatDuration六大 API 下的完整行为。你将掌握葡萄牙语序数1º、2º、月份/星期缩写、灵活时段da manhã、da madrugada等本地化令牌的输入输出规则并深入理解这些输出是如何由 localize/index.ts、match/index.ts、formatLong/index.ts 等源码实现的。一、pt Locale 的基本信息与加载方式葡萄牙语 locale 在仓库中的完整实现位于pkgs/core/src/locale/pt/通过 index.ts 导出export const pt: Locale { code: pt, formatDistance: formatDistance, formatLong: formatLong, formatRelative: formatRelative, localize: localize, match: match, options: { weekStartsOn: 0 /* Sunday */, firstWeekContainsDate: 4, }, };code: pt符合 ISO 639-1 的语言代码巴西葡萄牙语为独立的pt-BRlocale位于 pkgs/core/src/locale/pt-BR 同目录结构。options.weekStartsOn: 0一周从星期日开始这会直接影响formatRelative中 lastWeek/nextWeek 的判定边界。options.firstWeekContainsDate: 4一年中第一个包含 1 月 4 日的周为第 1 周这是葡萄牙语地区常用的周编号约定与部分国家使用的 1 月 1 日规则不同。这两项配置在 format/index.ts 中通过options?.locale?.options?.weekStartsOn等取值链路被实际消费。加载使用方式pt已被自动索引导出见 pkgs/core/src/locale/index.ts 的export * from ./pt/index.ts可直接从date-fns/locale导入import { pt } from date-fns/locale; import { format, parse, formatDistance } from date-fns; format(new Date(1987, 1, 11), PPPP, { locale: pt }); // quarta-feira, 11 de fevereiro de 1987快照表格中的时区基线所有示例日期均以T12:13:14.015Z等 UTC 时间戳给出测试在固定时区下运行format与parse结果均为确定性输出可用于回归验证。二、format 与 parse 令牌快照葡萄牙语序数与本地化文本快照文档的核心是一张覆盖全部令牌形态的对照表其输出由 localize/index.ts 定义解析侧由 match/index.ts 配合实现。以下按类别逐项解读。1. 序数令牌带o后缀葡萄牙语的序数规则非常统一任何数字后面直接追加º阳性序数符号。这一规则在源码中由ordinalNumber函数实现const ordinalNumber: LocalizeFnnumber (dirtyNumber, _options) { const number Number(dirtyNumber); return number º; };因此所有*o令牌年份、季度、月份、星期、时、分、秒、日的 format 结果都形如1º、11º、42º、365º令牌含义format 示例parse 回读yo日历年份1987º/5º1987-01-01/0005-01-01Yo本地周编号年份1987º/4º1987-01-04/0004-01-04Qo/qo季度格式化/独立1º/2º对应季度首日Mo/Lo月份格式化/独立1º~12º对应月份 1 日wo/Io本地周/ISO 周1º/49º周起始日do日1º/11º/28º对应日期Do年中的日42º/365º对应日期ho/Ho/Ko/ko小时1-12/0-23/0-11/1-2411º/23º对应时刻mo/so分 / 秒1º/55º对应时刻eo/io/co本地/ISO/独立星期几2º周一、6º周五对应日期注意Yo与yo的差异以0005-01-01为例Yo输出4º且 parse 回读为0004-01-04——这是因为本地周编号年份按firstWeekContainsDate: 4规则归入上一年度第 1 周。2. 月份三种宽度 × 两种上下文月份数据定义于 localize/index.tsconst monthValues { narrow: [j, f, m, a, m, j, j, a, s, o, n, d], abbreviated: [jan, fev, mar, abr, mai, jun, jul, ago, set, out, nov, dez], wide: [janeiro, fevereiro, março, abril, maio, junho, julho, agosto, setembro, outubro, novembro, dezembro], };令牌宽度format 示例MMMM/LLLLwidejaneiro、fevereiro、março、abril……dezembroMMM/LLLabbreviatedjan、fev、mar、abr、mai、jun、jul、ago、set、out、nov、dezMMMMM/LLLLLnarrowj、f、m、a、m、j、j、a、s、o、n、d窄宽度narrow的重要陷阱由于多个月份首字母相同MMMMM/LLLLL的 format 结果存在歧义——如2019-03-11与2019-05-11都输出m2019-06-11、2019-07-11都输出j。因此快照中这些行的parse 结果不可靠例如m被解析回2019-03-01、j被解析回2019-01-01实战中不要用窄宽度令牌做解析。对应地match/index.ts 的parseMonthPatterns中narrow与any两组正则正是这种有损匹配的来源any用^ja、^mar、^ab等更长的前缀消歧narrow只能靠首字母。3. 星期格式化与独立两种上下文localize/index.ts 定义了星期数据const dayValues { narrow: [d, s, t, q, q, s, s], short: [dom, seg, ter, qua, qui, sex, sáb], abbreviated: [dom, seg, ter, qua, qui, sex, sáb], wide: [domingo, segunda-feira, terça-feira, quarta-feira, quinta-feira, sexta-feira, sábado], };令牌宽度format 示例以周一2019-02-11为例EEEE/iiii/eeee/ccccwidesegunda-feiraE/EE/EEE/iii/eee/cccabbreviatedsegEEEEE/iiiii/eeeee/cccccnarrowsEEEEEE/iiiiii/eeeeee/ccccccshortsegio/eo/co序数ISO/本地/独立1º周一/2º本地周关键差异点E*格式化、i*ISO 星期、e*本地星期、c*独立星期四套令牌共用同一份本地化文本区别仅在编号体系与上下文。窄宽度EEEEE同样存在歧义周一与周五都输出s快照显示其 parse 回读都落在2019-02-11周一说明窄宽度星期不应作为唯一解析依据。本地星期序号eo中周一为2º因为weekStartsOn: 0星期日为 1ISO 序号io中周一为1º。4. 时段Day PeriodAM/PM、中午/午夜与灵活时段葡萄牙语对一天时段的划分是本地化最丰富的部分定义于 localize/index.tsa/b系列AM/PM、AM/PMnoon/midnightAM/PM或小写am/pmaaaaa/bbbbbnarrow只输出AM/PM且快照中对应parse 结果为Invalid Date——因为窄宽度无法被 match/index.ts 的matchDayPeriodPatterns唯一识别。B系列灵活时段这是葡萄牙语特色按一天 24 小时划分时段输入时刻format 结果parse 回读基准时刻da manhã早晨11:13da manhã04:00da tarde下午14:13da tarde12:00da noite晚上19:13da noite17:00da madrugada凌晨02:13da madrugada00:00注意B系列是格式化上下文formattingDayPeriodValues介词da与 morning/afternoon/evening/night 的阳阴性搭配由该映射表固定独立上下文standalone则使用不带介词的manhã、tarde、noite、madrugada。5. 本地化长日期/长时间令牌P、p 系列formatLong/index.ts 定义了这些组合令牌的底层格式const dateFormats { full: EEEE, d de MMMM de y, long: d de MMMM de y, medium: d de MMM de y, short: dd/MM/y, }; const timeFormats { full: HH:mm:ss zzzz, long: HH:mm:ss z, medium: HH:mm:ss, short: HH:mm, }; const dateTimeFormats { full: {{date}} às {{time}}, long: {{date}} às {{time}}, medium: {{date}}, {{time}}, short: {{date}}, {{time}}, };令牌format 示例1987-02-11说明P11/02/1987dd/MM/y日/月/年顺序PP11 de fev de 1987短月份 de连接词PPP11 de fevereiro de 1987全月名 de连接词PPPPquarta-feira, 11 de fevereiro de 1987星期 逗号 全月名p12:13HH:mmpp12:13:14HH:mm:ssppp/pppp12:13:14 GMT0/12:13:14 GMT00:00含时区名快照中parse 均为ErroredPp/PPpp/PPPppp/PPPPpppp日期 逗号/às 时间组合令牌两个实战要点de与às是字面量用单引号包裹PPPppp/PPPPpppp组合中日期与时间用às意为 at连接这是葡萄牙语自然语言的固定表达。ppp/pppp及其组合的 parse 结果在快照中全部标记为Errored——当timeFormats.full包含zzzz/z时区名时parse 无法解析GMT0这类时区表示。实战中解析长时间令牌时避免依赖时区名。三、formatDistance口语化距离表达快照## formatDistance节设定基准时刻为2000 年 1 月 1 日 00:00覆盖过去与未来两个方向。其文案与逻辑实现在 formatDistance/index.tsconst formatDistanceLocale { lessThanXSeconds: { one: menos de um segundo, other: menos de {{count}} segundos }, xSeconds: { one: 1 segundo, other: {{count}} segundos }, halfAMinute: meio minuto, lessThanXMinutes: { one: menos de um minuto, other: menos de {{count}} minutos }, xMinutes: { one: 1 minuto, other: {{count}} minutos }, aboutXHours: { one: aproximadamente 1 hora, other: aproximadamente {{count}} horas }, xHours: { one: 1 hora, other: {{count}} horas }, xDays: { one: 1 dia, other: {{count}} dias }, aboutXWeeks: { one: aproximadamente 1 semana, other: aproximadamente {{count}} semanas }, xWeeks: { one: 1 semana, other: {{count}} semanas }, aboutXMonths: { one: aproximadamente 1 mês, other: aproximadamente {{count}} meses }, xMonths: { one: 1 mês, other: {{count}} meses }, aboutXYears: { one: aproximadamente 1 ano, other: aproximadamente {{count}} anos }, xYears: { one: 1 ano, other: {{count}} anos }, overXYears: { one: mais de 1 ano, other: mais de {{count}} anos }, almostXYears: { one: quase 1 ano, other: quase {{count}} anos }, };单复数规则count 1用单数形式1 ano、1 mês、1 dia否则用复数anos、meses、dias。{{count}}由函数在运行时替换为数字export const formatDistance: FormatDistanceFn (token, count, options) { let result; const tokenValue formatDistanceLocale[token]; if (typeof tokenValue string) { result tokenValue; } else if (count 1) { result tokenValue.one; } else { result tokenValue.other.replace({{count}}, String(count)); } if (options?.addSuffix) { if (options.comparison options.comparison 0) { return daqui a result; // 未来 } else { return há result; // 过去 } } return result; };快照中的行为可归纳为未来方向addSuffix: true且comparison 0前缀daqui ain …如daqui a 6 anos、daqui a 30 minutos。过去方向前缀há… ago如há 2 dias、há aproximadamente 1 hora。includeSeconds: true当差值小于 1 分钟时细化秒级表达——menos de 5 segundos、menos de 10 segundos、menos de 20 segundos、meio minuto半分钟。约数词aproximadamente约、mais de超过、quase几乎分别对应aboutX*、overXYears、almostXYears令牌族。注意快照中2001-06-01输出mais de 1 anoover而2001-02-01输出aproximadamente 1 anoabout这是formatDistance内部按日差计算后选取不同令牌的结果。四、formatDistanceStrict精确距离与强制单位## formatDistanceStrict节输出的是不含约数的精确值并展示unit: hour强制单位的效果输入日期默认结果addSuffix: true强制hour单位2006-01-016 anosdaqui a 6 anos52608 horas2000-01-021 diadaqui a 1 dia24 horas2000-01-01T00:4545 minutosdaqui a 45 minutos1 hora2000-01-01T00:00:000 segundoshá 0 segundos0 horas1999-12-31T23:59:555 segundoshá 5 segundos0 horas与formatDistance的要点差异无约数差值 45 分钟直接输出45 minutosformatDistance会四舍五入为aproximadamente 1 hora。默认单位选择按跨度月/年/日/时/分/秒精确换算formatDistanceStrict内部实现见 pkgs/core/src/formatDistanceStrict/index.ts。强制单位时如unit: hour所有差值统一折算成小时取整6 anos ≈ 52608 horas含闰年 2004 的 366 天45 minutos折算后按取整规则输出1 hora不足 1 小时的15 minutos输出0 horas。后缀规则与 formatDistance 一致未来加daqui a过去加há如há 0 segundos。五、formatRelative相对日期表达## formatRelative节设定基准时刻为 2000-01-01 00:00输出由 formatRelative/index.ts 驱动const formatRelativeLocale { lastWeek: (date) { const weekday date.getDay(); const last weekday 0 || weekday 6 ? último : última; return last eeee às p; }, yesterday: ontem às p, today: hoje às p, tomorrow: amanhã às p, nextWeek: eeee às p, other: P, };快照对应关系输入日期相对关系结果2000-01-10超出下周10/01/2000other→P2000-01-05下周内quarta-feira às 00:002000-01-02明天amanhã às 00:002000-01-01今天hoje às 00:001999-12-31昨天ontem às 00:001999-12-27上周内última segunda-feira às 00:001999-12-21超出上周21/12/1999other→P两个语言细节值得注意lastWeek是函数而非字符串因为葡萄牙语的 上星期几 需要按名词性别变体——星期日domingo与星期六sábado是阳性名词用último其余星期几是阴性名词segunda-feira等以-feira结尾用última。这正是快照中出现última segunda-feira的原因。nextWeek不加定冠词直接输出quarta-feira às 00:00。六、formatDuration时长格式化## formatDuration节验证了Duration对象到葡萄牙语字符串的映射底层复用 formatDistance/index.ts 的xYears、xMonths、xWeeks、xDays、xHours、xMinutes、xSeconds令牌Duration结果{years: 0}/{years: 1}/{years: 2}0 anos/1 ano/2 anos{months: 0}/{months: 1}/{months: 2}0 meses/1 mês/2 meses{weeks: 0}/{weeks: 1}/{weeks: 2}0 semanas/1 semana/2 semanas{days: 0}/{days: 1}/{days: 2}0 dias/1 dia/2 dias{hours: 0}/{hours: 1}/{hours: 2}0 horas/1 hora/2 horas{minutes: 0}/{minutes: 1}/{minutes: 2}0 minutos/1 minuto/2 minutos{seconds: 0}/{seconds: 1}/{seconds: 2}0 segundos/1 segundo/2 segundos单复数规则贯穿始终数量为 1 时用单数1 mês、1 dia、1 hora其余含 0用复数meses、dias、horas。注意0与大于 1 的数字一样走复数分支。七、源码佐证pt 的数据结构、正则匹配与整体调用链1. 本地化数据的两种用途format 与 parse 各司其职ptlocale 内部以五个模块协作见 pkgs/core/src/locale/pt/index.ts 的导入localizelocalize/index.tsformat 侧负责把数值月份序号、星期序号等翻译成葡萄牙语文本所有值按narrow/abbreviated/wide三种宽度组织quarter还带有argumentCallback: (quarter) quarter - 1做数组下标偏移。matchmatch/index.tsparse 侧负责把葡萄牙语文本匹配回数值。每类单元都提供match*Patterns从文本到正则与parse*Patterns从正则到数值两组模式const matchMonthPatterns { narrow: /^[jfmasond]/i, abbreviated: /^(jan|fev|mar|abr|mai|jun|jul|ago|set|out|nov|dez)/i, wide: /^(janeiro|fevereiro|março|abril|maio|junho|julho|agosto|setembro|outubro|novembro|dezembro)/i, };formatLongformatLong/index.ts定义P/p系列组合令牌的底层格式串。formatDistance与formatRelative分别支撑口语化距离与相对时间表达。所有函数都通过通用构建器buildLocalizeFn、buildMatchFn、buildMatchPatternFn、buildFormatLongFn生成保证与 pkgs/core/src/locale/types.ts 中定义的Locale接口一致——该接口要求每个 locale 必须实现code、formatDistance、formatRelative、localize、formatLong、match六个成员。2. 配置项如何影响行为pt的optionsweekStartsOn: 0、firstWeekContainsDate: 4在核心函数中被读取。以 format/index.ts 为例options?.locale?.options?.firstWeekContainsDate ?? defaultOptions.locale?.options?.firstWeekContainsDate ?? /* 默认值 */, options?.locale?.options?.weekStartsOn ?? defaultOptions.locale?.options?.weekStartsOn ?? /* 默认值 */,这意味着weekStartsOn: 0决定了formatRelative中今天/昨天/上周/下周的边界划分firstWeekContainsDate: 4决定了Yo、wo等周编号令牌的分界如0005-01-01的Yo归入0004年第 1 周。如果显式传入的options中带weekStartsOn等覆盖值会优先于 locale 内置配置源码取值顺序为显式 options → locale options → 默认值。3. 与 pt-BR 的并列关系仓库中葡萄牙语存在两个独立 localept葡萄牙本土与pt-BR巴西二者目录并列于 pkgs/core/src/locale。快照所展示的pt使用1º序数、da manhã时段表达与PT地区周规则若目标用户为巴西应选择pt-BR两者在拼写如某些词汇差异与周起始约定上可能不同选错 locale 会直接影响format与formatDistance的输出。八、实战建议与快照使用场景做回归测试基准snapshot.md是 date-fns 为每个 locale 自动生成的确定性快照仓库中pkgs/core/src/locale/下每个语言目录均有同名文件。升级依赖或修改 locale 源码后可用快照表逐行比对 format/parse 输出是否漂移。解析输入规范化用户输入的葡萄牙语日期文本如11 de fevereiro de 1987可直接交给parse其内部会调用match模块的正则按wide宽度匹配全月名。避免窄宽度MMMMM/EEEEE的多义性多个月份/星期共享首字母会导致回读错误而aaaaa/bbbbb的 narrow AM/PM 甚至直接返回Invalid Date。时区名令牌慎用于 parseppp/pppp含GMT0在快照中 parse 均为Errored如需可解析的完整时间使用ppHH:mm:ss或自行附加时区处理。序数风格统一葡萄牙语所有序数统一追加º阳性质ordinalNumber实现简单直接不存在英语st/nd/rd/th那种按数字结尾变化的复杂性。距离表达的语义选择需要口语化约数用formatDistance会产出aproximadamente/mais de/quase需要精确数值用formatDistanceStrict可按unit强制折算为单一单位。总结ptlocale 快照文档pkgs/core/src/locale/pt/snapshot.md完整覆盖了 date-fns 六大格式化 API 在葡萄牙语下的行为*o序数统一追加º、月份/星期三档宽度、da manhã/da madrugada等灵活时段、de/às连接词的长日期表达、daqui a/há后缀的距离句式以及último/última按星期名词性别变化的相对时间。这些输出与 localize、match、formatLong、formatDistance、formatRelative 五个实现模块一一对应并受weekStartsOn: 0、firstWeekContainsDate: 4两个选项约束。理解快照与源码的映射关系既能让你准确预测任何日期在ptlocale 下的格式化结果也能在遇到 parse 回读异常窄宽度歧义、时区名无法解析时快速定位根因。【免费下载链接】date-fns⏳ Modern JavaScript date utility library ⌛️项目地址: https://gitcode.com/gh_mirrors/da/date-fns创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
