用戶端 API 清單

使用 Power Pages 用戶端 API 清單來存取並自訂傳統與現代清單。本參考說明如何處理列、欄位、儲存格、可見性及清單事件。

$pages.currentPage.lists

清單集合提供了方法，讓它能在頁面上處理傳統與現代的清單元素。

$pages.currentPage.lists 方法

利用這些方法枚舉頁面上的所有清單，並依據其 HTML 元素 ID 取得特定清單。

方法	Returns	Description
`getAll`	伊利斯主義者`[]`	回傳當前頁面上的所有清單。
`getListById(id: string)`	伊利斯主義者	會依照 HTML 元素 ID 取得清單。

$pages.currentPage.list 範例

這些範例展示了如何枚舉頁面上所有的清單，並依據其 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	類型	Description
`id`	字串	名單的唯一識別碼。
`isModern`	布爾	一個布林值，對現代清單成立，否則為假。
`rows`	IRow`[]`	清單目前公布的列。每次讀取這個屬性時，它會回傳最新的資料，因此請在事件處理程序 `loaded` 中讀取，確保資料可用。
`columns`	我也在`[]`	清單目前視圖中的欄位。

Note

rows和columns屬性、getColumnonoff方法及其回傳的一切僅支援於現代列表，其中isModern為真。在傳統的清單中，它們可以安全呼叫但什麼都不做：rows回columns傳空陣列、getColumn回傳未定義陣列，且onoff什麼都不做。在存取名單資料或使用loaded事件前，先確認isModern一下，這在傳統名單中是不會發生的。

IList 方法

使用這些方法檢查清單可見性、切換是否可見、存取底層 HTML 元素，並處理欄位和事件。

方法	Returns	Description
`getVisible`	`boolean`	如果清單可見，則會回傳 true。
`setVisible(isVisible: boolean)`	`void`	這會決定名單的能見度。
`getHtmlElement`	`HTMLElement`	回傳清單底層的 HTML 元素。
`getColumn(logicalName: string)`	我也在 \| `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	Description
`getId`	`string`	回傳該列的 Dataverse 記錄 ID 以 GUID 字串。
`getValue(logicalName: string)`	`string` \| `number` \| `boolean` \| `Date` \| `null`	回傳具有指定邏輯（結構）名稱欄位的原始字串、數字、布林值、有效日期或數值選項值。當欄位不在該列中或其原始值為不被支援的複雜值（包括查找形狀的物件）時，會回傳 null。當原始複數值無法取得時使用 `getDisplayValue` 。
`getDisplayValue(logicalName: string)`	`string`	回傳該欄位的值，該欄位格式化為當前地點。當該欄位不在該列時，會回傳一個空字串。
`getPrivileges`	`object` \| `undefined`	回傳伺服器評估記錄的權限：`canRead`、 `canAppendcanWritecanDeletecanAppendTo`和。當伺服器未提供時，會回傳未定義。利用這些數值來改變資料的呈現方式，而非強制執行安全。
`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)`	艾賽爾	回傳一個用來改變該列某一格格顯示方式的handle。

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.getColumn方法取得欄位list.columns。你可以分別設定標題、可見性和提示。

方法會 get 回傳原始資料，而不是你設定的值。例如，即使你呼叫，也會getDisplayName回傳已設定的顯示名稱，就像row.getDisplayValue回傳伺服器格式化的值一樣cell.setDisplayText。setHeader 這種行為讓你的程式碼可以安全執行多次，因為 loaded 每次清單擷取、排序、篩選或分頁資料時，處理器都會重新執行。例如，每次 column.setHeader(column.getDisplayName() + ' *') 都產生相同的結果，而不是再加一個星號。讀取來源值，然後推導出你設定的值。

IColumn 方法

使用這些方法讀取欄位名稱並改變欄位的外觀。

方法	Returns	Description
`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包含該儲存格的列的 or getDisplayValue 方法。

ICell 方法

利用這些方法來更改儲存格的文字和樣式。

方法	Returns	Description
`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 }`

Important

若同時rowclick註冊和 cellclick 處理器，選擇儲存格只會呼叫處理器。cellclick rowclick操作者不會被召喚來做相同的選擇。

列表事件範例

此範例涵蓋與rowclickcellclick事件。

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);
    };
});

要取消訂閱，請將與你傳on給方法相同的函式參考off。不同的參考不會取消主控。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-10-15