DEX475

课程介绍

同学们，今天我们来聊聊，怎么给 Experience Builder 网站创建自定义的 Lightning Web 组件。这个内容看起来有点多，别担心，我会慢慢讲清楚，就像讲故事一样，让你一听就懂。 首先，Experience Builder 就是咱们建站的那个拖拽工具。你做的自定义组件，要想能在里面拖来拖去，就得告诉平台：我这个组件能放在哪儿、能干什么。这个秘密就藏在组件的配置文件 `.js-meta.xml` 里。在文件里，你可以配置几个重要的“目标”，也就是 target。比如，你写个组件只想展示在某个页面上，那就用 `lightningCommunity__Page` 这个目标，这样它就能被拖到任意页面里了。如果你想做一个布局组件，用来控制页面的结构，比如左右分栏，那就要指定 `Page_Layout` 目标。要是你想做一套主题皮肤，让站点整体换风格，那就用 `Theme_Layout` 目标。最后还有一个叫 `Default` 的目标，它表示这个组件有一些属性可以在属性面板里直接修改，比如文字颜色、背景图什么的。这四种目标，基本覆盖了你在建站时拖拽组件的所有场景。 接下来，你会发现有些时候，自带的属性编辑界面太简单了。比如你想让用户选颜色用色盘、上传图片有预览，那就要用到“丰富的属性编辑”能力。这就要靠一个叫 `LightningTypeBundle` 的东西。它不是单一的组件，而是一个捆绑包，里面有两个核心文件：`schema.json` 和 `editor.json`。schema 文件用来定义这个属性的数据类型和结构，editor 文件则指定用哪个自定义编辑器来编辑它。自定义编辑器本身也是一个 Lightning Web 组件，只不过它要遵守一套属性编辑器契约，说白了就是实现约定的接口方法，让平台知道你如何收发值。这样，你的组件属性面板就能出现一个漂亮的专用编辑器，用户体验一下子就不一样了。 可能有同学会问，如果我的属性很多，有层级，怎么办？别急，咱们还可以用“标准布局定义”来组织复杂的属性表。就是把属性按分组、分区排列好，让管理员在配置时一目了然。你只需要在组件里引用编辑器属性去指定用哪个自定义编辑器，再用类型属性去绑定你定义的那个自定义属性类型，一切就串联起来了。 还有一点要特别提醒，如果你以前的项目里用过旧版的 `Legacy ExperiencePropertyTypeBundle`，现在必须要迁移到新的 `LightningTypeBundle` 模式。因为老的方式已经不推荐了，未来可能会被移除，所以趁现在赶紧换过来。迁移的原理就是把老的属性定义转成新的 schema 和 editor 组合。 最后，我们再来回顾一下整个开发生命周期：你创建组件，写好 `.js-meta.xml` 设好目标；如果需要增强编辑体验，就创建 `LightningTypeBundle` 做自定义属性类型，并开发编辑器组件；接着用标准布局把属性编排清爽；然后就可以在站点里拖拽使用，调整属性，看效果。整个过程就是设计、开发、配置、部署，一步步来，就像搭积木一样。 好了，今天关于 Experience Builder 自定义组件的核心就讲这么多。记住，关键是配置目标和自定义属性编辑，这样你能做出既强大又好用的站点组件。下节课我们更深入探讨每一步的细节，大家先消化一下这些概念，有问题的随时问我。

课程章节

本课程共有 12 个章节

