跳转到正文

构建基于文件的页面

传统的 WordPress 页面是在区块编辑器中构建的:拖动区块、配置设置,然后点击保存。这适用于由客户自行构建页面的情况,但对于构建结构化、受版本控制页面的开发者来说,会带来问题。页面布局存储在数据库中,而不是代码中。你无法在拉取请求中审核布局、使用 git 回滚,也无法在全新安装中复现布局。

Blockstudio 的基于文件的页面解决了这个问题。你可以将页面定义为主题中的文件,编写转换为 WordPress 区块的 HTML 模板,并精确控制客户可以和不可以编辑的内容。通过明确的命令将这些文件同步为常规的 WordPress 文章,而模板始终是唯一可信来源。

本指南将带你从头开始构建页面,并深入介绍锁定和编辑控制功能,说明它们如何让基于文件的页面适用于客户项目。

创建你的第一个页面

在主题中创建一个 pages 文件夹,然后添加一个包含两个文件的子文件夹:

代码
theme/
└── pages/
    └── about/
        ├── page.json
        └── index.php
JSON
{
  "name": "about",
  "title": "About Us",
  "postStatus": "publish"
}
HTML
<h1>About Us</h1>
<p>We build things for the web.</p>

运行页面同步命令:

命令行
wp bs pages sync

Blockstudio 会将 HTML 解析为 WordPress 区块,并创建一个名为“关于我们”、别名为 about 的页面。在编辑器中打开它,你会看到一个标题和一个段落,就像手动添加的一样。

编辑 index.php,更改文本,然后再次运行命令。重新加载编辑器即可查看更新。这就是核心流程:编写 HTML,有意执行同步,生成区块。

模板语言

Blockstudio 的 HTML 解析器会将标准 HTML 元素转换为 WordPress 区块。编写 <p> 会得到段落区块;编写 <h2> 会得到标题区块。映射关系直观明了:

HTML 区块
<p> 段落
<h1> 到 <h6> 标题(级别与标签一致)
<ul>、<ol> 列表
<blockquote> 引用
<img> 图像
<div>、<section> 分组
<hr> 分隔符
<details> 详细信息
<table> 表格

对于没有直接 HTML 对应项的区块,请使用带有 name 属性的 <block> 元素:

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h2>Hero Title</h2>
  <p>Content over the background image.</p>
</block>

<block name="core/spacer" height="80px" />

<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
  <block name="core/button" url="/work">See Our Work</block>
</block>

<block> 元素上的属性会作为区块属性传递。值会自动转换类型:"true" 会变成布尔值,"3" 会变成整数,而类似 '{"type":"flex"}' 的 JSON 字符串会解码为对象。

布局

分组通过 layout 属性支持不同的布局模式:

HTML
<!-- Default group (stacked) -->
<div>
  <p>Stacked by default.</p>
</div>

<!-- Row (horizontal flex) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
  <p>Side</p>
  <p>by side</p>
</block>

<!-- Stack (vertical flex) -->
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
  <p>Stacked</p>
  <p>with flex</p>
</block>

<!-- Columns -->
<block name="core/columns">
  <block name="core/column">
    <p>Left column.</p>
  </block>
  <block name="core/column">
    <p>Right column.</p>
  </block>
</block>

自定义区块

<block> 语法适用于任何已注册区块,包括你自己的 Blockstudio 区块:

HTML
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />

属性会自动映射到区块的 Blockstudio 字段值。

构建落地页

下面是一个完整的落地页示例,它使用核心区块构建结构和布局:

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "slug": "landing",
  "postStatus": "publish",
  "templateLock": "all"
}
HTML
<block name="core/cover" url="https://images.unsplash.com/photo-1497366216548-37526070297c?w=1600">
  <h1>Build faster with Blockstudio</h1>
  <p>File-based blocks. Zero build step. Full editor integration.</p>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Get Started</block>
    <block name="core/button" url="/docs">Documentation</block>
  </block>
</block>

<div>
  <h2>Why developers love it</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3>No build step</h3>
      <p>Write PHP, CSS, and JavaScript. No webpack, no bundler, no transpiler.</p>
    </block>
    <block name="core/column">
      <h3>File-based</h3>
      <p>Every block is a folder. Every page is a template. Version control everything.</p>
    </block>
    <block name="core/column">
      <h3>Full editor support</h3>
      <p>Fields, previews, and InnerBlocks work in the block editor out of the box.</p>
    </block>
  </block>
