Chrono (v2)

Chrono是一个用JavaScript编写的自然语言日期解析器。

它设计用于处理大多数日期/时间格式，并从任何给定文本中提取信息：

• 今天、明天、昨天、_上周五_等
• 2013年8月17日 - 2013年8月19日
• 本周五13:00 - 16:00
• 5天前
• 从现在起2周
• 2013年8月17日星期六 18:40:39 GMT+0900 (JST)
• 2014-11-30T08:15:30-05:30

安装

使用npm：

$ npm install --save chrono-node

import * as chrono from 'chrono-node';

chrono.parseDate('9月12-13日的约会'); 

对于Node.js：

const chrono = require('chrono-node');

// 或者对于ECMAScript使用 `import chrono from 'chrono-node'`

v2版本的变化

对于用户

• Chrono的默认设置现在只处理国际英语。而在之前的版本中，它会尝试解析所有已知语言。
• 目前完全支持的语言有en、ja、fr、nl、ru和uk（de、pt和zh.hant部分支持）。

对于贡献者和高级用户

• 项目使用TypeScript重写
• 新的Parser和Refiner接口
• 新的源代码结构。所有解析器、精炼器和配置都应该在一个locale目录下（参见locales/en）

注意：v1.x.x版本暂时仍会继续支持。

使用方法

只需将字符串传递给chrono.parseDate或chrono.parse函数。

import * as chrono from 'chrono-node';

chrono.parseDate('9月12-13日的约会');
// 2014年9月12日星期五 12:00:00 GMT-0500 (CDT)
    
chrono.parse('9月12-13日的约会');
/* [{ 
    index: 18,
    text: '9月12-13日',
    start: ...
}] */

对于更高级的用法，这里是parse函数的TypeScript定义：

parse(text: string, ref?: ParsingReference, option?: ParsingOption): ParsedResult[] {...}

解析引用（日期/时区）

今天的"星期五"与上个月的"星期五"是不同的。 引用日期的含义取决于它们被提到的时间和地点。 Chrono允许你将引用定义为Date或ParsingReference对象：

// （注意：示例在JST时区运行）

chrono.parseDate('星期五', new Date(2012, 8 - 1, 23)); 
// 2012年8月24日星期五 12:00:00 GMT+0900 (JST)

chrono.parseDate('星期五', new Date(2012, 8 - 1, 1)); 
// 2012年8月3日星期五 12:00:00 GMT+0900 (JST)

chrono.parseDate("星期五下午4点", {
    // 2021年6月9日星期三 21:00:00 GMT+0900 (JST)
    // = 2021年6月9日星期三 07:00:00 GMT-0500 (CDT)
    instant: new Date(1623240000000), 
    timezone: "CDT",
})
// 2021年6月12日星期六 06:00:00 GMT+0900 (JST)
// = 2021年6月11日星期五 16:00:00 GMT-0500 (CDT)

ParsingReference

• instant?: Date 输入被写入或提到的时刻
• timezone?: string | number 输入被写入或提到的时区。 支持分钟偏移（数字）和时区名称（如"GMT"、"CDT"）

解析选项

forwardDate（布尔值）假设结果应该发生在参考日期之后（向未来推进）

const referenceDate = new Date(2012, 7, 25);
// 2012年8月25日星期六 00:00:00 GMT+0900 -- 参考日期是星期六

chrono.parseDate('星期五', referenceDate);
// 2012年8月24日星期五 12:00:00 GMT+0900 (JST) -- 前一天是星期五

chrono.parseDate('星期五', referenceDate, { forwardDate: true });
// 2012年8月31日星期五 12:00:00 GMT+0900 (JST) -- 下一个星期五

timezones 覆盖或添加时区缩写和偏移之间的自定义映射。当你希望Chrono将某些文本解析为给定的时区偏移时使用此选项。Chrono支持无歧义（正常）的时区映射和在夏令时期间和非夏令时期间偏移不同的模糊映射。

// Chrono不理解XYZ，所以没有解析时区
chrono.parse('10:00 XYZ', new Date(2023, 3, 20))
// "knownValues": {"hour": 10, "minute": 0}