• 1

  Configure for Experience Builder — Targets & Properties

  第 330 页

  好，今天我们来看一个很关键的小文件——`.js-meta.xml` 配置文件。这个文件就像是你的组件在 Experience Builder 里的身份证，Builder 全靠它来认识你的组件，决定它能在哪儿出现、能接收哪些属性。 首先，它定义了三种目标类型，也就是你的组件可以出现在三种不同的地方。第一种是 `page` 目标，这是最常见的，它让你组件出现在 Builder 左侧的组件面板里，用户可以像拖积木一样把它拖到页面上去。第二种叫 `Page_Layout` 目标，专门给内容布局那个窗口用的，通常是用在 LWR 布局组件里。第三种是 `Theme_Layout`，用在设置里的主题布局，同样也是针对 LWR 主题的组件。所以，你这个组件想在哪里被使用，就要在配置文件里指明对应的目标类型。 还有一个特别重要的事情——，必须包含默认目标，。什么意思呢？就是哪怕你只把这组件用在某个特定地方，你也得给属性面板一个“默认”的入口。如果没有这个默认目标，Builder 的属性面板上就根本不会出现你定义的可编辑属性，等于你白写了属性定义，用户也就没法在界面上调整你的组件。 接下来看属性类型。标准属性类型有几种：字符串、数字、布尔、颜色，还有一个叫内容参考的。内容参考可以用来链接另一块内容，比如链接到一个页面或图片。如果你想做一个下拉选择框，给用户几个选项选一选，那就得用 `收件箱` 属性来模拟。做法是在属性里加 `inbox="option1,option2,option3"`，逗号分隔选项值，这样 Builder 就会为你生成一个选择列表。而且，收件箱属性还能带上最小和最大长度的限制，来控制输入或选项的范围。 最后，如果你在开发 LWR 网站，有两个很酷的配置项要记住：一个是 `screenResponsive=true`，另一个是 `exposedTo=css`。打开这个之后，Builder 的属性面板就能感知不同的屏幕尺寸了。比如你定义了一个颜色或文本属性，用户可以分别设置它在桌面、平板、手机上的值。背后其实是靠 CSS 自定义属性和媒体查询在起作用，但这个配置省去了你手写媒体查询的麻烦，直接在 Builder 里就能针对每个视图模式填入不同的值。界面会自动为每个模式显示独立的属性框，非常方便。 所以，`.js-meta.xml` 这个小小的配置文件，其实是 Experience Builder 集成的中央控制点。目标类型决定组件出现在哪里，默认目标决定了属性能不能被看见，属性类型决定了用户能输入什么，而 LWR 的响应式设置更是把多设备适配变得非常简单。记得每次新建组件时，都要认真写好这个文件哦。

  ▶ 播放视频 查看详情
• 2

  SVG Icons, CSP & Configuration Change Restrictions

  第 331 页

  好，同学，咱们今天讲几个Lightning Web Components里重要但容易被忽略的小细节，特别关系到你以后打包和部署组件时会不会踩坑。 首先说图标。你的组件在构建工具的“组件”面板里，是可以有个小图标的，让你一眼就认出来。这个图标是可选的，但我强烈建议你加上，团队协作时能省不少眼力。做法很简单：在你的组件文件夹里放一个SVG文件，名字跟组件名一致，比如myComponent.svg。记住，每个文件夹只要一个图标文件就行。 接下来是MPS安全，也就是移动端发布站点的安全策略。现在新创建的站点默认都是严格模式，就是说不允许随便加载外部的第三方资源。如果你的组件需要用到外部脚本或者样式，比如CDN上的库，就必须提前在站点的允许列表里明确声明，否则会报错。如果你是做托管包的，就是打包上架到AppExchange的，那么你的组件里必须加上一个叫lightningCommunity__RelaxedMPS的标签，这样即使在某些禁用了Lightning收件箱的特殊站点里，你的组件也能正常运行。 最后是今天最硬核的部分——BREAK部署组件的更改限制。什么是BREAK？就是你在组织里用元数据API部署组件之后，有些属性你再也不能随便改了，否则会破坏已经存在的组件实例。这个限制非常严格：你不能再给组件添加必填属性，不能删除任何已有的属性，也不能把现有的可选属性改成必填，还不能移除某个必填属性的默认值，更不能收紧属性的最小或最大长度等约束。为什么这么狠？因为每次一个有属性的组件被拖到页面上，就会保存当时的属性值；你这一改，那些老实例可能立刻失效，整个页面就崩了。对于只在站点里用的组件，还有一点回旋余地：你可以暂时把组件从页面移除，更新之后再加回来。但对于托管包里的组件，那就是永久的限制，一旦第一版发布出去，就改不了了。所以在首次发布之前，务必仔细规划好你的属性架构，别给自己留坑。 总结一下：图标虽小但实用，安全策略要配好，托管包别忘了那个标签，而属性一旦部署就锁死，前期设计要慎之又慎。这些点你记住了，打包上架就会顺畅很多。

  ▶ 播放视频 查看详情
