PostCSS 运行器指南(PostCSS Runner Guidelines)

¥PostCSS Runner Guidelines

PostCSS runner 是一个通过用户定义的插件列表处理 CSS 的工具；例如，postcss-cli 或 gulp‑postcss。这些规则对于任何此类运行器都是强制性的。

¥A PostCSS runner is a tool that processes CSS through a user-defined list of plugins; for example, postcss-cli or gulp‑postcss. These rules are mandatory for any such runners.

对于像 gulp-autoprefixer 这样的单插件工具，这些规则不是强制性的，但强烈推荐。

¥For single-plugin tools, like gulp-autoprefixer, these rules are not mandatory but are highly recommended.

另请参阅 ClojureWerkz 的建议 了解开源项目。

¥See also ClojureWerkz’s recommendations for open source projects.

目录

¥Table of Contents

• API

  • 1.1.接受插件参数中的函数

    ¥1.1. Accept functions in plugin parameters

• 加工

  ¥Processing

  • 2.1.设置 from 和 to 处理选项

    ¥2.1. Set from and to processing options

  • 2.2.仅使用异步 API

    ¥2.2. Use only the asynchronous API

  • 2.3.仅使用公共 PostCSS API

    ¥2.3. Use only the public PostCSS API

  • 3.1.当依赖发生变化时重建

    ¥3.1. Rebuild when dependencies change

• 输出

  ¥Output

  • 4.1.不显示 CssSyntaxError 的 JS 堆栈

    ¥4.1. Don’t show JS stack for CssSyntaxError

  • 4.2.显示 result.warnings()

    ¥4.2. Display result.warnings()

  • 4.3.允许用户将源映射写入不同的文件

    ¥4.3. Allow the user to write source maps to different files

• 文档

  ¥Documentation

  • 5.1.用英语记录你的运行器

    ¥5.1. Document your runner in English

  • 5.2.维护变更日志

    ¥5.2. Maintain a changelog

  • 5.3.package.json 中的 postcss-runner 关键字

    ¥5.3. postcss-runner keyword in package.json

  • 5.4.将 postcss 保留为对等依赖

    ¥5.4. Keep postcss to peerDependencies

1. API( API)

1.1.接受插件参数中的函数(1.1. Accept functions in plugin parameters)

¥1.1. Accept functions in plugin parameters

如果你的运行器使用配置文件，则它必须用 JavaScript 编写，以便它可以支持接受函数的插件，例如 postcss-assets：

¥If your runner uses a config file, it must be written in JavaScript, so that it can support plugins which accept a function, such as postcss-assets:

module.exports = [
  require('postcss-assets')({
    cachebuster: function (file) {
      return fs.statSync(file).mtime.getTime().toString(16)
    }
  })
]

2. 加工( Processing)

¥ Processing

2.1.设置 from 和 to 处理选项(2.1. Set from and to processing options)

¥2.1. Set from and to processing options

为了确保 PostCSS 生成源映射并显示更好的语法错误，运行器必须指定 from 和 to 选项。如果你的运行程序不处理磁盘写入（例如 gulp 转换），你应该将这两个选项设置为指向同一个文件：

¥To ensure that PostCSS generates source maps and displays better syntax errors, runners must specify the from and to options. If your runner does not handle writing to disk (for example, a gulp transform), you should set both options to point to the same file:

processor.process({ from: file.path, to: file.path })

2.2.仅使用异步 API(2.2. Use only the asynchronous API)

¥2.2. Use only the asynchronous API

PostCSS 运行程序必须仅使用异步 API。同步 API 仅用于调试，速度较慢，并且无法与异步插件一起使用。

¥PostCSS runners must use only the asynchronous API. The synchronous API is provided only for debugging, is slower, and can’t work with asynchronous plugins.

processor.process(opts).then(result => {
  // processing is finished
});

2.3.仅使用公共 PostCSS API(2.3. Use only the public PostCSS API)

¥2.3. Use only the public PostCSS API

PostCSS 运行程序不得依赖未记录的属性或方法，这些属性或方法可能会在任何次要版本中发生更改。公共 API 在 API 文档 中描述。

¥PostCSS runners must not rely on undocumented properties or methods, which may be subject to change in any minor release. The public API is described in API docs.

3. 依赖( Dependencies)

¥ Dependencies

3.1.当依赖发生变化时重建(3.1. Rebuild when dependencies change)

¥3.1. Rebuild when dependencies change

PostCSS 插件可以通过将消息附加到 result.xml 来声明文件或目录依赖。运行器应该注意这些并确保 CSS 在它们发生变化时重建。

¥PostCSS plugins may declare file or directory dependencies by attaching messages to the result. Runners should watch these and ensure that the CSS is rebuilt when they change.

