客户端 API 列表

使用Power Pages客户端 API 列表访问和自定义传统和新式列表。本参考说明如何使用行、列、单元格、可见性和列表事件。

$pages.currentPage.lists

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

$pages.currentPage.lists 方法

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

方法	Returns	说明
`getAll`	IList`[]`	返回当前页上的所有列表。
`getListById(id: string)`	IList	按其 HTML 元素 ID 获取列表。

$pages.currentPage.lists 示例

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

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let lists = $pages.currentPage.lists.getAll();
    let list = $pages.currentPage.lists.getListById('list_#1');
});

IList 接口

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

IList 属性

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

Property	类型	说明
`id`	字符串	列表的唯一标识符。
`isModern`	布尔值	对于新式列表，为 true 的布尔值，否则为 false。
`rows`	IRow`[]`	列表当前发布的行。每次读取此属性时，它都会返回最新的数据，因此请在事件处理程序中 `loaded` 读取它，以确保数据可用。
`columns`	IColumn`[]`	列表的当前视图中的列。

Note

属性rowscolumns、offgetColumnon属性、方法和返回的所有内容仅在新式列表中受支持，其中isModern为 true。在传统的列表中，它们可以安全地调用，但不执行任何操作：rows返回columns空数组、getColumn返回未定义且onoff不执行任何操作。在访问列表数据之前检查 isModern 或使用 loaded 从未针对传统列表发生的事件。

IList 方法

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

方法	Returns	说明
`getVisible`	`boolean`	如果列表可见，则返回 true。
`setVisible(isVisible: boolean)`	`void`	设置列表的可见性。
`getHtmlElement`	`HTMLElement`	返回列表的基础 HTML 元素。
`getColumn(logicalName: string)`	IColumn \| `undefined`	返回具有指定逻辑（架构）名称的列。如果未匹配列，则返回未定义。
`on(event: string, handler: function)`	`void`	订阅列表事件的处理程序。请参阅列表事件。多次向同一事件订阅同一个处理程序不起作用。
`off(event: string, handler: function)`	`void`	取消订阅注册到 `on`的处理程序。传递传递给 `on`的同一函数引用。不同的引用不会取消订阅处理程序。

IList 示例

以下示例按 ID 检索列表，记录其可见性状态，并在网格加载时读取其数据。

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

    // Modern list data is available only after the grid loads, so read it in a `loaded` handler.
    if (list.isModern) {
        list.on('loaded', () => {
            console.log(`List has ${list.rows.length} rows and ${list.columns.length} columns.`);
        });
    }
});

IRow 接口

该 IRow 接口表示新式列表中的单个行。从 list.rows 属性或列表事件有效负载获取行。

以返回网格发布的数据开头 get 的方法。其他方法设置行的显示方式，例如其样式、类名和可见性。网格在呈现行时应用这些设置。隐藏行只会更改行的显示方式;基础数据不会更改。

IRow 方法

使用这些方法来读取行的数据并更改行的显示方式。

方法	Returns	说明
`getId`	`string`	以 GUID 字符串的形式返回行的 Dataverse 记录 ID。
`getValue(logicalName: string)`	`string` \| `number` \| `boolean` \| `Date` \| `null`	返回具有指定逻辑（架构）名称的列的原始字符串、数字、布尔值、有效日期或数值选项值。当列不在行中或其原始值是不支持的复杂值（包括查找形状的对象）时返回 null。当原始复杂值不可用时使用 `getDisplayValue` 。
`getDisplayValue(logicalName: string)`	`string`	返回为当前区域设置设置格式化的列的值。当列不在行中时返回一个空字符串。
`getPrivileges`	`object` \| `undefined`	返回服务器为记录计算的特权：`canRead`、、`canWritecanDelete`、`canAppend`和`canAppendTo`。如果未提供服务器，则返回未定义。使用这些值可更改数据显示方式，而不是强制实施安全性。
`getState`	`object` \| `undefined`	返回 `stateCode` 记录的和 `statusCode` 值。如果未提供服务器，则返回未定义。
`setStyle(style: object)`	`void`	将内联 CSS 样式合并到行中。每个调用都会添加到已设置的样式。
`setClassName(className: string)`	`void`	将行的 CSS 类名替换为指定的空格分隔类名。
`addClassName(className: string)`	`void`	向行中添加一个或多个空格分隔的 CSS 类名称。
`removeClassName(className: string)`	`void`	从行中删除一个或多个空格分隔的 CSS 类名称。
`setVisible(visible: boolean)`	`void`	显示或隐藏行。此方法仅更改行的显示方式。
`getCell(logicalName: string)`	ICell	返回一个句柄，用于更改行的单元格的显示方式。

IRow 示例

