跳转到正文

registry.json

registry.json 是托管在 URL 上的 JSON 文件。它会列出注册表中所有可用区块、其元数据、依赖项和文件清单。

架构

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "ui",
  "description": "Core UI blocks for Blockstudio projects.",
  "baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
  "blocks": [
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with accessible keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": [
        "block.json",
        "index.php",
        "style.scss"
      ]
    }
  ]
}

顶层字段

name

必填。 注册表标识符。CLI 会验证该标识符,但不会显示它:命令和输出使用使用者在 blocks.json 中为注册表选择的键。

description

可选。对该注册表内容的简短说明。

baseUrl

必填。 用于下载区块文件的基础 URL。必须是有效的 URL。

文件通过组合基础 URL、区块名称和文件路径来获取:{baseUrl}/{block.name}/{file}。

例如,baseUrl 设置为 https://raw.githubusercontent.com/acme/blocks/main/blocks,区块名称为 tabs,文件为 index.php 时,CLI 会获取:

代码
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php

区块字段

name

必填。 区块的文件夹名称。这是在 CLI 命令中使用的标识符,也会成为磁盘上的文件夹名称。

title

可选。在 list 和 search 输出中显示的易读名称。

description

可选。在 search 结果中显示的单行说明。

category

可选。在 list 输出中用于分组的标签。

type

可选。可为 blockstudio、create-block 或 wordpress 之一。

此项仅供参考。CLI 不会根据区块类型改变行为。它始终会下载并复制 files 中列出的文件。

dependencies

可选。同一注册表中必须与此区块一起安装的其他区块名称数组。

用户添加带有依赖项的区块时,CLI 会解析完整的依赖树,并按正确顺序安装所有内容。检测到循环依赖时会拒绝操作。

依赖项必须存在于同一注册表中。不支持跨注册表依赖。

files

必填。 相对于区块文件夹的文件路径数组。至少需要一个文件。

这些是 CLI 下载并写入磁盘的确切文件。路径可以包含子目录:

JSON
{
  "files": [
    "block.json",
    "index.php",
    "style.scss",
    "src/components/tabs.tsx",
    "src/styles/tabs.css"
  ]
}

文件解析

对于区块清单中的每个文件,CLI 会构造下载 URL:

代码
{baseUrl}/{block.name}/{file}

并将其写入:

代码
{directory}/{block.name}/{file}

区块文件夹内的目录结构会保留。如果文件路径包含子目录,则会自动创建这些目录。

文件始终从 registry.json 内的 baseUrl 获取,而不会从 blocks.json 中注册表 URL 的相对位置获取。

验证

每次获取时,CLI 都会根据 Zod 架构验证 registry.json。注册表无效时会给出清晰的错误消息,指出验证失败的具体字段。

缺少必填字段、空的 blocks 或 files 数组、无效 URL 以及未知的 type 值,都会在下载任何文件前被检测出来。