• 3

  Custom Property Types & Editors — Why & Decision Framework

  第 332 页

  同学们，今天咱们来聊聊一个在实际开发中经常会遇到的问题：到底什么时候需要创建自定义的属性类型，什么时候又需要自定义属性的编辑器。 你可能会觉得有点绕，别着急，我们把它拆成两个独立的问题来看，就清楚了。 第一个问题，是关于，数据验证，的。也就是说，我们要确定这个属性应该接受什么样的值。在Salesforce里，已经有了一些标准的类型，比如日期类型、整数类型、文本类型等等。这些类型自带验证，能直接满足最常见的场景。但是，如果你需要做的验证比较特殊，比如要同时检查好几个字段的值，或者有一些独一无二的约束条件，那光靠标准类型就不够了。这个时候，你就需要用到自定义的LightningTypeBundle，通过在schema.json里定义验证规则来满足你的需求。 第二个问题，是关于，用户体验，的，也就是属性编辑器长什么样。就算类型确定了，编辑器也可能不一样。比如，日期类型默认给你一个日期选择器，可能就直接用了；但万一你觉得按钮组选择对齐方式更直观，或者想把属性按分组收进一个盒子里让界面更整洁，那就得自定义编辑器了。所以，用户体验的需求决定了你是用默认的编辑器，还是自己设计一个更顺手的。 为了让大家更容易理解，我们来看一个例子，它涵盖了三种常见的情况。 最简单的情况，比如articleDate这个属性，它直接用标准日期类型，编辑器也是默认的日期选择器，什么都不用额外做，省心省力。 稍微复杂一点的是textAlliance，它底层还是字符串类型，但我们不想让用户手动输入，而是提供一个按钮组来点选，那我们就只自定义了编辑器，类型保持标准字符串不变。 最复杂的是layoutProperties，它不仅需要自定义的类型来验证数据，还需要自定义的编辑器，而且编辑器还带有选项卡布局。这属于全都要自己动手的情况。 这些例子的代码，你都可以在Salesforce Experience Cloud的GitHub仓库里找到，一会儿可以去看看实际是怎么写的。 所以记住，要不要自定义属性和编辑器，就分两步想：一是验证要用标准类型还是自定义类型；二是编辑器要不要改得更顺手。这两步独立决定，思路就清晰了。 好了，这一块就讲到这里，大家有问题随时提。

  ▶ 播放视频 查看详情