// 让Chrono将XYZ解析为GMT-0300偏移（180分钟）
chrono.parse('10:00 XYZ', new Date(2023, 3, 20), { timezones: { XYZ: -180 } })
// "knownValues": {"hour": 10, "minute": 0, "timezoneOffset": -180}

// 让Chrono在非夏令时期间将XYZ解析为GMT-0300偏移，在夏令时期间解析为GMT-0200。假设夏令时在 
import { getLastDayOfMonthTransition } from "timezone";
import { Weekday, Month } from "parsing";

const parseXYZAsAmbiguousTz = {
  timezoneOffsetDuringDst: -120,
  timezoneOffsetNonDst: -180,
  dstStart: (year: number) => getLastWeekdayOfMonth(year, Month.FEBRUARY, Weekday.SUNDAY, 2),
  dstEnd: (year: number) => getLastWeekdayOfMonth(year, Month.SEPTEMBER, Weekday.SUNDAY, 3)
};
// 解析夏令时期间的日期
chrono.parse('2023年1月1日10:00 XYZ', new Date(2023, 3, 20), { timezones: { XYZ: parseXYZAsAmbiguousTz } })
// "knownValues": {"month": 1, ..., "timezoneOffset": -180}

// 解析非夏令时日期
chrono.parse('2023年6月1日10:00 XYZ', new Date(2023, 3, 20), { timezones: { XYZ: parseXYZAsAmbiguousTz } })
// "knownValues": {"month": 6, ..., "timezoneOffset": -120}

解析结果和组件

ParsedResult

• refDate: Date 此结果的参考日期
• index: number 此结果在输入文本中的位置
• text: string 此结果在输入中出现的文本
• start: ParsedComponents 解析的日期组件作为ParsedComponents对象
• end?: ParsedComponents 类似于start
• date: () => Date 创建JavaScript Date对象

ParsedComponents

• get: (c: Component) => number | null 获取组件的已知或推断值
• isCertain: (c: Component) => boolean 检查组件是否有已知值
• date: () => Date 创建JavaScript Date对象

例如：

const results = chrono.parse('我明天上午10点到11点有个约会');

results[0].index;     // 22
results[0].text;      // '明天上午10点到11点'
results[0].refDate;   // 2014年12月13日星期六 21:50:14 GMT-0600 (CST)

// `start`是2014年12月14日星期日 10:00:00
results[0].start.get('day');    // 14（14号，refDate的第二天）
results[0].start.get('month');  // 12（或12月）
results[0].start.get('hour');   // 10 
results[0].start.date();        // 2014年12月14日星期日 10:00:00 GMT-0600 (CST)

...
results[0].end.date();  // 2014年12月14日星期日 11:00:00 GMT-0600 (CST)

严格模式与随意模式配置

Chrono带有strict模式，只解析正式的日期模式。

// 'strict'模式
chrono.strict.parseDate('今天');       // null
chrono.strict.parseDate('星期五');      // null
chrono.strict.parseDate('2016-07-01');  // 2016年7月1日星期五 12:00:00 ...
chrono.strict.parseDate('2016年7月1日'); // 2016年7月1日星期五 12:00:00 ...

// 'casual'模式（默认）
chrono.parseDate('今天');              // 2016年6月30日星期四 12:00:00 ...
chrono.casual.parseDate('星期五');      // 2016年7月1日星期五 12:00:00 ...
chrono.casual.parseDate('2016-07-01');  // 2016年7月1日星期五 12:00:00 ...
chrono.casual.parseDate('2016年7月1日'); // 2016年7月1日星期五 12:00:00 ...

语言环境

默认情况下，Chrono配置为仅处理国际英语。 这与Chrono之前的版本不同，之前的版本会默认尝试所有语言环境。

在./locales目录下，有几个由多个开发者贡献的支持的语言环境。

// 默认英语（美国）
chrono.parseDate('6/10/2018');    

chrono.en.parseDate('6/10/2018');       // 2018年6月10日
chrono.en.GB.parseDate('6/10/2018');    // 2018年10月6日

chrono.ja.parseDate('昭和６４年１月７日'); 

当前支持的语言环境选项有：en、ja、fr、nl、ru和uk（de、pt和zh.hant部分支持）。

导入特定语言环境

