标签： 在 Visualforce Pages 中使用组件

将 Lightning Web 组件添加到您的 Visualforce 页面，以利用您在 Visualforce 中所做的任何投资。使用 Lightning Web 组件实现新功能，然后将其用于现有 Visualforce 页面。

重要

Lightning Components for Visualforce 基于 Lightning Out，这是一项强大而灵活的功能，可让您将 Aura 和 Lightning Web 组件嵌入到几乎任何网页中。当与 Visualforce 一起使用时，一些细节变得更加简单。例如，无需处理身份验证，也无需配置连接的应用。

在其他方面，使用 Visualforce 的 Lightning 组件就像使用 Lightning Out 一样。有关详细信息，请参阅闪电输出。

将 Lightning Web 组件添加到 Visualforce 页面有三个步骤。

步骤 1：添加 Visualforce JavaScript 库的 Lightning 组件

在 Visualforce 页面的开头添加。此组件加载 Lightning Components for Visualforce 使用的 JavaScript 文件。<apex:includeLightning/>

步骤 2：创建并引用独立的 Aura 依赖项应用

创建独立的 Aura 依赖项应用。使应用程序可全局访问并扩展 .声明对它使用的任何 Lightning 定义（如组件）的依赖关系。ltng:outApp

此示例 Aura 依赖项应用使用 Aura 标记来指示它使用标准 Lightning 组件 。<aura:dependency>lightning:button

<!--lwcvf.app-->
<aura:application access="GLOBAL" extends="ltng:outApp">
  <aura:dependency resource="lightning:button" />
</aura:application>

为您使用的每个 Lightning Web 组件添加一个标签。使用命名约定引用自定义 Lightning Web 组件。<aura:dependency><namespace:camelCaseComponentName>

注意

扩展范围会将 SLDS 资源添加到页面，以允许您的组件使用 Salesforce Lightning 设计系统 （SLDS） 进行样式设置。如果您不希望将 SLDS 资源添加到页面中，请改为从ltng:outAppltng:outAppUnstyled

若要在 Visualforce 页面上引用此应用程序，请使用以下 JavaScript 代码，其中 theNamespace 是应用程序的命名空间前缀。也就是说，您组织的命名空间，或提供应用程序的托管包的命名空间。

$Lightning.use("theNamespace:lwcvf", function () {});

如果应用是在组织中定义的（即，不在托管包中），请改用默认命名空间，如下例所示。如果您的组织未定义命名空间，则必须使用默认命名空间。c

有关创建 Lightning 依赖项应用程序的更多详细信息，请参阅 Lightning Out 依赖项。

步骤 3：在 Visualforce 页面上创建组件

最后，使用 将顶级组件添加到页面。$Lightning.createComponent(String type, Object attributes, String domLocator, function callback)

让我们看一个示例 Visualforce 页面，该页面使用上一个示例中的 创建。lightning:buttonlwcvf.app

<apex:page>
    <apex:includeLightning />

    <div id="lightningvf" />

    <script>
        $Lightning.use("c:lwcvf", function() {
          $Lightning.createComponent("lightning:button",
              { label : "Press Me!" },
              "lightningvf",
              function(cmp) {
                console.log("button was created");
                // do some stuff
              }
          );
        });
    </script>
</apex:page>

该调用将创建一个带有“Press Me！”标签的按钮。该按钮入到 ID 为 的 DOM 元素中。在页面上添加按钮并处于活动状态后，将调用回调函数并执行语句。回调接收创建的组件作为其唯一参数。在这个简单示例中，该按钮未配置为执行任何操作。$Lightning.createComponent()lightningvfconsole.log()

重要

您可以在一个页面上多次调用，但所有调用都必须引用同一个独立的 Aura 依赖项应用。$Lightning.use()

有关使用 和 的更多详细信息，请参阅闪电输出标记。$Lightning.use()$Lightning.createComponent()

浏览器第三方 Cookie

Lightning 组件在用户的浏览器中设置 Cookie。由于 Lightning 组件和 Visualforce 由不同的域提供，因此这些 Cookie 是“第三方”Cookie。您的用户必须在其浏览器设置中允许第三方 Cookie。有关更多详细信息，包括在 Safari 中禁用“阻止跨站点跟踪”设置的要求，请参阅闪电输出要求。

自定义选项卡

您可以将 Lightning Web 组件添加为 Lightning Experience 或 Salesforce 移动应用程序中的自定义选项卡。

为自定义选项卡配置组件

要将 Lightning Web 组件用作 Lightning Experience 或 Salesforce 移动应用程序中的自定义选项卡，请在组件的配置文件中添加选项卡目标。

componentName.js-meta.xml 文件定义组件的元数据值，包括允许在自定义选项卡中使用设置。将目标添加到组件的配置文件中。lightning__Tab

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
   <targets>
     <target>lightning__Tab</target>
  </targets>