• 4

  Considerations & Limitations for Custom Types/Editors

  第 333 页

  好，同学们，我们来聊聊Lightning Web Components里，关于自定义属性类型和编辑器，有几个必须要注意的限制。这些点很关键，不留意的话，部署可能会失败，或者在属性面板里只见一堆报错。 首先，记住一个核心：这些限制只对LWC有效，Aura框架不受影响。而且，在使用这些自定义属性时，你只能在目标配置里用`lightningCommunity__Default`，不能写成`Page_Layout`或者`Theme_Layout`，不然部署上去就直接报错。换句话说，它只服务于社区的默认页面，布局页或主题布局页不支持。 接下来，当你定义的属性类型指向自建的或Lightning自带类型时，你不能在属性上使用“最小值”、“最大值”、“步长”或者“占位文字”这些设置。为什么呢？因为这些约束应该预先定义在类型本身的架构里面，而不是在属性声明时随手加上去。 还有个小细节：如果你希望属性面板里出现屏幕响应图标，光靠自定义编辑器是自动出不来的，得你自己手动添加。也就是你得显式处理一下，它不会凭空出现。 另外，如果你通过元数据API部署了一些不支持的特性，千万要小心——这些特性只认元数据API，如果你通过安装界面去修改，它们可能会凭空消失。所以若用了非标功能，就老老实实一直用元数据API来管理，别混着来。 如果属性面板里你看见了“无效类型”或“无效编辑器”这样的错误，别慌，先打开浏览器控制台看看详细报错，那里会有定位问题的线索。 最后一点是打包时的更新：LightningTypeBundle现在已经取代了老旧的ExperiencePropertyTypeBundle。用新的Bundle，即使将来引用的地方升级，也不会被破坏；不过有个代价，就是它不支持自定义布局，你只能用标准布局去定义它的样子。 好，这些就是自定义属性类型需要特别注意的地方。记住它们，你在LWC开发过程中就能少踩很多坑。大家有什么疑问吗？

  ▶ 播放视频 查看详情
• 5

  Property Validation & Editor Decisions

  第 334 页

  好，我们来看这一页幻灯片。它讲的是一个很重要的决策框架：什么时候该自己写自定义的类型和编辑器，什么时候用标准的就行了。 想象你现在在做一个物业表单，里面有几个字段：一个叫 articleDate，是文章日期；一个叫 textAlignment，文本对齐方式；还有一个叫 layoutProperties，布局属性。你会发现，对于这三个字段，我们采用了完全不同的处理方式。 首先，articleDate 是日期类型。标准的 lightning__dateType 已经给你做好了日期选择器，自带日期格式验证，用户选个日期一点问题都没有。那这种情况下，我们就不用自定义，直接用标准的就行，省时省力。 再看 textAlignment，它要求用户选择左对齐、居中还是右对齐。后端只存一个字符串，验证其实很简单，任何字符串都行。但是，标准的组合框编辑器长得就是个下拉框，而产品设计的交互是一组漂亮的按钮，点哪个就选中哪个，视觉上更直观。这里就出现了一个矛盾：验证没问题，但用户体验不匹配。所以，我们只需要自定义一个编辑器，换成按钮组的样子，但类型还是用标准的文本类型，没必要自创一个类型。 最后是 layoutProperties，它更复杂。里面包含好几个必填的子字段，还要用收件箱的布局方式展示，每个子字段有自定义的标签。这些验证需求（多个必填子字段）和 UX 需求（自定义收件箱布局）都超出了标准功能。所以，我们既不能直接用标准类型，也不能只用默认编辑器，必须同时自定义一个类型，再给它配一个自定义编辑器。 这个框架的核心思想就是：不要过度工程化。你只在标准类型无法满足你数据验证的时候，才去创建自定义类型；只有在默认编辑器和你要的用户体验不匹配时，才去写自定义编辑器。平时开发的时候先查一下 Lightning Types Reference 这个参考文档，里面列出了所有标准类型以及它们默认的编辑器，看能不能直接用。 这样分开决策，一个一个字段独立判断，就能用最少的代码，做出健壮又好看的表单。大家在实际项目中，可以按这个思路来，避免什么都从头造轮子。

  ▶ 播放视频 查看详情
