APIs de clientes de Power Pages (vista previa)

[Este artigo é a documentación de prelanzamento e está suxeito a cambios.]

As APIs cliente de Power Pages axudan aos desenvolvedores a manipular compoñentes da interface, xestionar formularios e listas, xestionar a autenticación de usuarios e interactuar programáticamente cos rexistros Dataverse. A API do cliente faise dispoñible cando carga a túa páxina e pode accederse a ela a través dunha variable global co nome que escollas.

Este artigo usa o nome $pages da variable en todos os exemplos e recomenda que sigas esta convención de nomes para maior coherencia.

Coas APIs do cliente, podes:

Coa $pages API do cliente, podes:

• Recuperar e modificar formularios e controis de formularios
• Mostrar ou ocultar elementos da interface de usuario
• Crea e recupera rexistros usando a API web
• Xestionar a autenticación de usuarios
• Traballo con contido multilingüe

Inicialización da API do cliente

A $pages API do cliente non se inicializa inmediatamente cando carga a páxina. Usa a Microsoft.Dynamic365.Portal.onPagesClientApiReady función para asignar o obxecto API á $pages variable. Hai dúas formas de inicializar a API do cliente:

Preparación de API baseada en devolución de chamada

Usa unha función de chamada que asigne o obxecto API a unha variable que definas cando estea lista. Dous exemplos amosan como:

Usando unha función anónima:

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

Usando unha función nomeada:

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

Microsoft.Dynamic365.Portal.onPagesClientApiReady(start)

Preparación da API baseada en promesa/espera

Os usos await para xestionar a promesa devolta pola Microsoft.Dynamic365.Portal.onPagesClientApiReady función para un fluxo asincrónico máis limpo.

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

Cando utilizar cada enfoque

A seguinte táboa describe cando usar cada enfoque.

Colección $pages.currentPage.forms

A $pages.currentPage.forms colección inclúe métodos para traballar cos elementos da forma na páxina.

$pages.currentPage.forms métodos

Usa estes métodos para listar formularios e obter instancias específicas de formularios.

Exemplos de métodos $pages.currentPage.forms

Estes exemplos mostran como obter todos os formularios e recuperar formularios específicos por ID ou nome.

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

Interface IForm

A IForm interface representa un contedor para controis e pestanas.

Propiedades IForm

As seguintes propiedades describen o formulario e os seus controis e pestanas contidos.

Métodos IForm

Usa estes métodos para consultar a visibilidade dun formulario e cambiar se é visible.

Exemplo IForm

O seguinte exemplo recupera un formulario por ID e rexistra a súa visibilidade, número de controis e pestanas.

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

Formulario con varios pasos

Unha forma multipaso é un contedor que contén múltiples formas básicas.

Propiedades da forma multipaso

As seguintes propiedades aplícanse ao contedor de formulario multipaso e describen o que está dispoñible no paso actualmente activo.

Métodos de forma multipaso

Usa estes métodos para comprobar a visibilidade e moverte entre pasos en forma de varios pasos.

Exemplo de forma multipaso

Este exemplo mostra como recuperar un formulario de varios pasos, inspeccionalo e avanzar ao seguinte paso.

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

Tabulador

A Tab contén unha ou máis seccións dentro dun formulario.

Propiedade tab Sections

Un conxunto de seccións dentro da pestana.

Métodos de tabulación

Usa estes métodos para comprobar a visibilidade dunha pestana, recuperar o seu nome e cambiar se é visible.

Exemplo de tabulación

Este exemplo recupera un formulario, enumera as súas pestanas e rexistra o nome da primeira pestana.

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

Sección

As seccións agrupan os controis dentro dunha pestana.

Propiedade de sección Controls

Un conxunto de controis dentro da sección.

Métodos de sección

Usa estes métodos para ler o nome dunha sección e controlar a súa visibilidade.

Exemplo de sección

Este exemplo recupera seccións da primeira pestana dun formulario e rexistra detalles básicos.

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

Control

Os controis representan elementos individuais da forma.

Métodos de control

Usa estes métodos para recuperar ou actualizar o valor, visibilidade e estado desactivado dun control.

Exemplo de control

Este exemplo obtén un formulario, comproba a visibilidade do primeiro control e logo agochao.

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.  
}

Controis soportados

Todos os controis implementan os métodos estándar de control. Algúns controis proporcionan máis métodos e teñen detalles de implementación diferentes dos métodos de control estándar. Aprende sobre outros métodos e as diferenzas de implementación para diferentes tipos de controis.

$pages.currentPage.lists colección

A colección de listas ofrece métodos para traballar con elementos tradicionais e modernos da lista na páxina.

$pages.currentPage.lists métodos