</LightningComponentBundle>

配置选项卡目标后，将 Lightning Web 组件添加为 Lightning Experience 或 Salesforce 移动应用程序中的自定义选项卡。

在 Lightning Experience 应用程序中将组件添加为自定义选项卡

在自定义选项卡中提供 Lightning Web 组件，以便在桌面和 Salesforce 移动应用程序的 Lightning Experience 中访问该组件。

要配置要用作自定义选项卡的 Lightning Web 组件，请参阅为自定义选项卡配置组件。

要将您的组件包含在 Lightning Experience 应用程序中，并使其可供组织中的桌面和移动用户使用，请执行以下步骤。

1. 为组件创建自定义选项卡。
   1. 在“设置”中，输入“快速查找”框，然后选择“选项卡”。Tabs
   2. 单击 Lightning 组件选项卡相关列表中的新建。
   3. 选择要提供给用户的 Lightning 组件。
   4. 输入要在选项卡上显示的标签。
   5. 选择选项卡样式，然后单击下一步。
   6. 当系统提示将选项卡添加到配置文件时，接受默认值，然后单击保存。您的 Lightning 组件现在可从桌面应用程序启动器的“所有项目”部分和 Salesforce 移动应用程序的“所有项目”导航菜单项获得。
2. 将您的 Lightning 组件添加到 Lightning 应用程序的导航中。
   1. 在“设置”中，输入“快速查找”框，然后选择“应用程序管理器”。Apps
   2. 编辑现有应用程序或创建应用程序。
   3. 在“导航项目”屏幕上，从“可用项目”列表中选择您的 Lightning 组件选项卡，并将其移动到“所选项目”列表。
   4. 保存应用。
3. 检查输出。
   1. 在桌面上的 Lightning Experience 或 Salesforce 移动应用程序中导航到应用程序启动器。
   2. 搜索自定义应用名称，然后单击它。
   3. 查看您添加的组件。

针对不同的外形规格配置组件

将组件配置为在以桌面格式 （）、手机格式 （） 或两者呈现页面时显示在 Lightning 应用程序页面上。LargeSmall

在组件配置文件的部分中，使用标记集来声明组件支持页面类型的外形规格。<targetConfigs><supportedFormFactors>

如果未定义，则组件支持页面类型支持的外形规格。但是，我们建议为每个页面类型进行定义。<supportedFormFactors><supportedFormFactors>

应用和记录页面支持 和 外形规格。主页仅支持外形规格。LargeSmallLarge

应用和记录页面上的组件可以在手机和桌面上呈现，因为这些页面同时支持手机和桌面。主页上的组件只能在桌面上呈现，因为主页仅支持桌面。

此示例组件在三种页面类型上受支持：应用、记录和主页。在应用页面上，它配置为仅在具有外形规格的设备上呈现。当用户在具有外形规格的设备上查看应用页面时，该组件不会呈现。SmallLarge

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>42.0</apiVersion>
    <isExposed>true</isExposed>
    <masterLabel>Best Component Ever</masterLabel>
    <description>This is a demo component.</description>
    <targets>
        <target>lightning__RecordPage</target>
        <target>lightning__AppPage</target>
        <target>lightning__HomePage</target>
    </targets>
    <targetConfigs>
        <targetConfig targets="lightning__AppPage">
            <property name="prop2" type="Boolean" />
            <supportedFormFactors>
                <supportedFormFactor type="Small" />
            </supportedFormFactors>
        </targetConfig>
        <targetConfig targets="lightning__RecordPage">
            <property name="prop1" type="String" />
            <supportedFormFactors>
                <supportedFormFactor type="Large" />
            </supportedFormFactors>
        </targetConfig>
        <targetConfig targets="lightning__HomePage">
            <property name="prop3" type="Integer" />
            <supportedFormFactors>
                <supportedFormFactor type="Large" />
            </supportedFormFactors>
        </targetConfig>
    </targetConfigs>
</LightningComponentBundle>

注意

在 Lightning 页面上使用组件后，您只能增加该组件支持的外形规格，而不能减小它们。

使组件了解其上下文

组件可以知道其记录上下文、对象上下文及其在 Lightning 应用程序生成器中的区域宽度。

使组件了解其记录上下文

在某些用例中，让组件了解其记录上下文会很有帮助。例如，您希望提供记录上下文，以便组件可以在查看的记录页面上返回和显示子记录信息。要使组件了解其对象上下文，请使用 Lightning 记录页面上的属性。然后，该页将该属性设置为当前记录的 ID。recordId

提示

lwc-recipes 存储库有一个 wireGetRecordDynamicContact 组件，该组件返回正在查看的联系人记录的一些数据。

