跳转到正文

岛屿

区块岛屿让区块继续使用常规的 Blockstudio 渲染流程,同时将特定于请求的输出移出初始 HTML 响应。

当页面需要积极缓存,但其中某个区块仍依赖当前访客、会话、购物车、权限或其他实时请求上下文时,这种方式很有用。

Blockstudio 区块仍然是动态的 WordPress 区块。岛屿不会将其变成预编译的静态 HTML。相反,Blockstudio 会改变首次请求时的渲染内容:

  • 已水合的岛屿会渲染其常规的缓存安全 HTML,并接收挂载事件
  • 动态岛屿会先渲染缓存安全的占位内容,然后从访客的浏览器获取实际片段

模式

已水合岛屿

当服务器输出可安全缓存,且区块只需要前端挂载信号时,请使用已水合岛屿。

JSON
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}

初始响应中包含完整的区块 HTML。岛屿运行时不会为其发起 REST 请求,而是在标记上分发 blockstudio:island:hydrate,以便前端代码附加行为。

动态岛屿

当实际区块输出必须在访客的请求上下文中渲染时,请使用动态岛屿。

JSON
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}

初始响应中只包含占位内容。浏览器会将所有已就绪的动态岛屿合并为一个请求,发送到:

Text
POST /wp-json/blockstudio/v1/island/render

该端点只渲染已注册、属于动态区块且 blockstudio.island.mode 设置为 dynamic 的 Blockstudio 区块。

配置

island 值可以是简写形式,也可以是对象。

JSON
{
  "blockstudio": {
    "island": true
  }
}

true 和 "hydrate" 都表示已水合。"dynamic" 表示动态。

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
属性 类型 默认值 描述
mode "hydrate" 或 "dynamic" "hydrate" 孤岛模式。
tag string "div" 标记包装标签。
attributes string[] 所有区块属性 发送到动态片段请求的属性允许列表。
placeholder string 自动检测 相对占位模板路径。
loading "eager" 或 "visible" "eager" 运行时何时应获取动态孤岛。
event string 未设置 刷新动态孤岛的窗口事件名称。
context boolean false 为动态片段签名并还原所查询页面的文章 ID 和文章类型。
cache boolean 或 object false 可选的片段缓存策略。

页面上下文

动态片段通常独立于页面外壳渲染。如果区块会读取特定于页面的设置或相关内容,请选择使用页面身份:

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "context": true,
      "cache": { "ttl": 60, "per": "global" }
    }
  }
}

标记会在 data-bs-island-context 中包含所查询页面的 postId 和 postType。这两个值使用提供服务的网站密钥,与区块名称和属性允许列表一起签名。若在请求中更改或添加这些值,签名便会失效。运行时会在现有的批量片段请求中发送这些值,包括可见内容和事件驱动的刷新。这也适用于 bs_render_block()、bs_block() 和区块标签。

渲染片段时,$block['postId']、$block['postType']、get_the_ID() 和 get_queried_object_id() 都会指向该页面。WordPress 查询和文章全局变量随后会恢复,包括渲染发生异常之后。这里指的是所查询的页面,而不是 Query Loop 中的某个项目。它不会重放任意 URL 参数,也不会恢复原始请求 URL。如果需要 HTML 页面的规范 URL,请使用 get_permalink($block['postId'])。归档页和未查询文章的渲染不会发送页面身份。

端点会先检查页面是否仍然存在、文章类型是否与签名一致,以及当前访客是否有权读取,然后才查询片段缓存。有效签名不会绕过私密文章或密码保护、孤岛资格、属性允许列表,也不会绕过区块自身的权限检查。只要页面身份存在,它就始终是片段缓存键的一部分,因此不同页面上的同一区块及其属性不会共用片段。如果输出还取决于访客,请使用 per: "user" 或停用片段缓存。

省略 context 或设为 false 时,现有标记和无上下文行为保持不变。请勿将机密数据放入公开标记。

动态占位内容

