Experience Cloud | LWC | Salesforce CRM 中文站

Experience Cloud 站点

为 Aura 和 LWR 站点创建自定义 LWC。添加自定义属性类型和属性编辑器——给 Experience Builder 用户流畅的站点构建体验。支持三种 target 类型：拖放组件（Page）、页面布局组件（Page_Layout）、主题布局组件（Theme_Layout）。

配置组件以支持 Experience Builder —— Targets 与属性

配置文件四步：

isExposed=true + 在 targets 中添加三种 target 之一：
- lightningCommunity__Page —— Components 面板中的拖放组件
- lightningCommunity__Page_Layout —— LWR 站点的页面布局组件（Content Layout 窗口）
- lightningCommunity__Theme_Layout —— LWR 站点的主题布局组件（Settings → Theme）
lightningCommunity__Default 在 targets + targetConfigs 中定义可编辑属性——仅 Page 和 Page_Layout 的属性在 Builder 中可编辑
LWR 响应式属性：screenResponsive="true" + exposedTo="css" → CSS 变量 + 媒体查询 + Builder 中按屏幕尺寸设值
可选 SVG 图标：componentName.svg 放在组件文件夹——每文件夹仅一个

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle>
  <isExposed>true</isExposed>
  <targets>
    <target>lightningCommunity__Page</target>
    <target>lightningCommunity__Default</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightningCommunity__Default">
      <property name="string" type="String" default="jsMetaValue"/>
      <property name="boolean" type="Boolean" default="true"/>
      <property name="integer" type="Integer" default="5"/>
      <property name="picklist" type="String" default="value3" datasource="value1,value2,value3"/>
      <property name="backgroundColor" type="Color" default="#ff00ff"/>
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>

SVG 图标、CSP 与配置变更限制

SVG 图标：默认使用通用图标——添加 componentName.svg 获得自定义图标。

CSP 考量：新站点默认严格 CSP——引用第三方资源需在 Builder 中配置安全级别和 allowlist。托管包中未配置 lightningCommunity__RelaxedCSP 标签的 LWC 在禁用 Locker 的站点中被禁用。

js-meta.xml 变更限制（站点或托管包中已使用的组件）：

不能新增 required=true 的 property
不能删除已有 property
不能给已有 property 加 required=true（除非本来就 required）
不能移除 required=true + 有默认值的属性的默认值
min/max 限制：不能新增 min/max → 已有 min 不能增大 → 已有 max 不能减小

重要：这些严格限制不可逆——确保组件生产就绪后再加入托管包。仅在站点中使用时：先从站点移除组件 → 更新 → 重新部署 → 加回站点。

自定义属性类型与编辑器 —— 为什么需要及决策框架

无自定义编辑器时，属性编辑仅限于文本框和下拉菜单等几种字段类型。自定义编辑器可创建颜色选择器、滑块等更直观的编辑器。

以 Custom Article 组件示例：三个属性需要不同的处理方式：

articleDate：用标准 lightning_dateType——自带的日期选择器已满足需求
textAlignment：默认编辑器是 combobox——你希望用按钮组直观展示对齐选项 → 需自定义编辑器
layoutProperties：默认 lightning__objectType 编辑器是垂直布局——你希望分标签页展示、下拉选项显示不同标签 → 需自定义类型 + 自定义编辑器 + editor.json 定义布局

决策流程：① 需要什么数据验证？→ 标准类型足够还是自定义类型？② 需要什么编辑体验？→ 标准编辑器满足还是自定义编辑器？③ 每个属性按此二步分析。

自定义类型/编辑器的考量与限制

核心限制：仅限自定义 LWC + lightningCommunity__Default target。不能用于 Page_Layout/Theme_Layout 或其他不相关 target——部署失败。属性引用自定义类型时不能指定 datasource/max/min/placeholder。

