跳转到正文

用代码定义完整页面

模板和Markdown只需一条命令即可同步到WordPress。

从文件创建集合

定义pages.json,让Blockstudio发现其下的所有源文件。嵌套路径会变成嵌套页面,默认值应用于整个集合,还可以自动生成缺失的父级页面。

可将集合用于文档、知识库或着陆页,也可使用loader.php将外部文件夹挂载到路径前缀下。

将 layout.php 或 layout.tsx 之类的渲染器布局放在 pages.json 旁边,即可用一个外壳包裹集合中的每个页面,并使用 blockstudio_page_tree() 显示侧边栏。

pages/docs/pages.json
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}

显式同步

wp bs pages sync 会应用更改;未更改的页面不会产生任何写入。

Markdown源

使用带 frontmatter 的index.md,或将page.json与Markdown内容配对使用。

原始Markdown

Markdown 文件页面可通过其 URL 加 .md 访问;对于 Accept: text/markdown,也可通过常规的 URL 访问,并附带指向 HTML 的规范链接。

集合加载器

将外部文档文件夹挂载到集合中,并置于路径前缀下。

站点集合

作用域为 site 的 pages.json 会为整个页面树应用共享默认设置并列出该页面树,同时不会更改 URL 或文章行。

导航辅助工具

blockstudio_page_tree()、blockstudio_page_children()、blockstudio_current_page() 和 blockstudio_page_content() 用于构建侧边栏、分页器和正文。

集合和文章类型

集合可以注册专用的层级文章类型。

模板锁定

使用 contentOnly、all 或 insert 锁定页面或单个区块。

编写 HTML,生成区块

<h1>、<p>和<ul>等标准元素会映射到核心区块。其他所有区块名称和嵌套层级都使用<block>。

Blockstudio会将完整的页面布局解析为真正可编辑的WordPress区块。

index.php
<div>
  <h1 blockEditingMode="contentOnly">About Us</h1>
  <p>We build tools for WordPress developers.</p>
  <img src="/team.jpg" alt="Our team" />
</div>

<block name="core/columns">
  <block name="core/column"><h2>Our Mission</h2></block>
  <block name="core/column"><h2>Our Stack</h2></block>
</block>

由组件渲染的页面

在 page.json 中将 render 设置为 page.tsx 之类的条目,并提供一个 data.php 加载器,你的主题或插件注册的页面渲染器就会绘制整个页面。Sync 会存储一个 blockstudio/page 区块,而简码等 WordPress 内容会保留在其插槽中。

渲染器返回的资源会像区块资源一样经过处理,并且只打印一次,因此预渲染的页面会包含这些资源。blockstudio.dev 本身由组件页面构建而成。

pages/legal-notice/page.json
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

没有文章的路由

Blockstudio\Virtual_Routes::register() 为没有文章作为基础的文档提供服务,例如组件参考或目录。使用 prefix 和 match 后,一次注册即可响应一系列 URL;返回 null 后,URL 会交由 WordPress 处理。

路由会在 Blockstudio 的输出缓冲区中渲染,因此其中的区块会获得各自的资源和 Tailwind 输出。urls 中的路径会加入静态预渲染构建,而 Virtual_Routes::urls() 会返回这些路径以供生成站点地图。

functions.php
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

由你决定何时同步

只有在你提出要求时,页面文件才会更改WordPress。wp bs pages sync会应用所有已更改的源文件,保留带键的编辑器内容,并清理文件已不存在的页面。

指纹涵盖清单、加载器、布局和源文件,因此未更改的页面不会产生任何写入。部署时调用Pages::reconcile()并获取机器可读报告。

终端
# Apply changed sources, keep keyed edits
wp bs pages sync

# Replace managed content from the files
wp bs pages sync --authoritative

# Compare every page and report as JSON
wp bs pages sync --full --format=json

带键的区块会保留内容

为任意区块添加key。下次同步时,带键的区块会将模板属性与现有用户内容合并,而不带键的区块则会被替换。

在部署过程中调整结构,同时保留客户内容。

index.php
<h1 key="title">About Us</h1>
<block name="core/cover" key="hero" url="/hero.jpg">
  <h2>Welcome to our company</h2>
  <p>Edit this content freely.</p>