• 6

  High-Level Build Guide & LightningTypeBundle

  第 335 页

  我们来看这一页幻灯片，它讲的是构建序列要遵循的逻辑顺序。其实很简单，就是先从标准类型入手，然后把自定义编辑器加上去，最后再用自定义编辑器去处理那些更复杂的类型。 这里要记住，对于LightningTypeBundle这种捆绑包，我们只能用它来做基于对象的类型，基于Apex的捆绑包是不支持的。而且，整个结构的根必须是一个叫做 `lightning__ObjectType` 的类型。在这个根下面，只能嵌套那九种被Salesforce明确支持的Lightning类型，别的不行。另外，自定义类型和 `datateTimeStringType` 都不能再做嵌套，它们是“叶子”了。 接下来，`schema.json` 这个文件是用来定义数据的形状，以及怎么校验这些数据。简单说，就是描述这个类型的数据长什么样。 而`editor.json` 呢，它放在 `experienceBuilder/` 这个子文件夹里面，主要负责两件关键的事。第一件，用 `componentOverrides` 这个部分，把属性编辑器换成我们自定义的组件，比如如果你想让 borderStyle 这个属性的编辑器，变成一个你自己做的收件箱样式，就在这里配置。第二件，通过 `layout` 来定义属性的视觉组织方式。通常我们会用标准定义，像 `TabSetLayout`，它可以把属性分成不同的选项卡，比如“边框”选项卡和“尺寸”选项卡。在这每个选项卡里面，又会用属性布局子项，去引用 schema 里面对应的子属性，这样编辑界面就组织得清清楚楚。 最后一个小点：当我们在 js-meta.html 里引用属性的时候，如果在属性上设置了 `label` 标签，它会直接覆盖掉在 `schema.json` 里面写的 `title`。举个例子，如果schema里面标题是“布局属性”，但你在标签里写了“布局”，界面上显示出来的就是“布局”。所以这个优先级要记住。 好，这一页的重点就是这些，你掌握了吗？

  ▶ 播放视频 查看详情
• 7

  Standard Layout Definitions — verticalLayout & accordionLayout

  第 336 页

  同学们，咱们今天来聊聊属性编辑器里的布局设计。其实核心就两种样式，理解了它们，你在设计组件属性面板时就会很得心应手。 先看最简单的，叫垂直布局，也就是vertical layout。你可以想象它就是一张清单，把你的属性按顺序从上到下直直地排下来。每个属性占一行，一目了然。当你的属性个数很少，而且彼此之间没啥明显的逻辑分组时，用这种平面列表的方式就非常合适，简简单单，不用搞复杂的分组。 另一种更灵活的叫手风琴布局，也就是accordion plan。它会把属性归类，放进一个个可折叠的扇区里，每个扇区都有一个标签。想编辑哪一类属性，就单独点开那一扇，其他的自动收起来。这样界面上不会一下子塞满所有字段，特别适合属性已经被你分了类、而且用户通常一次只修改一个类别的场景。比如把“外观设置”和“行为设置”分开，交互起来就很清爽。 这两种布局在底层都用到了同一个东西——propertyLayout子组件。你必须给每个propertyLayout绑定一个“property”属性，让它去引用模式定义里的具体子属性。这样布局才知道“这一行到底对应哪个字段”。 至于这个属性最终渲染成什么样的编辑控件呢？是文本框、下拉菜单还是开关按钮？主要看两个因素：一是该属性在模式里的默认类型，比如文本、布尔、数字等；另一个就是我们可以在editor.json里用componentOverrides去做定制覆盖，替掉默认的编辑器。所以整套机制既统一，又留着给你自定义的空间。 好，这一页我们就讲这么多。记住：属性少且平铺用垂直布局，属性分类多时用折叠手风琴，编辑器长相靠类型和覆盖来决定。下一节咱们继续深入实操。

  ▶ 播放视频 查看详情
