云策 WordPress 开发者社区

块编辑器开发文档

@wordpress/date

查看官方原文 ↗
💡 云策文档标注

概述

@wordpress/date 是 WordPress 的日期处理模块，提供了一系列函数用于格式化、转换和比较日期，支持国际化、时区处理和与 PHP 日期函数的兼容性。该模块基于 ES2015+ 环境，需通过 npm 安装，并可集成 polyfill 以支持旧环境。

关键要点

  • 安装方式：通过 npm install @wordpress/date --save 安装，需 ES2015+ 环境，否则需包含 @wordpress/babel-preset-default 的 polyfill。
  • 核心函数：包括 date、dateI18n、format、getDate、getSettings、gmdate、gmdateI18n、humanTimeDiff、isInTheFuture 和 setSettings，覆盖日期格式化、时区转换、本地化、时间差计算和未来判断等功能。
  • 参数与返回值：函数通常接受 dateFormat（PHP 风格格式字符串）、dateValue（Moment、Date、字符串或数字）和 timezone（时区或 UTC 偏移）等参数，返回格式化字符串、Date 对象或布尔值。
  • 国际化支持：dateI18n 和 gmdateI18n 函数可将日期翻译为站点语言环境，类似于 PHP 的 wp_date()。
  • 时区处理：支持站点时区、UTC 时区和自定义时区，gmdate 和 gmdateI18n 专门用于 UTC 时区格式化。
  • 向后兼容性：dateI18n 的 timezone 参数支持布尔值以保持向后兼容，但已弃用。
  • 相关资源：参考维基百科的时区列表和 ISO 8601 标准，以及 PHP 的 date 函数文档。
  • 贡献方式：作为 Gutenberg 项目的一部分，遵循 monorepo 结构，可通过项目贡献指南参与开发。
📄 原文内容

Date module for WordPress.

Installation

Install the module

npm install @wordpress/date --save

This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

API

date

Formats a date (like date() in PHP).

Related

Parameters

  • dateFormat string: PHP-style formatting string. See php.net/date.
  • dateValue Moment | Date | string | number: Date object or string, parsable by moment.js.
  • timezone string: Timezone to output result in or a UTC offset. Defaults to timezone from site.

Returns

  • string: Formatted date in English.

dateI18n

Formats a date (like wp_date() in PHP), translating it into site’s locale.

Backward Compatibility Notice: if timezone is set to true, the function behaves like gmdateI18n.

Related

Parameters

  • dateFormat string: PHP-style formatting string. See php.net/date.
  • dateValue Moment | Date | string | number: Date object or string, parsable by moment.js.
  • timezone string | number | boolean: Timezone to output result in or a UTC offset. Defaults to timezone from site. Notice: boolean is effectively deprecated, but still supported for backward compatibility reasons.

Returns

  • Formatted date.

format

Formats a date. Does not alter the date’s timezone.

Parameters

  • dateFormat string: PHP-style formatting string. See php.net/date.
  • dateValue Moment | Date | string | number: Date object or string, parsable by moment.js.

Returns

  • Formatted date.

getDate

Create and return a JavaScript Date Object from a date string in the WP timezone.

Parameters

  • dateString string | null: Date formatted in the WP timezone.

Returns

  • Date

getSettings

Returns the currently defined date settings.

Returns

  • DateSettings: Settings, including locale data.

gmdate

Formats a date (like date() in PHP), in the UTC timezone.

Parameters

  • dateFormat string: PHP-style formatting string. See php.net/date.
  • dateValue Moment | Date | string | number: Date object or string, parsable by moment.js.

Returns

  • Formatted date in English.

gmdateI18n

Formats a date (like wp_date() in PHP), translating it into site’s locale and using the UTC timezone.

Parameters

  • dateFormat string: PHP-style formatting string. See php.net/date.
  • dateValue Moment | Date | string | number: Date object or string, parsable by moment.js.

Returns

  • Formatted date.

humanTimeDiff

Returns a human-readable time difference between two dates, like human_time_diff() in PHP.

Parameters

  • from Moment | Date | string | number: From date, in the WP timezone.
  • to Moment | Date | string | number: To date, formatted in the WP timezone.

Returns

  • Human-readable time difference.

isInTheFuture

Check whether a date is considered in the future according to the WordPress settings.

Parameters

  • dateValue Date | string | number: Date String or Date object in the Defined WP Timezone.

Returns

  • Is in the future.

setSettings

Adds a locale to moment, using the format supplied by wp_localize_script().

Parameters

  • dateSettings DateSettings: Settings, including locale data.

Contributing to this package

This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.