vtex-io-render-runtime-and-blocks

渲染运行时与区块注册

适用场景

当 VTEX IO 店铺组件需要作为区块提供给 Store Framework 使用时，请使用此技能。

• 在 store/interfaces.json 中注册组件
• 将区块名称映射到 React 组件
• 定义区块组合方式和允许的子项
• 检查组件是否已正确接入主题 JSON

请勿将此技能用于：

• 面向购物者的组件内部实现
• 管理界面
• 后端服务或路由设计
• 策略建模

决策规则

• Store Framework 中可见的每个区块都必须在 store/interfaces.json 中注册。
• 明确指定区块名称、组件映射和组合方式。
• 在 store/interfaces.json 中用作键的区块 ID（例如 product-reviews），与店铺主题在 store/*.json 的 blocks 下引用的 ID 相同。
• component 字段应映射到 react/ 下的 React 入口名称，例如 ProductReviews；如果应用结构是分层的，也可以使用 product/ProductReviews 这样的嵌套路径。
• 当区块需要明确的子项模型时，有意设置 composition。children 表示组件通过 props.children 渲染嵌套区块；blocks 表示该区块公开由 Store Framework 控制的命名区块槽位。
• composition 是可选的。对于许多简单区块，声明 component，并在需要时声明 allowed 即可。
• 区块 ID 的作用域由声明该区块的应用的 MAJOR 版本决定。vtex.pages-graphql 会将 acme-related-products 这类区块引用解析为工作区中实际安装的主版本对应的 [email protected]:acme-related-products。即使 ID 相同，在 0.x 中声明的区块与在 5.x 中声明的区块也并非同一个区块。
• 通过 store/blocks.json 引用区块 ID 的使用方主题，只有在声明该区块的应用安装版本与依赖范围的主版本匹配时才能看到该区块。如果版本不匹配，解析器会报出 Missing block [email protected]:block-id 错误，导致页面无法正常显示。
• 渲染/运行时契约请使用此技能；组件本身的实现请使用店铺/管理后台相关技能。

硬性约束

约束：店铺区块必须在 interfaces.json 中声明

所有预期供 Store Framework 使用的 React 组件都必须有对应的 interfaces.json 条目。

原因

没有接口声明，就无法在主题 JSON 中引用该组件。

检测

如果某个店铺 React 组件预期作为区块使用，但没有匹配的接口条目，请停止操作并先添加该条目。

正确

{
  "product-reviews": {
    "component": "ProductReviews"
  }
}

错误

// react/ProductReviews.tsx exists with no interfaces.json mapping

约束：组件映射必须指向真实的 React 入口文件

interfaces.json 中的 component 字段必须映射到真实导出的 React 入口文件。

原因

映射失效会导致区块契约与实现脱节，且不会明显报错。

检测

如果某个接口指向的组件名称没有对应的 React 入口文件，请停止操作并修正映射。

正确

{
  "product-reviews": {
    "component": "ProductReviews"
  }
}

错误

{
  "product-reviews": {
    "component": "MissingComponent"
  }
}

约束：块 ID 必须在声明应用的已安装主版本下解析

主题应用的 store/blocks.json 中引用的块 ID，必须能在已安装应用的 interfaces.json 条目中解析，且该应用的主版本必须符合消费者的依赖范围。渲染时的解析器使用 [email protected]:block-id 作为键，而不是单独的块 ID。

为什么这很重要

vtex.pages-graphql 会将声明应用的主版本作为块查找的一部分。存在于 [email protected] 中的块，对解析 [email protected] 的消费者不可见，即使块 ID 相同。版本不匹配会在 GraphQL 层返回 Missing block 错误，页面则会回退到默认内容或直接失败。

检测

如果消费者主题引用了某个块 ID，而声明应用的已安装主版本与消费者的依赖范围不匹配，请停止并调整依赖范围，或将块声明移到正确的主版本。

正确

// consumer theme manifest.json
{ "dependencies": { "acme.product-widgets": "0.x" } }

// [email protected] ships store/interfaces.json with:
{ "acme-related-products": { "component": "RelatedProducts" } }

// consumer theme store/blocks.json
{ "store.product": { "children": ["acme-related-products"] } }

错误

// consumer theme depends on [email protected]
// but the block "acme-related-products" was added in @5.x and never backported
{ "store.product": { "children": ["acme-related-products"] } }

解析器会返回 Missing block [email protected]:acme-related-products。

约束：块组合必须经过有意设计

组合方式和允许的子块必须符合组件的实际布局和运行时预期。

为什么这很重要

组合契约不正确，会让主题的使用变得脆弱且令人困惑。

检测

如果 allowed 或 composition 未能反映组件应如何接收子项，请停止并修正块契约。

正确

{
  "product-reviews": {
    "component": "ProductReviews",
    "composition": "children",
    "allowed": ["product-review-item"]
  }
}

错误

{
  "product-reviews": {
    "component": "ProductReviews",
    "composition": "blocks",
    "allowed": []
  }
}

推荐模式

在 interfaces.json 中明确声明块契约，并将块实现相关内容与渲染运行时注册分开。

最简块生命周期：

// store/interfaces.json
{
  "product-reviews": {
    "component": "ProductReviews",
    "composition": "children",
    "allowed": ["product-review-item"]
  },
  "product-review-item": {
    "component": "ProductReviewItem"
  }
}

// store/home.json
{
  "store.home": {
    "blocks": ["product-reviews"]
  }
}

// react/ProductReviews.tsx
export default function ProductReviews() {
  return <div>...</div>
}

此接线方式会让块名称在主题中可见，将其映射到真实的 React 入口，并在渲染运行时边界明确组合规则。

常见故障模式

• 忘记将店面组件注册为块。
• 将块名称映射到不存在的 React 入口文件。
• 使用了错误的组合模型。
• 在 5.x 系列中添加新块，并假定依赖 0.x 的消费者也能看到它。块的可见范围受声明应用的已安装主版本限制。
• 未与已在存储内容中引用该块的消费者主题协调，就重命名块 ID；对于已存储内容而言，重命名实际上属于破坏性变更。

审核清单

• 是否已在 interfaces.json 中声明该块？
• 组件映射是否能正确解析？
• 组合方式和允许的子项是否经过有意设计？
• 运行时注册是否与组件内部实现明确分开？
• 声明应用的安装主版本是否符合每个消费者的依赖范围？

相关技能

• vtex-io-storefront-theme-app — 当问题涉及消费者主题如何将这些块组合到页面和路由中时使用。
• vtex-io-storefront-theme-versioning — 当问题涉及块声明应用的主版本变更如何影响已在存储内容中引用这些块的商家时使用。

参考资料

• Store Framework - 块和主题上下文
• Interfaces — interfaces.json 如何将块 ID 映射到 React 组件，以及块 ID 如何按应用主版本进行命名空间隔离。