云策 WordPress 开发者社区

社区新闻

WordPress 中的 JSON Schema

查看官方原文 ↗ 发布于

作为一名 WordPress 开发者，你很可能在工作的各个方面都遇到过用 JavaScript 对象表示法 (JSON) 编写的文件。也许你定义过自定义块、配置过主题，或者设置过本地开发环境。你是否曾希望有一种方法能确保为这些配置文件使用正确的选项？这就是 JSON Schema 的用武之地。让我们来探索这个工具如何帮助你及早发现错误并简化开发流程。

JSON Schema 为 JSON 数据应呈现的样貌设定了规则。它允许你定义期望的值类型、哪些字段是必需的，以及对数据的任何其他约束。JSON Schema 是数据创建者和使用者之间的一份契约，它使得理解数据结构变得容易，并能自动检查 JSON 内容是否正确。

JSON Schema 有不同的模式版本，称为“元模式”，因为它们是用于编写模式的模式。大多数编辑器和集成开发环境 (IDE) 都支持 http://json-schema.org/draft-07/schema# (草案 7)，但在某些情况下，如果不支持草案 7，你可能需要使用不同的元模式。

为何使用 JSON Schema？

想象一下，你正在处理一个项目，其中有一个复杂的 JSON 格式配置文件。如果没有模式，你可能会发现自己需要不断查阅文档或之前的示例来记住哪些属性允许在何处使用。这正是 JSON Schema 大显身手的地方：

  1. 自动完成和智能感知：许多现代 IDE 和文本编辑器可以使用 JSON Schema 在你输入时提供智能的自动完成建议。
  2. 文档：模式本身作为一种文档形式，描述了 JSON 数据的结构和约束。
  3. 验证：JSON Schema 可以自动验证你的 JSON 数据，在错误导致应用程序问题之前捕获它们。
  4. 自动化测试：你可以在自动化测试中使用 JSON Schema，以确保你的 JSON 数据始终符合预期的结构。
  5. API 设计：在设计 API 时，JSON Schema 可以帮助你明确定义请求和响应正文的结构。

通过利用 JSON Schema，你可以编写更准确的代码，及早发现错误，并加速开发过程。它在大型项目或团队协作中尤其有价值，因为它能确保项目不同部分的一致性。

验证 JSON 文件

JSON 验证的最佳位置是在你的代码编辑器或 IDE 中。不仅在你编写 JSON 文件时会检查其正确性，而且许多编辑器还支持基于 JSON Schema 中属性的自动完成。让我们来看看如何设置你的编辑器以使用 JSON Schema。

带有 $schema 属性的 JSON 文件

指定 JSON Schema 版本最常见的方法是使用 $schema 属性。所有 WordPress 模式都支持 $schema 属性，用于指定要验证的特定模式版本。

许多 WordPress 模式与主要的 wp/x.y WordPress 版本一起进行版本控制。它们还有一个 trunk 版本，包含未来 WordPress 版本的所有最新开发更改。我们稍后会介绍这些模式。

通常，你会希望将模式版本与你的主题或插件支持的最低 WordPress 版本相匹配。

{
  "$schema": "https://schemas.wp.org/wp/x.y/schema.json"
}

没有 $schema 属性的 JSON 文件

有时，你正在处理的 JSON 文件可能没有 $schema 属性。那你该怎么办？

许多编辑器允许你为匹配的文件名手动设置模式。这样，你就可以将特定的模式版本与一个文件或一组文件关联起来。深入研究你的编辑器文档，了解如何配置这一点——通常只需要调整几个设置。

但是，如果你不想手动配置每一个，并且不关心使用特定的模式版本呢？这时 JSON Schema Store 目录 就来帮忙了。该目录包含许多常见的 JSON 模式，包括 WordPress 模式。一旦设置好，你的编辑器就可以自动从目录中获取并应用模式。

配置你的编辑器

大多数代码编辑器都支持某种形式的 JSON 模式。尝试使用 $schema 属性或查看你的编辑器文档。以下是一些 WordPress 开发者常用的流行编辑器的详细信息。

Visual Studio Code (VS Code)

VS Code 开箱即用地支持 $schema 属性。要使用 JSON Schema Store 目录，请安装 JSON Schema Store Catalog 扩展。

有关其他配置选项，请参阅 Visual Studio Code 文档。

PhpStorm 和 JetBrains IDE

像 PhpStorm、WebStorm 和 IntelliJ IDEA 这样的 JetBrains IDE 开箱即用地支持 $schema 属性和 JSON Schema Store 目录。

有关其他配置选项，请参阅 JetBrains 文档。

Sublime Text

Sublime Text 没有内置的 JSON Schema 支持，但你可以使用 语言服务器协议 (LSP) 和 LSP-json 包来获得 $schema 属性和 JSON Schema Store 目录支持：

  1. 如果尚未安装，请先安装 Package Control。
  2. 从 Package Control 安装 LSP 和 LSP-json 包。
  3. 重启 Sublime Text。

有关其他配置选项，请参阅 Sublime Text 文档 和 LSP-json 主页。

在项目中自动化验证

