标签： 将 Salesforce 外部的组件与 Lightning Out（测试版）配合使用

使用 Lightning Out 在 Salesforce 服务器之外运行组件。无论是在 Heroku 上运行的 Node.js 应用程序，还是防火墙内的部门服务器，都可以将您的 Lightning Web 组件添加到独立的 Aura 依赖项应用程序中。然后，无论用户身在何处，都可以运行它们。

注意

此版本包含 Lightning Out 的测试版，这意味着它是一项具有已知限制的高质量功能。您可以在 IdeaExchange 上提供对 Lightning Out 的反馈和建议。

开发可部署在任何地方的 Lightning Web 组件通常与开发它们在 Salesforce 中运行相同。您所知道的有关组件开发的所有内容仍然适用。区别在于如何将应用嵌入远程 Web 容器或源服务器。

以 JavaScript 库的形式将 Lightning Out 添加到外部应用程序，这些库包含在源服务器上的页面中。添加标记以配置和激活您的独立 Aura 应用程序。初始化后，Lightning Out 会通过安全连接拉入 Lightning 组件应用程序，将其启动，然后将其插入到运行它的页面的 DOM 中。到达此点后，您的 Lightning Web 组件代码将接管并运行节目。

注意

此方法不同于使用 iframe 嵌入应用。通过 Lightning Out 运行的 Lightning Web 组件是页面上的正式公民。如果您愿意，您可以启用独立 Aura 应用程序与您嵌入的页面或应用程序之间的交互。此交互使用 Lightning 事件进行处理。

除了一些简单的标记外，Salesforce 中还有少量的设置和准备工作，以实现 Salesforce 和源服务器之间的安全连接。而且，由于源服务器托管应用程序，因此您需要使用自己的代码管理身份验证。

此设置过程类似于您对使用 Lightning Platform REST API 连接到 Salesforce 的应用程序执行的操作，您应该期望它需要同等的工作量。

闪电输出要求

使用 Lightning Out 部署 Lightning Web 组件需要满足一些要求，以确保连接性和安全性。

远程 Web 容器

验证远程 Web 容器或源服务器是否支持这些要求。

• 能够修改提供给客户端浏览器的标记，包括 HTML 和 JavaScript。您必须能够添加 Lightning Out 标记。
• 能够获取有效的 Salesforce 会话 ID。
• 能够访问您的 Salesforce 实例。例如，如果源服务器位于防火墙后面，则它需要访问Internet的权限，至少可以访问Salesforce。

闪电储物柜

使用 Lightning Locker，这是 Lightning 组件的安全体系结构。启用 Lightning Web Security 时，不支持 Lightning Out。我们建议将 Lightning Web Security 作为大多数组织的首选安全架构，但如果您使用 Lightning Out，则必须改用 Lightning Locker。

Salesforce组织

配置您的 Salesforce 组织。

• 创建连接的应用程序，以便源服务器可以进行身份验证和连接。
• 将源站加入跨域资源共享（CORS）白名单。

Lightning 依赖应用程序

创建一个特殊的独立 Aura 应用程序，其中包含源服务器上托管的所有 Lightning Web 组件的依赖关系信息。此应用程序仅供 Lightning Out 使用。

浏览器第三方 Cookie

要使用 Lightning Out，您必须设置自定义域，或者您的 Safari 用户必须更改其跨站点跟踪浏览器设置。此要求适用于桌面和移动设备上的 Safari 用户。有关更多详细信息，请参阅为闪电输出启用浏览器第三方 Cookie。

启用浏览器第三方 Cookie 以实现闪电输出

Lightning 组件在用户的浏览器中设置 Cookie。由于 Lightning Out 在 Salesforce 外部运行 Lightning 组件，因此这些 Cookie 是“第三方”Cookie。有几种替代方法可以使这些第三方 Cookie 在 Lightning Out 中发挥作用。

启用基于令牌的身份验证

Salesforce 使用 Cookie 进行身份验证。对于 Lightning Out 应用程序，我们建议您启用在 Lightning 应用程序处于第三方上下文中时将身份验证 Cookie 替换为会话令牌的设置。

