页面装修开发

BBC 8.0 不再维护独立的 manager-decor 应用。页面装修能力集中在 packages/decor，由 Admin、Seller 和买家 PC 端按不同入口使用。

包入口与职责

入口	使用方	内容
`@shop-tnt/decor`	类型或纯工具调用方	装修类型、数据标准化和返回通知等轻量能力
`@shop-tnt/decor/editor`	Admin、Seller	完整装修编辑器与编辑器样式，按路由懒加载
`@shop-tnt/decor/pc-preview`	买家 PC	PC 预览渲染器、固定区块和数据标准化，不包含编辑器

不要从包根入口间接引入编辑器，也不要让买家 PC 端直接依赖 editor、setting 或 normal 组件。入口拆分用于避免前台构建加载完整装修运行时。

目录结构

packages/decor/
├── api/                         # 装修页接口
├── components/
│   ├── accessory/               # 编辑器附加面板
│   ├── normal/                  # 选择器、上传、富文本等编辑器组件
│   ├── setting/                 # 配置协议对应的表单控件和 registry
│   └── decor/
│       ├── pc/                  # PC 装修模块
│       └── mobile/              # 移动端装修预览模块
├── editor/                      # Admin/Seller 编辑器入口
├── runtime/                     # provide/inject 运行时上下文
├── store/                       # 编辑器状态
├── types.ts                     # 模块、设置项与适配器类型
├── index.ts                     # 轻量根入口
└── pc-preview.ts                # 买家 PC 专用预览入口

mobile 目录在本仓库中只负责装修编辑器的移动端预览，不代表当前 PC UI 工程包含移动端应用。涉及真正的移动应用，需要单独使用对应版本的移动端源码。

编辑器路由

Admin 和 Seller 都注册隐藏路由：

/decor/:clientType/:mode?

对应 route name 为 DecorEditor。组件映射按端注入 ownerType：

DecorEditor: {
  component: () => import('@shop-tnt/decor/editor'),
  props: route => ({
    ownerType: 'admin',
    clientType: route.params.clientType,
    mode: route.params.mode
  }),
  meta: { bare: true }
}

Seller 使用 ownerType: 'seller'。编辑器路由通过 backNames: ['pcPages', 'mobilePages'] 跟随装修页面入口授权，不应出现在后端可见菜单中。

新增装修模块

PC 和 mobile 模块都采用独立目录。以 PC 的 PromoBanner 为例：

packages/decor/components/decor/pc/PromoBanner/
├── index.ts
└── PromoBannerPreview.vue

index.ts 声明模块协议：

import type { DecorModuleConfig } from "@shop-tnt/decor/types";
import SettingTypes from "@shop-tnt/decor/utils/setting-types";
import { translateText } from "@shop-tnt/utils/i18n";

export default {
  name: "promo-banner",
  label: {
    title: translateText("促销横幅"),
    limit: 1,
  },
  sort: 20,
  data: {
    title: "",
  },
  settings: {
    title: {
      type: SettingTypes.input,
      label: translateText("标题"),
    },
  },
  layout: {
    width: "content",
  },
} satisfies DecorModuleConfig;

配置的核心字段：

字段	说明
`name`	保存到装修数据中的稳定模块名，使用 kebab-case。
`aliases`	当前只参与布局识别，不会自动注册 PC/mobile Preview。
`label`	编辑器模块标题、图标、数量限制和显示状态。
`sort`	左侧模块库排序。
`data`	新模块的完整默认数据。
`settings`	默认设置面板协议。
`decor_type`	兼容旧数据的 owner 过滤字段，可限制 admin 或 seller。
`layout.width`	PC 模块使用 `content` 内容区或 `public` 通铺布局。
`validate`	跨字段或结构化数据的模块级校验。

简单展示模块可以只创建目录和 XxxPreview.vue，发现器会从目录名生成基础配置；需要中文标题、默认数据、设置项、owner 限制或稳定排序时必须提供 index.ts。

编写预览组件

预览组件通过装修运行时读取模块数据和宿主能力，不再依赖旧全局 mixin：

<script setup lang="ts">
import { useDecorRuntimeBindings } from "@shop-tnt/decor/runtime/context";
import { useTranslate } from "@shop-tnt/components/useTranslate";

defineOptions({ name: "PromoBannerPreview" });

const decor = useDecorRuntimeBindings();
const t = useTranslate();
</script>

<template>
  <section class="promo-banner">
    <h2>{{ decor.formData.title || t("促销横幅") }}</h2>
  </section>
</template>

PC 和 mobile 的 preview registry 都通过 import.meta.glob 自动发现 **/*Preview.vue，并根据目录名、文件名和组件 name 建立映射。moduleConfig.aliases 不会自动进入这两个 registry，因此模块 name、目录和 Preview 名归一化后必须一致。不要再手工复制组件到买家应用，也不要注册全局组件。

设置项协议

当前基础 type 包括：

input、boolean、radio-button、color-picker。
switch、slider、select。
image、video、link、goods、imageLinkEditor。
custom。

常用设置字段包括 label、props、options、show、disabled、space_line、column、component_name、optionsChange 和 validation。默认值必须同时存在于模块 data，不能依赖表单控件第一次渲染时补值。

新增自定义面板不能依赖文件名自动成为全局组件：

模块级 XxxSetting.vue 需要在 components/setting/block-setting-registry.ts 显式登记。
type: custom 的 component_name 需要在 custom-setting-registry.ts 显式登记。
新增一种基础 setting type 需要在 setting-control-registry.ts 显式登记。

block setting 和 custom setting registry 必须按 pc、mobile 分端，避免同名设置组件串端。setting-control-registry.ts 是基础控件的共享映射，不需要机械拆成两份。

移动预览单位

只有 packages/decor/components/decor/mobile/**/*.vue 会经过 rpx 转换插件。设计基准为 750rpx，编辑器预览宽度为 375px，因此当前换算为 1rpx = 0.5px。

<div :style="{ marginLeft: decor.formData.margin_left + 'rpx' }" />

不要在普通 PC、Admin 或 Seller 页面使用 rpx，也不要把多个动态值写进无法稳定转换的样式缩写。

业务适配边界

共享装修组件只负责渲染。购物车、收藏、登录校验和客服打开方式由宿主通过适配器传入，例如 DecorCartAdapter 和 DecorShopActionsAdapter。不要在 packages/decor 中直接导入 apps/pc 的 store、路由或业务 API。

同样，装修模块需要图片、商品、链接选择能力时，应使用 runtime bindings 或现有 normal/setting 组件，不能自行创建上传客户端或硬编码端域名。

验证

修改装修模块会影响共享包、后台编辑器和 PC 展示端，至少执行：

pnpm typecheck
pnpm build:dev

视觉与数据验收包括：

Admin 与 Seller 的模块可见性符合 decor_type 和入口权限。
PC/mobile 编辑器预览可以新增、编辑、保存并重新加载模块。
PC 买家端通过 @shop-tnt/decor/pc-preview 正确渲染保存数据。
未识别历史模块不会导致整页崩溃，兼容别名命中预期组件。
缺少必填值或结构错误时，编辑器给出可定位的校验提示。
PC 前台产物没有意外引入完整 editor runtime。
mobile 预览单位、图片、链接和自定义设置在 375px 预览中表现正确。

页面装修开发

包入口与职责​

目录结构​

编辑器路由​

新增装修模块​

编写预览组件​

设置项协议​

移动预览单位​

业务适配边界​

验证​