vtex-io-storefront-react

店铺前端 React 组件

适用场景

在店铺体验中，使用 react 构建器开发面向购物者的 React 组件时，请使用此技能。

• 创建商品或类目 UI 小部件
• 构建自定义横幅、表单和面向购物者的布局组件
• 使用店铺前端钩子或上下文提供程序
• 使用 css-handles 为组件添加样式

以下场景请勿使用此技能：

• 管理页面
• 区块注册和 render-runtime 契约
• 服务运行时或后端路由设计
• GraphQL 模式设计

决策规则

• 将店铺前端组件视为面向浏览器的 UI，并确保其在购物者场景中安全运行。
• 尽量让店铺前端组件保持展示层属性驱动的形式，并将复杂的数据获取或业务逻辑移至钩子或容器组件。
• 使用 vtex.css-handles，而不是硬编码全局类名。
• 尽量通过属性或有文档说明的店铺前端钩子和上下文（例如 useProduct、useRuntime 或 useOrderForm）接收数据，而不是直接在浏览器中调用 VTEX API，或在店铺前端代码中使用应用密钥。
• 确保组件能够妥善处理商品或搜索上下文的加载中、内容为空和不可用状态。
• 对于面向购物者的文案，请使用消息基础设施中的消息 ID 和辅助函数，如 vtex-io-messages-and-i18n 中所述，而不是使用字符串字面量。
• 将店铺前端组件视为店铺无障碍体验的一部分：使用 button 或 a 等语义化 HTML 元素，而不是可点击的 div，并确保重要内容具有适当的标签或替代文本。
• 访问 window 或 document 等浏览器全局对象时，请防范服务器端执行，例如使用 useEffect，或检查 typeof window !== 'undefined'。

硬性约束

约束：店铺前端样式必须使用 css-handles

店铺前端组件必须通过 css-handles 提供样式接口，不得使用任意硬编码的类名。

重要原因

css-handles 是店铺前端组件的自定义契约。硬编码或隐藏的类名会增加安全扩展主题的难度。

检测方法

如果店铺前端组件使用了没有通过 css-handles 提供接口的任意全局类名，请停止操作，优先通过 handles 提供样式接口。

正确

const CSS_HANDLES = ['container', 'title'] as const

错误

return <div className="my-random-block-root">...</div>

约束：店铺前端组件必须确保浏览器安全

店铺前端 React 代码不得依赖仅限 Node.js 的 API 或仅适用于服务器端的假设。

重要原因

这些组件运行在面向购物者的前端中。仅限服务器端的依赖会破坏渲染，并导致浏览器运行时错误。

检测方法

如果组件使用仅限 Node.js 的模块、文件系统访问或仅适用于服务器运行时的假设，请停止操作，并针对浏览器环境重新设计。

正确

return <span>{label}</span>

错误

import fs from 'fs'

约束：面向购物者的字符串必须支持本地化

店铺前端中可见的字符串必须遵循应用国际化模式，不得使用硬编码文本。

重要原因

店铺前端 UI 需要适配不同的语言区域和店铺。硬编码字符串会降低组件的可复用性，也会使其与 VTEX IO 本地化机制不一致。

检测方法

如果 JSX 中硬编码了购物者可见的文案，请停止操作，并将其移至国际化机制中。

正确

<FormattedMessage id="storefront.cta" />

错误

<span>Buy now</span>

推荐模式

让店铺前端组件保持精简、属性驱动、基于 css-handles，并确保其在购物者场景中安全运行。

最简 css-handles 模式：

import { useCssHandles } from 'vtex.css-handles'

const CSS_HANDLES = ['container', 'title'] as const

export function MyComponent() {
  const { handles } = useCssHandles(CSS_HANDLES)

  return (
    <div className={handles.container}>
      <h2 className={handles.title}>...</h2>
    </div>
  )
}

常见问题

• 硬编码类名，而不是使用 css-handles。
• 使用对浏览器不安全的依赖。
• 硬编码购物者可见的字符串。
• 使用临时方式获取数据，而不是遵循 VTEX 店铺前端模式。
• 将复杂业务逻辑或大量数据获取直接放入展示组件，而不是使用钩子或容器。
• 使用 div 或 span 等非语义化的可点击元素并绑定 onClick，而本应使用 button 或 a 元素。

审核清单

• 该组件是否确实面向购物者？
• 是否通过 css-handles 暴露样式？
• 该组件是否适合在浏览器中运行？
• 可见文本是否已本地化？
• 数据流是否适用于店面组件？

相关技能

• vtex-io-render-runtime-and-blocks - 当主要问题涉及区块注册和 Store Framework 接线时使用
• vtex-io-messages-and-i18n - 当主要问题涉及如何翻译和组织面向购物者的文本时使用

参考资料

• Store Framework - 店面应用上下文、数据和钩子
• CSS Handles - VTEX IO 店面组件的样式约定