Usa estes métodos para enumerar todas as listas da páxina e obter unha lista específica polo seu ID de elemento HTML.

Exemplos de $pages.currentPage.lists

Estes exemplos mostran como enumerar todas as listas na páxina e obter unha lista específica polo seu ID de elemento HTML.

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

Interface IList

Unha lista representa un compoñente de datos tabular ou en forma de grella.

Propiedades IList

Estas propiedades identifican a lista e indican se usa o modelo moderno de renderizado.

Métodos IList

Usa estes métodos para comprobar a visibilidade da lista, cambiar se é visible e acceder ao elemento HTML subxacente.

Exemplo IList

O seguinte exemplo recupera unha lista por ID e rexistra o seu estado de visibilidade.

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

$pages.obxecto usuario

O $pages.user obxecto proporciona métodos para iniciar ou desconectar ao usuario.

Métodos $pages.user

Estes métodos non achegan ningún valor.

$pages.webAPI obxecto

O $pages.webAPI obxecto proporciona métodos para crear e recuperar rexistros dunha fonte de datos.

Método createRecord

Crea un novo rexistro na táboa especificada.

Sintaxe: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<object>
Devolucións: Unha promesa que se resolve ao rexistro creado ou resultado da operación.

Parámetros do método createRecord

Proporciona a táboa de destino e o obxecto de datos que representa o rexistro para crear.

Exemplo do método createRecord

Este exemplo demostra chamar createRecord cun nome de conxunto de entidade e un obxecto de datos mínimo.

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

método retrieveRecord

Recupera un rexistro polo seu identificador único.

Sintaxe: $pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
Devolucións: Unha promesa que se resolve ao obxecto rexistrado.

Parámetros do método retrieveRecord

Especifica a táboa, o ID do rexistro e opcións opcionais de consulta OData $select para dar forma á resposta.

Exemplo do método retrieveRecord

Este exemplo recupera un único rexistro por ID e limita as columnas retornadas usando unha opción de consulta OData $select .

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

método retrieveMultipleRecords

Recupera múltiples rexistros baseándose nas opcións de consulta proporcionadas.

Sintaxe: $pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
Devolucións: Unha Promesa que resolve a un conxunto de obxectos de rexistro.

Parámetros do método retrieveMultipleRecords

Especificar a táboa e a consulta opcional de OData para filtrar os resultados e limitar as columnas retornadas.

Exemplo do método retrieveMultipleRecords

Este exemplo recupera múltiples rexistros e usa OData $select para $top limitar as columnas retornadas e o número de filas.

let records = await $pages.webAPI.retrieveMultipleRecords('accounts','$select=name&$top=3');

$pages.idiomas

O $pages.languages obxecto proporciona métodos para recuperar a lista de linguas dispoñibles para o sitio web, obter a linguaxe actualmente activa e configurar unha nova linguaxe activa.

$pages.métodos de linguas

Usa estes métodos para ler os idiomas dispoñibles, comprobar o idioma actual e cambialo para o sitio.

Exemplos de métodos $pages.languages

Estes exemplos mostran como listar todas as linguas, ler a linguaxe activa e establecer unha nova linguaxe activa.

let allLanguages = $pages.languages.getAll();
let activeLanguage = $pages.languages.getActive();
$pages.languages.setActive('hi-IN');

$pages.axente

O obxecto $pages.agent proporciona métodos para establecer comunicación entre o sitio e o axente Microsoft Copilot Studio dispoñible para o usuario actual.

$pages.agent.SendActivity(
    agentSchemaName: string,
    inputActivity: object,
    responseSubscriber: function,
    errorSubscriber: function
);

Tipo de retorno: void - A función non devolve nada.

Obxecto de resposta do axente recibido no seguinte formato:

Exemplo

Método de chamada de retorno

Define as responseSubscriber funcións e errorSubscriber callback para xestionar as respostas e erros dos axentes.

const responseSubscriber = (response) => {  
// Replace with your response handling.
console.log('Agent response:', response);
};

const errorSubscriber = (error) => {
// Replace with your error handling.
console.error('Error:', error);
};  

// Replace with your agent schema name.
const agentSchemaName = 'agent SchemaName';  

Enviar mensaxe ao axente

const inputActivity = {
    text: 'Hello!', // Message to the agent.
    };

$pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, 
  ErrorSubscriber);

Invocar evento cliente

const inputActivity = {
    name: 'AgentEvent', // The name of the event to be invoked
    value: {key1:'value1', key2:'value2'} // Open-ended value used to carry additional data or payloads necessary for specific agent operations or responses
    };

$pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, 
  ErrorSubscriber);

Mensaxes de erro

Aquí tes posibles mensaxes de erro que os usuarios poden atopar e as súas posibles causas.