画布开发（5）Canvas SDK

学习目标

完成本单元后，您将能够了解到：

• Visualforce页面代码示例
  
• Visualforce注意事项
  
• apex：canvasApp组件
  
• 在Visualforce页面和Canvas应用程序之间使用事件

除了标准的画布应用程序，Canvas还允许您在Visualforce页面上公开画布应用程序。 这意味着您可以在任何可以显示Visualforce页面的地方显示画布应用程序。

开发人员可以使用Visualforce页面：

• 覆盖标准按钮，例如帐户的“新建”按钮或联系人的“保存”按钮
  
• 覆盖选项卡概述页面，例如“帐户”选项卡主页
  
• 定义自定义选项卡
  
• 在详细的页面布局中嵌入组件
  
• 创建仪表板组件或自定义帮助页面
  
• 自定义，扩展或集成Salesforce控制台中的侧边栏（自定义控制台组件）

要在Visualforce页面上托管画布应用程序，请使用 <apex:canvasApp> 组件。

注意：Canvas框架包含的方法可用于规避包含画布应用程序的iframe的导航限制，而无需使用Visualforce页面。这些方法提供了一种简化的替代方法，用于控制Salesforce应用程序中的画布应用程序的导航。有关详细信息，请参阅第75页的“与Canvas应用程序一起使用的Salesforce App导航方法”。

Visualforce页面代码示例

您可以通过多种方式在Visualforce页面上显示画布应用程序。这些示例显示了使用applicationName，developerName和namespacePrefix引用canvas应用程序的不同方法。

对象细节页面

以下代码段是如何在“帐户”页面上显示画布应用程序的示例。该代码指定画布应用程序的大小为400像素高和750像素宽。此示例使用applicationName和namespacePrefix指定画布应用程序。

<apex:page standardController=”Account”>
<apex:canvasApp applicationName=”Test Inline Visualforce” namespacePrefix=”testorg”
height=”400px” width=”750px”/>
</apex:page>

Standard Page

以下代码段是如何在Visualforce页面上显示画布应用程序的示例。该代码指定画布应用程序的大小为1,000像素高和800像素宽。此外，代码将三个自定义参数传递给画布应用程序。此示例使用developerName和namespacePrefix指定canvas应用程序。

<apex:page>
<apex:canvasApp developerName=”Test_Standard_Visualforce” namespacePrefix=”testorg” height=”1000px” width=”800px” parameters=”{p1:’value1′,p2:’value2′,p3:’value3′}”/>
</apex:page>

带边框和滚动的标准页面

以下代码段是如何在Visualforce页面上显示具有一些其他UI增强功能的画布应用程序的示例。该代码指定画布应用程序的大小为100像素高和500像素宽。此外，代码指定画布应用程序周围应该有2个像素的边框，并且应该启用滚动。此示例仅使用applicationName指定画布应用程序（这仅在创建画布应用程序的组织中有效，并且该组织没有namespacePrefix。

<apex:page>
<apex:canvasApp applicationName=”Test Scrolling Visualforce” height=”100px” width=”500px”
border=”2″ scrolling=”yes”/>
</apex:page>

Visualforce注意事项

使用 <apex:canvasApp> component:组件时，请记住以下注意事项：

• <apex:canvasApp> 组件仅在启用了Canvas且在版本为27.0或更高版本的Visualforce页面中可用。
• 如果在对象详细信息布局上包含画布应用程序，则必须在页面布局中以及 <apex:canvasApp>组件中提供画布应用程序的高度。
• Location—如果画布应用程序位于Visualforce页面中，则Environment.displayLocation字段包含该值Visualforce

apex:canvasApp Component

Use this component to display a canvas app on a Visualforce page. The table below lists the component attributes.

使用此组件在Visualforce页面上显示画布应用程序。下表列出了组件属性。
将包含非字母数字字符（如引号，撇号等）的参数作为JavaScript安全对象传递。为此，编写一个Apex类，该类使用Apex JSONGenerator类的方法来构建JSON字符串。从参数值调用Apex类：

<apex:page controller=”JSONGeneratorSample”>
<apex:canvasApp developerName=”mycanvas” parameters=”{!generateJSON}” />
</apex:page>

或者，您也可以使用JSENCODE函数来转义字符串：

<apex:page standardController=”Account”>
<apex:canvasApp developerName=”mycanvas” parameters=”{!JSENCODE(Account.Description)}”/>
</apex:page>