在“设置”的“快速查找”框中，输入“会话”，然后选择“会话设置”。在“会话设置”页面上，选择“在第三方站点中嵌入 Lightning 应用程序时，请使用会话令牌而不是会话 Cookie”。

如果未启用此设置，则用户必须在其浏览器设置中允许第三方 Cookie。

在 Safari 中启用跨站点跟踪

Salesforce 使用身份验证 Cookie 以外的 Cookie。要使这些来自 Salesforce 的第三方 Cookie 正常工作，您的用户必须在其浏览器设置中允许第三方 Cookie。

默认情况下，“阻止跨站点跟踪”设置在 iOS 和 iPadOS 13.4 以及 Safari 浏览器 13.1 及更高版本中处于启用状态。若要允许第三方 Cookie 并使用 Lightning Out，必须禁用此设置。

要查看“阻止跨网站跟踪”设置，请执行以下操作：

• 在 Mac 桌面上的 Safari 浏览器 App 中，前往 Safari |首选项，然后单击隐私。
• 在 iOS 和 iPadOS 中，前往“设置”|”苹果浏览器。

设置自定义域

要求所有 Safari 用户更改其跨站点跟踪浏览器设置的替代方法是设置自定义域。自定义域与调用“闪电输出”应用的外部服务器的第一级域匹配。这种方法会导致浏览器将外部服务器和 Lightning Out 应用程序视为同一域的一部分，因此可以在两个站点之间共享 Cookie。

例如，要从服务器调用 Lightning Out 应用程序，请在 Salesforce 中添加自定义域，例如 。您必须设置 DNS 记录以将完全限定域名 （FQDN） 映射到 Salesforce 中的自定义域 URL。external.example.comlightningout.example.comlightningout.example.com

1. 确定自定义域名，例如 .自定义域必须解析为与调用 Lightning Out 应用程序的第三方站点相同的父域。lightningout.example.com
2. 通过输入“快速查找”框，从“设置”中查找 18 个字符的组织 ID，然后选择“域”。单击“添加域”，并记下页面顶部列出的组织 ID。Domains
3. 使用 DNS 提供商设置 CNAME 记录，以将自定义域名（例如 ）映射到 Salesforce 中的自定义域。CNAME 记录的目标使用格式 ，其中 是您在第一步中选择的自定义域名。lightningout.example.comYourFQDN.Your18charOrgId.live.siteforce.comYourFQDN
4. 通过完成“添加域”页创建自定义域。
   1. 对于 Domain Name （域名），输入您在第一步中选择的自定义域名，例如 。lightningout.example.com
   2. 对于 HTTPS 选项，选择 Salesforce 使用您的 HTTPS 证书在 Salesforce 的服务器上通过 HTTPS 提供域。
5. 在外部服务器页面上配置闪电输出标记，以使用 CNAME 记录的 FQDN，例如 ，这是您使用 DNS 提供商设置的。标记中的属性和函数中的参数都必须使用 CNAME 记录的 FQDN。lightningout.example.comsrcscriptlightningEndPointURI$Lightning.use()
6. 如果您的应用使用身份验证，请参阅闪电输出身份验证。

闪电输出依赖项

创建一个特殊的独立 Aura 依赖项应用程序来描述要使用 Lightning Out 部署的组件。

一个独立的 Aura 依赖项应用只是一个具有一些属性的依赖项，以及使用标签描述的依赖组件。独立的 Aura 依赖项应用程序并不是您真正部署为供人们直接使用的应用程序的应用程序。独立的 Aura 依赖项应用仅用于指定 Lightning Out 的依赖项。<aura:application><aura:dependency>

此独立的 Aura 依赖项应用程序使用默认命名空间中的 Lightning Web 组件。myAppComponentc

<aura:application access="GLOBAL" extends="ltng:outApp">
    <aura:dependency resource="c:myAppComponent"/>
</aura:application>

注意

要在 Aura 应用程序或 Aura 组件中引用 Lightning Web 组件，请使用命名约定。<namespace:camelCaseComponentName>

使用独立的 Aura 依赖应用程序

独立的 Aura 依赖项应用必须执行以下操作。

• 将访问控制设置为 。GLOBAL
• 从 或 扩展。ltng:outAppltng:outAppUnstyled
• 将调用 中引用的每个组件作为依赖项列出。$Lightning.createComponent()

