Power Pages客户端 API （预览版）

[本文是预发行文档，可能会有所更改。]

Power Pages客户端 API 可帮助开发人员作 UI 组件、管理表单和列表、处理用户身份验证以及以编程方式与 Dataverse 记录交互。当页面加载并且可以通过具有所选名称的全局变量访问客户端 API 时可用。

本文在整个示例中都使用变量名称，并建议遵循此命名约定保持一致性。

使用客户端 API，可以：

检索和修改窗体和窗体控件
显示或隐藏 UI 元素
使用 Web API 创建和检索记录
管理用户身份验证
使用多语言内容

重要

这是一项预览功能。
预览功能不适用于生产用途，并且可能具有受限功能。这些功能受补充使用条款的约束，在正式发布之前提供，以便客户能够提前访问并提供反馈。

客户端 API 初始化

当页面加载时，客户端 API 不会立即初始化。使用函数将 API 对象分配给变量。可通过两种方式初始化客户端 API：

基于回调的 API 就绪情况

使用回调函数，将 API 对象分配给在准备就绪时定义的变量。两个示例演示如何：

通过使用匿名函数：

Microsoft.Dynamic365.Portal.onPagesClientApiReady(($pages) => {
    const forms = $pages.currentPage.forms.getAll();
    console.log(`Found ${forms.length} forms on the page.`);
});

通过使用命名函数：

function start($pages){
    const forms = $pages.currentPage.forms.getAll();
    console.log(`Found ${forms.length} forms on the page.`);
}

Microsoft.Dynamic365.Portal.onPagesClientApiReady(start)

基于 Promise/await 的 API 就绪情况

使用 await 来处理函数为更简洁的异步流返回的承诺。

let $pages = await Microsoft.Dynamic365.Portal.onPagesClientApiReady();
const forms = $pages.currentPage.forms.getAll();
console.log(`Found ${forms.length} forms on the page.`);

何时使用每个方法

下表描述了何时使用每个方法。

方法	何时使用
基于回调的 API 就绪情况	如果需要支持旧版浏览器或不支持的旧脚本，或者想要注册在 API 准备就绪时运行的多个处理程序，请使用。非常适合事件驱动的模式。
基于 Promise/await 的 API 就绪情况	在支持更简洁有序代码的新式 JavaScript 环境中使用。最好是逻辑取决于 API 在继续执行之前准备好的 API。

小窍门

如果代码库已使用，则首选基于 Promise 的方法来实现一致性。

$pages.currentPage.forms 集合

该集合包含用于处理页面上的表单元素的方法。

$pages.currentPage.forms 方法

使用这些方法列出窗体并获取特定的窗体实例。

方法	退货	Description
`getAll`	`IForm[]`	返回添加到当前页的所有表单。
`getFormById(id: string)`	`IForm`	按其 HTML 元素 ID 检索窗体。
`getFormByName(name: string)`	`IForm`	按其名称检索窗体。

$pages.currentPage.forms 方法示例

这些示例演示如何获取所有窗体，并按 ID 或名称检索特定表单。

let forms = $pages.currentPage.forms.getAll();
let form1 = $pages.currentPage.forms.getFormById('form_#1');
let form2 = $pages.currentPage.forms.getFormByName('form_name')

IForm 接口

该接口表示控件和选项卡的容器。

IForm 属性

以下属性描述窗体及其包含的控件和选项卡。

资产	类型	Description
`id`	字符串	窗体的 ID。
`name`	字符串	窗体的名称。
`controls`	控制	窗体上的所有控件。
`tabs`	标签	窗体上的所有选项卡。
`isMultiStep`	布尔	如果窗体为多步骤，则为 True;否则为 false。请参阅 Multistep 窗体。

IForm 方法

使用这些方法来查询窗体的可见性，并切换窗体是否可见。

方法	退货	Description
`getVisible`	`boolean`	如果窗体可见，则返回 true;否则为 false。
`setVisible(isVisible: boolean)`	`void`	设置窗体的可见性。

IForm 示例

以下示例按 ID 检索窗体，并记录其可见性、控件数和选项卡。

let form = $pages.currentPage.forms.getFormById('form_#1');

console.log(`Form id: ${form.id} has ${form.controls.length} controls.`); 

