Listas de API do Cliente

Use Power Pages listas de API do Cliente para acessar e personalizar listas tradicionais e modernas. Essa referência explica como trabalhar com linhas, colunas, células, visibilidade e eventos de lista.

$pages.currentPage.lists

A coleção de listas fornece métodos para trabalhar com elementos de lista tradicionais e modernos na página.

Métodos $pages.currentPage.lists

Use esses métodos para enumerar todas as listas na página e obter uma lista específica pela ID do elemento HTML.

Método	Returns	Descrição
`getAll`	Ilist`[]`	Retorna todas as listas na página atual.
`getListById(id: string)`	IList	Obtém uma lista por sua ID de elemento HTML.

exemplos de $pages.currentPage.lists

Esses exemplos mostram como enumerar todas as listas na página e obter uma lista específica por sua ID de elemento HTML.

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

Interface IList

Uma lista representa um componente de dados tabular ou semelhante à grade.

Propriedades de IList

Essas propriedades identificam a lista e indicam se ela usa o modelo de renderização moderno.

Propriedade	Tipo	Descrição
`id`	cadeia	O identificador exclusivo da lista.
`isModern`	booleano	Um valor booliano que é verdadeiro para listas modernas e false caso contrário.
`rows`	IRow`[]`	As linhas que a lista publica atualmente. Cada vez que você lê essa propriedade, ela retorna os dados mais recentes, portanto, leia-os em um `loaded` manipulador de eventos para garantir que os dados estão disponíveis.
`columns`	IColumn`[]`	As colunas no modo de exibição atual da lista.

Note

As rows propriedades, columns os métodos e off os métodos e tudo o getColumnonque retornam têm suporte apenas em listas modernas, onde isModern é verdade. Em uma lista tradicional, eles são seguros para chamar, mas não fazem nada: rows e columns retornam matrizes vazias, getColumn retornam indefinidos e onoff não fazem nada. Verifique isModern antes de acessar os dados da lista ou use o loaded evento, que nunca ocorre para uma lista tradicional.

Métodos IList

Use esses métodos para verificar a visibilidade da lista, alternar se ela está visível, acessar o elemento HTML subjacente e trabalhar com colunas e eventos.

Método	Returns	Descrição
`getVisible`	`boolean`	Retornará true se a lista estiver visível.
`setVisible(isVisible: boolean)`	`void`	Define a visibilidade da lista.
`getHtmlElement`	`HTMLElement`	Retorna o elemento HTML subjacente para a lista.
`getColumn(logicalName: string)`	IColumn \| `undefined`	Retorna a coluna que tem o nome lógico (esquema) especificado. Retorna indefinido quando nenhuma coluna corresponde.
`on(event: string, handler: function)`	`void`	Assina um manipulador em um evento de lista. Consulte os eventos de lista. Assinar o mesmo manipulador no mesmo evento mais de uma vez não tem efeito.
`off(event: string, handler: function)`	`void`	Cancela a assinatura de um manipulador registrado com `on`. Passe a mesma referência de função para a `on`qual você passou. Uma referência diferente não cancela a assinatura do manipulador.

Exemplo de IList

O exemplo a seguir recupera uma lista por ID, registra seu status de visibilidade e lê seus dados quando a grade é carregada.

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

Interface IRow

A IRow interface representa uma única linha em uma lista moderna. Obtenha uma linha da list.rows propriedade ou de uma carga de evento de lista .

Os métodos que começam com get retornam os dados que a grade publicou. Os outros métodos definem como a linha aparece, como seu estilo, nomes de classe e visibilidade. A grade aplica essas configurações quando renderiza a linha. Ocultar uma linha altera apenas como a linha é exibida; os dados subjacentes não são alterados.

Métodos IRow

Use esses métodos para ler os dados de uma linha e alterar a forma como a linha é exibida.

Método	Returns	Descrição
`getId`	`string`	Retorna a ID de registro do Dataverse da linha como uma cadeia de caracteres GUID.
`getValue(logicalName: string)`	`string` \| `number` \| `boolean` \| `Date` \| `null`	Retorna uma cadeia de caracteres bruta, número, booliano, data válida ou valor de opção numérica para a coluna que tem o nome lógico (esquema) especificado. Retorna nulo quando a coluna não está na linha ou seu valor bruto é um valor complexo sem suporte, incluindo um objeto em forma de pesquisa. Use `getDisplayValue` quando o valor complexo bruto não estiver disponível.
`getDisplayValue(logicalName: string)`	`string`	Retorna o valor da coluna formatada para a localidade atual. Retorna uma cadeia de caracteres vazia quando a coluna não está na linha.
`getPrivileges`	`object` \| `undefined`	Retorna os privilégios que o servidor avaliou para o registro: `canRead`, , `canWrite`, `canDelete`, e `canAppendTocanAppend`. Retorna indefinido quando o servidor não os fornece. Use esses valores para alterar a forma como os dados são exibidos, não para impor a segurança.
`getState`	`object` \| `undefined`	Retorna o e `statusCode` os `stateCode` valores do registro. Retorna indefinido quando o servidor não os fornece.
`setStyle(style: object)`	`void`	Mescla estilos CSS embutidos na linha. Cada chamada adiciona aos estilos que já estão definidos.
`setClassName(className: string)`	`void`	Substitui os nomes de classe CSS da linha pelos nomes de classe separados por espaço que você especificar.
`addClassName(className: string)`	`void`	Adiciona um ou mais nomes de classe CSS separados por espaço à linha.
`removeClassName(className: string)`	`void`	Remove um ou mais nomes de classe CSS separados por espaço da linha.
`setVisible(visible: boolean)`	`void`	Mostra ou oculta a linha. Esse método altera apenas a forma como a linha é exibida.
`getCell(logicalName: string)`	ICell	Retorna um identificador que você usa para alterar a forma como uma das células da linha é exibida.

