云策 WordPress 开发者社区

块编辑器开发文档

@wordpress/token-list

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

概述

@wordpress/token-list 是一个可构造的纯 JavaScript DOMTokenList 实现，支持非浏览器运行时环境。它提供了与 DOMTokenList 接口匹配的功能，适用于 ES2015+ 环境，并包含一些实现上的差异。

关键要点

  • 安装方式：通过 npm install @wordpress/token-list 安装，需确保运行环境支持 ES2015+，否则需包含 @wordpress/babel-preset-default 中的 polyfill。
  • 使用方法：导入 TokenList 类，可传入初始值构造实例，支持 add、remove、replace 等方法，所有 DOMTokenList 方法均已实现。
  • 实现差异：TokenList#supports 始终返回 true；add 和 remove 方法会忽略空字符串或空白参数而不报错；不能通过索引属性引用项，需使用 TokenList#item。
  • 浏览器支持：不旨在作为 Element#classList 的 polyfill，但在 ES5 环境（如 IE8+）中基本兼容；内部实现使用数组方法如 entries、forEach，使用时需确保这些函数被支持或 polyfilled。
  • 贡献信息：此包是 Gutenberg 项目的一部分，采用 monorepo 结构，可通过项目贡献指南参与。
📄 原文内容

Constructable, plain JavaScript DOMTokenList implementation, supporting non-browser runtimes.

Installation

Install the module

npm install @wordpress/token-list

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.

Usage

Construct a new token list, optionally with an initial value. A value with an interface matching DOMTokenList is returned.

import TokenList from '@wordpress/token-list';

const tokens = new TokenList( 'abc def' );
tokens.add( 'ghi' );
tokens.remove( 'def' );
tokens.replace( 'abc', 'xyz' );
console.log( tokens.value );
// "xyz ghi"

All methods of DOMTokenList are implemented.

Note the following implementation divergences from the specification:

  • TokenList#supports will always return true, regardless of the token passed.
  • TokenList#add and TokenList#remove will simply disregard the empty string argument or whitespace of a token argument, rather than throwing an error.
  • An item cannot be referenced by its index as a property. Use TokenList#item instead.

Browser Support

While it could be used in one’s implementation, this is not intended to serve as a polyfill for Element#classList or other instances of DOMTokenList.

The implementation of the DOMTokenList interface provided through @wordpress/token-list is broadly compatible in environments supporting ES5 (IE8 and newer). That being said, due to its internal implementation leveraging arrays for TokenList#entries, TokenList#forEach, TokenList#keys, and TokenList#values, you may need to assure that these functions are supported or polyfilled if you intend to use them.

  • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries#Browser_compatibility
  • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values#Browser_compatibility

TokenList’s own internal implementation of the DOMTokenList interface does not leverage any of these functions, so it is not necessary to polyfill them for basic usage.

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.