if (form.getVisible()) {  
console.log('Form is currently visible.');  
}  
let tabs = form.tabs;  
console.log(`Form has ${tabs.length} tabs.`);

多步窗体

多步骤窗体是包含多个基本窗体的容器。

Multistep 窗体属性

以下属性适用于多步骤窗体容器，并描述当前活动步骤中可用的属性。

资产	类型	Description
`id`	字符串	多步骤窗体的 ID。
`controls`	控制	当前步骤中的所有控件。
`tabs`	标签	当前步骤中的所有选项卡。
`isMultiStep`	布尔	如果窗体为多步骤，则为 True;否则为 false。
`nextButton`	JQuery 元素	表示下一个按钮（如果缺少空对象）。
`previousButton`	JQuery 元素	表示上一个按钮（如果不存在，则为空对象）。

多步骤表单方法

使用这些方法来检查多步骤窗体中的步骤之间的可见性和移动。

Name	退货	Description
`getVisible`	`boolean`	如果窗体可见，则返回 true;否则为 false。
`setVisible(isVisible: boolean)`	`void`	设置窗体的可见性。
`isVisible`	`boolean`	指示窗体是应显示（true）还是隐藏（false）的属性。
`hasNextStep`	`boolean`	如果下一步存在，则返回 true;否则为 false。
`hasPreviousStep`	`boolean`	如果上一步存在，则返回 true;否则为 false。
`goToNextStep`	`void`	导航到下一步;如果不存在下一步，则提交表单。
`goToPreviousStep`	`void`	导航到上一步;如果不存在，则引发异常。

Multistep 表单示例

此示例演示如何检索多步骤窗体、检查它并前进到下一步。

let $pages = await Microsoft.Dynamic365.Portal.onPagesClientApiReady();
let form = $pages.currentPage.forms.getFormById('multiform_#1');
console.log(`Form id: ${form.id} has ${form.controls.length} controls.`);

if (form.getVisible()) {
console.log('Form is currently visible.');
}

let tabs = form.tabs;
console.log(`Form has ${tabs.length} tabs.`);

form.goToNextStep();

选项卡

一个窗体中包含一个或多个节。

Tab 属性

选项卡中各节的数组。

Tab 方法

使用这些方法来检查选项卡的可见性、检索其名称，以及切换它是否可见。

方法	退货	Description
`getVisible`	`boolean`	如果选项卡可见，则返回 true;否则为 false。
`getName`	`string`	返回选项卡的名称。
`setVisible(isVisible: boolean)`	`void`	设置选项卡的可见性。

选项卡示例

此示例检索窗体、枚举其选项卡并记录第一个选项卡的名称。

let form = $pages.currentPage.forms.getFormById('form_#1');  
let tabs = form.tabs;  
console.log(`Form has ${tabs.length} tabs.`);  
console.log(`First tab is named: ${tabs[0].getName()}`);

Section

分区组选项卡中的控件。

Section 属性

节中的控件数组。

节方法

使用这些方法来读取节的名称并控制其可见性。

方法	退货	Description
`getVisible`	`boolean`	如果节可见，则返回 true;否则为 false。
`getName`	`string`	返回节名称。
`setVisible(isVisible: boolean)`	`void`	设置节的可见性。

节示例

此示例从窗体的第一个选项卡中检索部分并记录基本详细信息。

let form = $pages.currentPage.forms.getFormById('form_#1');  
let sections = form.tabs[0].sections;  
console.log(`Tab has ${sections.length} section(s).`);  
console.log(`First section is named: ${sections[0].getName()}`);

控件

控件表示单个窗体元素。

控制方法

使用这些方法来检索或更新控件的值、可见性和禁用状态。

方法	退货	Description
`getDisabled`	`boolean`	如果控件处于禁用状态，则返回 true。
`getVisible`	`boolean`	如果控件可见，则返回 true。
`getName`	`string`	返回控件的名称。
`getValue`	`string` \| `undefined`	检索当前值。
`setDisabled(isDisabled: boolean)`	`void`	设置禁用状态。
`setVisible(isVisible: boolean)`	`void`	设置可见性。
`setValue(value: string)`	`void`	设置控件的新值。

控件示例

此示例提取窗体，检查第一个控件的可见性，然后隐藏它。