screenResponsive 属性 + 自定义编辑器：可设 screenResponsive="true" 但响应式图标不自动出现在属性标签旁——需手动添加。

LightningTypeBundle vs 旧版 ExperiencePropertyTypeBundle：旧版需迁移到 LightningTypeBundle。LightningTypeBundle 支持更新（无破坏性变更时即使被站点/包引用也可更新）但不支持自定义布局——旧版自定义布局需替换为标准布局。

Setup UI 限制：某些功能未在 Lightning Types Setup UI 中暴露——通过 Metadata API 部署的不支持功能需继续用 Metadata API 更新。

无效编辑器/类型 → Builder 属性面板显示错误消息 → 浏览器控制台查看详情。

属性验证与编辑器决策

验证需求决定类型：

需要日期验证 → 标准 lightning_dateType 已提供
无验证需求 → 直接用 <property type="String"> 无需自定义类型
需要复合验证（多属性+结构） → lightning__objectType 创建包含多个子属性的自定义类型

编辑体验决定编辑器：检查每种属性类型的默认编辑器——是否满足体验需求？不满足→创建自定义编辑器。参考 Lightning Types Reference 查看各标准类型的默认编辑器截图。

Custom Article 示例决策结果：一个自定义类型（layoutProperties）+ 两个自定义编辑器（textAlignment + layoutProperties）+ 一个 editor.json 定义标签页布局。

高层构建指南与 LightningTypeBundle

Custom Article 示例需要创建的元素：

articleDate：引用标准 Lightning 类型 lightning__dateType
textAlignment：创建自定义编辑器 alignmentCPE
layoutProperties：创建自定义类型 layoutProperty（LightningTypeBundle）+ 自定义编辑器 borderStyleDropdownCPE + editor.json 定义标签页布局

创建 LightningTypeBundle（自定义属性类型）

仅支持object-based 自定义类型（不支持 Apex-based）。嵌套属性只允许 9 种标准 Lightning 类型：booleanType/dateType/dateTimeType/integerType/multilineTextType/numberType/richTextType/textType/urlType。不能用自定义类型嵌套自定义类型（如 c__layoutProperty 作子属性）。

// schema.json——定义数据类型和验证
{
  "title": "Layout Properties",
  "lightning:type": "lightning__objectType",
  "properties": {
    "borderStyle": { "lightning:type": "lightning__textType", "title": "Border Style" },
    "borderWeight": { "lightning:type": "lightning__integerType", "title": "Border Weight (px)" },
    "borderRadius": { "lightning:type": "lightning__integerType", "title": "Border Radius (px)" },
    "layoutHeight": { "lightning:type": "lightning__integerType", "title": "Layout Height (px)" },
    "layoutWidth": { "lightning:type": "lightning__integerType", "title": "Layout Width (px)" }
  },
  "required": []
}

创建自定义编辑器

LWC 组件实现属性编辑器合约。js-meta.xml 必须包含 lightning__PropertyEditor target。接收 @api 属性：value/label/schema/errors/description/required。派发 valuechange 事件（非 propertychange——注意名称！）。

使用流程

创建类型（如有）→ 创建编辑器（如有）→ 在组件 js-meta.xml 中引用：type="c__layoutProperty" 或 editor="c/alignmentCPE"。自定义类型名必须以 __ 为前缀。引用自定义类型的属性不能用 editor 属性直接指定编辑器——需通过 editor.json 的 componentOverrides。

标准布局定义 —— verticalLayout 与 accordionLayout

editor.json 中布局由布局定义树组成——每个节点有 definition（布局类型）和 children（子节点）。属性节点用 lightning/propertyLayout + attributes.property 引用子属性名。

verticalLayout —— 垂直堆叠

属性按定义顺序从上到下排列。只能包含 lightning/propertyLayout 子节点：