使用编辑器集成在独自工作时很有用，但如果你与多个协作者一起工作，你可能希望添加一些自动化检查，以确保每个人都遵循模式。

Ajv JSON 模式验证器 提供了用于验证模式的 Node.js 包。查看 WordPress 社区主题 以获取 如何添加自动化验证的示例。

WordPress 中的 JSON 模式

WordPress 使用多种 JSON 模式来配置主题、插件和开发的不同方面。以下是可用的关键模式：

theme.json

https://schemas.wp.org/wp/x.y/theme.json

theme.json 文件用于配置 WordPress 块主题。它允许主题开发者以结构化和一致的方式定义其主题的样式、设置、预设和变体。主要功能包括：

  • 编辑器设置：控制各种设置，例如启用或禁用自定义颜色、渐变和字体大小等功能。
  • 自定义预设：定义用于全局样式的自定义变量，例如调色板预设、渐变预设和间距预设。
  • 全局样式：定义适用于整个主题的排版、颜色、间距和其他样式。
  • 变体：位于 /styles 文件夹下的单独文件，包含对主 theme.json 的部分覆盖。

theme.json 模式包含一个 "version" 属性，该属性与模式版本不同。如果你使用的模式版本与主题支持的最低 WordPress 版本相匹配，模式会告诉你使用哪个 theme.json 版本。theme.json 版本 3 文章详细解释了其中的区别。

更多信息，请参考 全局样式 & theme.json 文档。

block.json

https://schemas.wp.org/wp/x.y/block.json

block.json 文件用于为 Gutenberg 编辑器配置自定义块。此模式允许开发者以结构化格式定义块属性和设置。主要功能包括：

  • 注册：定义基本块属性，如名称、标题、类别和图标，以便轻松注册。
  • 属性：详细说明用于管理块数据和功能的自定义属性。
  • 支持：指示要添加到块的功能支持，例如对齐方式、颜色、HTML 编辑等，而无需编写额外的代码。

block.json 模式包含一个 "apiVersion" 属性，该属性与模式版本不同。"apiVersion" 表示正在使用的块 API 版本，这会影响编辑器如何处理该块。更多信息，请参阅 API 版本文档。

更多信息，请参考 block.json 指南。

font-collection.json

https://schemas.wp.org/wp/x.y/font-collection.json

font-collection.json 模式用于在 WordPress 中注册自定义字体集合。这对于需要特定字体的主题和插件特别有用。主要功能包括：

  • 字体家族：定义字体家族的名称。
  • 字体变体：指定字体家族中可用的不同样式和字重。
  • 来源：提供字体文件的来源 URL 或路径。
  • 许可：包含字体的许可信息以确保合规性。

更多信息，请参考 font-collection.json 指南。要了解更多信息，请阅读 如何为字体库注册自定义字体集合。

wp-env.json

https://schemas.wp.org/trunk/wp-env.json

wp-env.json 文件用于配置本地 WordPress 环境，主要用于开发和测试目的。此模式有助于在不同的机器上建立一致的环境。主要功能包括：

  • WordPress 版本：指定环境中使用的 WordPress 版本。
  • 插件和主题：列出要包含在环境中的插件和主题。
  • 环境变量：定义环境特定的变量以自定义设置。
  • Docker 配置：如果使用 Docker 作为本地环境，则配置 Docker 设置。

在撰写本文时，无法从 schemas.wp.org 获取该模式的标记版本。如果你需要使用特定版本，则需要使用扩展的 GitHub URL：https://raw.githubusercontent.com/WordPress/gutenberg/@wordpress/env@x.y.z/schemas/json/wp-env.json。版本 10.1.0 使用带前导点的文件名：.wp-env.json。未来版本不使用前导点。

更多信息，请参考 wp-env.json 文档。

blueprint.json

https://playground.wordpress.net/blueprint-schema.json

blueprint.json 模式与 wp-env.json 类似，但专门用于 WordPress Playground。此模式有助于为教育和实验目的设置和配置 WordPress 实例。主要功能包括：

  • 配置：定义 Playground 环境的设置参数。
  • 资源：指定要包含的资源，例如主题和插件。
  • 环境设置：自定义 Playground 实例的环境设置。

更多信息，请参考 blueprint.json 文档。

WordPress REST API

虽然我们目前讨论的模式主要用于配置，但 JSON Schema 在 WordPress REST API 中扮演着不同的角色。

如果你正在开发 REST API 端点，你可以使用 JSON Schema 来：

  1. 验证请求数据：当数据发送到 API 端点时，会在处理之前根据模式进行验证。
  2. 提供客户端验证：该模式用于自动生成 API 的 OPTIONS 端点，可以查询这些端点以获取支持的 HTTP 方法和请求结构。

WordPress REST API 不支持草案 7 元模式。它仅支持草案 04 和草案 03 元模式的子集。详情请参阅 REST API 文档的 JSON Schema 部分。

更多信息，请参阅 扩展 REST API 的文档。

为 WordPress JSON 模式做贡献

WordPress JSON 模式开放供贡献。你可以通过向 Gutenberg 代码库提交拉取请求来做出贡献。

阅读 WordPress 模式自述文件 以了解如何贡献。