let form = $pages.currentPage.forms.getFormById('form_#1');  
let controls = form.controls;  
if (controls.length > 0) {  
if (controls[0].getVisible()) {  
console.log(`Control ${controls[0].getName()} is visible.`);  
}  
controls[0].setVisible(false); // Hide the first control.  
}

支持的控件

所有控件都实现标准控件方法。某些控件提供了更多方法，并且具有与标准控制方法不同的实现详细信息。了解不同类型的控件的其他方法和实现差异。

$pages.currentPage.lists 集合

列表集合提供用于处理页面上的传统和新式列表元素的方法。

$pages.currentPage.lists 方法

使用这些方法枚举页面上的所有列表，并通过其 HTML 元素 ID 获取特定列表。

方法	退货	Description
`getAll`	IList	返回当前页上的所有列表。
`getListById(id: string)`	IList	按其 HTML 元素 ID 获取列表。

$pages.currentPage.lists 示例

这些示例演示如何枚举页面上的所有列表，并通过其 HTML 元素 ID 获取特定列表。

let lists = $pages.currentPage.lists.getAll();
let list = $pages.currentPage.lists.getListById('list_#1');

IList 接口

列表表示表格或类似网格的数据组件。

IList 属性

这些属性标识列表并指示它是否使用新式呈现模型。

资产	类型	Description
`id`	字符串	列表的唯一标识符。
`isModern`	布尔	对于新式列表，为 true 的布尔值，否则为 false。

IList 方法

使用这些方法来检查列表可见性、切换是否可见以及访问基础 HTML 元素。

方法	退货	Description
`getVisible`	`boolean`	如果列表可见，则返回 true。
`setVisible(isVisible: boolean)`	`void`	设置列表的可见性。
`getHtmlElement`	`HTMLElement`	返回列表的基础 HTML 元素。

IList 示例

以下示例按 ID 检索列表并记录其可见性状态。

let list = $pages.currentPage.lists.getListById('list_#1');  
console.log(`List id: ${list.id}`);  
if (list.getVisible()) {  
console.log('List is currently visible.');  
}

$pages.user 对象

该对象提供用于让用户登录或注销的方法。

$pages.user 方法

这些方法不返回任何值。

方法	Description
`signIn`	将用户重定向到登录页。
`signOut`	注销当前登录的用户。

$pages.webAPI 对象

该对象提供从数据源创建和检索记录的方法。

createRecord 方法

在指定的表中创建新记录。

语法：
返回：解析为创建的记录或作结果的 Promise 。

createRecord 方法参数

提供表示要创建的记录的目标表和数据对象。

参数	类型	Description
`entitySetName`	字符串	实体集的名称。了解 Dataverse Web API 中的实体集名称
`data`	对象	要创建的记录数据。

createRecord 方法示例

此示例演示如何使用实体集名称和最小数据对象进行调用。

$pages.webAPI.createRecord('contacts', {  
firstName: 'User',
lastName: 'Test'  
});

retrieveRecord 方法

按记录的唯一标识符检索记录。

语法：
返回：解析为记录对象的 Promise 。

retrieveRecord 方法参数

指定表、记录 ID 和可选的 OData 查询选项以调整响应。

参数	类型	Description
`entitySetName`	字符串	实体集的名称。了解 Dataverse Web API 中的实体集名称。
`id`	字符串	记录的唯一标识符。
`options`	string （可选）	可选的 OData 查询字符串，用于限制返回的数据。

注释

虽然参数是可选的，但为了获得最佳性能，始终会限制使用选项返回的列值数。

retrieveRecord 方法示例

此示例按 ID 检索单个记录，并使用 OData 查询选项限制返回的列。

let record = await $pages.webAPI.retrieveRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',  '$select=name');

retrieveMultipleRecords 方法

基于提供的查询选项检索多个记录。

语法：
返回：解析为记录对象的数组的 Promise 。

retrieveMultipleRecords 方法参数

指定表和可选的 OData 查询以筛选结果并限制返回的列。

参数	类型	Description
`entitySetName`	字符串	实体集的名称。
`options`	string （可选）	用于控制返回数据的 OData 查询选项字符串。详细了解 Dataverse Web API 支持的 OData 查询选项

注释