marketplace-build-component

使用 Blok Design System 构建 UI

你正在帮助用户使用 Blok 设计系统（Sitecore 基于 shadcn 的组件库）为 Sitecore Marketplace 应用构建 UI 组件。

核心原则

1. 始终使用 Blok 组件 — 它们与 Sitecore 宿主 UI 匹配，并自动支持浅色／深色主题
2. SDK 数据集成 — 获取 SDK 数据时使用加载状态（Skeleton）和错误状态（Alert）
3. 了解扩展点限制 — 不同的扩展类型有不同的 UI 限制（见下文）
4. 响应式 — 组件会在尺寸各异的 iframe 中渲染

安装组件

通过 shadcn CLI 安装 Blok 组件：

# Install the Blok theme (required first)
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/blok-theme.json

# Install individual components
npx shadcn@latest add https://marketplace-sdk.sitecorecloud.io/r/<component-name>.json

请参阅 blok-components.md，了解完整的组件目录和安装命令。

不同扩展类型的 UI 模式

紧凑字段（custom-field）

• 空间非常有限（宽约 300px，高度可变）
• 使用：Input、Select、Badge、小型内联组件
• 避免：表格、大型布局、模态框

仪表板小组件

• 中等空间（默认约 400x300px，可调整大小）
• 使用：卡片、图表、统计信息、紧凑表格
• 适用于：汇总数据、快捷操作

Pages 上下文面板

• 侧边面板（宽约 350px，高度占满）
• 使用：垂直布局、列表、Accordion、Tabs
• 适用于：当前页面的上下文信息、操作

全屏

• Sitecore shell 内的整个视口
• 使用：任何组件、复杂布局、表格、表单
• 适用于：完整的 CRUD 界面、仪表板、设置

独立页面

• 独立页面，不在 Sitecore shell 中
• 使用：任何组件，完全自由发挥
• 适用于：面向公众的页面、OAuth 回调

SDK 数据集成模式

"use client";

import { useEffect, useState } from "react";
import { useMarketplaceClient, useAppContext } from "@/components/providers/marketplace";
import { Skeleton } from "@/components/ui/skeleton";
import { Alert, AlertDescription } from "@/components/ui/alert";

export function MyComponent() {
  const { client } = useMarketplaceClient();
  const appContext = useAppContext();
  const [error, setError] = useState<string | null>(null);

  const loading = !appContext;

  if (loading) return <Skeleton className="h-32 w-full" />;
  if (error) return <Alert variant="destructive"><AlertDescription>{error}</AlertDescription></Alert>;

  return <div>{/* Render data */}</div>;
}

参考文件

• Blok 组件 — 完整的组件目录和安装命令