</div>

<block name="core/media-text" mediaurl="https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=800" mediatype="image">
  <h2>Ship entire sites from your IDE</h2>
  <p>Define pages, blocks, and patterns as files. Blockstudio handles the rest.</p>
</block>

<div>
  <h2>Frequently asked questions</h2>
  <details>
    <summary>Do I need to learn React?</summary>
    <p>No. Templates are PHP. Fields are JSON. Interactivity is optional.</p>
  </details>
  <details>
    <summary>Does it work with my existing theme?</summary>
    <p>Yes. Drop a blockstudio folder into any theme and start creating blocks.</p>
  </details>
</div>

<div>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Start Building</block>
  </block>
</div>

这个页面包含封面 Hero、三列功能网格、媒体文本区块、FAQ 手风琴和 CTA,全部来自一个 HTML 文件。page.json 中的 templateLock: "all" 表示客户无法更改任何内容。下一节将说明如何放宽此限制。

控制编辑器

基于文件的页面正是在这里展现出真正的强大之处。Blockstudio提供两种独立的控制方式:模板锁定和区块编辑模式。结合使用后,你可以精确指定客户能修改页面的哪些部分。锁定结构,同时允许他们编辑文本。冻结某些区块,同时让其他区块完全开放。还可以创建这样的页面:客户唯一能做的就是填写三个指定标题。

模板锁定

page.json中的templateLock属性控制结构编辑:区块能否添加、删除或重新排列。

"all"(默认)

JSON
{
  "name": "terms",
  "templateLock": "all"
}

最严格的锁定。客户不能添加、删除或移动区块,也不能编辑区块内容(除非与blockEditingMode结合使用)。未指定值时,这是默认设置。

适用场景: 法律页面、服务条款、隐私政策,以及任何内容只能通过代码更改的页面。

"insert"

JSON
{
  "name": "about",
  "templateLock": "insert"
}

客户不能添加或删除区块,但可以移动现有区块并编辑其内容。区块数量固定,但顺序可以调整。

适用场景: 区块集合固定,但希望客户可以重新排序的页面。例如,区块数量预先确定、顺序由客户决定的作品集页面。

"contentOnly"

JSON
{
  "name": "homepage",
  "templateLock": "contentOnly"
}

客户可以编辑文本内容,但不能添加、删除或移动区块。与"all"的区别在于,"all"也会阻止内容编辑,而"contentOnly"则明确允许编辑。

适用场景: 面向客户的页面中最常见的选择。开发者控制布局,客户填写文本。

false

JSON
{
  "name": "blog",
  "templateLock": false
}

完全不锁定。客户拥有全部控制权:可以添加、删除、移动和编辑任何区块。模板提供一个起始结构,之后由客户自行管理。

适用场景: 博客索引页、自由编辑内容页,或任何应给予客户完全编辑自由的页面。

区块编辑模式

templateLock控制结构(添加、删除、移动),而blockEditingMode控制单个区块的交互:区块是否可以被选中、配置或编辑。

在page.json中设置页面级默认值:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

"default"

完全编辑。可以选中区块、修改其设置并编辑内容。这是常规的编辑器体验。

"contentOnly"

区块可编辑,但只能编辑其中的文本内容。你无法打开区块设置、更改颜色、调整内边距或修改任何非内容属性。区块工具栏只显示文本格式选项。

"disabled"

区块完全不可交互。它们会在编辑器中呈现,但不能点击、选中或以任何方式修改。客户可以看到内容,但无法对其进行操作。

单个元素的覆盖设置

这里就有意思了。页面级的blockEditingMode为页面上的每个区块设置默认值,但你可以在模板中的单个元素上覆盖该设置:

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Heading</h1>
  <p blockEditingMode="contentOnly">Edit this paragraph too.</p>
</block>

<div>
  <h2>Features</h2>
  <p>This paragraph cannot be edited (inherits "disabled").</p>
  <p blockEditingMode="contentOnly">But this one can.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">This button is frozen</block>
</block>

页面默认值为"disabled",因此每个区块初始都不可交互。随后,特定元素可以选择启用"contentOnly",仅允许编辑其中的文本。结果就是,客户只能在两个文本字段(主视觉标题和段落)以及一个功能介绍段落中输入内容,页面其他部分全部锁定。