在此示例中，是您计划使用 在源服务器上创建的顶级 Lightning Web 组件。使用 为添加到页面的每个组件创建一个依赖项。<c:myAppComponent>$Lightning.createComponent()$Lightning.createComponent()

注意

不要担心顶级组件中使用的组件。该框架处理子组件的依赖项解析。

独立的 Aura 依赖应用程序不是普通的 Aura 应用程序，您不应将其视为一个应用程序。仅用于指定 Lightning Out 应用的依赖项。

特别要注意以下几点。

• 无法将模板添加到独立的 Aura 依赖项应用。
• 添加到独立 Aura 依赖项应用正文的内容不会呈现。

定义样式依赖关系

您有两种选项可用于设置 Lightning Out 应用程序的样式：Salesforce Lightning Design System 和 unstyled。Lightning Design System 样式是默认样式，Lightning Out 会自动将当前版本的 Lightning Design System 包含在使用 Lightning Out 的页面上。要省略 Lightning Design System 资源并完全控制您的样式，也许是为了匹配源服务器的样式，请将您的依赖项应用程序设置为 extend from 而不是 .ltng:outAppUnstyledltng:outApp

闪电输出标记

Lightning Out 需要在页面上添加一些简单的标记，并使用两个简单的 JavaScript 函数激活。

Lightning Out 库中的标记和 JavaScript 函数是 Lightning Out 唯一特有的功能。其他一切都是您已经知道和喜爱的 Lightning Web 组件代码。

将 Lightning Out 库添加到页面

通过将 Lightning Out JavaScript 库包含在托管独立 Aura 依赖项应用程序的应用程序或页面中，启用源服务器以与 Lightning Out 一起使用。包含库需要一行标记。

<script src="https://myDomainName.my.salesforce.com/lightning/lightning.out.js"></script>

重要

使用主机的自定义域。不要从示例源代码中复制和粘贴其他人的实例。如果这样做，则每当 Salesforce 实例与从中加载 Lightning Out 库的实例之间存在版本不匹配时，您的应用程序就会中断。在Salesforce的定期升级期间，这种情况每年至少发生三次。别这样！

加载和初始化 Lightning 组件应用程序

使用该函数加载并初始化 Lightning 组件框架和独立的 Aura 依赖项应用程序。$Lightning.use()

该函数有四个参数。$Lightning.use()

名字	类型	描述
appName	字符串	必填。独立 Aura 依赖项应用的名称，包括命名空间。例如。"c:expenseAppDependencies"
callback	功能	在 Lightning 组件框架和应用程序完全加载后调用的函数。回调不接收任何参数。此回调通常是你调用将应用添加到页面的位置（请参阅下一节）。还可以通过其他方式更新显示内容，或者以其他方式响应依赖项应用准备就绪。$Lightning.createComponent()
lightningEndPointURI	字符串	Salesforce 实例上 Lightning 域的 URL。例如。https://myDomainName.lightning.force.com
authToken	字符串	有效、活动 Salesforce 会话的会话 ID 或 OAuth 访问令牌。您必须在自己的代码中获取此令牌。Lightning Out 不会为您处理身份验证。请参阅闪电输出的身份验证。

appName是必需的。其他三个参数是可选的。通常，您需要提供所有四个参数。

注意

您不能在一个页面上使用多个独立的 Aura 依赖项应用。可以多次调用，但必须在每次调用中引用相同的依赖项应用。$Lightning.use()

将 Lightning Web 组件添加到页面

使用该功能在页面上添加并激活您的组件。$Lightning.createComponent()

该函数有四个参数。$Lightning.createComponent()

名字	类型	描述
componentName	字符串	必填。要添加到页面的 Lightning Web 组件的名称，包括命名空间。例如。"c:newExpenseForm"
attributes	对象	必填。创建组件时要在组件上设置的属性。例如。如果组件不需要任何属性，请传入一个空对象 .{ name: theName, amount: theAmount }{ }
domLocator	元素或字符串	必填。指示在页面上插入所创建组件的位置的 DOM 元素或元素 ID。
callback	功能	在组件添加到页面并在页面上处于活动状态后调用的函数。回调接收创建的组件作为其唯一参数。

