快速入门
先决条件
- Node.js 18+
- 一个 WordPress 主题或插件,用于安装区块
npm 上的 blockstudio 软件包版本为 0.0.1。该版本只是占位版本:它仅包含 add 命令,该命令会打印 Adding block: <name> 并退出,不会获取任何内容;同时会将 init、list、search、remove、--yes 和 --dry-run 视为未知项并拒绝。这些页面中的命令介绍的是 Blockstudio 仓库(packages/registry)中的注册表 CLI。
初始化项目
在主题或插件的根目录中运行 init:
npx blockstudio init
CLI 会引导你完成交互式设置:
- 区块目录:区块的安装位置(默认:
blockstudio) - 注册表:按名称添加一个或多个注册表 URL
这会创建一个 blocks.json 文件:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"ui": "https://blocks.example.com/registry.json"
}
}
你也可以跳过交互式提示:
npx blockstudio init --yes
这会使用默认值创建 blocks.json。之后你可以手动编辑。
添加区块
npx blockstudio add ui/tabs
格式为 namespace/block,其中 namespace 与 registries 配置中的某个键相匹配。
CLI 会:
- 获取注册表
- 查找区块
- 解析任何依赖项(例如,e.g 依赖于
tabs。tab-item) - 下载所有文件
- 将它们写入区块目录
如果区块只存在于一个注册表中,可以省略命名空间:
npx blockstudio add tabs
如果区块存在于多个注册表中,CLI 会在终端中提示你选择。没有终端时,它会停止并报错,列出匹配的注册表;而 --yes 会按 blocks.json 顺序选择第一个注册表。
添加多个区块
npx blockstudio add ui/tabs ui/hero ui/accordion
所有区块会在一次运行中安装。
安装前预览
npx blockstudio add ui/tabs --dry-run
这会显示将要安装的内容,但不会写入任何文件。
浏览可用区块
npx blockstudio list
npx blockstudio list ui
npx blockstudio search hero
list 会显示所有注册表中的区块(或特定注册表中的区块)。search 会对区块名称、标题和说明进行不区分大小写的子字符串匹配。
删除区块
npx blockstudio remove tabs
这会删除区块文件夹。在交互模式下,系统会提示你确认。传入 --yes 可跳过提示。
CI 和自动化
init、add 和 remove 接受 --yes,用于跳过交互式提示。list 和 search 不会提示,并会将 --yes 作为未知选项拒绝。stdin 不是终端时(CI 运行器、管道输入),CLI 会切换到非交互模式:init 会覆盖已有的 blocks.json;如果区块文件夹已存在或区块名称不明确,add 会报错停止;remove 则会直接删除,不询问。
npx blockstudio init --yes --directory blockstudio
npx blockstudio add ui/tabs --yes
npx blockstudio remove tabs --yes