Power Pages exemplos de API do cliente

Os exemplos neste artigo mostram como combinar as APIs do cliente Power Pages para implementar cenários comuns em formulários e listas. Cada exemplo é concluído, para que você possa copiá-lo para um arquivo Web JavaScript ou para a seção JavaScript personalizada de uma página e, em seguida, alterar os nomes de formulário, nomes de coluna e nomes de tabela para corresponder ao seu site.

Todos os exemplos usam o padrão de retorno de chamada descrito na inicialização da API do Cliente, que garante que a API do cliente esteja pronta antes da execução do código. O callback é declarado com async para que possa usar await. Omita a async palavra-chave quando seu próprio código não usa await.

Exemplo Descrição
Definir um valor de pesquisa modal de um registro do Dataverse Recupere um registro do Dataverse e use-o para preencher um controle de pesquisa modal.
Definir um valor de pesquisa quando a pesquisa for renderizada como uma lista suspensa Defina um valor de pesquisa com base em se o controle é renderizado como uma lista suspensa ou uma pesquisa modal.
Ler e definir valores em uma coluna de múltipla escolha Leia as opções selecionadas e adicione uma opção sem remover as seleções existentes.
Trabalhando com controles que são somente para leitura ou ocultos no servidor Verifique a disponibilidade do controle e o estado de somente leitura antes de alterar o comportamento do controle.
Fazer uma coluna necessária com base no valor de outra coluna Aplique requisitos condicionais e validação personalizada com base no valor de outro controle.
Mostrar ou ocultar colunas em uma lista Oculte uma coluna de lista moderna e personalize o título e a dica de ferramenta de outra coluna.
Mostrar ou ocultar registros em uma lista Ocultar linhas inativas e distinguir visualmente registros que o usuário atual não pode editar.

Definir um valor de pesquisa modal de um registro do Dataverse

Este exemplo recupera um registro de conta com a API Web e o usa para preencher uma pesquisa modal em um formulário. Uma pesquisa modal requer um objeto que contenha a ID, o nome e o nome da tabela do registro relacionado.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    // 1. Retrieve the first account record.
    //    $top=1 returns a single record, and $select limits the payload to the
    //    columns that the lookup control needs.
    const queryOptions = '$select=accountid,name&$top=1';
    const response = await $pages.webAPI.retrieveMultipleRecords('accounts', queryOptions);
    const records = response.value;

    if (!records || records.length === 0) {
        console.warn('No account records were returned from Dataverse.');
        return;
    }

    const firstAccount = records[0];
    console.log(`Retrieved account: ${firstAccount.name}`);

    // 2. Get the form. Use the name or the ID of your basic or multistep form.
    const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');

    if (!form) {
        console.error('The target form was not found on the page.');
        return;
    }

    // 3. Get the lookup control by its logical name.
    const lookupControl = form.getControlByLogicalName('new_managingpartnerid');

    if (!lookupControl) {
        console.error('The lookup control was not found on the form.');
        return;
    }

    // 4. Set the lookup value. A modal lookup expects an object that contains
    //    the id, name, and entityType values.
    lookupControl.setValue({
        id: firstAccount.accountid,
        name: firstAccount.name,
        entityType: 'account'
    });

    console.log('The lookup control is populated.');
});

Dica

Para encontrar um controle quando você não souber seu nome lógico, enumere form.controls e use o getName método, como em form.controls.find(control => control.getName() === 'Managing Partner').

Definir um valor de pesquisa quando a pesquisa for renderizada como uma lista suspensa

Uma coluna de pesquisa é exibida como uma caixa de diálogo modal ou como uma lista suspensa, dependendo da configuração do formulário. Os dois controles aceitam valores diferentes no setValue método, portanto, verifique a isDropdown propriedade antes de definir o valor. Uma pesquisa suspensa espera que a ID da opção seja selecionada e uma pesquisa modal espera um objeto.

Importante

Um campo de pesquisa suspenso contém apenas os registros retornados pela exibição e pelos filtros configurados. Defina o valor como o ID de um registro que está disponível na lista suspensa. Neste exemplo, filtre sua consulta para que ela retorne apenas registros que a pesquisa oferece.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');
    const lookupControl = form && form.getControlByLogicalName('new_managingpartnerid');

    if (!lookupControl) {
        console.error('The lookup control was not found on the form.');
        return;
    }

    const response = await $pages.webAPI.retrieveMultipleRecords('accounts', '$select=accountid,name&$top=1');
    const records = response.value;

    if (!records || records.length === 0) {
        return;
    }

    const account = records[0];

    if (lookupControl.isDropdown) {
        // A dropdown lookup expects the ID of the option to select.
        lookupControl.setValue(account.accountid);

        // getValue returns an object that contains the id and name of the selected option.
        const selected = lookupControl.getValue();
        console.log(`Selected option: ${selected && selected.name}`);
    } else {
        // A modal lookup expects an object.
        lookupControl.setValue({
            id: account.accountid,
            name: account.name,
            entityType: 'account'
        });
    }
});

Ler e definir valores em uma coluna de escolha de múltipla seleção

Um controle de lista de seleção múltipla armazena um array de números. Este exemplo adiciona uma opção à seleção atual sem remover as opções que alguém já selecionou.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');
    const control = form && form.getControlByLogicalName('new_areasofinterest');

    if (!control || control.getType() !== 'MultiSelectPicklist') {
        return;
    }

    // 1. Read the options that are currently selected.
    const selectedValues = control.getValue() || [];
    console.log(`Selected options: ${selectedValues.join(', ')}`);

    // 2. Add an option only when it isn't selected yet.
    //    setValue throws an error when a value isn't one of the available options.
    const newsletterOption = 740740002;

    if (!selectedValues.includes(newsletterOption)) {
        control.setValue([...selectedValues, newsletterOption]);
    }

    // 3. Clear the selection.
    // control.setValue([]);
});

