woocommerce/packages/js/date/zh-cn/README.md

# 日期

一组用于显示和处理日期值的实用工具。

## 安装

安装模块

```bash
pnpm install @woocommerce/date --save
```

_此包假定您的代码将在 **ES2015+** 环境中运行。如果您使用的环境对 ES2015+ 支持有限或完全不支持（例如较低版本的 IE），那么使用 [core-js](https://github.com/zloirock/core-js) 或 [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) 将为这些方法添加支持。在 [Babel 文档](https://babeljs.io/docs/en/next/caveats) 中了解更多信息。_

## 用法

`date` 包使用全局的 `window.wcSettings.timeZone`。如果设置了时区，当前和最后周期将从您的浏览器时区转换为商店时区。如果未设置，这些周期将基于您的浏览器时区。

### 函数

<dl>
<dt><a href="#appendTimestamp">appendTimestamp</a> ⇒ <code>string</code></dt>
<dd><p>向字符串日期添加时间戳。</p>
</dd>
<dt><a href="#getDateValue">getDateValue</a> ⇒ <code><a href="#DateValue">DateValue</a></code></dt>
<dd><p>获取一个由周期、比较值以及自定义日期的开始/结束日期所描述的日期范围的 DateValue 对象。</p>
</dd>
<dt><a href="#getDateParamsFromQueryMemoized">getDateParamsFromQueryMemoized</a> ⇒ <code>Object</code></dt>
<dd><p>getDateParamsFromQuery() 的已记忆化内部逻辑。</p>
</dd>
<dt><a href="#getDateParamsFromQuery">getDateParamsFromQuery</a> ⇒ <code><a href="#DateParams">DateParams</a></code></dt>
<dd><p>向查询对象添加默认的日期相关参数</p>
</dd>
<dt><a href="#getCurrentDatesMemoized">getCurrentDatesMemoized</a> ⇒ <code>Object</code></dt>
<dd><p>getCurrentDates() 的已记忆化内部逻辑。</p>
</dd>
<dt><a href="#getCurrentDates">getCurrentDates</a> ⇒ <code>Object</code></dt>
<dd><p>获取主要和次要日期范围的日期值对象</p>
</dd>
<dt><a href="#getDateDifferenceInDays">getDateDifferenceInDays</a> ⇒ <code>number</code></dt>
<dd><p>计算两个日期之间的天数差。用于计算上一周期的匹配日期。</p>
</dd>
<dt><a href="#getPreviousDate">getPreviousDate</a> ⇒ <code>Object</code></dt>
<dd><p>获取上一周期或上一年的日期。</p>
</dd>
</dl>
<dl>
<dt><a href="#toMoment">toMoment(format, str)</a> ⇒ <code>Object</code> | <code>null</code></dt>
<dd><p>将字符串转换为 Moment 对象</p>
</dd>
<dt><a href="#getRangeLabel">getRangeLabel(after, before)</a> ⇒ <code>string</code></dt>
<dd><p>给定两个日期，推导出字符串表示形式</p>
</dd>
<dt><a href="#getStoreTimeZoneMoment">getStoreTimeZoneMoment()</a> ⇒ <code>string</code></dt>
<dd><p>如果已设置，获取店铺时区的当前时间。</p>
</dd>
<dt><a href="#getLastPeriod">getLastPeriod(period, compare)</a> ⇒ <code><a href="#DateValue">DateValue</a></code></dt>
<dd><p>获取当前周期之前一个周期的 DateValue 对象。</p>
</dd>
<dt><a href="#getCurrentPeriod">getCurrentPeriod(period, compare)</a> ⇒ <code><a href="#DateValue">DateValue</a></code></dt>
<dd><p>获取当前周期的 DateValue 对象。该周期从该周期的第一天开始，到当前天结束。</p>
</dd>
<dt><a href="#getAllowedIntervalsForQuery">getAllowedIntervalsForQuery(query, defaultDateRange)</a> ⇒ <code>Array</code></dt>
<dd><p>返回特定查询允许的可选择间隔。</p>
</dd>
<dt><a href="#getIntervalForQuery">getIntervalForQuery(query, defaultDateRange)</a> ⇒ <code>string</code></dt>
<dd><p>返回要使用的当前间隔。</p>
</dd>
<dt><a href="#getChartTypeForQuery">getChartTypeForQuery(query)</a> ⇒ <code>string</code></dt>
<dd><p>返回要使用的当前图表类型。</p>
</dd>
<dt><a href="#getDateFormatsForInterval">getDateFormatsForInterval(interval, [ticks], [option])</a> ⇒ <code>string</code></dt>
<dd><p>返回当前间隔的日期格式。</p>
</dd>
<dt><a href="#getDateFormatsForIntervalD3">getDateFormatsForIntervalD3(interval, [ticks])</a> ⇒ <code>string</code></dt>
<dd><p>返回当前间隔的 d3 日期格式。
图表格式请参见 <a href="https://github.com/d3/d3-time-format">https://github.com/d3/d3-time-format</a>。</p>
</dd>
<dt><a href="#getDateFormatsForIntervalPhp">getDateFormatsForIntervalPhp(interval, [ticks])</a> ⇒ <code>string</code></dt>
<dd><p>返回当前间隔的 php 日期格式。
请参见 <a href="https://www.php.net/manual/en/datetime.format.php">https://www.php.net/manual/en/datetime.format.php</a>。</p>
</dd>
<dt><a href="#loadLocaleData">loadLocaleData(config)</a></dt>
<dd><p>古腾堡的 moment 实例加载了 i18n 值，这些值是 PHP 日期格式，例如 'LLL: "F j, Y g:i a"'。用 moment 风格 js 格式的翻译覆盖它们。</p>
</dd>
<dt><a href="#validateDateInputForRange">validateDateInputForRange(type, value, [before], [after], format)</a> ⇒ <code>Object</code></dt>
<dd><p>验证为日期范围提供的文本输入。</p>
</dd>
</dl>

### 类型定义

<dl>
<dt><a href="#DateValue">DateValue</a> : <code>Object</code></dt>
<dd><p>DateValue 对象</p>
</dd>
<dt><a href="#DateParams">DateParams</a> : <code>Object</code></dt>
<dd><p>DateParams 对象</p>
</dd>
<dt><a href="#validatedDate">validatedDate</a> : <code>Object</code></dt>
<dd></dd>
</dl>

<a name="appendTimestamp"></a>

### appendTimestamp ⇒ <code>string</code>
向字符串日期添加时间戳。

**Kind**: 全局常量
**Returns**: <code>string</code> - - 附加了时间戳的字符串日期。

| Param | Type | 描述 |
| --- | --- | --- |
| date | <code>moment.Moment</code> | 作为 moment 对象的日期。 |
| timeOfDay | <code>string</code> | 一天的 `开始`、`现在` 或 `结束`。 |

<a name="getDateValue"></a>

### getDateValue ⇒ [<code>DateValue</code>](#DateValue)
获取一个 DateValue 对象，用于描述由时间段、比较值以及开始/结束日期定义的自定义日期范围。

**种类**：全局常量
**返回**：[<code>DateValue</code>](#DateValue) - - 关于所选时间段的 DateValue 数据

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| period | <code>string</code> | 所选时间段 |
| compare | <code>string</code> | `previous_period` 或 `previous_year` |
| [after] | <code>Object</code> | 自定义时间段的后日期 |
| [before] | <code>Object</code> | 自定义时间段的前日期 |

<a name="getDateParamsFromQueryMemoized"></a>

### getDateParamsFromQueryMemoized ⇒ <code>Object</code>
getDateParamsFromQuery() 的已记忆化内部逻辑。

**种类**：全局常量
**返回**：<code>Object</code> - - 从查询参数派生的日期参数，并添加了默认值

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| period | <code>string</code> | 期间值，例如 `last_week` |
| compare | <code>string</code> | 比较值，例如 `previous_year` |
| after | <code>string</code> | iso 日期格式的日期，例如 `2018-07-03` |
| before | <code>string</code> | iso 日期格式的日期，例如 `2018-07-03` |
| defaultDateRange | <code>string</code> | 商店的默认日期范围 |

<a name="getDateParamsFromQuery"></a>

### getDateParamsFromQuery ⇒ [<code>DateParams</code>](#DateParams)
向查询对象添加默认的日期相关参数

**种类**: 全局常量
**返回**: [<code>DateParams</code>](#DateParams) - - 从查询参数派生并添加了默认值的日期参数

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| query | <code>Object</code> | 查询对象 |
| query.period | <code>string</code> | 期间值，例如 `last_week` |
| query.compare | <code>string</code> | 比较值，例如 `previous_year` |
| query.after | <code>string</code> | iso 日期格式的日期，例如 `2018-07-03` |
| query.before | <code>string</code> | iso 日期格式的日期，例如 `2018-07-03` |
| defaultDateRange | <code>string</code> | 商店的默认日期范围 |

<a name="getCurrentDatesMemoized"></a>

### getCurrentDatesMemoized ⇒ <code>Object</code>
getCurrentDates() 的已记忆化内部逻辑。

**种类**：全局常量
**返回**：<code>Object</code> - - 主要和次要的 DateValue 对象

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| period | <code>string</code> | 期间值，例如 `last_week` |
| compare | <code>string</code> | 比较值，例如 `previous_year` |
| primaryStart | <code>Object</code> | 主要查询起始日期时间，为 Moment 实例。 |
| primaryEnd | <code>Object</code> | 主要查询起始日期时间，为 Moment 实例。 |
| secondaryStart | <code>Object</code> | 主要查询起始日期时间，为 Moment 实例。 |
| secondaryEnd | <code>Object</code> | 主要查询起始日期时间，为 Moment 实例。 |

<a name="getCurrentDates"></a>

### getCurrentDates ⇒ <code>Object</code>
获取主要和次要日期范围的日期价值对象

**种类**：全局常量
**返回**：<code>Object</code> - - 主要和次要的 DateValue 对象

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| query | <code>Object</code> | 查询对象 |
| query.period | <code>string</code> | 期间值，例如 `last_week` |
| query.compare | <code>string</code> | 比较值，例如 `previous_year` |
| query.after | <code>string</code> | ISO 日期格式的日期，例如 `2018-07-03` |
| query.before | <code>string</code> | ISO 日期格式的日期，例如 `2018-07-03` |
| defaultDateRange | <code>string</code> | 商店的默认日期范围 |

<a name="getDateDifferenceInDays"></a>

### getDateDifferenceInDays ⇒ <code>number</code>
计算两个日期之间的日期差。用于计算上一周期的匹配日期。

**种类**：全局常量
**返回**：<code>number</code> - 天数差。

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| date | <code>string</code> | 要比较的日期 |
| date2 | <code>string</code> | 次要的比较日期 |

<a name="getPreviousDate"></a>

### getPreviousDate ⇒ <code>Object</code>
获取上一周期或上一年的上一日期。

**种类**：全局常量
**返回**：<code>Object</code> - - 计算出的日期

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| date | <code>string</code> | 基准日期 |
| date1 | <code>string</code> | 主要开始日期 |
| date2 | <code>string</code> | 次要开始日期 |
| compare | <code>string</code> | `previous_period` 或 `previous_year` |
| interval | <code>string</code> | 间隔 |

<a name="toMoment"></a>

### toMoment(format, str) ⇒ <code>Object</code> \| <code>null</code>
将字符串转换为 Moment 对象

**种类**：全局函数
**返回**：<code>Object</code> \| <code>null</code> - 表示给定字符串的 Moment 对象

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| format | <code>string</code> | 本地化日期字符串格式 |
| str | <code>string</code> | 日期字符串 |

<a name="getRangeLabel"></a>

### getRangeLabel(after, before) ⇒ <code>string</code>
给定两个日期，推导出字符串表示形式

**种类**: 全局函数
**返回**: <code>string</code> - - 所提供日期范围的文本价值

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| after | <code>Object</code> | 起始日期 |
| before | <code>Object</code> | 中止日期 |

<a name="getStoreTimeZoneMoment"></a>

### getStoreTimeZoneMoment() ⇒ <code>string</code>
获取商店时区中的当前时间（如果已设置）。

**Kind**: 全局函数
**Returns**: <code>string</code> - - 日期时间字符串。
<a name="getLastPeriod"></a>

### getLastPeriod(period, compare) ⇒ [<code>DateValue</code>](#DateValue)
获取当前周期之前一个周期的 DateValue 对象。

**种类**：全局函数
**返回**：[<code>DateValue</code>](#DateValue) - - 关于所选周期的 DateValue 数据

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| period | <code>字符串</code> | 选择的周期 |
| compare | <code>字符串</code> | `previous_period` 或 `previous_year` |

<a name="getCurrentPeriod"></a>

### getCurrentPeriod(period, compare) ⇒ [<code>DateValue</code>](#DateValue)
获取当前周期的 DateValue 对象。该周期从周期的第一天开始，到当前天结束。

**类型**: 全局函数
**返回**: [<code>DateValue</code>](#DateValue) - - 关于所选周期的 DateValue 数据

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| period | <code>string</code> | 所选周期 |
| compare | <code>string</code> | `previous_period` 或 `previous_year` |

<a name="getAllowedIntervalsForQuery"></a>

### getAllowedIntervalsForQuery(query, defaultDateRange) ⇒ <code>Array</code>
返回特定查询允许的可选择间隔。

**种类**: 全局函数
**返回**: <code>Array</code> - 包含允许间隔的数组。

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| query | <code>Object</code> | 当前查询 |
| defaultDateRange | <code>string</code> | 商店的默认日期范围 |

<a name="getIntervalForQuery"></a>

### getIntervalForQuery(query, defaultDateRange) ⇒ <code>string</code>
返回要使用的当前间隔。

**种类**：全局函数
**返回**：<code>string</code> - 当前间隔。

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| query | <code>Object</code> | 当前查询 |
| defaultDateRange | <code>string</code> | 商店的默认日期范围 |

<a name="getChartTypeForQuery"></a>

### getChartTypeForQuery(query) ⇒ <code>string</code>
返回当前要使用的图表类型。

**Kind**: 全局函数
**Returns**: <code>string</code> - 当前图表类型。

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| query | <code>Object</code> | 当前查询 |
| query.chartType | <code>string</code> |  |

<a name="getDateFormatsForInterval"></a>

### getDateFormatsForInterval(interval, [ticks], [option]) ⇒ <code>string</code>
返回当前间隔的日期格式。

**Kind**: 全局函数
**Returns**: <code>string</code> - 当前间隔。

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| interval | <code>string</code> | 要获取日期格式的间隔。 |
| [ticks] | <code>number</code> | 坐标轴将具有的刻度数量。 |
| [option] | <code>Object</code> | 选项 |
| [option.type] | <code>string</code> | 日期格式类型，d3 或 php，默认为 d3。 |

<a name="getDateFormatsForIntervalD3"></a>

### getDateFormatsForIntervalD3(interval, [ticks]) ⇒ <code>string</code>
返回当前间隔的 d3 日期格式。
图表格式请参见 https://github.com/d3/d3-time-format。

**类型**: 全局函数
**返回**: <code>string</code> - 当前间隔。

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| interval | <code>string</code> | 要获取日期格式的间隔。 |
| [ticks] | <code>number</code> | 坐标轴将具有的刻度数量。 |

<a name="getDateFormatsForIntervalPhp"></a>

### getDateFormatsForIntervalPhp(interval, [ticks]) ⇒ <code>string</code>
返回当前间隔的 PHP 日期格式。
参见 https://www.php.net/manual/en/datetime.format.php。

**Kind**: 全局函数
**Returns**: <code>string</code> - 当前间隔。

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| interval | <code>string</code> | 要获取日期格式的间隔。 |
| [ticks] | <code>number</code> | 坐标轴将具有的刻度数。 |

<a name="loadLocaleData"></a>

### loadLocaleData(config)
古腾堡的 moment 实例加载了 i18n 值，这些值是 PHP 日期格式，例如 'LLL: "F j, Y g:i a"'。使用 moment 风格 js 格式的翻译来覆盖这些值。

**类型**：全局函数

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| config | <code>Object</code> | 区域设置配置对象，来自商店设置。 |
| config.userLocale | <code>string</code> |  |
| config.weekdaysShort | <code>Array</code> |  |

<a name="validateDateInputForRange"></a>

### validateDateInputForRange(type, value, [before], [after], format) ⇒ <code>Object</code>
验证为日期范围提供的文本输入。

**种类**：全局函数
**返回**：<code>Object</code> - validatedDate - 已验证的日期对象

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| type | <code>string</code> | 指定范围的开始或结束，例如 `before` 或 `after`。 |
| value | <code>string</code> | 用户输入值 |
| [before] | <code>Object</code> \| <code>null</code> | 如果已指定，则为 before 日期参数 |
| [after] | <code>Object</code> \| <code>null</code> | 如果已指定，则为 after 日期参数 |
| format | <code>string</code> | 用户区域设置中预期的日期格式 |

<a name="DateValue"></a>

### DateValue : <code>Object</code>
日期值对象

**类型**: 全局类型定义
**属性**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| label | <code>string</code> | 周期的翻译值。 |
| range | <code>string</code> | 日期范围的人类可读值。 |
| after | <code>moment.Moment</code> | 日期范围的开始。 |
| before | <code>moment.Moment</code> | 日期范围的结束。 |

<a name="DateParams"></a>

### DateParams : <code>Object</code>
DateParams 对象

**Kind**: 全局类型定义

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| after | <code>moment.Moment</code> \| <code>null</code> | 如果提供的周期为"custom"，则此为 after 日期 |
| before | <code>moment.Moment</code> \| <code>null</code> | 如果提供的周期为"custom"，则此为 before 日期 |

**属性**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| period | <code>string</code> | 周期值，例如 `last_week` |
| compare | <code>string</code> | 比较值，例如 previous_year |

<a name="validatedDate"></a>

### validatedDate : <code>Object</code>
**类型**：全局类型定义
**属性**

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| date | <code>Object</code> \| <code>null</code> | 一个结果 Moment 日期对象，如果无效则为 null |
| error | <code>string</code> | 如果日期无效，可选的错误消息 |