Workbench 组件页标准（参考模板）

本文档用于统一 Workbench 组件页的结构与内容规范。以 ButtonPage 为参考样板，后续新增/改造组件页请按此标准执行。

目标

  • 统一结构：让所有组件页保持一致的信息层级与布局。
  • 可复用：为后续新组件页提供可直接复制的模板。
  • 可审阅：保证 Demo、Playground、代码片段、参数面板都可被快速核对。

页面结构（强制顺序）

  1. 页面路由
    • @page "/components/组件名"，与组件名称一致（大小写一致）。
  2. 页面头部说明区
    • 使用 SxSection + SxPageBox + SxTypography。
    • 包含：标题（H3）+ 一句说明（Body）。
  3. Playground 区
    • 使用 SxComponentPlayground 渲染标准 Demo、参数面板、代码片段。
    • 必须支持：Blazor 代码预览、HTML 预览、Config 预览。
  4. 组件使用原则（强制）
    • 页面实现优先使用现有的 Sx* 组件完成布局与内容。
    • 仅在找不到合适 Sx* 组件时，才使用原生元素或最小化自定义结构。

标准页面模板（参考结构）

@page "/components/SxButton"
@using NextUI.Workbench.Models

<SxSection Background="var(--sx-colorNeutralBackground2)" GutterSize="ControlSize.None">
    <SxPageBox PaddingSize="ControlSize.Medium">
        <SxTypography Variant="TypographyVariant.H3">SxButton (按钮)</SxTypography>
        <SxTypography Variant="TypographyVariant.Body">最基础的交互组件，遵循 Fluent UI Blazor API 规范。</SxTypography>
    </SxPageBox>
</SxSection>

<SxSection GutterSize="ControlSize.None" Fill="true">
    <SxPageBox Fill="true" PaddingSize="ControlSize.None" EnableSafeArea="false">
        <SxComponentPlayground ComponentName="SxButton"
                             Showcase="@RenderShowcase"
                             BlazorPreview="@RenderBlazor"
                             HtmlPreview="@_htmlSnippet"
                             ConfigPreview="@_configSnippet"
                             CurrentCode="@_currentCode"
                             CodeLanguage="@_codeLang"
                             InspectorGroups="@_inspectorGroups"
                             OnPropertyUpdate="HandleUpdate" />
    </SxPageBox>
</SxSection>

SxComponentPlayground 标准项（必须）

  • ComponentName：组件名（如 SxButton）。
  • Showcase：展示多个典型场景。
  • BlazorPreview：单一可控的示例实例（用于反映 Inspector 调整）。
  • HtmlPreview / ConfigPreview：对应的静态片段。
  • InspectorGroups：参数面板分组配置。
  • OnPropertyUpdate：面板交互与预览同步。

Inspector 规范

分组建议（至少 2 组）

  • 外观配置：Appearance / Size / Shape / 颜色 / 图标等。
  • 状态与布局：Disabled / Loading / Fluid / 必填等。

分组仅作建议，具体分组需结合组件使用场景自行组织。

字段规范

  • Id：camelCase，语义清晰。
  • Label：中文 + 英文补充（如 尺寸 (Size)）。
  • Type：匹配组件实际参数类型（Text / Boolean / Enum / Number 等）。
  • Options：枚举类参数必须提供。

完整性要求（强制）

  • 列出全部参数：Inspector 必须覆盖组件的所有公开参数。
  • 可编辑并生效：所有参数应可在 Inspector 中调整，且修改应即时反映在展示效果中。
  • 类型未支持的处理：
    • 仍需列出该参数；
    • 以“不可编辑”的形式展示，并标注原因（例如 Inspector 不支持该类型 / 功能待实现）；
    • 保留后续完善计划的入口，避免参数遗漏。
  • 异常情况：若参数已可编辑但不生效，必须记录为组件缺陷，优先修复组件而非隐藏参数。

