sfnext-page-designer

用途

sfnext-page-designer 是 Storefront Next 中集成 Page Designer 的技能，用于构建商家可编辑的页面。Page Designer 是 Commerce Cloud 面向商家的可视化编辑器。在 Storefront Next 中，页面结构（区域、组件、属性）从 Shopper Experience API 获取，并通过组件注册表和 <Region> 组件渲染。

主要能力

该技能涵盖以下核心概念：

Page（页面）：在路由 loader 中通过 fetchPageFromLoader(args, { pageId }) 获取。
Region（区域）：使用 <Region page={...} regionId="..." /> 渲染的命名区域。
Component（组件）：带有 typeId 和属性的内容块，注册在 @/lib/registry 中。
Registry（注册表）：由 Vite 插件自动生成的静态注册表，请勿手动编辑。

哪些页面使用 Page Designer：首页（homepage）、分类/PLP、搜索、产品/PDP。不使用 Page Designer 的页面：购物车、结账、账户、认证。

使用方式

路由设置

在 Loader 中：

import { fetchPageFromLoader, collectComponentDataPromises } from '@/lib/page-designer';

export function loader(args: LoaderFunctionArgs) {
    const pagePromise = fetchPageFromLoader(args, { pageId: 'homepage' });
    const componentData = collectComponentDataPromises(args, pagePromise);

    return {
        page: pagePromise,
        componentData,
    };
}

在 Layout 中：

import { Region } from '@/components/region';

export default function HomePage({ loaderData: { page, componentData } }) {
    return (
        <div>
            <Region page={page} regionId="hero" componentData={componentData}
                fallbackElement={<HeroSkeleton />}
                errorElement={<RegionError />} />

            <Region page={page} regionId="content" componentData={componentData}
                fallbackElement={<ContentSkeleton />} />
        </div>
    );
}

组件设置

使用装饰器的元数据类：

import { Component, AttributeDefinition, RegionDefinition } from '@salesforce/storefront-next-runtime/design';

@Component('hero-banner', {
    name: 'Hero Banner',
    description: 'Full-width banner with image and CTA'
})
class HeroBannerMeta {
    @AttributeDefinition({ type: 'image' })
    image: string;

    @AttributeDefinition()
    headline: string;

    @AttributeDefinition({ type: 'url' })
    ctaUrl: string;

    @AttributeDefinition()
    ctaText: string;

    @AttributeDefinition({ type: 'boolean' })
    fullWidth: boolean;
}

React 组件：

export default function HeroBanner({ image, headline, ctaUrl, ctaText, fullWidth }) {
    return (
        <div className={cn('relative', fullWidth && 'w-full')}>
            <DynamicImage src={image} alt={headline} />
            <h1>{headline}</h1>
            {ctaUrl && <a href={ctaUrl}>{ctaText}</a>}
        </div>
    );
}

带服务端数据的组件

如果组件需要服务端数据（例如产品轮播）：

// Export a loader for the component
export function loader({ componentData, context }) {
    const clients = createApiClients(context);
    return clients.shopperProducts.getProducts({
        params: { query: { ids: componentData.productIds } }
    }).then(({ data }) => data);
}

// Optional fallback during loading
export function fallback() {
    return <CarouselSkeleton />;
}

// Component receives data as prop
export default function ProductCarousel({ data, ...props }) {
    return <Carousel products={data.products} />;
}

设计模式

检测是否在 Page Designer 内运行：

import { isDesignModeActive, isPreviewModeActive } from '@salesforce/storefront-next-runtime/design/mode';

// In loaders
const isDesignMode = isDesignModeActive(request);
const isPreview = isPreviewModeActive(request);

// Root layout exposes pageDesignerMode in loader data
// 'EDIT' | 'PREVIEW' | undefined

MCP 工具

使用 B2C DX MCP 服务器工具进行 Page Designer 开发：

storefront_next_page_designer_decorator — 为组件添加装饰器（自动模式或交互模式）
storefront_next_generate_page_designer_metadata — 为 Business Manager 生成元数据 JSON
cartridge_deploy — 将 cartridge 部署到 Commerce Cloud

典型工作流

为组件添加装饰器（使用 storefront_next_page_designer_decorator 的 autoMode）
生成元数据 JSON（storefront_next_generate_page_designer_metadata）
部署 cartridge（cartridge_deploy）

适用场景

适用于在 Storefront Next 中构建商家可编辑的页面，包括首页、分类/PLP、搜索、产品/PDP 等页面。

限制与最佳实践

保持 loader 同步 — 返回 promise 以支持流式传输。
使用注册表 — 用正确的 typeId 注册组件。
处理设计模式 — 当 pageDesignerMode 为 'EDIT' 或 'PREVIEW' 时调整 UI。
更改后重新构建 — 静态注册表在构建时重新生成。
使用 MCP 工具 — 比手写装饰器和元数据更快。

相关技能：storefront-next:sfnext-data-fetching（Page Designer 路由的 Loader 模式）、storefront-next:sfnext-components（组件开发模式）、b2c:b2c-page-designer（经典 ISML Page Designer，非 Storefront Next）。

参考文档：Decorator Patterns Reference（所有装饰器类型和选项）、Component Registry Reference（注册表设置和组件 loader）。