Exemplo de IRow

Este exemplo realça registros cancelados e oculta registros inativos.

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

Interface IColumn

A IColumn interface representa uma única coluna em uma lista moderna. Obtenha uma coluna da list.columns propriedade ou do list.getColumn método. Você pode definir o cabeçalho, a visibilidade e a dica de ferramenta independentemente um do outro.

Os get métodos retornam os dados de origem, não os valores definidos. Por exemplo, getDisplayName retorna o nome de exibição configurado mesmo depois de você chamar setHeader, assim como row.getDisplayValue retorna o valor formatado pelo servidor mesmo após você chamar cell.setDisplayText. Esse comportamento torna seu código seguro para ser executado mais de uma vez, pois o loaded manipulador é executado novamente sempre que a lista busca, classifica, filtra ou páginas dados. Por exemplo, column.setHeader(column.getDisplayName() + ' *') produz o mesmo resultado todas as vezes em vez de adicionar outro asterisco. Leia o valor de origem e, em seguida, derive o valor definido.

Métodos IColumn

Use esses métodos para ler os nomes de uma coluna e alterar a forma como a coluna é exibida.

Método	Returns	Descrição
`getLogicalName`	`string`	Retorna o nome lógico (esquema) da coluna.
`getDisplayName`	`string`	Retorna o nome de exibição configurado da coluna. `setHeader` não altera esse valor.
`setHeader(header: string)`	`void`	Substitui o texto no cabeçalho da coluna.
`setVisible(visible: boolean)`	`void`	Mostra ou oculta a coluna inteira.
`setTooltip(tooltip: string)`	`void`	Define a dica de ferramenta para o cabeçalho da coluna. A dica de ferramenta é exibida quando alguém passa o mouse sobre o cabeçalho e os leitores de tela a usam como o nome acessível do cabeçalho.

Exemplo de IColumn

Este exemplo define o texto do cabeçalho e a dica de ferramenta para uma coluna.

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

Interface ICell

A ICell interface representa uma única célula, que é a interseção de uma linha e uma coluna. Obtenha uma célula do row.getCell método. Uma célula é somente gravação por design. Para ler o valor de uma célula, use o getValue método da getDisplayValuelinha que a contém.

Métodos ICell

Use esses métodos para alterar o texto e o estilo de uma célula.

Método	Returns	Descrição
`setDisplayText(text: string)`	`void`	Substitui o texto que aparece na célula. Use esse método para mostrar texto amigável em vez de um código, mascarar um valor ou mostrar um selo.
`setStyle(style: object)`	`void`	Mescla estilos CSS embutidos na célula. Cada chamada adiciona aos estilos que já estão definidos.

Exemplo de ICell

Este exemplo altera o texto e o estilo de uma célula em cada linha.

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

Listar eventos

As listas modernas geram eventos aos quais você assina usando o list.on método e cancelam a assinatura usando o list.off método. Como esses eventos fornecem objetos de linha , eles também são o local recomendado para ler ou estilo de dados de linha. Os dados estão disponíveis após a ocorrência do loaded evento.

Event	Quando ocorre	Carga útil
`loaded`	Depois que a lista busca e publica seus dados de linha. Esse evento ocorre novamente sempre que a lista atualiza ou páginas dados.	`{ rows: IRow[] }`
`rowclick`	Alguém seleciona uma linha.	`{ row: IRow, event: MouseEvent }`
`cellclick`	Alguém seleciona uma célula. Quando um `cellclick` manipulador é registrado, o `rowclick` evento não ocorre para essa seleção.	`{ row: IRow, columnName: string, event: MouseEvent }`

Importante

Se ambos rowclick e cellclick manipuladores forem registrados, selecionar uma célula invocará apenas o cellclick manipulador. O rowclick manipulador não é invocado para a mesma seleção.

Exemplo de eventos de lista

Este exemplo assina e rowclickcellclick eventos.

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

Para cancelar a assinatura, passe a mesma referência de função para o off método que você passou para o on método. Uma referência diferente não cancela a assinatura do manipulador.

Comentários

Esta página foi útil?

Última atualização em 2026-10-15