generating-ui-bundle-custom-app

React UI 包的自定义应用程序

创建并配置 Salesforce 自定义应用程序，以便在 Lightning Experience 中托管 React UI 包。此技能会生成 CustomApplication 元数据，使应用显示在 Lightning App Launcher 中，并可供内部用户访问。

自定义应用程序与 Experience Sites 不同：它们不需要 Networks、CustomSite、DigitalExperienceConfig 或 DigitalExperienceBundle 元数据。自定义应用程序充当轻量级启动器入口，将渲染工作委托给 uiBundle 引用的 React UI 包。

必需属性

生成任何元数据之前，请先解析所有属性。每个属性都有一条回退链——请按顺序尝试各个选项，直到找到值。

属性	格式	解析方式
appName	lowercamelcase（例如，myInternalApp）	uiBundles/<name>/ 目录中的 UI 包名称
appNamespace	字符串	sfdx-project.json 中的 namespace → sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias} → 默认值 c
appLabel	易于阅读的字符串	用户提供，或将 appName 从驼峰命名转换为标题格式

appNamespace 和 appName 用于将自定义应用程序连接到正确的 React UI 包。在较新的 API 版本中使用 <uiBundle>{appNamespace}__{appName}</uiBundle>；在较旧的版本中使用 <webApplication>{appName}</webApplication>。如果设置错误，应用启动器中会显示入口，但打开后页面为空。工作流的第 2 步会确定应使用哪个字段。

生成工作流

第 1 步：解析所有必需属性

在构建任何内容之前，确定所有属性的值。使用上表中的解析策略。

第 2 步：查询 API 上下文（按版本发现字段）

调用 salesforce-api-context MCP 工具，发现目标组织的 API 版本支持哪些字段。这样可以确保生成的元数据与用户的 Salesforce 版本兼容。

必需调用：

1. 对 CustomApplication 调用 get_metadata_type_fields——检查是否存在 uiBundle 字段
2. 对 UIBundle 调用 get_metadata_type_fields——检查是否存在 target 字段

根据 API 响应解析字段：

字段检查	如果存在	如果不存在（较旧的 API 版本）
CustomApplication.uiBundle	使用 <uiBundle>{appNamespace}__{appName}</uiBundle>	使用 <webApplication>{appName}</webApplication>（不带命名空间）
UIBundle.target	使用 <target>CustomApplication</target>	完全省略 <target> 元素

如果在实际尝试后仍无法使用 salesforce-api-context，则回退到较新的字段名称（uiBundle + target）。

第 3 步：创建项目结构

创建所有尚不存在的文件和目录：

元数据类型	路径
CustomApplication	<sourceDir>/applications/{appName}.app-meta.xml

注意： <sourceDir> 根据 sfdx-project.json 确定。读取 packageDirectories[]，并使用其中 "default": true 的条目；完整源目录为 <path>/main/default。如果没有设置默认项，则使用第一个条目。常见路径为 force-app/main/default，但此路径可配置。

第 4 步：填充所有元数据字段

使用下方文档中的默认模板。{braces} 中的值是已解析的属性引用——请将其替换为第 1 步中的实际值。应用第 2 步中的字段解析结果，以确定要使用哪些 XML 元素。

元数据类型	模板引用
CustomApplication	configure-metadata-custom-application.md

步骤 4 的执行说明：加载并使用文档

• 在尝试填充元数据字段之前，Agent 必须先完整阅读步骤 4 中引用的 docs/*.md 文件。
• 完整阅读文件，将占位符（例如 {appName}）替换为解析出的值，然后使用展开后的模板填充元数据 XML 内容。
• 如果步骤 2 确认适用的是旧字段名称，则在生成的输出中将 <uiBundle> 替换为 <webApplication>。

步骤 5：更新 UI Bundle Meta XML

如果步骤 2 确认 UIBundle 存在 target 字段，则在 .uibundle-meta.xml 文件中添加 <target>CustomApplication</target>（如果组织的 API 版本中不存在此字段，则跳过）：

<?xml version="1.0" encoding="UTF-8"?>
<UIBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>{appName}</masterLabel>
    <description>A Salesforce UI Bundle.</description>
    <isActive>true</isActive>
    <version>1</version>
    <target>CustomApplication</target>
</UIBundle>

步骤 6：不要修改非模板属性

不要修改 CustomApplication 元数据的任何默认属性值，除非这些值以 {大括号} 包裹的变量形式表示。

验证清单

部署前，请确认：

• 所有必需属性均已解析
• 已查询 API 上下文，以确定可用字段（步骤 2）
• applications/{appName}.app-meta.xml 存在且内容正确
• Bundle 引用字段与组织的 API 版本相符（<uiBundle> 或 <webApplication>）
• 如果支持 target 字段：.uibundle-meta.xml 中包含 <target>CustomApplication</target>
• 部署验证成功：

sf project deploy validate --metadata CustomApplication UIBundle --target-org ${usernameOrAlias}