• 8

  Standard Layout — tabSetLayout & Hierarchy Summary

  第 337 页

  同学们，咱们今天来看一下 Lightning Web Components 里属性编辑器中一种特别常用的布局方式——TabSet，也就是选项卡布局。 你可以这样想，当你去编辑一个组件，属性特别多的时候，如果所有输入框、下拉列表都一股脑堆在同一个面板上，那画面可能又长又乱。这时候选项卡就能帮大忙了。 TabSet 布局，本质上就是把不同的属性，按照编辑时的上下文分组，放到不同的选项卡页签下。每个页签就像一个小抽屉，打开之后只会看到那一组的属性。这样一来，不管属性总量有多少，整个属性面板看起来都始终很紧凑，高度保持不变，不会忽大忽小，使用体验就稳定多了。 比如说，一个组件可能有外观相关的属性，像颜色、尺寸；有行为相关的，像触发方式、自动播放；还有数据相关的，像数据源、过滤条件。如果把它们全叠在一个竖直列表里，你得上下翻着找。但用选项卡，就可以设计成“外观”一个页签，“行为”一个页签，“数据”一个页签，切换页签就能快速找到对应的属性，编辑上下文非常清晰。 在开发时，每个选项卡都是一个布局子集，它自己会有一个标签，里面再包含具体的属性布局项。系统是怎么决定用哪种编辑器来展示某个属性的呢？这里有一个两步走的逻辑：首先，它会检查这个组件有没有自定义的编辑器，也就是通过 componentOverrides 指定的；如果有，就优先使用自定义编辑器；如果没有，就会回退到该属性类型默认的编辑器。这个机制让开发者既能享受到默认的便利，又能在特殊需求时精确控制。 另外你会发现，不仅是选项卡，我们还有竖直排列和手风琴折叠这些布局。怎么选呢？简单说，属性又少、关系又简单的，用竖直排列最直接；如果想让用户按需展开不同分类，手风琴就很合适，但它的面板高度会随着展开和折叠而变大变小；而一旦我们面对属性很多、并且分属于不同编辑模式的场景，选项卡就是最优解，因为它始终保持面板高度固定，切换时不造成布局跳动。 最后，在层次结构上，选项卡布局还有一个一致的特点：不管你怎么组合，它的底部总会有一个引用模式的子属性做结尾，这是元数据定义上的一个固定模式，了解即可。 好，以上就是选项卡布局的核心要点，大家只要记住一句话：按编辑上下文分组，面板紧凑稳定，适合多属性分模式编辑的场景。

  ▶ 播放视频 查看详情
• 9

  Create a Custom Property Editor — Contract & Pattern

  第 338 页

  嘿，同学们，今天我们聊聊Lightning Web Components里一个特别实用的东西——属性编辑器合同。 你想象一下，你在Experience Builder里拖拽一个自定义组件，右侧属性面板上会显示一些设置项，对吧？那这些设置项怎么和你的代码互动呢？就靠这个“合同”啦。它像一套规则，规定编辑器需要接收什么，该做什么。 具体来说，编辑器会拿到六个属性，全是@api装饰的，都是从外面传进来的。我一个个说：第一个是“值”，就是当前这个属性的实际数据；第二个是“标签”，就是你在面板上看到的字段名字；第三个是“描述”，也就是悬停时显示的帮助文本；第四个是“必需”，一个布尔值，告诉你这个字段是不是必填的；第五个是“模式”，它是一个JSON Schema，用来做验证的；最后是“错误”，如果验证出问题了，错误信息会通过这个属性传回来，你得显示给用户看。 那用户改动了值，编辑器怎么通知外面呢？很简单，触发一个叫“valueChange”的自定义事件。注意，这个事件的detail里要带上一个对象，里面有个“Value”属性，把新值传出去就行。 这时候，属性表就会根据之前定义的模式去验证这个新值。如果没问题，它就帮你存到画布上；要是有问题，它会反过来把错误信息注入回编辑器的“错误”属性里。所以你的编辑器一定要能把回传的错误显示出来，别把用户蒙在鼓里。 举个实际例子——AlignmentCPD这个示例，它做了一个按钮组编辑器。当你点某个按钮时，它先更新自己的内部值，然后立刻触发valueChange事件，整套流程就串起来了。 另外，为了访问网站上下文，咱们还支持三个@salesforce模块。这个合同的存在，就是为了保证你写的自定义编辑器能无缝地跟属性表的验证、持久化系统配合，不会掉链子。 简单说，记住六进一出，外加错误回显，你的编辑器就稳了。这节课就到这里，下回我们看看怎么动手写一个。

  ▶ 播放视频 查看详情
