岛屿
区块岛屿让区块继续使用常规的 Blockstudio 渲染流程,同时将特定于请求的输出移出初始 HTML 响应。
当页面需要积极缓存,但其中某个区块仍依赖当前访客、会话、购物车、权限或其他实时请求上下文时,这种方式很有用。
Blockstudio 区块仍然是动态的 WordPress 区块。岛屿不会将其变成预编译的静态 HTML。相反,Blockstudio 会改变首次请求时的渲染内容:
- 已水合的岛屿会渲染其常规的缓存安全 HTML,并接收挂载事件
- 动态岛屿会先渲染缓存安全的占位内容,然后从访客的浏览器获取实际片段
模式
已水合岛屿
当服务器输出可安全缓存,且区块只需要前端挂载信号时,请使用已水合岛屿。
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
初始响应中包含完整的区块 HTML。岛屿运行时不会为其发起 REST 请求,而是在标记上分发 blockstudio:island:hydrate,以便前端代码附加行为。
动态岛屿
当实际区块输出必须在访客的请求上下文中渲染时,请使用动态岛屿。
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
初始响应中只包含占位内容。浏览器会将所有已就绪的动态岛屿合并为一个请求,发送到:
POST /wp-json/blockstudio/v1/island/render
该端点只渲染已注册、属于动态区块且 blockstudio.island.mode 设置为 dynamic 的 Blockstudio 区块。
配置
island 值可以是简写形式,也可以是对象。
{
"blockstudio": {
"island": true
}
}
true 和 "hydrate" 都表示已水合。"dynamic" 表示动态。
{
"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 |
可选的片段缓存策略。 |
页面上下文
动态片段通常独立于页面外壳渲染。如果区块会读取特定于页面的设置或相关内容,请选择使用页面身份:
{
"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 会按以下顺序查找占位内容:
- 显式的
island.placeholder路径 placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- 带有占位标志的常规模板
<div class="cart-count-placeholder">
Loading cart...
</div>
如果不存在占位文件,请在常规模板中使用模板标志:
<?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 模板:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase 可以是 "normal"、"hydrate"、"placeholder" 或 "fragment"。
运行时行为
Blockstudio 仅在渲染后的页面包含岛屿标记时才会注入岛屿运行时。没有岛屿的页面不会加载额外的岛屿 JavaScript。
对于动态岛屿,运行时会:
- 收集所有已就绪的标记
- 对相同的区块名称、属性和签名组合去重
- 发送一个批量 REST 请求
- 将每个占位内容替换为返回的片段
- 分发
blockstudio:island:rendered - 分发
blockstudio:island:hydrate
loading: "eager" 岛屿会在运行时启动后立即渲染。loading: "visible" 岛屿会等待 IntersectionObserver。如果多个可见岛屿同时进入视口,它们会合并为一个请求。
触发指定的窗口事件时,event 会刷新岛屿:
window.dispatchEvent(new Event('cart:updated'));
发生故障时会保留占位内容,并分发
blockstudio:island:error。
片段端点
岛屿端点是公开的,但它不是通用的区块渲染 API。
每个标记都包含:
- 区块名称
- 允许列表中的属性
- 服务器生成的签名
只有满足以下条件时,端点才会进行渲染:
- 区块已注册
- 区块是动态的 WordPress 区块
- 区块被标记为动态 Blockstudio 岛屿
- 传入的属性符合区块架构和岛屿允许列表
- 签名与规范化后的区块名称和属性匹配
签名是在提供内容的 WordPress 网站上渲染时生成的,依据该网站的盐值和岛屿载荷计算。签名不会导出,也不会打包到主题中。
端点响应会标记为不可缓存。如果要缓存片段,请使用 island.cache。
片段缓存
默认情况下,动态片段不会缓存。
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true 使用短期全局缓存。要进行显式控制,请使用对象形式:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" 会为相同的区块、属性和选择加入的页面上下文共用一个缓存片段。
per: "user" 会根据当前 WordPress 用户 ID 区分缓存。
以编程方式渲染
在 Blockstudio 区块渲染的任何位置,岛屿都能正常工作:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
它们也能通过区块标签使用:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
初始输出仍然是岛屿标记和占位内容;当渲染后的响应包含该标记时,会注入运行时。
PHP API
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 时,才会构建动态标记。
钩子
检测和标记:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
端点和渲染:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request 会更改单个批量端点请求可接受的动态岛屿数量上限。默认值为 50。
运行时配置:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
签名:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
生命周期操作:
blockstudio/islands/registered
blockstudio/islands/rendered
不适合使用岛屿的情况
请勿将动态岛屿用于对 SEO 至关重要的内容。动态岛屿片段不会出现在初始 HTML 中,也不适合被索引。
如果内容可安全缓存且应对爬虫可见,请使用常规渲染或已水合岛屿。动态岛屿仅适用于可在页面外壳加载后再显示的内容,例如账户 UI、购物车状态、个性化推荐或受权限限制的控件。