{
  "editor": {
    "layout": {
      "definition": "lightning/verticalLayout",
      "children": [
        { "definition": "lightning/propertyLayout", "attributes": { "property": "borderStyle" } },
        { "definition": "lightning/propertyLayout", "attributes": { "property": "borderWeight" } },
        { "definition": "lightning/propertyLayout", "attributes": { "property": "borderRadius" } }
      ]
    }
  }
}

accordionLayout —— 可折叠手风琴

属性分组在可折叠分区中——点击标题展开/折叠。只能包含 lightning/accordionSectionLayout 子节点（每节含 label 属性）：

{
  "editor": {
    "layout": {
      "definition": "lightning/accordionLayout",
      "children": [
        { "definition": "lightning/accordionSectionLayout", "attributes": { "label": "Borders" },
          "children": [
            { "definition": "lightning/propertyLayout", "attributes": { "property": "borderStyle" } }
          ]
        },
        { "definition": "lightning/accordionSectionLayout", "attributes": { "label": "Size" },
          "children": [ /* layoutHeight, layoutWidth */ ]
        }
      ]
    }
  }
}

标准布局 —— tabSetLayout 与层次总结

tabSetLayout：属性组织在标签页中——每个标签页显示不同属性组。Custom Article 示例中 layoutProperties 的边框样式/粗细/圆角分三个标签页展示。

布局层次架构：顶层 → tabSetLayout（标签页）→ 每个标签页内 → verticalLayout 或 accordionLayout → 每个 item 引用一个属性 → 属性关联编辑器。

关键：属性名必须在 component 的 js-meta.xml 和 editor.json 中一致。

创建自定义属性编辑器 —— 合约与模式

自定义属性编辑器是一个实现属性编辑器合约的 LWC。属性面板（Property Sheet）将相关信息注入每个编辑器组件。

完整合约接口

interface PropertyEditorContract {
  label: string;         // 属性标签
  description: string;   // 提示描述
  required: boolean;     // 是否必填
  value: any;            // 当前属性值（String/Boolean/Integer/Object）
  errors: PropertyError[];  // 验证错误数组 [{ message: string }]
  schema: JSONSchema;    // 属性类型的 JSON Schema
}

输出——派发 valuechange 事件：用户修改值→派发 new CustomEvent("valuechange", { detail: { value: this.value } })。属性面板验证值→持久化到 Builder 画布。验证错误通过 errors 属性注回编辑器。注意事件名是 valuechange 不是 propertychange！

export default class AlignmentCPE extends LightningElement {
  @api value; @api label; @api schema; @api errors;

  handleAlignmentClick(event) {
    const value = event.target.value;
    this.value = value;
    this.dispatchEvent(new CustomEvent("valuechange", { detail: { value: this.value } }));
  }
}

五大指南（避免常见错误）

不要用编辑器验证用户输入：编辑器只负责发送原始值——属性面板根据类型 schema 验证。不要自己设 errors 或跳过 valuechange
不要创建弹出层/模态框：飞窗、弹窗、窗口覆盖会打断 Builder 用户编辑体验
不要用 CSS 绝对定位：position: absolute 行为不稳定——可能导致元素错位
不要设置 CSS width 属性：影响 Builder 属性面板宽度——导致 UX 问题
不要频繁触发 valuechange：每次触发→画布刷新。绑定到提交型事件（如 blur）而非连续事件（keydown/mousemove）——避免每秒数十次刷新拖慢 Builder

js-meta.xml 必需 target：<target>lightning__PropertyEditor</target>。支持的 @salesforce 模块：@salesforce/community/Id、@salesforce/community/basePath、@salesforce/site/Id。

属性编辑器 —— UI、XML 配置与指南

在 js-meta.xml 中引用编辑器：<property name="alignment" type="String" editor="c__alignmentEditor"/>——editor 属性值指向编辑器组件的命名空间+名称。

编辑器 UI 设计指南：

使用 SLDS 样式保持一致外观
提供清晰的视觉反馈（当前值/选中状态）
处理空值和默认值
响应 required 属性——显示必填指示
label 属性作为编辑器标题——不要硬编码标签