这适用于任何HTML元素(<h1>、<p>、<div>等)以及<block>元素。你也可以在特定元素上设置blockEditingMode="default",以授予完整的编辑权限:

HTML
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>

现在,客户可以更改按钮文本、URL、样式和其他任何设置。页面的其他部分仍保持锁定。

祖先级联

有一点很重要:单个元素的覆盖设置与容器区块交互时会受到影响。如果页面默认值为"disabled",而你在某个组内的标题上设置blockEditingMode="contentOnly",那么该标题必须能够访问。但它的父级组为"disabled",这意味着根本无法进入该组。

Blockstudio会自动处理这一情况。当子区块覆盖编辑模式时,它的所有祖先区块都会设置为"contentOnly",从而确保子区块仍可访问。你无需手动设置父级容器的模式。只需在要允许编辑的区块上设置覆盖值,相应的访问路径就会打开。

HTML
<!-- page default: "disabled" -->
<div>
  <!-- this group is auto-set to "contentOnly" because it contains an override -->
  <div>
    <!-- this group is also auto-set to "contentOnly" -->
    <p blockEditingMode="contentOnly">Deeply nested but still editable.</p>
  </div>
</div>

祖先级联只会将容器提升为"contentOnly",不会提升为"default"。这意味着可以导航祖先组(进入其中),但不能完全编辑它们(更改其设置)。

决策矩阵

组合使用templateLock和blockEditingMode,即可实现不同程度的控制。以下是最实用的组合:

开发者控制所有内容

JSON
{ "templateLock": "all" }

无需设置blockEditingMode。默认的templateLock: "all"会阻止所有更改。适用于完全通过代码管理的页面。

客户编辑所有文本

JSON
{ "templateLock": "contentOnly" }

客户可以编辑任何区块中的文本,但不能更改页面结构。简单且宽松。

客户只能编辑指定文本

JSON
{
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

与模板中特定元素上的blockEditingMode="contentOnly"结合使用。这是最精确的选择:客户只能编辑你指定的区块。

客户重新排列固定区块

JSON
{ "templateLock": "insert" }

客户可以重新排列区块并编辑内容,但不能添加或删除区块。适用于区块集合固定、顺序可调整的页面。

客户拥有完全控制权

JSON
{ "templateLock": false }

模板只是起点,之后客户可以随意编辑。

保留客户的编辑内容

默认情况下,更新模板文件时,Blockstudio会替换整个页面内容。如果客户在编辑器中修改了某个标题,下次同步后该修改就会消失。对于由开发者控制的页面,这没有问题;但如果客户也会提供内容,你就需要一种方式来保留他们的修改。

键

在任意元素上添加key属性,即可指定合并而非替换该元素:

HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1>Default Hero Title</h1>
  <p>Default hero description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p>Feature introduction text.</p>
</div>

<div>
  <h2>Unkeyed Section</h2>
  <p>This gets replaced on every sync.</p>
</div>

模板更改并重新同步页面时:

  • 带键的区块会保留客户的内容(文本、内部区块、格式)。模板的结构属性(例如封面上的url)仍会更新。
  • 不带键的区块会整体替换为模板版本。

一个键会保护整个区块及其所有子区块。带键的组内每个段落都不必单独设置键;组的键会保护其中的所有内容。

键必须唯一

键在整个模板中必须全局唯一。如果两个元素使用相同的键,第二个元素会被视为不带键(并发出PHP警告)。请使用描述性名称:"hero"、"features"、"cta"、"testimonial-section"。

逐步扩展模板

使用键可以在不影响客户现有内容的情况下向模板添加新区块:

HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
<div key="testimonials">
  <h2>What Clients Say</h2>
  <p>Default testimonial text.</p>
</div>

同步后,标题和服务内容会保留客户的修改。新的客户评价区块会以模板默认内容显示。如果之后从模板中删除某个带键的区块,它也会从页面中删除。

完整的客户工作流程

以下是一个真实项目中的完整流程:

JSON
{
  "name": "homepage",
  "title": "Home",
  "slug": "home",
  "postStatus": "publish",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Your Company Name</h1>
  <p blockEditingMode="contentOnly">Your tagline goes here.</p>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Contact Us</block>
  </block>
</block>

<div key="features">
  <h2 blockEditingMode="contentOnly">What We Do</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service One</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Two</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Three</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
  </block>
</div>

<block name="core/media-text" key="about" mediaurl="https://example.com/team.jpg" mediatype="image">
  <h2 blockEditingMode="contentOnly">About Us</h2>
  <p blockEditingMode="contentOnly">Tell your story here.</p>
</block>

<div key="cta">
  <h2 blockEditingMode="contentOnly">Ready to get started?</h2>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Get in Touch</block>
  </block>
</div>

此页面包含四个带键的区块。客户可以编辑带有blockEditingMode="contentOnly"标记的标题和段落,这些修改会在模板更新后保留。开发者控制布局、图像、按钮 URL 和整体结构。如果开发者之后在“about”和“cta”之间添加客户评价区块,它会在下次同步时出现,且不会影响客户的任何文本。

区块绑定:键的另一种选择

WordPress 6.5 引入了区块绑定API,用于将区块属性连接到文章元数据。无需将可编辑内容存储在区块标记中(由键保护),内容会存放在wp_postmeta中(模板同步无法触及该位置)。

HTML
<h1 metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'>
  Default Title
</h1>

<p metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'>
  Default description.
</p>

必须在PHP中注册元数据键:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest' => true,
    'single'       => true,
    'type'         => 'string',
    'default'      => 'Default Title',
) );