Chrono 默认导出所有区域设置选项以简化使用。但是，如果您使用的是禁用 Intl 模块构建的 Node.js 运行时（使用 --without-intl 标志），在使用 Chrono 时可能会出现问题，例如：

Invalid regular expression: /* 已省略 */: Invalid property name in character class

这是因为 Intl 模块是处理特殊字符（如西里尔字母 (ru)）所必需的。

为避免这种情况，您可以仅指定要导入的区域设置：

// CommonJS (Node.js)
const chrono = require('chrono-node/en')

// ECMAScript
import chrono from 'chrono-node/en'

// TypeScript
// 警告：必须在 tsconfig.json 中将 `moduleResolution` 设置为 `node16` 或 `nodeNext`
import * as chrono from 'chrono-node/en'

自定义 Chrono

Chrono 的提取管道配置由 parsers: Parser[] 和 refiners: Refiner[] 组成。

• 首先，每个解析器独立地从输入文本中提取模式并创建解析结果（ParsingResult）。
• 然后，解析结果通过优化器进行组合、排序和优化。在优化阶段，结果可能会被过滤掉、合并或附加额外信息。

解析器

interface Parser {
    pattern: (context: ParsingContext) => RegExp,
    extract: (context: ParsingContext, match: RegExpMatchArray) =>
        (ParsingComponents | ParsingResult | {[c in Component]?: number} | null)
}

解析器是一个用于低级模式匹配解析的模块。 理想情况下，每个解析器应该设计为处理单一特定的日期格式。

用户可以通过提供正则表达式模式 pattern() 和从正则表达式匹配中提取结果或组件的 extract() 函数来创建新的解析器，以支持新的日期格式或语言。

const custom = chrono.casual.clone();
custom.parsers.push({
    pattern: () => { return /\bChristmas\b/i },
    extract: (context, match) => {
        return {
            day: 25, month: 12
        }
    }
});

custom.parseDate("I'll arrive at 2.30AM on Christmas night");
// Wed Dec 25 2013 02:30:00 GMT+0900 (JST)
// 'at 2.30AM on Christmas'

优化器

interface Refiner {
    refine: (context: ParsingContext, results: ParsingResult[]) => ParsingResult[]
}

优化器是一个用于改进或操作结果的高级模块。用户可以添加新类型的优化器来自定义 Chrono 的结果或向 Chrono 添加一些自定义逻辑。

const custom = chrono.casual.clone();
custom.refiners.push({
    refine: (context, results) => {
        // 如果没有指定上午/下午（子午线），
        // 让所有 1:00 - 4:00 之间的时间为下午（13:00 - 16:00）
        results.forEach((result) => {
            if (!result.start.isCertain('meridiem') &&
                result.start.get('hour') >= 1 && result.start.get('hour') < 4) {

                result.start.assign('meridiem', 1);
                result.start.assign('hour', result.start.get('hour') + 12);
            }
        });
        return results;
    }
});

// 这将被解析为下午。
// > Tue Dec 16 2014 14:30:00 GMT-0600 (CST) 
custom.parseDate("This is at 2.30");

// 除非指定了"AM"部分
// > Tue Dec 16 2014 02:30:00 GMT-0600 (CST)
custom.parseDate("This is at 2.30 AM");

在这个例子中，自定义优化器为具有模糊子午线的解析结果分配了下午。 优化器类的 refine 方法将被调用，传入解析结果（来自解析器或其他先前的优化器）。 该方法必须返回新结果的数组（在这种情况下，我们直接修改了这些结果）。

更多文档

查看项目 Github 页面上的 TypeScript 文档。

开发指南

本指南解释了如何为潜在贡献者设置 chrono 项目。

# 克隆并安装库
$ git clone https://github.com/wanasit/chrono.git chrono
$ cd chrono
$ npm install

从文本解析日期是复杂的。一个小的更改可能会对意想不到的地方产生影响。 因此，Chrono 是一个经过大量测试的库。 在任何情况下都不应允许破坏测试的提交。

Chrono 的单元测试基于 Jest。

# 运行测试
$ npm run test

# 以监视模式运行测试
$ npm run watch

Chrono 的源文件位于 src 目录中。 构建的包（dist/*）是通过运行 Webpack 创建的，使用以下命令：

$ npm run build