在 Lightning Experience 中访问记录上下文

在组件的 JavaScript 类中，使用修饰器创建公共属性。@apirecordId

// testClass.js
import { LightningElement, api } from "lwc";
export default class TestClass extends LightningElement {
  @api recordId;
}

在 Lightning Experience 或移动应用程序的记录上下文中调用组件时，recordId 设置为记录的 18 个字符的 ID，例如：。001xx000003DGSWAA4

重要

仅当您在显式记录上下文中放置或调用组件时，才会自动设置 。在所有其他情况下，不会设置 ，并且组件不能依赖于它。在这种情况下，您可以设置自己。例如，用于快速操作的组件在记录页面上使用时，可以显式设置是否需要访问记录 ID。recordIdrecordIdrecordIdrecordId

在 Experience Builder 站点中访问记录上下文

Experience Builder 站点不会自动绑定到组件的模板。recordId

包含修饰器以在组件上创建公共属性后，在组件的文件中添加表达式。参数中指定的所有页面类型都可以访问记录 ID。@apirecordIdrecordId*.js-meta.xmltargets

<targetConfigs>
  <targetConfig targets="lightningCommunity__Default">
    <property
      name="recordId"
      type="String"
      label="Record Id"
      description="Automatically bind the page's record id to the component variable"
      default="{!recordId}"
    />
  </targetConfig>
</targetConfigs>

在Experience Builder站点的记录上下文中调用组件时，表达式将设置为记录的18个字符的ID。"{!recordId}"

使组件了解其对象上下文

在某些用例中，使组件了解其对象上下文会很有帮助。例如，您希望提供对象上下文，以便组件可以根据页面上正在查看的对象返回一些信息。要使组件了解其对象上下文，请使用 Lightning 记录页面上的属性。然后，页面将该属性设置为当前对象的 API 名称。objectApiName

提示

lwc-recipes 存储库有一个 wireGetObjectInfo 组件，该组件返回所选对象的对象信息。

在 Lightning Experience 中访问对象上下文

在组件的 JavaScript 类中，使用修饰器创建公共属性。@apiobjectApiName

// testClass.js
import { LightningElement, api } from "lwc";
export default class TestClass extends LightningElement {
  @api objectApiName;
}

在 Lightning Experience 或移动应用程序的记录上下文中调用组件时，将设置为与正在查看的记录关联的对象的 API 名称，例如：。objectApiNameWarehouse__c

重要

仅当您在显式记录上下文中放置或调用组件时，才会设置 。在所有其他情况下，未设置 ，并且组件不应依赖于它。objectApiNameobjectApiName

在Experience Builder Sites中访问对象上下文

Experience Builder 站点不会自动绑定到组件的模板。objectApiName

包含修饰器以在组件上创建公共属性后，在组件的文件中添加表达式。参数中指定的所有页面类型都可以访问对象名称。@apiobjectApiNameobjectApiName*.js-meta.xmltargets

注意

此方法仅适用于 在路由中 的组件。{!objectApiName}

<targetConfigs>
  <targetConfig targets="lightningCommunity__Default">
    <property
      name="objectApiName"
      type="String"
      label="Object Name"
      description="Automatically bind the page's object name to the component variable"
      default="{!objectApiName}"
    />
  </targetConfig>
</targetConfigs>

在Experience Builder站点的对象上下文中调用组件时，表达式将设置为对象的18个字符的ID。objectApiName

使组件具有宽度感知能力

当您在 Lightning 应用程序构建器中将组件添加到页面上的区域时，请使用将区域的宽度传递给组件。然后，通过一些战略性的 CSS，你可以告诉组件在运行时以不同的方式在不同的区域中呈现。@api flexipageRegionWidth

例如，列表视图组件在大区域中的呈现方式与在小区域中的呈现方式不同，因为它是宽度感知组件。

在组件的 JavaScript 类中，使用修饰器创建公共属性。此属性接收组件在页面上所在的区域的宽度值。@apiflexipageRegionWidth

// testClass.js
import { LightningElement, api } from "lwc";

export default class TestClass extends LightningElement {
  @api flexipageRegionWidth;
}

使用 HTML 模板中的属性。当值更改时，组件将重新呈现。flexipageRegionWidthflexipageRegionWidth

<!-- testClass.html -->
<template>
  <div class={flexipageRegionWidth}>...</div>
</template>

使用 CSS 定义组件在以不同区域宽度呈现时的行为。有效的 CSS 类值为 、 和 。此示例 CSS 代码段告诉组件在大型区域中时以红色背景呈现。当它位于一个小区域时，它以蓝色背景呈现。SMALLMEDIUMLARGE

/* testClass.css */

div.LARGE {
  background: red;
  ...;
}
div.SMALL {
  background: blue;
  ...;
}