注意

您可以向一个页面添加多个 Lightning Web 组件。也就是说，您可以使用多个 DOM 定位器多次调用，以将组件添加到页面的不同部分。以这种方式创建的每个组件都必须在页面的独立 Aura 依赖项应用中指定。$Lightning.createComponent()

在幕后，调用 Aura 中的标准函数。除了 DOM 定位器之外，参数是相同的。除了将调用包装在一些 Lightning Out 语义中之外，行为也是相同的。$Lightning.createComponent()$A.createComponent()

来自 Lightning Out 的身份验证

要处理身份验证，您必须在初始化 Lightning Out 应用程序时手动提供 Salesforce 会话 ID 或身份验证令牌。

有两种受支持的方式来获取用于闪电输出的身份验证令牌。

• 在 Visualforce 页面上，您可以使用表达式 获取当前 Visualforce 会话 ID。使用会话 ID 启动的会话只能在 Visualforce 页面上使用。{! $Api.Session_ID }
• 在其他地方，使用 OAuth 获取经过身份验证的会话，其过程与获取用于 REST API 的经过身份验证的会话的过程相同。在这种情况下，您将获得 OAuth 令牌，并且可以在任何地方使用它。

重要

Lightning Out 不会自动为您处理身份验证。该函数只是将您提供的任何身份验证令牌传递给安全子系统。对于大多数组织，令牌是会话 ID 或 OAuth 令牌。$Lightning.use()

Lightning Out 具有与您从中获取身份验证令牌的会话相同的权限。对于 Visualforce 使用，会话具有当前用户的权限。对于 OAuth，它是定义 OAuth 连接应用时使用的任何 OAuth 范围设置。通常，将 Lightning Out 与 OAuth 结合使用需要向返回 OAuth 令牌的连接应用程序授予“完全访问权限”范围。{! $Api.Session_ID }

当使用会话访问令牌授予经过 Lightning Out 身份验证的会话时，该会话将保留对活动浏览器会话中运行的任何域的访问。用户使用有效的访问令牌登录后，将在活动浏览器会话中运行的所有 Salesforce 应用程序中验证会话凭据。lightning.force.com

为了防止会话持久性，Salesforce 管理员可以将会话锁定到原始 IP 地址。要选择此选项，请导航到：

设置>安全>会话设置

激活“将会话锁定到会话源自的 IP 地址”复选框。

与未经身份验证的用户共享 Lightning Out 应用程序

将界面添加到您的独立 Aura 依赖项应用程序，使其可供用户使用，而无需他们向 Salesforce 进行身份验证。通过此界面，您可以使用 Lightning Web 组件构建应用程序，并将其部署到任何地方和任何人。ltng:allowGuestAccess

注意

如果用户已通过 Lightning Out 端点进行身份验证，则必须在 中设置会话。尽管我们谈论的是未经身份验证的用户，但如果用户已通过身份验证，了解要求也很重要。$Lightning.use()

用法

您可以将带有界面的独立 Aura 依赖项应用程序添加到 Visualforce 页面，也可以将其与托管在 Salesforce 外部的 Lightning Out 应用程序一起使用。ltng:allowGuestAccess

• 使用适用于 Visualforce 的 Lightning Web 组件，您可以将依赖项应用程序添加到 Visualforce 页面，然后在 Salesforce 选项卡 + Visualforce 站点中使用该页面。然后，您可以允许公众访问该页面。
• 使用 Lightning Out，您可以在支持 Lightning Out 的任何地方部署依赖项应用程序，这几乎是任何地方！

该界面仅在启用了数字体验的组织中可用，并且您的 Lightning Out 应用程序与您在组织中定义的所有站点终结点相关联。ltng:allowGuestAccess

重要

当您通过添加界面使依赖项应用程序可供访客用户访问时，无论该站点是否启用了公共访问，都可以通过组织中的每个 Experience Cloud 站点访问该应用程序。您无法阻止通过站点 URL 访问它，也无法使其可用于某些网站，而不适用于其他网站。ltng:allowGuestAccess

注意