动态岛屿应渲染可安全放入共享整页缓存的占位内容。请勿在占位分支中包含特定于访客的数据。

Blockstudio 会按以下顺序查找占位内容:

  1. 显式的 island.placeholder 路径
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. 带有占位标志的常规模板
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

如果不存在占位文件,请在常规模板中使用模板标志:

PHP
<?php if ( $isIslandPlaceholder ) : ?>
  <div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
  <div class="cart-count">
    <?php echo esc_html( acme_cart_count() ); ?>
  </div>
<?php endif; ?>

相同的值可用于 PHP、Twig 和 Blade 模板:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase 可以是 "normal"、"hydrate"、"placeholder" 或 "fragment"。

运行时行为

Blockstudio 仅在渲染后的页面包含岛屿标记时才会注入岛屿运行时。没有岛屿的页面不会加载额外的岛屿 JavaScript。

对于动态岛屿,运行时会:

  1. 收集所有已就绪的标记
  2. 对相同的区块名称、属性和签名组合去重
  3. 发送一个批量 REST 请求
  4. 将每个占位内容替换为返回的片段
  5. 分发 blockstudio:island:rendered
  6. 分发 blockstudio:island:hydrate

loading: "eager" 岛屿会在运行时启动后立即渲染。loading: "visible" 岛屿会等待 IntersectionObserver。如果多个可见岛屿同时进入视口,它们会合并为一个请求。

触发指定的窗口事件时,event 会刷新岛屿:

JavaScript
window.dispatchEvent(new Event('cart:updated'));

发生故障时会保留占位内容,并分发 blockstudio:island:error。

片段端点

岛屿端点是公开的,但它不是通用的区块渲染 API。

每个标记都包含:

  • 区块名称
  • 允许列表中的属性
  • 服务器生成的签名

只有满足以下条件时,端点才会进行渲染:

  • 区块已注册
  • 区块是动态的 WordPress 区块
  • 区块被标记为动态 Blockstudio 岛屿
  • 传入的属性符合区块架构和岛屿允许列表
  • 签名与规范化后的区块名称和属性匹配

签名是在提供内容的 WordPress 网站上渲染时生成的,依据该网站的盐值和岛屿载荷计算。签名不会导出,也不会打包到主题中。

端点响应会标记为不可缓存。如果要缓存片段,请使用 island.cache。

片段缓存

默认情况下,动态片段不会缓存。

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "cache": true
    }
  }
}

true 使用短期全局缓存。要进行显式控制,请使用对象形式:

JSON
{
  "cache": {
    "ttl": 120,
    "per": "user"
  }
}

per: "global" 会为相同的区块、属性和选择加入的页面上下文共用一个缓存片段。 per: "user" 会根据当前 WordPress 用户 ID 区分缓存。

以编程方式渲染

在 Blockstudio 区块渲染的任何位置,岛屿都能正常工作:

PHP
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

echo bs_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

它们也能通过区块标签使用:

HTML
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />

初始输出仍然是岛屿标记和占位内容;当渲染后的响应包含该标记时,会注入运行时。

PHP API

PHP
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);

marker() 会验证区块元数据。只有已注册的动态 Blockstudio 区块且 island.mode 设置为 dynamic 时,才会构建动态标记。

钩子

检测和标记:

PHP
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder

端点和渲染:

PHP
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment

blockstudio/islands/max_per_request 会更改单个批量端点请求可接受的动态岛屿数量上限。默认值为 50。

运行时配置:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

签名:

PHP
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature

生命周期操作:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

不适合使用岛屿的情况

请勿将动态岛屿用于对 SEO 至关重要的内容。动态岛屿片段不会出现在初始 HTML 中,也不适合被索引。

如果内容可安全缓存且应对爬虫可见,请使用常规渲染或已水合岛屿。动态岛屿仅适用于可在页面外壳加载后再显示的内容,例如账户 UI、购物车状态、个性化推荐或受权限限制的控件。