Attribute	Type	Description
applicationName	String	画布应用程序的名称。 applicationName或 developerName是必需的。
border	String	画布应用程序边框的宽度（以像素为单位）。如果未指定，则默认为0像素。
canvasId	String	画布应用程序窗口的唯一ID。将事件定位到画布应用程序时使用此属性。
containerId	String	呈现画布应用程序的HTML元素的ID。如果未指定，则默认为null。此属性指定的容器不能出现在 <apex:canvasApp> 组件之后。这些代码示例显示了 <div> 容器和containerId属性的有效用法： <apex:page> <div id=”container1″></div> <apex:canvasApp applicationName=”myApp” containerId=”container1″/> </apex:page> <apex:page> <div id=”container1″> <apex:canvasApp applicationName=”myApp” containerId=”container1″/> </div> </apex:page> 此代码示例显示 <div>容器和containerId属性的无效用法： <apex:page> <apex:canvasApp applicationName=”myApp” containerId=”container1″/> <div id=”container1″> </div> </apex:page>
developerName	String	画布应用程序的内部名称。 通过创建连接的应用程序公开画布应用程序时，可以在“API名称”字段中指定此值。 developerName或applicationName都是必需的。
entityFields	String	当组件出现在放置在对象上的Visualforce页面上时，指定签名请求Record对象中返回的字段。 如果未指定此属性或为空，则仅返回Id字段。 有效的属性值包括： •以逗号分隔的字段名称列表。 例如，要返回“帐户电话”和“传真”字段，该属性将如下所示：entityFields =“Phone，Fax” •星号“*”返回关联对象的所有字段。
height	String	Canvas应用程序窗口高度，以像素为单位。 如果未指定，则默认为900像素。
id	String	允许<apex:canvasApp>的唯一标识符 要由页面上的其他组件引用的组件。
maxHeight	String	Canvas应用程序窗口的最大高度（以像素为单位）。默认为2000 px; ‘无限’也是一个有效的值。
maxWidth	String	Canvas应用程序窗口的最大宽度（以像素为单位）。默认为1000 px; ‘无限’也是一个有效的值。
namespacePrefix	String	创建画布应用程序的Developer Edition组织的名称空间值。您只能在Developer Edition组织中设置命名空间，因此如果画布应用程序是在不同类型的组织中创建的，则这是可选的。如果未指定，则默认为null。
onCanvasAppError	String	如果画布应用程序无法呈现，则要调用的JavaScript函数的名称。
onCanvasAppLoad	String	加载画布应用程序后要调用的JavaScript函数的名称。
parameters	String	传递给画布应用程序的参数的对象表示。 以JSON格式或JavaScript对象文字提供。 以下是JavaScript对象文字中的参数示例： {参数1：’VALUE1’，参数2： ‘值2’}。 如果未指定，则默认为null。
rendered	Boolean	指定是否在页面上呈现组件。 如果未指定，则默认为true。
scrolling	String	指定画布应用程序窗口是否使用滚动条。 有效值为： auto no yes 如果未指定，则默认为no。 如果此属性包含无效值，则将其视为“否”以防止浏览器错误。
width	String	Canvas应用程序窗口宽度，以像素为单位。 如果未指定，则默认为800像素。

返回记录对象中的字段

当您使用 <apex:canvasApp> 组件在Visualforce页面上显示画布应用程序，并且该页面与对象关联（例如放置在页面布局上）时，您可以指定要从相关对象返回的字段。为此，请使用entityFields属性。您可以通过以下方式之一使用此属性。

返回特定对象字段

通过将entityFields属性设置为以逗号分隔的字段名称列表，可以返回Record对象中的特定对象字段。如果列表中的字段名称无效，则忽略该字段名称，并在Record对象中返回有效字段。

<apex:canvasApp applicationName=”MyApp” entityFields=”Phone,Fax,BillingCity” containerId=”canvasAppDiv”/>

返回一个如下所示的Record对象：

“record”:{
“attributes”:{ “type”:”Account”,
“url”:”/services/data/v44.0/sobjects/Account/001xx000003DGWiAAO”
}, “Id”:”001xx000003DGWiAAO”, “Phone”:”(555) 555-5555″,
“Fax”:”(555) 555-5555″,
“BillingCity”:”Seattle”
}

返回所有对象字段

您可以通过将entityFields属性设置为通配符“*”来返回Record对象中的所有对象字段。

<apex:canvasApp applicationName=”MyApp” entityFields=”*” containerId=”canvasAppDiv”/>

返回一个如下所示的Record对象：

“record”:{
“attributes”:{ “type”:”Account”,
“url”:”/services/data/v44.0/sobjects/Account/001xx000003DGWiAAO”
}, “Id”:”001xx000003DGWiAAO”,
“IsDeleted”:false, “MasterRecordId”:null, “Name”:”Edge Communications”, “Type”:”Customer – Channel”, “ParentId”:null, “BillingStreet”:”123 Main Street”, “BillingCity”:”Seattle”, “BillingState”:”WA”, “BillingPostalCode”:”98121″, “BillingCountry”:”USA”,
…
}

