Lightning App Builder — LWC 页面与导航完全指南

Lightning App Builder

开发可用于 Lightning Experience 和 Salesforce 移动应用的自定义页面组件。通过 .js-meta.xml 配置文件定义：是否暴露（isExposed）、支持的页面类型（RecordPage/AppPage/HomePage）、每个页面类型的属性和支持对象。

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>47.0</apiVersion>
  <isExposed>true</isExposed>
  <masterLabel>Best Component Ever</masterLabel>
  <targets>
    <target>lightning__RecordPage</target>
    <target>lightning__AppPage</target>
    <target>lightning__HomePage</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightning__RecordPage">
      <property name="prop1" type="String"/>
      <objects><object>Account</object><object>Opportunity</object></objects>
    </targetConfig>
    <targetConfig targets="lightning__AppPage, lightning__HomePage">
      <property name="prop2" type="Boolean"/>
    </targetConfig>
  </targetConfigs>
</LightningComponentBundle>

配置八条技巧：① masterLabel 设友好名称 ② 所有属性加 label（友好显示名）和 description（悬停提示）③ 必填属性必须有默认值（否则加入页面时显示无效状态）④ .js 和配置文件中类型一致（不一致时配置文件优先）⑤ 用基本类型（String/Integer/Boolean）⑥ 整数设 min/max 控制范围 ⑦ String 用 datasource 提供下拉选项 ⑧ 可选 SVG 自定义图标（componentName.svg，每文件夹一个）。

破坏性变更保护：已用于页面或托管包的组件不能做以下操作——删除已使用的 object 标签、移除已使用的页面类型支持、修改已使用组件的 min/max 值。限制：不支持 Map/Object/java:// 类型、已使用组件只能增加不能减少 form factor、移动端下拉刷新不支持自定义 LWC。

控制台应用配置：添加 lightning__AppPage target→组件可作为导航项用于自定义控制台应用。用 lightning/platformWorkspaceApi 编程操作工作区标签页和子标签。参考 lwc-recipes 中以 workspace 开头的组件（如 workspaceAPIFocusTab）。

配置 App Builder 与动态交互

动态交互（Dynamic Interactions）：仅 LWC 可作为源组件——通过两个 targetConfig 子标签暴露事件：<event>（name/label/description）+ <schema>（JSON Schema 定义属性）。仅 lightning__AppPage target 可用。Schema 中仅 type 和 properties 被使用——属性仅支持 String/Integer/Boolean，属性特性仅 type/title/description。事件元数据不验证 .js 文件。

<targetConfig targets="lightning__AppPage">
  <event name="itemselected" label="Item Selected">
    <schema>
      { "type":"object", "properties":{
        "recordId":{"type":"string","title":"Record ID","description":"Enter an 18-digit record ID."},
        "apiName":{"type":"string"}
      }}
    </schema>
  </event>
</targetConfig>

Lightning App Builder 技巧：组件填满 100% 宽度、提供占位行为（不显示空白框）、依赖事件时给默认状态、宽度感知（flexipageRegionWidth）。限制：不支持 Map/Object 类型、不支持 java:// 复杂类型、已使用的组件只能增加不能减少外形尺寸、移动端下拉刷新不支持自定义 LWC。

Lightning Message Service —— 创建与配置

LMS 用于跨 DOM 通信——同一 Lightning 页面内的 Visualforce/Aura/LWC 之间（包括实用工具栏和弹出工具）。也支持从 Salesforce Classic 迁移时与现有 Visualforce 或 Aura 组件通信，以及 Open CTI 软电话通信。支持 Lightning Experience 和 Experience Builder。不支持 Salesforce Tabs + Visualforce 站点。不支持 iframe 内发布（需改用 sforce.one API）。

创建消息通道：LightningMessageChannel 元数据类型，放在 force-app/main/default/messageChannels/，文件命名 ChannelName.messageChannel-meta.xml。部署到 scratch org 或 sandbox/Developer Edition 用 sf project deploy start。

import channelName from "@salesforce/messageChannel/Channel_Name__c";
// 托管包：import ... from "@salesforce/messageChannel/namespace__Channel_Name__c";
// 注意：__c 后缀不表示自定义对象——它是 LightningMessageChannel 的命名约定

作用域详解：默认仅活跃区域（选中的导航标签页+控制台工作区标签页+子标签+导航项+实用工具+ES6库——实用工具始终活跃）。需整个应用（包括后台标签页）接收时用 APPLICATION_SCOPE。作用域功能仅当使用 @wire(MessageContext) 时可用。

import { subscribe, APPLICATION_SCOPE, MessageContext } from 'lightning/messageService';
@wire(MessageContext) messageContext;
subscribe(this.messageContext, channel, handler, { scope: APPLICATION_SCOPE });

组件缓存未销毁时——即使导航离开页面——Application Scope 的组件仍会发布和接收消息。

