跳转到正文

在 GitHub 上发布区块注册表

构建了几个不错的区块后,你肯定也希望在下一个项目中使用它们。手动在主题之间复制文件夹,直到副本逐渐不一致,没人记得哪个主题包含修复后的版本。为每个区块打包并单独构建,又显得过于繁琐,因为这些文件夹里只有一个 block.json 和一个模板。

区块注册表正好介于两者之间。它由一个 registry.json 文件和一组通过普通 HTTP 提供服务的区块文件夹组成。使用者运行 CLI 命令,区块源代码会复制到其主题中,之后该副本就归他们所有。GitHub 仓库足以托管注册表,因为 GitHub 会通过原始 URL 提供公共仓库中的所有文件。

本指南将构建一个名为 acme 的注册表,其中包含四个区块;通过仓库 acme/acme-blocks 发布注册表,将区块安装到主题中,并通过 git 标签固定一个发行版本。

blockstudio 包在 npm 上的版本为 0.0.1。该版本只是一个占位版本:它唯一的命令 add 会打印 Adding block: <name>,然后退出,不会获取任何内容。本指南中的命令和输出来自 Blockstudio 仓库(packages/registry)中的注册表 CLI,这正是 CLI 所描述的 注册表文档。

各部分如何配合

需要了解的文件有两个:

  • registry.json由区块作者发布。它列出区块、每个区块包含的文件,以及用于下载这些文件的 baseUrl。
  • blocks.json位于使用者的主题或插件中。它指定要使用的注册表,以及区块的安装目录。

安装区块时,CLI 会获取 blocks.json 中的每个注册表,查找该区块并解析其依赖项,从 {baseUrl}/{block}/{file} 下载列出的每个文件,再将其写入 {directory}/{block}/{file}。它不会转换任何内容,因此磁盘上的文件与仓库中的文件完全相同。

第 1 步:整理仓库结构

创建一个仓库,在根目录放置 registry.json,并在 blocks/ 下为每个区块创建一个文件夹:

代码
acme-blocks/
  registry.json
  blocks/
    hero/
      block.json
      index.php
    card/
      block.json
      index.php
      style.scss
    tabs/
      block.json
      index.php
      style.scss
    tab-item/
      block.json
      index.php

文件夹名称是区块在注册表中的名称,也会成为区块在使用者主题中的文件夹名称。请确保它与 block.json 中区块名称的后半部分完全一致(acme/hero 位于 hero/ 中),这样安装后的文件夹就容易识别。

第 2 步:编写区块

每个文件夹都是普通的 Blockstudio 区块。主视觉区区块包含一个字段:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "category": "design",
  "blockstudio": {
    "attributes": [
      {
        "id": "heading",
        "type": "text",
        "label": "Heading",
        "default": "Build faster"
      }
    ]
  }
}
PHP
<section useBlockProps class="acme-hero">
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>

card 遵循相同模式,并添加一个 style.scss。tabs 会渲染 <InnerBlocks allowedBlocks='["acme/tab-item"]' />,而 tab-item 会声明 "parent": ["acme/tabs"],因此没有 tab-item 时,tabs 就没有用处。下一步会在注册表中声明这种关系。

这些区块没有任何注册表专属内容。CLI 会复制文件夹,因此使用 @wordpress/create-block 构建或通过普通的 PHP 注册的区块,也可以用相同方式发布。

第 3 步:编写 registry.json

registry.json 会列出 CLI 应下载的所有区块和文件:

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "acme",
  "description": "Acme block library.",
  "baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
  "blocks": [
    {
      "name": "hero",
      "title": "Hero",
      "description": "Full-width hero section with a heading.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    },
    {
      "name": "card",
      "title": "Card",
      "description": "Content card with a title.",
      "category": "components",
      "type": "blockstudio",
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tab-item",
      "title": "Tab Item",
      "description": "Single tab panel used inside Tabs.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    }
  ]
}

以下几条规则决定此文件是否有效:

  • files 是一个明确的列表。 CLI只会下载这些路径,不会下载其他内容。它不使用 glob,因此只有将新资源添加到此处后,它才会随包发布。路径可以包含子目录,安装时会创建这些目录。
  • baseUrl必须是绝对URL。 CLI会将其验证为URL,并拒绝相对值。区块文件始终从baseUrl获取,绝不会从registry.json加载位置的相对路径获取。
  • dependencies必须引用同一注册表中的区块。 添加tabs会先安装tab-item。缺失依赖和循环依赖都会导致安装停止并报错。
  • name为必填项,但不会显示。 命令和输出使用使用者在blocks.json中提供给注册表的键,两者不必一致。
  • type仅供参考。 它接受blockstudio、create-block或wordpress,不会改变CLI的行为。

CLI每次获取文件时都会验证整个文件,并报告每个校验失败的字段,因此拼写错误会在下载任何文件之前显示出来。$schema行会在编辑器中执行相同的检查。

第 4 步:通过原始 URL 发布

将仓库提交并推送到GitHub。之后,公共仓库中的每个文件都可通过以下地址访问:

代码
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref>是分支、标签或提交 SHA。对于此注册表,有两个重要的 URL:

  • 使用者配置的注册表URL: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • registry.json中的baseUrl: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

使用该baseUrl时,hero的index.php会从https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php获取。 原始主机会返回文件内容,而不是HTML的GitHub页面,这是CLI所需的内容。所有者、仓库或 ref 有误时,第一次执行命令就会出现404:

代码
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

第 5 步:在主题中安装区块

在使用方主题的根目录中创建blocks.json:

命令行
npx blockstudio init --yes
代码
Created .../acme-theme/blocks.json

init --yes会写入一个空的registries对象。在你希望用于输入命令的命名空间下添加注册表:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
  }
}