区块绑定比键有两个优势:可以通过meta_query使用WP_Query查询数据,也可以在RESTAPI中使用。代价是,你需要在PHP中注册每个元数据键,而且绑定只适用于单个区块属性(不适用于复杂的嵌套内容)。

对于区块结构很重要的丰富内容区块(例如包含标题、段落和图像的组),请使用键。对于还需要查询或在其他位置显示的单个文本值,请使用绑定。

文章类型模板

使用templateFor为指定类型的所有新文章设置默认区块结构:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}
HTML
<h1>Product Name</h1>

<block name="core/columns">
  <block name="core/column">
    <img src="" alt="Product image" />
  </block>
  <block name="core/column">
    <p>Product description goes here.</p>
    <block name="core/buttons">
      <block name="core/button" url="#">Buy Now</block>
    </block>
  </block>
</block>

<div>
  <h2>Specifications</h2>
  <table>
    <thead>
      <tr><th>Feature</th><th>Value</th></tr>
    </thead>
    <tbody>
      <tr><td>Weight</td><td>1.2 kg</td></tr>
    </tbody>
  </table>
</div>

每篇新的“product”文章都会采用此结构。templateLock: "insert"允许编辑者重新排列区块并编辑内容,但不能添加或删除区块。

提示

在有意安排的部署节点进行同步。 更改或部署页面源文件后,运行wp bs pages sync。访问前端或管理后台都不会同步页面。PHP部署工具可以调用Blockstudio\Pages::reconcile()并检查其机器可读报告。

固定重要文章 ID。 对于菜单、硬编码链接或外部系统引用的页面,请在page.json中使用postId。如果不固定 ID,删除后重新创建的页面会获得新 ID,从而破坏这些引用。

使用sync: false创建脚手架。 如果你想创建一次页面,然后完全交给客户管理,请设置"sync": false并使用Blockstudio\Pages::force_sync()创建。之后的常规协调过程会忽略该页面。

通过PHP锁定和解锁。 调用Blockstudio\Pages::lock('about')可阻止特定页面同步(适用于客户集中编辑期间)。调用Blockstudio\Pages::unlock('about')可重新启用同步。

模板引擎。 除了PHP,模板还可以用Twig或Blade编写(分别需要Timber和illuminate/view)。这对循环和过滤器很有用,但页面模板是在显式同步期间编译的,而不是在前端请求期间编译。如果源文件编译本身需要PHP专用辅助函数,请使用PHP。

强制同步会忽略键。 调用Pages::force_sync('about')会替换整个页面内容,并忽略键和修改时间检查。只有在你有意将页面重置为模板状态时才使用它。

后续步骤

  • 页面参考:详细介绍所有page.json属性、PHPAPI和带键合并算法。
  • 页面与模式概览:介绍HTML解析器、区块语法参考、自定义渲染器和元素映射。
  • 模式:相同的模板语法也可用于创建可复用的区块模式,而非页面。