vtex-io-admin-react

管理端 React 界面

适用场景

在构建 VTEX Admin 管理体验的 React 界面时使用此技能。

• 设置页面
• 审核工具
• 内部仪表板
• 运营表单和表格

以下场景不适用：

• 店面组件
• render-runtime 区块
• 路由授权设计
• 后端服务结构

决策规则

• 管理界面使用 VTEX 官方设计系统。
• 对于面向客户发布的 VTEX IO 管理应用，优先选择 vtex.styleguide 作为默认方案。
• @vtex/shoreline 也是 VTEX 官方设计系统，尤其适用于内部后台场景。
• 页面布局优先使用 Styleguide 的核心布局模式，例如 Layout、PageHeader 和 PageBlock。
• 常见管理需求优先使用 Styleguide 构建组件：Table、Input、Dropdown、Toggle、Tabs、Modal、Spinner 和 Alert。
• 管理界面应专注于清晰的运营体验，而不是店面样式。
• 数据量较大的管理页面应优先明确呈现加载、空数据和错误状态。
• 对于异步操作，应使用按钮加载状态和基于 toast 的反馈，让用户了解变更何时开始、成功或失败。
• 优先使用国际化消息，而非硬编码的管理端文案，以确保标签和反馈在不同店铺和区域设置中保持一致。
• 表格、表单、筛选器和反馈模式应符合 VTEX Admin 的惯例。
• 优先使用官方设计系统组件，而不是自定义的可点击 div 或 span 模式，以确保焦点行为、键盘导航和无障碍属性默认正确。
• 对于大型列表和表格，优先使用分页和服务端筛选，而不是将所有数据加载到浏览器中并在内存中筛选。
• 对于搜索和筛选，优先使用官方设计系统提供的模式，而不是自行设计控件行为。
• 每个应用中的标签、消息和操作文案应使用同一种语言，并避免在同一界面混用不同语气或语言。
• 表单操作应保持一致：使用主要保存操作；适当时提供可选的次要取消操作；提交后明确反馈。

硬性约束

约束：管理界面必须使用 VTEX 设计系统

管理面板组件必须使用 VTEX 官方设计系统。

原因

VTEX Admin 具有一致的设计语言。VTEX 官方设计系统能够保持这种一致性，而通用第三方 UI 库会造成视觉不一致、样式冲突和审核问题。

检测方式

如果在管理应用中发现 Material UI、Chakra、Ant Design 或其他通用第三方 UI 系统，请停止并替换为 VTEX 设计系统模式。不要将 @vtex/shoreline 标记为第三方系统。

正确

import { Layout, PageHeader, PageBlock, Table } from 'vtex.styleguide'

import { Button, Table, EmptyState } from '@vtex/shoreline'

错误

import { DataGrid } from '@material-ui/data-grid'

约束：管理界面必须呈现加载、空数据和错误状态

运营界面必须让用户清楚了解数据状态。

原因

管理端用户需要可靠的运营反馈。与明确展示状态相比，空白界面更难支持和诊断。

检测方式

如果页面加载远程数据，但在加载、无数据或出错时没有呈现有意义的内容，请停止并添加明确的 UI 状态。

正确

if (loading) {
  return (
    <PageBlock>
      <Spinner />
    </PageBlock>
  )
}

if (error) {
  return (
    <PageBlock>
      <Alert type="error">Failed to load data. Please try again.</Alert>
    </PageBlock>
  )
}

错误

return <Table items={data?.items ?? []} />

约束：管理操作必须向用户提供明确反馈

管理界面中的变更操作必须清楚报告成功、失败或待处理状态。

原因

运营操作会影响真实的店铺配置和数据。用户需要即时反馈，以避免重复操作或操作结果不明确。

检测方式

如果按钮触发写入操作后没有提供结果反馈，请停止并添加明确的反馈。

正确

<Button isLoading={saving}>Save</Button>
showToast({ message: 'Settings saved successfully' })

错误

<Button onClick={save}>Save</Button>

约束：数据量大的管理界面必须有边界且易于浏览

列表、表格和搜索密集型管理界面必须采用分页等有界渲染模式；如果 API 支持，应优先使用服务端筛选。

重要原因

管理页面通常需要处理会随时间增长的运营数据集。一次性渲染过多行，或只在内存中筛选，会导致性能不佳和脆弱的用户体验。

检测

如果页面在没有分页的情况下渲染超大型集合，或为了在本地筛选而将完整数据集加载到浏览器中，请立即停止，并添加有界导航或服务端筛选。

正确

<Table items={items} />
<Pagination currentItemFrom={1} currentItemTo={10} totalItems={120} />