Showcase 规范（必须）

至少包含 2～3 个场景，按 使用场景 分组，建议：

  1. 基础使用场景（默认/主流程）
  2. 状态与异常场景（禁用、加载、空态、错误）
  3. 组合与高级场景（图标、前后缀、复合布局）

每个场景分组中必须包含：

  • 效果展示区：集中展示该场景下的视觉与交互。
  • 对应代码区：展示可直接复制的真实代码（Blazor 或 HTML）。

并且：

  • Blazor 组与 HTML 组必须保持相同的分组结构与布局，只在语法上不同。

Playground 底部区样式（补充）

  • Documentation / API / Source Code 的标签栏需有浅色背景，与内容区区分。
  • 标签栏下方需有分割线（细线），保持视觉稳定对齐。

Showcase 布局实现（推荐做法）

为保证页面一致性与可复用性，优先使用 Workbench 统一组件 来承载场景分组：

  • 使用 WorkbenchScenarioGroup（位于 workbench/NextUI.Workbench/Components/WorkbenchScenarioGroup.razor）
    • 内部已封装：场景标题 + Tabs（效果/代码） + 全宽卡片
    • 支持默认的上下内边距与最小高度
    • 代码区域自动滚动、效果区域可撑开

推荐结构示例

<SxTabPanel Id="blazor-group" Label="Blazor" ContentPadding="var(--sx-spacing-md) 0">
    <SxStack Orientation="StackOrientation.Vertical"
             Gap="ControlSize.Large"
             HorizontalAlignment="HorizontalAlignment.Stretch">
        <WorkbenchScenarioGroup Title="基础使用场景"
                                Effect="@RenderBasicEffect"
                                Code="@_basicCode"
                                Language="razor" />
        <WorkbenchScenarioGroup Title="状态与异常场景"
                                Effect="@RenderStateEffect"
                                Code="@_stateCode"
                                Language="razor" />
        <WorkbenchScenarioGroup Title="组合与高级场景"
                                Effect="@RenderAdvancedEffect"
                                Code="@_advancedCode"
                                Language="razor" />
    </SxStack>
</SxTabPanel>

关键布局约定

  • 场景卡片：WorkbenchScenarioGroup 内部使用 SxCard，默认全宽。
  • Tabs 内容区内边距：通过 SxTabPanel.ContentPadding 控制（推荐 var(--sx-spacing-md) 0）。
  • 内容区最小高度：通过 SxTabPanel.MinContentHeight 或 WorkbenchScenarioGroup.MinContentHeight 控制（推荐 6rem）。
  • 效果区：内容超出时允许撑开（不设 max-height）。
  • 代码区：内容超出时滚动（通过 SxCodeSnippet 的 MaxHeight/Scrollable 控制）。

代码片段规范

  • _htmlSnippet：可读 HTML 或 sx-* 标签示例。
  • _currentCode：完整 Blazor 示例，能直接复制使用。
  • _configSnippet：若无可省略，但必须明确说明空值行为。

样式与布局约束

  • 禁止内联样式：除非已获批准（与 .cursorrules 2.3 对齐）。
  • 优先使用 SxStack / SxGrid / SxSpacer 等布局组件，避免手写布局。
  • 若确需样式补充，请落在 .razor.css 并使用 Design Tokens。

改造指引（现有页面）

  1. 对齐页面头部结构（标题 + 描述）。
  2. 补齐 SxComponentPlayground 所有标准字段。
  3. 明确 Inspector 分组与字段类型。
  4. Showcase 至少 2～3 个典型场景。
  5. 同步更新 _htmlSnippet / _currentCode 内容。

审核清单（提交前自查）

  • 路由名称与组件名一致。
  • 标题与说明清晰、简短。
  • Playground 可交互，Inspector 同步渲染。
  • Showcase 展示 2～3 个典型场景。
  • 代码片段可直接复制使用。
  • 无内联样式或已获批准。