mcpField
D
date-fns

date-fns

github.com/wottpal开发0109 次安装5 周前更新
代码仓库

关于 date-fns

用于使用 date-fns 和 @date-fns/tz 编写、审查及重构日期时间代码的指导技能，强调明确时区上下文、尽早验证输入，并规避解析和夏令时问题。

主要功能

  1. 01日期解析与验证
  2. 02时区感知计算
  3. 03格式化与比较指导
  4. 04不可变工具函数模式
  5. 05夏令时与令牌防错

适用场景

  1. 01实现业务排期逻辑
  2. 02审查日期时间代码
  3. 03迁移旧版时区处理
  4. 04避免格式令牌错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wottpal/skills --skill date-fns

安装后在 Claude Code 中输入/date-fns确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

reference/
anti-patterns.md
core-functions.md
examples.md
format-parse-tokens.md
imports-and-practices.md
native-timezones.md
version-and-sources.md

详细介绍

date-fns + @date-fns/tz

用途

使用此技能，通过现代 date-fns 和原生时区包 @date-fns/tz 实现、审查和重构日期/时间代码。

版本基线（调用时重新检查）

  • 已验证的最新 date-fns 版本：4.1.0
  • 已验证的最新 @date-fns/tz 版本：1.4.1
  • 重新检查的命令：
    • npm view date-fns version
    • npm view @date-fns/tz version
    • npm view date-fns dist-tags --json
    • npm view @date-fns/tz dist-tags --json

适用场景

  • 解析、验证、格式化、比较和计算日期。
  • 构建具备时区感知能力的业务逻辑（排程、边界、报告）。
  • 将日期逻辑迁移到不可变工具模式。
  • 加强代码对夏令时（DST）和令牌格式错误的防护。

不可妥协的规则

  • 使用原生时区包：@date-fns/tz。
  • 不要推荐 date-fns-tz。
  • 如果旧代码已使用 date-fns-tz，请建议迁移到 @date-fns/tz。
  • 只解析一次，尽早验证（isValid），并在操作中传递 Date 值。
  • 正确使用 Unicode 令牌（yyyy、MM、dd），避免沿用 Moment 风格的令牌假设。
  • 对于时区敏感的计算，使用显式时区上下文（TZDate 或 { in: tz("...") }）。

标准导入

import { format, parseISO, isValid, addDays, startOfDay } from "date-fns";
import { TZDate, tz, tzOffset, tzName, tzScan } from "@date-fns/tz";

工作流

1) 规范化输入
  • 使用 parseISO/toDate 进行转换。
  • 使用 isValid 进行检查。
  • 内部值保持为 Date/TZDate，不要混用字符串运算。
2) 使用纯函数辅助工具进行计算
  • 优先使用 add/sub、differenceIn*、startOf*/endOf*、isSame*、isWithinInterval。
  • 除非有明确理由，否则避免通过 setter 修改 Date。
3) 显式应用时区上下文
  • 选项 A：使用 TZDate 值。
  • 选项 B：使用 date-fns 的 in 选项和 tz("Area/City")，以获得确定性的时区上下文。
4) 安全地格式化/输出
  • 使用 format 进行显示。
  • 使用标准格式辅助工具处理交换格式（formatISO、formatRFC3339）。
  • 将传输格式与显示格式分开。

交付内容

回答时请提供：

  • 准确的导入语句。
  • 针对使用场景所需的最精简正确函数集。
  • 时区策略（TZDate 或 { in: tz(...) }）及原因。
  • 边缘情况说明（DST 边界、令牌正确性、无效输入）。

渐进式披露

仅加载所需内容：

  • reference/core-functions.md：核心辅助工具。
  • reference/native-timezones.md：@date-fns/tz 的使用模式。
  • reference/imports-and-practices.md：导入和运行时实践。
  • reference/format-parse-tokens.md：令牌正确性。
  • reference/examples.md：可直接复制的代码片段。
  • reference/anti-patterns.md：严格禁止使用 date-fns-tz 的指导。
  • reference/version-and-sources.md：版本检查和来源链接。

评论

支持 Markdown