• 10

  Property Editor — UI, XML Config & Guidelines

  第 339 页

  好，同学们，咱们这节课来看一个很实用的知识点——怎么给 Lightning Web Components 构建自定义的属性编辑器，以及设计它的时候必须遵守哪些硬规矩。 首先，在做个属性编辑器的时候，你在 UI 上拥有完全的设计自由度。什么意思呢？就是你可以用任何你觉得合适的 HTML 和 CSS，去打造你想要的编辑体验。比如，咱们例子里面用到了 `lightning-button-group` 和 `lightning-button-icon-stateful` 来做视觉上的对齐选择器，看起来就很直观。只要让构建器（Builder）知道这是个属性编辑器就行，这需要在组件里配置一个叫做 `Lightning__PropertyEditor` 的目标。 链接的时候，只要在属性标签上指定 `editor` 属性，指向你这个编辑器就可以了。 但最关键的是，有五个非常重要的准则，你一定得刻在脑子里，违背了这些，你的编辑器在体验构建器（Experience Builder）里就会翻车。 ，第一条，永远、绝对不要在编辑器里自己做验证。， 这是一个最常见的错误。属性面板自己会根据你定义的类型模式来处理验证的事。如果你自己设了自定义错误，或者试图阻止值的变化，这叫反模式，破坏了契约。简单说，别越权，把验证交给系统。 ，第二条，不要用弹出窗口或模态框。， 为什么？因为它们会打断 Builder 的工作流程。用户正编辑着组件呢，突然弹出个东西，体验非常糟糕。所以，任何需要弹出的交互统统避免。 ，第三条，绝对别用绝对定位。， CSS 里的 `position: absolute` 不能用，因为它会导致布局对不齐，在属性面板里看起来会歪歪扭扭，非常不专业。 ，第四条，别随便设置 CSS 的 `width` 属性。， 属性面板有自己的宽度规则，你强行设置宽度值，比如 `width: 300px`，会直接影响面板的大小，破坏整个统一性。所以，别动宽度。 ，第五条，值的触发时机要控制好。， 不要在每次键盘输入（也就是每按一个键）的时候就触发值的变化。这么做会导致画布剧烈刷新，Builder 性能会直线下降。正确做法是，只在提交事件上触发值改变，比如输入框失去焦点（blur）的时候，或者点击按钮确认的时候。这样既能保证性能，又符合最佳实践。 好了，这五点准则记住了，你就能做出流畅、可靠的自定义属性编辑器。简单总结一下：不验证、不弹窗、不绝对定位、不设宽度、不频繁触发值变化。把它们当成铁律，你的组件在 Experience Builder 里就能工作得很好。 下节课我们接着聊怎么样通过这些编辑器打造更复杂的配置面板，大家有什么问题随时提。

  ▶ 播放视频 查看详情
