跳转到正文

快速入门

本指南将帮助你设置 Blockstudio 并创建你的第一个自定义区块。

安装

命令行
composer require blockstudio/blockstudio

Blockstudio 可以作为插件通过 composer/installers 安装,也可以直接打包在主题中。所有安装方式请参阅Composer文档。

Composer 安装会通过 Composer 接收更新。内置的 GitHub 更新程序会自动停用。

手动安装

从GitHub下载最新版本

将 zip 文件上传到 WordPress 插件目录并启用插件。手动安装后,会通过内置的 GitHub 更新程序在 WordPress 仪表盘中收到自动更新通知。

这两种安装方式都会捆绑 Markdown、YAML 和更新器库的独立副本及其依赖项。它们不会使用或替换其他插件或主题提供的版本。如果你的应用直接使用其中某个库,请安装自己的 Composer 依赖项;Blockstudio 捆绑的副本仅供内部使用,不是公开的 PHP API。

已验证身份的更新检查

默认情况下,手动安装会匿名检查 GitHub。多个站点共用一个出站 IP 时,可能会耗尽 GitHub 的匿名 API 额度,检查更新时收到 HTTP 403 响应。从 7.7.4 起,请在 wp-config.php 中配置 GitHub 个人访问令牌,并确保在 WordPress 加载之前完成:

PHP
define('BLOCKSTUDIO_GITHUB_TOKEN', 'your-github-token');

该令牌只需拥有访问公共仓库信息的权限。请勿授予写入权限。请将其保存在服务器端配置中,勿纳入版本控制,也不要放在 blockstudio.json、区块属性或前端代码中。更新器会将令牌传递给其捆绑的 GitHub 客户端,用于经过身份验证的检查和版本发布下载。向无关仓库和其他下载主机发出的请求不会收到该令牌。

对于由环境管理的机密信息,可以通过 MU 插件提供或覆盖令牌:

PHP
<?php
add_filter('blockstudio/updater/token', function ($token) {
  return getenv('BLOCKSTUDIO_GITHUB_TOKEN') ?: $token;
});

此筛选器会在 Blockstudio 初始化其更新器时运行,早于主题加载。请在 MU 插件中注册,而非 functions.php。即使常量已定义,返回空字符串也会禁用身份验证。空值或非字符串值会使检查保持匿名。令牌为可选项;不提供令牌时,现有更新行为不变。Composer 安装仍通过 Composer 更新,且不会初始化此更新器。

创建你的第一个区块

1. 创建区块目录

在你的主题中创建一个新目录:

代码
my-theme/
  blockstudio/
    my-first-block/
      block.json
      index.php

2. 定义区块架构

创建 block.json 并配置区块:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "my-theme/my-first-block",
  "title": "My First Block",
  "category": "common",
  "icon": "star-filled",
  "blockstudio": {
    "attributes": [
      {
        "id": "heading",
        "type": "text",
        "label": "Heading",
        "default": "Hello World"
      },
      {
        "id": "content",
        "type": "textarea",
        "label": "Content"
      }
    ]
  }
}

3. 创建模板

创建 index.php 用于渲染:

PHP
<div class="my-first-block">
  <h2><?php echo $a['heading']; ?></h2>
  <p><?php echo $a['content']; ?></p>
</div>

使用 Twig 模板

Blockstudio 开箱即支持 Twig 模板。只需改用 index.twig:

Twig
<div class="my-first-block">
  <h2>{{ a.heading }}</h2>
  <p>{{ a.content }}</p>
</div>

添加样式

在同一文件夹中创建一个 style.css 文件:

CSS
.my-first-block {
  padding: 2rem;
  background: #f5f5f5;
}

使用区块时,Blockstudio 会自动加入此样式表。

翻译

Blockstudio 的编辑器控件和管理后台概览会通过 WordPress 加载 blockstudio 文本域的 JavaScript 翻译。请安装对应的语言包,或使用翻译工具在 wp-content/languages/plugins/ 中生成脚本翻译 JSON 文件。没有可用翻译的字符串会保留英文。这只会翻译 Blockstudio 自身的界面,不会翻译你在区块中定义的内容或字段标签。

后续步骤

现在可以在 WordPress 编辑器中使用你的区块了。继续阅读文档,了解以下内容:

构建区块库

从单个区块扩展到完整的区块库:设计令牌、区块模式、重复字段、图像和页面编排。