错误

const filtered = allItems.filter(matchesSearch)
return <Table items={filtered} />

约束：交互控件必须使用无障碍语义

管理交互必须使用无障碍控件，并且应优先使用官方设计系统组件，而不是自定义的、可点击但不具备语义的元素。

重要原因

键盘导航、焦点处理和屏幕阅读器行为是管理界面基本可用性的一部分。使用可点击但不具备语义的元素，会大幅增加无障碍回归的可能性。

检测

如果看到将可点击的 div 或 span 元素用作主要控件，而本应使用按钮、链接或设计系统组件，请立即停止并替换它们。

正确

<Button variation="primary">Save</Button>

错误

<div onClick={save}>Save</div>

Admin 构建器结构

VTEX IO 中的管理页面通过 Admin 构建器公开：

• 使用 admin/ 文件夹声明导航和路由。
• 使用 admin/navigation.json 定义 Admin 导航路径中的分区、子分区和导航项。
• 使用 admin/routes.json 将每个 Admin 路径映射到 react/ 下实现的 React 组件。
• 使用 react/ 文件夹实现 Admin 路由所用的页面组件。

实用规则：

• admin/routes.json 中的每个条目都应指向 react/ 中真实存在的组件。
• 路由 path 应与 admin/navigation.json 中声明的导航结构保持一致。
• 页面组件应使用 VTEX Admin 布局模式，例如 Layout、PageHeader 和 PageBlock；在内部场景中，也可使用官方 Shoreline 对应模式。

示例：navigation.json 结构

admin/navigation.json：

[
  {
    "section": "storeSettings",
    "subSection": "storeFront",
    "subSectionItems": [
      {
        "labelId": "admin/my-settings.navigation.title",
        "path": "/admin/app/my-settings"
      }
    ]
  }
]

主要字段：

• section / subSection：定义链接在 Admin 导航树中的位置。
• subSectionItems[].path：应与 admin/routes.json 中声明的 path 相匹配。
• titleId / labelId：用于国际化导航标签的消息 ID。
• adminVersion：可选，仅在兼容旧版和新版 Admin 体验时需要。新应用的默认示例中不要使用它。

示例：将 Admin 构建器关联到 React 页面

admin/routes.json：

{
  "admin.app.my-settings": {
    "component": "MySettingsPage",
    "path": "/admin/app/my-settings"
  }
}

react/MySettingsPage.tsx：

import React from 'react'
import { Layout, PageHeader, PageBlock } from 'vtex.styleguide'

const MySettingsPage: React.FC = () => (
  <Layout pageHeader={<PageHeader title="My settings" />}>
    <PageBlock>
      {/* Page content goes here */}
    </PageBlock>
  </Layout>
)

export default MySettingsPage

首选模式

使用 VTEX 设计系统明确呈现运营状态，并优先追求清晰，而非装饰性 UI。 在适用时搭配 Styleguide 使用 PageHeader 和 PageBlock；在内部场景中，也可使用官方 Shoreline 对应模式。使用 Spinner / Alert / EmptyState 展示数据状态，并通过 showToast 和按钮加载状态提供异步操作反馈。 大型数据集应使用分页表格；尽可能优先使用服务端筛选，并保持表单操作一致：主要操作用于保存，可选操作用于取消。

常见故障模式

• 在管理应用中使用第三方 UI 库。
• 缺少加载、空数据或错误状态。
• 触发变更操作却没有提供可见反馈。
• 渲染大型表格却不分页，或只在内存中筛选所有数据。
• 使用不具备语义的元素构建可点击控件，而不是使用无障碍按钮或链接。
• 在同一管理界面中混用语言，或文案风格不一致。

审查清单

• 界面是否使用 VTEX 官方设计系统（Styleguide 或 Shoreline），而非通用 UI 库？
• 页面是否在适当位置采用 PageHeader 和 PageBlock 布局模式（或 Shoreline 的对应模式）？
• 是否明确呈现加载、空状态和错误状态？
• 大型表格或列表是否以可扩展的方式进行分页和筛选？
• 写入操作是否安全且清晰可见？
• 交互控件是否采用无障碍语义，而非可点击的非语义元素？
• 标签和反馈消息是否经过国际化，而非硬编码？
• 应用的标签和操作是否使用统一的语言和语气？
• UI 的外观和行为是否符合 VTEX Admin 工具的风格？

参考资料

• Admin 应用 - Admin Builder 背景信息
• Shoreline 代码库 - VTEX 官方 Shoreline 设计系统代码库
• Shoreline 文档 - Shoreline 组件和设计系统文档