按钮组编辑器示例：三个对齐按钮（左/中/右）→ 当前值高亮 → 点击派发 propertychange。处理初始 null 值——默认选中某个对齐方式。

引用类型、编辑器与属性特性

引用自定义编辑器（editor 属性）：直接用 editor="c/alignmentCPE"——适合只需覆盖默认 UI、无需额外验证的场景。但引用自定义类型的属性不能用 editor 属性——需在 editor.json 的 componentOverrides 中指定："componentOverrides": { "borderStyle": { "definition": "c/borderStyleDropdownCPE" } }。

引用标准类型（type 属性）：type="lightning__dateType"——直接使用标准 Lightning 类型。引用自定义类型：type="c__layoutProperty"——可在 property 定义中覆盖 label/description（覆盖 schema.json 中的 title）。

属性特性完整清单与考量：

属性	说明
screenResponsive	指示属性是否屏幕响应——仅 LWR 站点。需同时设 `exposedTo="css"`。仅底层 JSON schema 为 string/integer/number 的自定义类型可用
translatable	设为 true→属性可持不同语言的不同值。仅底层 JSON schema 为 string 的自定义类型可用。richTextType 导出为富文本 .xlf 格式
type	支持 5 种标准类型（String/Integer/Boolean/ContentReference/Color）或标准/自定义 Lightning 类型。引用旧版 ExperiencePropertyTypeBundle 可更新为 LightningTypeBundle（需确保 schema 无破坏性变更）

editor.json 完整结构（Custom Article layoutProperties 示例）

{
  "editor": {
    "componentOverrides": {              // 覆盖默认编辑器
      "borderStyle": { "definition": "c/borderStyleDropdownCPE" }
    },
    "layout": {                           // 定义属性面板布局
      "definition": "lightning/tabSetLayout",
      "children": [
        { "definition": "lightning/tabLayout", "attributes": { "label": "Borders" },
          "children": [
            { "definition": "lightning/propertyLayout", "attributes": { "property": "borderStyle" } },
            { "definition": "lightning/propertyLayout", "attributes": { "property": "borderWeight" } },
            { "definition": "lightning/propertyLayout", "attributes": { "property": "borderRadius" } }
          ]
        },
        { "definition": "lightning/tabLayout", "attributes": { "label": "Size" },
          "children": [ /* layoutHeight, layoutWidth */ ]
        }
      ]
    }
  }
}

XML 转义、测试与迁移

XML 转义：editor.json 和 type.schema.json 中包含特殊字符时需正确转义——特别是 JSON 中的引号和反斜杠在 XML 属性值中的处理。

测试编辑器：在 Experience Builder 中实际使用——选择属性值→保存→刷新页面→确认值保留。在组件 JS 的 connectedCallback 中 log 属性值验证。检查错误消息——面板中显示或控制台中查看。

从 ExperiencePropertyTypeBundle 迁移到 LightningTypeBundle 六步：

创建新 LightningTypeBundle（不同名称）
复制 schema.json 到新 Bundle
如有 design.json→创建 editor.json：propertySheet→editor、propertyRenderers→componentOverrides、view→layout
更新组件 js-meta.xml 的 type 属性指向新 Bundle
部署新 Bundle + 更新组件
非托管包→用 destructiveChanges.xml 删除旧 Bundle

JSON 转换对照：旧版 {"propertySheet":{"propertyRenderers":{...},"view":{...}}} → 新版 {"editor":{"componentOverrides":{...},"layout":{...}}}。后续更新无破坏性变更时即使被站点/包引用也可直接更新。但注意 LightningTypeBundle 不支持旧版中的自定义布局——需替换为标准布局。

感谢阅读本指南。如需继续学习，请参阅下一章：Flows。

Experience Cloud 站点 — LWC Experience Builder 完全指南