for (let message of result.messages) {
  if (message.type === 'dependency') {
    watcher.addFile(message.file)
  } else if (message.type === 'dir-dependency' && message.glob) {
    watcher.addPattern(file.join(message.dir, message.glob))
  } else if (message.type === 'dir-dependency') {
    watcher.addPattern(file.join(message.dir, '**', '*'))
  }
}

默认情况下应递归监视目录，但 dir-dependency 消息可能包含可选的 glob 属性，指示依赖于目录中的哪些文件（例如 **/*.css）。如果指定了 glob，那么运行器应该只在可能的情况下监视与 glob 模式匹配的文件。

¥Directories should be watched recursively by default, but dir-dependency messages may contain an optional glob property indicating which files within the directory are depended on (e.g. **/*.css). If glob is specified then runners should only watch files matching the glob pattern, where possible.

4. 输出( Output)

¥ Output

4.1.不显示 CssSyntaxError 的 JS 堆栈(4.1. Don’t show JS stack for CssSyntaxError)

¥4.1. Don’t show JS stack for CssSyntaxError

PostCSS 运行程序不得显示 CSS 语法错误的堆栈跟踪，因为不熟悉 JavaScript 的开发者可以使用该运行程序。相反，请优雅地处理此类错误：

¥PostCSS runners must not show a stack trace for CSS syntax errors, as the runner can be used by developers who are not familiar with JavaScript. Instead, handle such errors gracefully:

processor.process(opts).catch(error => {
  if (error.name === 'CssSyntaxError') {
    process.stderr.write(error.message + error.showSourceCode())
  } else {
    throw error
  }
})

4.2.显示 result.warnings()(4.2. Display result.warnings())

¥4.2. Display result.warnings()

PostCSS 运行程序必须输出来自 result.warnings() 的警告：

¥PostCSS runners must output warnings from result.warnings():

result.warnings().forEach(warn => {
  process.stderr.write(warn.toString())
})

另请参阅 postcss-log-warnings 和 postcss-messages 插件。

¥See also postcss-log-warnings and postcss-messages plugins.

4.3.允许用户将源映射写入不同的文件(4.3. Allow the user to write source maps to different files)

¥4.3. Allow the user to write source maps to different files

PostCSS 默认情况下会在生成的文件中内联源映射；但是，PostCSS 运行程序必须提供将源映射保存在不同文件中的选项：

¥PostCSS by default will inline source maps in the generated file; however, PostCSS runners must provide an option to save the source map in a different file:

if (result.map) {
  fs.writeFile(opts.to + '.map', result.map.toString())
}

5. 文档( Documentation)

¥ Documentation

5.1.用英语记录你的运行器(5.1. Document your runner in English)

¥5.1. Document your runner in English

PostCSS 运行器的 README.md 必须用英文书写。不要害怕你的英语技能，因为开源社区会修复你的错误。

¥PostCSS runners must have their README.md written in English. Do not be afraid of your English skills, as the open source community will fix your errors.

当然，欢迎你用其他语言编写文档；只需适当地命名它们（例如 README.ja.md）。

¥Of course, you are welcome to write documentation in other languages; just name them appropriately (e.g. README.ja.md).

5.2.维护变更日志(5.2. Maintain a changelog)

¥5.2. Maintain a changelog

PostCSS 运行器必须在单独的文件中描述所有版本的更改，例如 ChangeLog.md、History.md 或 GitHub 发布。请访问 保留变更日志 以获取有关如何编写其中之一的更多信息。

¥PostCSS runners must describe changes of all releases in a separate file, such as ChangeLog.md, History.md, or with GitHub Releases. Visit Keep A Changelog for more information on how to write one of these.

当然，你应该使用 SemVer。

¥Of course, you should use SemVer.

5.3.package.json 中的 postcss-runner 关键字(5.3. postcss-runner keyword in package.json)

¥5.3. postcss-runner keyword in package.json

为 npm 编写的 PostCSS 运行程序必须在其 package.json 中包含 postcss-runner 关键字。这个特殊的关键字对于获取有关 PostCSS 生态系统的反馈非常有用。

¥PostCSS runners written for npm must have the postcss-runner keyword in their package.json. This special keyword will be useful for feedback about the PostCSS ecosystem.

对于未发布到 npm 的包，这不是强制性的，但如果包格式允许包含关键字，则建议这样做。

¥For packages not published to npm, this is not mandatory, but recommended if the package format is allowed to contain keywords.

5.4.保留 postcss 至 peerDependencies(5.4. Keep postcss to peerDependencies)

¥5.4. Keep postcss to peerDependencies

由于不同插件中的 postcss 版本不同，AST 可能会被破坏。不同的插件可以使用不同的节点创建者（例如 postcss.decl()）。

¥AST can be broken because of different postcss version in different plugins. Different plugins could use a different node creators (like postcss.decl()).

{
  "peerDependencies": {
    "postcss": "^8.0.0"
  }
}