Lightning Message Service —— 发布与订阅

发布：导入 publish, MessageContext + 消息通道。用 @wire(MessageContext) 创建上下文（组件必须已挂载到 DOM）。publish(this.messageContext, channelName, payload)——payload 为 JSON 对象。

订阅：在 connectedCallback() 中订阅→disconnectedCallback() 中取消订阅。subscribe(messageContext, channel, handler, { scope }) 返回 subscription 对象用于取消。Handler 接收 message payload。

API 模块组件（非 LightningElement）：不能用 @wire(MessageContext)——改用 createMessageContext() 创建 + releaseMessageContext() 释放。

限制：支持 Lightning Experience 标准/控制台导航+移动端 Aura/LWC（Visualforce 不支持移动端）+ Experience Builder。不支持 iframe 内发布（用 sforce.one API 替代）。1GP/2GP 均支持。

导航服务 —— 基础导航与 PageReference

lightning/navigation 适用于 Lightning Experience、Experience Builder、移动端。不适用于 Visualforce/Lightning Out（即使在 LE 内部）。LWR 站点用 lwr/navigation。

import { NavigationMixin } from "lightning/navigation";
export default class MyComp extends NavigationMixin(LightningElement) {}

// PageReference = { type, attributes, state? }
// Navigate：this[NavigationMixin.Navigate](pageRef, replace?)
// GenerateUrl：this[NavigationMixin.GenerateUrl](pageRef).then(url => this.url = url)

PageReference 示例——导航到各种页面：对象主页（standard__objectPage + home）、列表视图（list + filterName）、新建记录（new）、查看记录（standard__recordPage + view）、编辑记录（edit）、关联列表（standard__recordRelationshipPage）、自定义标签页（standard__navItemPage）、外部 URL（standard__webPage）。

NavigationMixin.GenerateUrl：获取 Promise→resolve 为 URL——用于 <a href={url}> 或 window.open(url)。PageReference 对象是冻结的（不可直接修改）——用 Object.assign({}, pageRef, { state: {...} }) 拷贝后修改。state 属性规则：键必须有命名空间前缀双下划线（c__key 或ns__key）；值必须为字符串（消费时 parse）；删除状态值用 undefined。不安全敏感数据不放 URL。仅 URL query string 变化不会重渲染——组件需观察 CurrentPageReference 来响应变化。

完整示例——导航到 Account Home 并生成 URL：

connectedCallback() {
  this.accountHomePageRef = { type:"standard__objectPage",
    attributes:{ objectApiName:"Account", actionName:"home" } };
  this[NavigationMixin.GenerateUrl](this.accountHomePageRef).then(url => this.url = url);
}
handleClick(evt) { evt.preventDefault(); evt.stopPropagation();
  this[NavigationMixin.Navigate](this.accountHomePageRef); }

导航 —— 查询参数与 URL 可寻址组件

URL 可寻址组件：添加 lightning__UrlAddressable target（仅 LE + 移动端）。导航用 standard__component type + componentName: "c__MyComponent"。

this[NavigationMixin.Navigate]({ type:"standard__component",
  attributes:{ componentName:"c__myComponent" },
  state:{ c__propertyValue:"2000" }
});

// 目标组件中用 CurrentPageReference 读取 state
@wire(CurrentPageReference) currentPageRef;
get propertyValue() { return this.currentPageRef.state.c__propertyValue; }

控制台应用中打开新标签页：openTab({ pageReference, icon, label })——防止重复标签用 uid state 值。

查询参数示例——Show/Hide Panel：用 Object.assign({}, currentPageRef, { state: {...} }) 创建更新后的 PageReference 拷贝→导航到同页不同 state。replace=true 避免浏览器历史堆栈加倍。

导航 —— 模态框、默认值与快速操作

从模态框导航：扩展 LightningModal 的组件不能直接用 NavigationMixin——在子组件中定义 PageReference→通过自定义事件传给父组件→父组件调用 NavigationMixin 导航。

记录创建页默认值：encodeDefaultFieldValues({ FirstName:"Morag", LastName:"de Fault" })→赋给 state.defaultFieldValues。覆盖操作用 CurrentPageReference 读取 + decodeDefaultFieldValues() 解码。注意所有值以字符串传递——Boolean 需特殊处理（"true"==="true"）。

Headless Quick Action：空模板 + @api invoke() 中导航。Screen Quick Action：replace=false→模态框堆叠（旧框保持打开但不活跃）；replace=true→自动关闭旧框打开新框。创建记录后默认重定向回记录页。

打开文件：standard__namedPage + pageName:"filePreview" + state { recordIds:"id1,id2", selectedRecordId:"id1" }。桌面端模态预览+幻灯片+文件操作；移动端下载。

感谢阅读本指南。如需继续学习，请参阅下一章：打开模态窗口和通知。