Trabalhando com controles que são somente para leitura ou ocultos no servidor

Power Pages aplica metadados de formulário e permissões de tabela no servidor e a API do cliente não pode substituir essas configurações. Escreva um código defensivo que verifica se existe um controle e se ele é somente leitura antes de alterá-lo.

Aplicam-se os seguintes comportamentos:

  • Uma coluna que não está no formulário ou que alguém não tem permissão para ler não é renderizada. O getControlByLogicalName método retorna undefined para essa coluna, portanto, verifique o resultado antes de usá-lo.
  • Quando um controle é bloqueado no servidor, como uma lista de seleção múltipla em um formulário ou campo somente leitura, o método setDisabled(false) não tem efeito.
  • O setRequired(false) método não pode tornar uma coluna opcional quando a coluna é necessária no servidor.
  • O setVisible(false) método oculta apenas um controle no navegador. Use permissões de tabela e segurança de coluna para proteger dados. Nunca confie em ocultar um controle para proteger dados.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');

    if (!form) {
        return;
    }

    const creditLimit = form.getControlByLogicalName('creditlimit');

    // The column isn't on the form, or the user can't read it.
    if (!creditLimit) {
        console.log('The credit limit column is not available to this user.');
        return;
    }

    // A control that's locked on the server stays disabled, even after
    // you call setDisabled(false).
    creditLimit.setDisabled(false);

    if (creditLimit.getDisabled()) {
        console.log('The credit limit column is locked on the server.');
    }

    // Hide the control in the browser. This changes only what people see.
    // Use table permissions and column security to protect the data.
    const internalNotes = form.getControlByLogicalName('new_internalnotes');

    if (internalNotes) {
        internalNotes.setVisible(false);
    }
});

Tornar uma coluna obrigatória com base no valor de outra coluna

Este exemplo torna necessária uma coluna somente quando alguém seleciona uma opção específica em outra coluna e adiciona um validador personalizado que é executado quando o formulário é enviado. Para obter mais informações, consulte os parâmetros do método addValidator.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const form = $pages.currentPage.forms.getFormByName('Profile Web Form (Enhanced)');

    if (!form) {
        return;
    }

    const contactMethod = form.getControlByLogicalName('preferredcontactmethodcode');
    const mobilePhone = form.getControlByLogicalName('mobilephone');

    if (!contactMethod || !mobilePhone) {
        return;
    }

    const applyRules = () => {
        // Option 3 is Phone in this example.
        const requiresPhone = contactMethod.getValue() === '3';

        // Make the column required and provide a localized message.
        mobilePhone.setRequired(requiresPhone, 'Enter a mobile phone number.');

        if (requiresPhone) {
            // Add a format check that runs when the form is submitted.
            // Reusing the same ID replaces the earlier validator instead of adding another one.
            mobilePhone.addValidator(
                'mobilePhoneFormat',
                (value) => /^(?=.*\d)[0-9\s+()-]{7,20}$/.test((value || '').trim()),
                'Enter a valid mobile phone number.'
            );
        } else {
            mobilePhone.removeValidator('mobilePhoneFormat');
        }
    };

    // Apply the rules when the page loads and whenever a value on the form changes.
    applyRules();
    form.getHtmlElement().addEventListener('change', applyRules);
});

Note

Uma coluna necessária no servidor permanece necessária, mesmo quando você chama setRequired(false).

Mostrar ou ocultar colunas em uma lista

Este exemplo oculta uma coluna em uma lista moderna e renomeia outra coluna. Leia os dados da lista em um manipulador de eventos loaded, pois o evento ocorre novamente sempre que a lista é atualizada, classificada, filtrada ou paginada. Para obter mais informações, consulte Eventos de lista.

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

    if (!list || !list.isModern) {
        return;
    }

    list.on('loaded', () => {
        // Hide a column that people don't need to see.
        const createdOn = list.getColumn('createdon');

        if (createdOn) {
            createdOn.setVisible(false);
        }

        // Rename a column and add a tooltip that screen readers use as the
        // accessible name of the header. Read the configured display name, and
        // then derive the header so that the code produces the same result
        // each time the event occurs.
        const name = list.getColumn('name');

        if (name) {
            name.setHeader(`${name.getDisplayName()} (primary)`);
            name.setTooltip('The primary name of the account.');
        }
    });
});

Mostrar ou ocultar registros em uma lista

Este exemplo oculta registros inativos e realça os registros que alguém não pode editar. Ocultar uma linha altera apenas o que as pessoas veem na lista; ele não altera os dados nem o número de registros retornados pelo servidor.

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

    if (!list || !list.isModern) {
        return;
    }

    list.on('loaded', () => {
        list.rows.forEach((row) => {
            const state = row.getState();

            // Hide inactive records, where statecode is 1.
            if (state && state.stateCode === 1) {
                row.setVisible(false);
                return;
            }

            // Highlight the records that this user can't edit.
            const privileges = row.getPrivileges();

            if (privileges && !privileges.canWrite) {
                row.addClassName('read-only-row');

                const nameCell = row.getCell('name');

                if (nameCell) {
                    nameCell.setStyle({ fontStyle: 'italic' });
                }
            }
        });
    });
});

Importante

Use os valores que o getPrivileges método retorna para alterar a forma como os dados são exibidos. Não os use para impor a segurança. Power Pages impõe permissões de tabela no servidor.

  • Última atualização em