在终端中运行不带--yes的init,即可改为交互式回答相同的问题(区块目录、注册表名称和 URL)。

检查注册表是否可解析:

命令行
npx blockstudio list
代码
acme (4 blocks)

  Name      Title     Category      Type
  hero      Hero      layout        blockstudio
  card      Card      components    blockstudio
  tabs      Tabs      layout        blockstudio
  tab-item  Tab Item  layout        blockstudio

search会对名称、标题和描述进行不区分大小写的子字符串匹配:

命令行
npx blockstudio search tab
代码
Results for "tab"

  acme/tabs - Tabs
    Tabbed content with keyboard navigation.
  acme/tab-item - Tab Item
    Single tab panel used inside Tabs.

使用--dry-run预览安装。依赖项会列在前面,因为它会先安装:

命令行
npx blockstudio add acme/tabs --dry-run
代码
Would install:
  tab-item (2 files)
  tabs (3 files)

然后正式安装:

命令行
npx blockstudio add acme/tabs
代码
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

现在这两个文件夹都位于主题的blockstudio目录中,结构与仓库中的完全一致:

代码
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

如果只有一个已配置的注册表包含该区块,可以省略命名空间;也可以一次传入多个区块:

命令行
npx blockstudio add hero card
代码
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio会像发现主题中的其他区块一样,发现这些新文件夹。

更新已安装的区块

安装的文件只是副本。系统不会跟踪你安装的版本,CLI也不会自行更新区块。要获取较新版本,请再次添加该区块。如果没有终端,或在 CI 中运行,已有文件夹会导致命令停止:

命令行
npx blockstudio add tab-item
代码
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

在终端中,CLI会先询问是否覆盖。--dry-run会报告将要替换的文件夹,--yes则会执行替换:

命令行
npx blockstudio add acme/tab-item --dry-run
代码
Would overwrite tab-item
Would install:
  tab-item (2 files)

覆盖会将所列文件替换为注册表中的版本,因此请先提交本地更改,再使用git diff检查结果。

卸载时,按名称移除文件夹:

命令行
npx blockstudio remove tabs --yes
代码
Removed tabs

remove接收的是文件夹名称,而不是namespace/block。它不会移除依赖项,因此移除tabs后,tab-item仍会保留。

使用 git ref 进行版本管理

CLI没有版本字段,也没有版本标志。它获取的内容完全由 URL 决定;在GitHub上,URL中的 ref 就是版本。使用者若指向main,安装时会获取main当前包含的内容。

要发布固定不变的版本,标签中的registry.json也必须从该标签下载。打标签前,将baseUrl设置为该标签:

JSON
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"

然后提交、打标签并推送:

命令行
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

之后,将baseUrl恢复为main并提交,这样分支就会继续提供当前文件。如果跳过第一步,固定到该标签的使用者会获取标签中的区块列表,却从main下载文件。

使用者可以在注册表URL中使用标签来固定版本:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

在此示例中,v1.0.0是在tabs和tab-item创建之前打的标签,因此固定的注册表只提供最初的两个区块:

命令行
npx blockstudio list
代码
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
命令行
npx blockstudio add acme/tabs
代码
Block "tabs" not found in registry "acme".

提交 SHA 也可以用于注册表URL,但提交本身无法在baseUrl中包含自己的 SHA。因此,按 SHA 固定可以锁定区块列表,但文件仍来自该提交的baseUrl所指向的 ref,所以发布版本时建议使用标签。

注意事项

  • 会先获取每个注册表。 add 会先加载 blocks.json 中的所有注册表,再解析任何内容,因此即使是 acme/hero,只要有一个注册表无法访问,命令就会失败。请移除不再使用的注册表。
  • 名称有歧义时需要指定命名空间。 如果两个注册表都包含 hero,终端会话会询问要使用哪一个,--yes 会按 blocks.json 顺序选择第一个,而非交互式运行则会以 Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero 退出。
  • 私有仓库需要请求头。 使用注册表条目的对象形式,并设置 url 和 headers。请求头的值支持 ${VAR} 占位符,其内容会从环境中读取;CLI 会在获取注册表和下载每个文件时发送这些请求头。有关令牌设置,请参阅 GitHub 托管。

后续步骤