</block>
<block name="core/columns" key="team">
  <block name="core/column"><h3>Our Team</h3></block>
</block>

模板锁定和编辑模式

"all"禁止更改;"contentOnly"锁定结构,但允许编辑文本;"insert"允许编辑和重新排序,但不允许添加或删除。

使用blockEditingMode覆盖任何元素,即可让已锁定的页面选择性地允许编辑,或禁用单个区块。

index.php
<h1>Welcome to Our Product</h1>
<p>The best solution for your needs.</p>
<block name="core/cover" blockEditingMode="disabled" url="/static-banner.jpg">
  <p>Promotional banner</p>
</block>
<block name="core/group" blockEditingMode="default">
  <h2>Customizable Section</h2>
</block>

从文件提供站点编辑器模板

将template.json和模板添加到templates/,或将part.json添加到parts/,即可让你的区块主题获得基于文件的wp_template和wp_template_part源。

它们使用与页面相同的语法。只要不重置,站点编辑器中的自定义内容仍会优先生效;重置后,文件源就会恢复。

templates/front-page/index.php
<block name="core/template-part" slug="header" />

<div>
  <h1>Welcome</h1>
  <block name="core/post-content" />
</div>

<block name="core/template-part" slug="footer" />

git 中选定的数据库内容

wp bs content pull 会将允许列表中的文章、术语、关系和已声明元数据导出为可移植文件,push 则会将其应用到另一个环境。已声明的引用、父级和术语关系会以稳定的 UID 随文件迁移。

由页面同步管理的文章可以与 includePageSyncManaged 一起使用。它们的文件带有 "bodyOwner": "page-sync",因此 Content Sync 会迁移元数据,而页面同步会保留正文。

blockstudio.json
{
  "content": {
    "enabled": true,
    "id": "default",
    "path": "content",
    "postTypes": ["team_member"],
    "taxonomies": ["category"],
    "meta": {
      "include": ["_my_*"],
      "references": {
        "_thumbnail_id": { "kind": "attachment" },
        "_related_posts": { "kind": "post", "path": "*" }
      }
    },
    "media": "manifest"
  }
}

带键区块

模板不断演进,用户内容依然保留。

编辑模式

设置页面默认值,并覆盖单个元素的设置。

区块绑定

将区块连接到文章元数据,让内容在同步后得以保留。

文章类型模板

templateFor 会将一个页面设为某种类型每篇新文章的起始区块结构。

固定文章 ID

删除页面并重新同步时,postId 会恢复使用相同的 ID,因此菜单和链接仍能正常工作。

脚手架与锁定

sync: false 与 Pages::force_sync() 一起使用时,会创建一次页面,供编辑者自行管理。Pages::lock() 和 unlock() 可阻止某个页面参与同步。

自定义解析器渲染器

构建器和渲染器筛选器可将区块标签转换为第三方区块的区块数组,也可更改核心区块的写入方式。

元素映射

将一个 HTML 元素映射到另一个区块,根据元素属性选择区块,并将段落 HTML 路由到内容字段。

自定义发现路径

筛选器可为页面、版式和站点编辑器模板添加根目录,例如来自某个插件的根目录。

逻辑发现源

预览、叠加层和生成的主题可以向 Blockstudio 提供组合后的文件清单,而不是单个主题文件夹。

稳定引用

声明的文章、术语和附件引用会在拉取时转换为可移植的 UID,在推送时解析为本地 ID。

推送前检查状态

wp bs content status 会将每个实体报告为未更改、将要更新、数据库中缺失、冲突、已锁定或孤立,并警告看起来像机密信息的元键。

经过验证且范围明确的推送

推送会在写入前验证整个计划,并跳过已锁定的实体。–dry-run 会显示计划,而 –prune –yes 只会移除此内容集中的实体。

纳入版本控制

在Git中跟踪页面文件,并将它们部署到不同环境。

PHP API

以编程方式访问树、子项、元数据、同步、锁定和 ID。

Plus

官方扩展套件

高级站点模板、AI 系统指令和私人 Discord 社区。一次购买,终身更新。

  • 500+ 个网站模板
  • AI 系统指令
  • 终身更新
  • 私有 Discord 社区