返回Id字段

如果<apex:canvasApp> 组件没有entityFields属性，或者该属性为空，则只在Record对象中返回Id字段。

<apex:canvasApp applicationName=”MyApp” containerId=”canvasAppDiv”/>

返回一个如下所示的Record对象：

“record”:{
“attributes”:{ “type”:”Account”,
“url”:”/services/data/v44.0/sobjects/Account/001xx000003DGWiAAO”
}, “Id”:”001xx000003DGWiAAO”
}

在Visualforce页面和Canvas应用程序之间使用事件

Canvas提供了一些方法，可用于在画布应用程序和父Visualforce页面之间发布和订阅事件。此过程包括从Visualforce页面发布事件，在Visualforce页面上侦听事件，从Visualforce页面上的事件取消订阅以及调整包含画布应用程序的Visualforce页面的大小。调整画布应用程序大小的过程与画布应用程序自身调整大小的过程不同，这在“调整画布应用程序大小”中有所描述。可以在SDK和此处找到这些方法的完整参考文档。

• publish – 从画布应用程序可以订阅的Visualforce页面发布事件。请参阅从Visualforce页面发布Canvas事件。
  
• resize – 由Visualforce页面用于调整画布应用程序iFrame的大小。请参阅在Visualforce页面中调整画布应用程序的大小。
  
• subscribe – 由Visualforce页面用于订阅画布应用程序可能发布的事件。请参阅订阅事件。
  
• unsubscribe – 由Visualforce页面用于取消订阅画布应用程序可能发布的父事件。请参阅从Visualforce页面中的事件取消订阅。

Visualforce页面需要Controller.js对象才能使用这些方法。 Visualforce页面中的脚本可能如下所示：

<script type=”text/javascript”src=”https://yourDomain.my.salesforce.com/canvas/sdk/js/30.0/controller.js”>

注意：您可以使用Lightning Platform方法在画布应用程序和Salesforce应用程序之间平滑地集成导航，而无需使用Visualforce。这些方法是驻留在Canvas框架内的JavaScript库中的事件。从画布代码调用其中一种导航方法时，会向Salesforce发送一个事件，该事件将读取有效内容并将用户定向到指定的目标。有关更多信息，请参阅“与Canvas应用程序一起使用的Salesforce App导航方法”。

从Visualforce页面发布Canvas事件

以下代码示例演示如何调用publish方法以从Visualforce页面发布myevent事件。订阅此活动的任何画布应用程序都将收到该活动。

// Target all canvas apps.
Sfdc.canvas.controller.publish({name : ‘mynamespace.myevent’,
payload : {}});

以下代码示例演示如何调用publish方法以从Visualforce页面将事件发布到指定的画布应用程序。

如果将事件发布到特定画布应用程序，即使Visualforce页面上的其他画布应用程序订阅了它，也只有指定的画布应用程序才会收到该事件。使用此代码示例，如果Visualforce页面包含画布应用程序app1，app2和app3，并且它们都订阅了myevent，则只有app1会收到该事件。

// Target a specific canvas app
// where “app1” is the canvasId specified in the canvas component.
// For example:
Sfdc.canvas.controller.publish({name : ‘mynamespace.myevent’,
payload : {},
target : {canvas : ‘app1’}});

在target参数中，您可以通过传入一组画布应用程序来指定多个画布应用程序：target：[{canvas：’app1′}，{canvas：’app2′}]。

在Visualforce页面中调整Canvas应用程序的大小

以下代码示例演示如何调用resize方法以在Visualforce页面中的特定画布应用程序上显式设置高度和宽度。

// Set the height and width explicitly and target a canvas app
// Where ‘mycanvas0’ is the canvasId on the canvas component
// <apex:canvasApp canvasId=”mycanvas0″/>
var target = {canvas : “mycanvas0”};
Sfdc.canvas.controller.resize( {height : “1000px”, width : “900px”}, target);

下面的代码示例演示如何调用resize方法来设置Visualforce页面中所有画布应用程序的高度。

//Set only the height on all canvas apps
Sfdc.canvas.controller.resize( {height : “1000px”});

订阅活动

以下代码示例演示如何在Visualforce页面中调用subscribe方法以订阅从画布应用程序发布的指定事件。

// Subscribe to a single event.
Sfdc.canvas.controller.subscribe({name : ‘mynamespace.myevent0’,
onData : function (e) {}});
// Subscribe to multiple events in a single call.
Sfdc.canvas.controller.subscribe([
{name : ‘mynamespace.myevent1’, onData : function(e) {}},
{name : ‘mynamespace.myevent2’, onData : function(e) {}}
]);

取消订阅Visualforce中的事件

以下代码示例演示如何在Visualforce页面中调用unsubscribe方法以取消订阅两个事件。