对于为访客访问打开的应用，请格外小心。启用访客访问的应用程序会绕过您为站点的访客用户配置文件设置的对象级和字段级安全性 （FLS）。当您引用或检索对象时，组件不会在 Apex 方法中自动强制执行 CRUD 和 FLS。该框架继续显示用户没有 CRUD 访问权限和 FLS 可见性的记录和字段。启用来宾访问的应用中使用的代码错误可能会向全世界开放组织的数据。

示例：允许访客访问 Lightning Out 应用程序

将界面添加到独立的 Aura 依赖项应用。ltng:allowGuestAccess

<aura:application access="GLOBAL" extends="ltng:outApp"
    implements="ltng:allowGuestAccess">

    <aura:dependency resource="c:storeLocatorMain"/>

</aura:application>

注意

只能将接口添加到依赖项应用，而不能添加到单个组件。ltng:allowGuestAccess

接下来，将 Lightning Out JavaScript 库添加到您的页面。

• 使用适用于 Visualforce 的 Lightning Web 组件，只需在页面上的任意位置添加标签即可。<apex:includeLightning />
• 借助 Lightning Out，使用站点终结点 URL 添加直接引用库的标记。<script><script src="https://YOURSITEDOMAIN/SITEURL/lightning/lightning.out.js"></script>例如：https://universalcontainers.force.com/ourstores/lightning/lightning.out.js

最后，添加 JavaScript 代码以加载和激活依赖项应用。此代码是标准的 Lightning Out，但重要的补充是，您必须将组织的站点 URL 之一用于端点。终结点 URL 采用 的格式，如本示例所示。https://YOURSITEDOMAIN/SITEURLhttps://universalcontainers.force.com/ourstores/

<script>
  $Lightning.use(
    "c:locatorApp", // name of the Lightning app
    function () {
      // Callback once framework and app loaded
      $Lightning.createComponent(
        "c:storeLocatorMain", // top-level component of your app
        {}, // attributes to set on the component when created
        "lightningLocator", // the DOM location to insert the component
        function (cmp) {
          // callback when component is created and active on the page
        },
      );
    },
    "https://universalcontainers.force.com/ourstores/", // Site endpoint
  );
</script>

闪电输出注意事项和限制

使用 Lightning Out 创建应用程序通常与使用 Lightning Web 组件创建任何应用程序一样。但是，由于您的组件在 Salesforce 外部运行，因此您需要注意一些问题。

您必须注意的问题可以分为两类。

使用闪电输出的注意事项

由于 Lightning Out 应用程序在任何 Salesforce 容器之外运行，因此您需要牢记并可能解决一些事项。浏览器支持

Lightning Out 支持与 Lightning Experience 相同的浏览器。这种支持意味着您的 Lightning Out 应用程序和组件会在这些浏览器中加载。但是，如果组件或功能不支持特定浏览器，则该组件或功能在 Lightning Out 中也无法运行。性能

Lightning Out 无法从 Lightning Experience 的许多缓存功能中受益，因此启动和性能通常较慢。浏览器第三方 Cookie

Lightning 组件在用户的浏览器中设置 Cookie。由于 Lightning Out 在 Salesforce 之外运行 Lightning 组件，因此这些 Cookie 是“第三方”Cookie。要使 Lightning Out 应用程序能够与第三方 Cookie 配合使用，请参阅闪电输出要求。认证

没有 Salesforce 容器可以为您处理身份验证，因此您必须自己处理。Authentication from Lightning Out 中详细讨论了这一重要主题。

标准组件的局限性

虽然 Lightning Out 的核心功能稳定且完整，但我们仍在努力与其他 Salesforce 功能进行一些交互。

这些功能中最主要的是内置于 Lightning 组件框架中的标准组件。许多标准组件在独立环境中使用时无法正常运行，例如 Lightning Out 和基于 Lightning Out 的 Lightning Web Components for Visualforce。此限制是因为组件依赖于容器中的可用资源。one.app

若要避免自己的组件出现此问题，请明确其依赖项。用于引用未嵌入组件本身的所有必需静态资源。@salesforce/resourceUrl

如果您在应用程序中使用标准组件，则在 Lightning Out 或 Lightning Web Components for Visualforce 中使用它们时，它们可能没有完全样式或行为与文档中所述。

“组件库”中的“组件引用”为每个组件都有一个“体验”字段，其中列出了组件支持的容器。