本示例突出显示已取消的记录并隐藏非活动记录。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const list = $pages.currentPage.lists.getListById('list_#1');

    list.on('loaded', () => {
        list.rows.forEach((row) => {
            // Highlight canceled records where statuscode is 6.
            if (row.getValue('statuscode') === 6) {
                row.setStyle({ backgroundColor: '#fde7e9', color: '#a80000' });
            }
            // Hide inactive records where statecode is 1.
            if (row.getValue('statecode') === 1) {
                row.setVisible(false);
            }
        });
    });
});

IColumn 接口

该 IColumn 接口表示新式列表中的单个列。从 list.columns 属性或 list.getColumn 方法获取列。可以单独设置标头、可见性和工具提示。

这些 get 方法返回源数据，而不是设置的值。例如，getDisplayName即使在调用setHeader后也返回配置的显示名称，就像返回服务器即使在调用cell.setDisplayText后设置格式的值一样row.getDisplayValue。此行为使代码可以安全地运行多次，因为 loaded 每次列表提取、排序、筛选器或页面数据时，处理程序都会再次运行。例如， column.setHeader(column.getDisplayName() + ' *') 每次生成相同的结果，而不是添加另一个星号。读取源值，然后派生设置的值。

IColumn 方法

使用这些方法可读取列的名称并更改列的显示方式。

方法	Returns	说明
`getLogicalName`	`string`	返回列的逻辑（架构）名称。
`getDisplayName`	`string`	返回列配置的显示名称。 `setHeader` 不会更改此值。
`setHeader(header: string)`	`void`	重写列标题中的文本。
`setVisible(visible: boolean)`	`void`	显示或隐藏整个列。
`setTooltip(tooltip: string)`	`void`	设置列标题的工具提示。当有人将鼠标悬停在标题上时，工具提示将显示，屏幕阅读器将其用作标头的辅助名称。

IColumn 示例

本示例设置列的标题文本和工具提示。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const list = $pages.currentPage.lists.getListById('list_#1');

    list.on('loaded', () => {
        const column = list.getColumn('name');
        if (column) {
            column.setHeader('Account name');
            column.setTooltip('The primary name of the account');
        }
    });
});

ICell 接口

该 ICell 接口表示单个单元格，该单元格是行和列的交集。从 row.getCell 方法获取单元格。单元格按设计仅写。若要读取单元格的值，请使用getValue包含单元格的行的或getDisplayValue方法。

ICell 方法

使用这些方法来更改单元格的文本和样式。

方法	Returns	说明
`setDisplayText(text: string)`	`void`	替换单元格中显示的文本。使用此方法可显示友好文本，而不是代码、屏蔽值或显示锁屏提醒。
`setStyle(style: object)`	`void`	将内联 CSS 样式合并到单元格中。每个调用都会添加到已设置的样式。

ICell 示例

本示例更改每行中单元格的文本和样式。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const list = $pages.currentPage.lists.getListById('list_#1');

    list.on('loaded', () => {
        list.rows.forEach((row) => {
            const cell = row.getCell('statuscode');
            cell.setDisplayText('Active');
            cell.setStyle({ fontWeight: 'bold', backgroundColor: '#fff4ce' });
        });
    });
});

列出事件

新式列表会引发使用 list.on 该方法订阅的事件，并使用该方法取消订阅 list.off 。由于这些事件提供行对象，因此它们也是读取或设置行数据的样式的建议位置。事件发生后 loaded ，数据可用。

Event	事件发生时	有效载荷
`loaded`	列表提取并发布其行数据后。每次列表刷新或页面数据时，都会再次发生此事件。	`{ rows: IRow[] }`
`rowclick`	有人选择一行。	`{ row: IRow, event: MouseEvent }`
`cellclick`	有人选择一个单元格。 `cellclick`注册处理程序时，`rowclick`该选择不会发生该事件。	`{ row: IRow, columnName: string, event: MouseEvent }`

重要

如果同时注册了这两 rowclick 个处理程序和 cellclick 处理程序，则选择一个单元格仅 cellclick 调用处理程序。 rowclick不会为同一选择调用处理程序。

列表事件示例

此示例订阅 rowclick 和 cellclick 事件。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const list = $pages.currentPage.lists.getListById('list_#1');

    const onRowClick = (e) => {
        console.log('Selected row:', e.row.getId());
        e.row.setStyle({ outline: '2px solid #0078d4' });
    };

    list.on('rowclick', onRowClick);

    list.on('cellclick', (e) => {
        console.log('Selected cell:', e.row.getId(), 'column:', e.columnName);
        e.row.getCell(e.columnName).setStyle({ backgroundColor: '#e5f1fb' });
    });

    // Define a cleanup function, and call it when your code no longer needs
    // the events. Pass the same handler reference that you passed to the on method.
    const stopListening = () => {
        list.off('rowclick', onRowClick);
    };
});

若要取消订阅，请将相同的函数引用 off 传递给传递给 on 该方法的方法。不同的引用不会取消订阅处理程序。

反馈

此页面是否有帮助？

上次更新时间为 2026-10-15