chinese-datetime-parser

从中文文本中提取完整的公历日期和时间，严格校验年月日、闰年和时间范围。无运行时依赖，需要 Node.js 18 或更高版本。

使用

const { parse, parseAll } = require('@crapthings/chinese-datetime-parser')

parse('会议定在二〇二六年九月十六日下午三点半')
// { value: '2026-9-16 15:30:0' }

parseAll('会议2026年9月16日，复盘2026/9/17 09:05')
// [
//   { value: '2026-9-16', text: '2026年9月16日', index: 2 },
//   { value: '2026-9-17 9:5:0', text: '2026/9/17 09:05', index: 15 }
// ]

parse('2023年2月29日') // undefined

parse(text) 返回文本中第一个有效日期，保留旧接口的 { value } 格式；无有效日期或参数不是字符串时返回 undefined。

parseAll(text) 返回所有有效日期，按文本顺序排列。text 是匹配的原文，index 是其在原文中的 JavaScript 字符串偏移（UTF-16）。没有有效日期时返回 []。无效的日期候选会被跳过。

TypeScript

包内附带类型声明，无需安装额外的 @types 包。

import { parse, parseAll } from '@crapthings/chinese-datetime-parser'
import type { ParseResult, DateMatch } from '@crapthings/chinese-datetime-parser'

const result: ParseResult | undefined = parse('2026年9月16日')
if (result) console.log(result.value)

const matches: DateMatch[] = parseAll('会议2026年9月16日')
for (const match of matches) {
  console.log(match.value, match.text, match.index)
}

两个接口的输入类型均为 unknown，与运行时对非字符串输入的处理一致。parse() 可能返回 undefined，使用前需要判空；parseAll() 始终返回数组。

支持范围

• 完整年月日：2026年9月16日、二〇二六年九月十六号。
• 数字日期：2026-9-16、2026/9/16、2026.9.16；分隔符必须一致。
• 全角数字、中文零（〇、零）和两；年份需四位，范围为 0001–9999。
• 日期后接时间：09:05、09：05：30、九点零五、十五时三十分、三点半；支持不带时区的 2026-09-16T09:05:06。
• 时间段：凌晨、早上、上午、中午、下午、晚上。带时间段时小时需为 1–12；凌晨/早上/上午十二点按 0 点解释，下午/中午十二点按 12 点解释，晚上十二点按当天 0 点解释，不自动跨日。中午十一点按 11 点解释，其余中午小时按下午解释。
• 不带时间段时使用 24 小时制，省略的分钟和秒取零。
• 时间仅附着于紧邻的日期，允许空格或制表符，不跨行附着。

返回值保持原来的不补零格式：YYYY-M-D 或 YYYY-M-D H:m:s。日期时间表示输入中的本地钟面值，不做时区转换，也不依赖系统时区或原生 Date 的字符串解析。

这是规则提取器，只支持以上形式。暂不支持相对时间（今天、明天、下周三）、缺少年份的日期、农历、时区后缀、小数秒、日期区间的语义解析或单独的时间。紧邻「农历」「阴历」及其繁体标记的日期会被跳过；没有标记时不会推断历法。

如果日期后出现明确的时间候选，格式错误或不受支持时会跳过整个候选，不退回日期。例如 parse('2026-9-16 09:xx')、parse('2026-9-16T09:05Z') 均返回 undefined；后文若有其他有效日期，仍可继续提取。普通叙述如「2026年9月16日下午开会」只提取日期。

匹配时会排除相邻数字、英文标识符和数字日期的额外分段，避免从身份证号或 v2026.9.16、2026.9.16.1 等字符串截取日期。这些边界规则不能判断所有文本语义；例如没有前缀的 2026.9.16 本身就是支持的日期格式。

与 chinese-timeword-parser 的分工

本库负责明确的公历日期和附着的钟点。chinese-timeword-parser 负责时间词、期限、方向和范围，以及日期比较，例如「十日内」「两周后」「年初年末」「2018年第二季度」。这些表达式在本库中不会产生日期结果，也不提供 isBefore、isAfter、isSame 或 compare 接口。

文本「2026年9月16日后三天」在本库中只提取 2026-9-16，不会计算三天后的日期。日期区间中两个写完整的端点可以分别提取，但不会返回区间关系或补全省略的年月日。

开发

npm test

使用 Node.js 内置测试运行器，无需安装测试依赖。旧版 Moment、AVA 和 Chai 已移除；旧日期样例保留为回归测试。扩展测试覆盖完整 400 年公历周期的月末、钟点边界、残缺时间、文本偏移、长文本和两个库的职责边界。