• 11

  Reference Types & Editors + Property Attributes

  第 340 页

  同学们，今天咱们聊一聊怎么把自定义的类型和编辑器挂到组件的属性上。这里有两种连接方式，听我慢慢说。 第一种是通过 ，editor， 属性。如果你只想换个编辑界面，比如让用户在属性面板里看到更漂亮的输入框，但不需要额外的数据验证，那就直接建一个自定义编辑器组件，然后用 `editor` 属性，通过全限定名（就是组件在项目里的完整路径名）去引用它，特别方便。不过有个坑要注意：如果你用的类型本身已经是一个 LightningTypeBundle（也就是类型已经打包了自己的编辑和验证逻辑），就，不要，再用 `editor` 属性了。这时候得去 editor 的 json 配置文件里，用 `componentOverrides` 这个字段去覆盖，这样才不打架。 第二种是通过 ，type， 属性，它更纯粹一些，就是直接指定这个属性的数据类型。可以是 Salesforce 自带的普通类型，比如文本、数字，也可以是你自己封装好的自定义 LightningTypeBundle。两种方式配合起来，就能很灵活地控制属性的行为。 接下来要说说属性标签上的那些设置。你可以在属性的 `label` 和 `description` 里写一些文案，这会，覆盖，掉类型 bundle 里 schema.json 原本定义的标题和描述，让它在界面上显示得更贴切。属性标签一共能设 13 种属性，但记住了，一旦你引用了自定义或 Lightning 类型，像 RST（比如 required、step 这类约束）、max、min 和 placeholder 这些就，不能，在标签上写了。因为这些约束本来就该属于类型自己的 schema，放在那儿统一管，不会乱。 最后是可翻译属性。想让你的属性值支持多语言吗？那就是 `translatable` 打开，但它只对基于字符串的 Lightning 类型有效。如果你把一条文本标记成 `richTextType`，它在导出的翻译文件 .xlf 里就会以富文本格式输出；其他类型的值呢，就老老实实地输出纯文本。这对做国际化的时候很有用，注意区分一下就好。 简单来说，editor 管界面，type 管数据，标签能覆盖显示名，但约束要去类型的 schema 里定，翻译只对字符串生效——这样是不是就清楚多了？

  ▶ 播放视频 查看详情
• 12

  XML Escaping, Testing & Migration

  第 341 页

  大家好，今天咱们来看看Slide上这个知识点，它其实讲了两件事：一个是怎么在属性编辑器里处理那些会让HTML乱套的特殊字符，另一个是从老的ExperiencePropertyTypeBundle迁移到新的LightningTypeBundle要怎么做。咱们慢慢聊。 先说特殊字符这事儿。有时候你在Lightning Web Components的属性默认值里，写了一些字符，比如小于号、大于号，还有JSON里的双引号，这些字符在HTML里是敏感字符，如果不处理，页面解析就会出问题。所以我们要做HTML转义，也就是把这些特殊符号变成安全的实体引用。比如richTextType的默认值里如果含有HTML标签，你就得把小于号换成 `<`，把大于号换成 `>`。而对于那种JSON格式的默认值，比如在objectType里，JSON字符串内部的双引号要记得转义，否则JSON就断裂了。开发完之后，还要测试一下，把组件部署到组织里，拖到Experience Builder的画布上，检查每个属性编辑器是不是能正确显示，能不能正常工作，同时试一下输入有效的值和无效的值，看看报错信息是否友好。 接下来是迁移的部分。以前的ExperiencePropertyTypeBundle现在要迁移到新的LightningTypeBundle。这个过程就像搬家，有六个明确的步骤。 第一步，创建一个新的LightningTypeBundle，注意，它的名字要和旧的不一样，不能重名。 第二步，把旧包里的模式文件，也就是描述属性结构的那些schema，复制到新包里。 第三步，最关键的一步，是把旧的design.json文件转换成新的editor.json文件。这里头有三个映射要记住：原来的“Property sheet”部分对应到新文件的“编辑器”配置里；原来的“Property Renders”相当于现在componentOverrides部分，用来覆盖组件渲染的行为；原来的“视图”配置对应到新文件的“布局”部分。 第四步，更新你组件里的js-meta.xml引用，让它指向新的LightningTypeBundle，而不是旧的。 第五步，部署到环境里。 第六步，确认一切正常后，就可以把旧的ExperiencePropertyTypeBundle删除掉了。 新的LightningTypeBundle有个好处，就是你在更新属性编辑器的时候，不需要中断已有的引用，改起来更顺滑。不过它也有个小限制，就是不支持自定义布局了，咱们得用标准布局来重新设计。所以迁移的时候心里要有数，原来如果做了很花哨的布局，可能得简化一下。 整体看下来，就是处理特殊字符保证安全，然后按照六步稳妥搬家，新家更灵活但布局规矩变了。大家实际操作的时候一步步来，测试仔细些，就没问题啦。 好了，这块内容咱们就讲完了，有什么问题随时问。

  ▶ 播放视频 查看详情