Power Pages Client-API's (preview)

Dit artikel is documentatie voorafgaand aan de release en kan nog wijzigen.

Power Pages client-API's helpen ontwikkelaars bij het bewerken van UI-onderdelen, het beheren van formulieren en lijsten, het afhandelen van gebruikersverificatie en het programmatisch werken met Dataverse-records. De client-API wordt beschikbaar wanneer uw pagina wordt geladen en kan worden geopend via een globale variabele met een naam die u kiest.

In dit artikel wordt de naam $pages van de variabele in alle voorbeelden gebruikt en wordt u aangeraden deze naamconventie te volgen voor consistentie.

Met de client-API's kunt u het volgende doen:

Met de $pages client-API kunt u het volgende doen:

• Formulieren en formulierbesturingselementen ophalen en wijzigen
• UI-elementen weergeven of verbergen
• Records maken en ophalen met behulp van de web-API
• Gebruikersverificatie beheren
• Werken met meertalige inhoud

Initialisatie van client-API

De $pages client-API wordt niet onmiddellijk geïnitialiseerd wanneer de pagina wordt geladen. Gebruik de Microsoft.Dynamic365.Portal.onPagesClientApiReady functie om het API-object toe te wijzen aan de $pages variabele. Er zijn twee manieren om de client-API te initialiseren:

Gereedheid voor callback-API

Gebruik een callback-functie waarmee het API-object wordt toegewezen aan een variabele die u definieert wanneer deze gereed is. In twee voorbeelden ziet u hoe:

Met behulp van een anonieme functie:

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

Met behulp van een benoemde functie:

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

Microsoft.Dynamic365.Portal.onPagesClientApiReady(start)

Gereedheid voor promise/await-gebaseerde API

Gebruikt wacht op het afhandelen van de belofte die door de Microsoft.Dynamic365.Portal.onPagesClientApiReady functie wordt geretourneerd voor een schonere asynchrone stroom.

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

Wanneer moet u elke benadering gebruiken

In de volgende tabel wordt beschreven wanneer u elke benadering gebruikt.

$pages.currentPage.forms-verzameling

De $pages.currentPage.forms verzameling bevat methoden voor het werken met formulierelementen op de pagina.

methoden $pages.currentPage.forms

Gebruik deze methoden om formulieren weer te geven en specifieke formulierexemplaren op te halen.

$pages.currentPage.forms-methodevoorbeelden

Deze voorbeelden laten zien hoe u alle formulieren ophaalt en specifieke formulieren op id of naam ophaalt.

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

IForm-interface

De IForm interface vertegenwoordigt een container voor besturingselementen en tabbladen.

IForm-eigenschappen

In de volgende eigenschappen worden het formulier en de bijbehorende besturingselementen en tabbladen beschreven.

IForm-methoden

Gebruik deze methoden om een query uit te voeren op de zichtbaarheid van een formulier en om te schakelen of het zichtbaar is.

Voorbeeld van IForm

In het volgende voorbeeld wordt een formulier opgehaald op basis van id en worden de zichtbaarheid, het aantal besturingselementen en tabbladen geregistreerd.

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

Formulier voor meerdere stappen

Een formulier met meerdere taken is een container met meerdere basisformulieren.

Eigenschappen van formulier met meerdere taken

De volgende eigenschappen zijn van toepassing op de formuliercontainer met meerdere stappen en beschrijven wat er beschikbaar is in de huidige actieve stap.

Multistep-formuliermethoden

Gebruik deze methoden om de zichtbaarheid te controleren en te schakelen tussen stappen in een formulier met meerdere stappen.

Voorbeeld van multistep-formulier

In dit voorbeeld ziet u hoe u een formulier met meerdere stappen ophaalt, inspecteert en verder gaat met de volgende stap.

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

Tab

Een Tab bevat een of meer secties in een formulier.

Tab-eigenschap Sections

Een matrix met secties op het tabblad.

Tabmethoden

Gebruik deze methoden om de zichtbaarheid van een tabblad te controleren, de naam op te halen en te schakelen of deze zichtbaar is.

Tabbladvoorbeeld

In dit voorbeeld wordt een formulier opgehaald, de bijbehorende tabbladen opgesomd en de naam van het eerste tabblad geregistreerd.

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

Afdeling

Secties groep besturingselementen binnen een tabblad.

Sectie-eigenschap Controls

Een matrix met besturingselementen in de sectie.

Sectiemethoden

Gebruik deze methoden om de naam van een sectie te lezen en de zichtbaarheid ervan te beheren.

Sectievoorbeeld

In dit voorbeeld worden secties opgehaald van het eerste tabblad van een formulier en logboeken met basisdetails.

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

Besturingselement

Besturingselementen vertegenwoordigen afzonderlijke formulierelementen.

Besturingsmethoden

Gebruik deze methoden om de waarde, zichtbaarheid en uitgeschakelde status van een besturingselement op te halen of bij te werken.

Voorbeeld van besturingselement

In dit voorbeeld wordt een formulier opgehaald, de zichtbaarheid van het eerste besturingselement gecontroleerd en vervolgens verborgen.

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

Ondersteunde besturingselementen

Alle besturingselementen implementeren de standaardbesturingsmethoden. Sommige besturingselementen bieden meer methoden en hebben verschillende implementatiedetails van de standaardbeheermethoden. Meer informatie over andere methoden en implementatieverschillen voor verschillende typen besturingselementen.

$pages.currentPage.lists collection

De lijstenverzameling biedt methoden om te werken met traditionele en moderne lijstelementen op de pagina.

methoden $pages.currentPage.lists

Gebruik deze methoden om alle lijsten op de pagina op te sommen en een specifieke lijst op te halen op basis van de HTML-element-id.

voorbeelden van $pages.currentPage.lists

In deze voorbeelden ziet u hoe u alle lijsten op de pagina opsommen en een specifieke lijst op basis van de HTML-element-id opgeeft.

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

IList-interface

Een lijst vertegenwoordigt een gegevensonderdeel in tabelvorm of rasterachtig.

IList-eigenschappen

Deze eigenschappen identificeren de lijst en geven aan of het moderne renderingmodel wordt gebruikt.

IList-methoden

Gebruik deze methoden om de zichtbaarheid van lijsten te controleren, te schakelen of deze zichtbaar is en toegang te krijgen tot het onderliggende HTML-element.

Voorbeeld van IList

In het volgende voorbeeld wordt een lijst opgehaald op basis van id en wordt de zichtbaarheidsstatus geregistreerd.

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

$pages.user-object

Het $pages.user object biedt methoden voor het aanmelden van de gebruiker in of uit.

$pages.user-methoden

Deze methoden retourneren geen waarde.

$pages.webAPI-object

Het $pages.webAPI object biedt methoden voor het maken en ophalen van records uit een gegevensbron.

methode createRecord

Hiermee maakt u een nieuwe record in de opgegeven tabel.

Syntaxis: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<object>
Retourneert: Een belofte die wordt omgezet in het gemaakte record- of bewerkingsresultaat.

parameter createRecord-methode

Geef de doeltabel en het gegevensobject op dat de record vertegenwoordigt die moet worden gemaakt.

voorbeeld van createRecord-methode

In dit voorbeeld ziet u het aanroepen createRecord met een naam van een entiteitsset en een minimaal gegevensobject.

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

methode retrieveRecord

Haalt een record op met de unieke id.

Syntaxis: $pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
Retourneert: Een belofte die wordt omgezet in het recordobject.

methodeparameters retrieveRecord

Geef de tabel, record-id en optionele OData-queryopties $select op om het antwoord vorm te geven.

voorbeeld van methode retrieveRecord

In dit voorbeeld wordt één record opgehaald op basis van id en worden de geretourneerde kolommen beperkt met behulp van een OData-queryoptie $select .

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

methode retrieveMultipleRecords

Hiermee worden meerdere records opgehaald op basis van de opgegeven queryopties.

Syntaxis: $pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
Retourneert: Een belofte die wordt omgezet in een matrix met recordobjecten.

methodeparameters retrieveMultipleRecords

Geef de tabel en optionele OData-query op om resultaten te filteren en geretourneerde kolommen te beperken.

voorbeeld van methode retrieveMultipleRecords

In dit voorbeeld worden meerdere records opgehaald en OData $select gebruikt en $top om het aantal geretourneerde kolommen en rijen te beperken.

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

$pages.languages

Het $pages.languages object biedt methoden voor het ophalen van de lijst met beschikbare talen voor de website, het ophalen van de huidige actieve taal en het instellen van een nieuwe actieve taal.

methoden voor $pages.talen

Gebruik deze methoden om de beschikbare talen te lezen, de huidige taal te controleren en deze voor de site te wijzigen.

$pages.languages-methodevoorbeelden

In deze voorbeelden ziet u hoe u alle talen weergeeft, de actieve taal leest en een nieuwe actieve taal instelt.

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

$pages.agent

Het object $pages.agent biedt methoden voor het tot stand brengen van communicatie tussen de site en de Microsoft Copilot Studio-agent die beschikbaar is voor de huidige gebruiker.

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

Retourtype: void - De functie retourneert niets.

Antwoordobject van agent ontvangen in de volgende indeling:

Example

Callbackmethode

Definieer de functies en errorSubscriber callback voor het responseSubscriber afhandelen van agentreacties en -fouten.

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

Bericht verzenden naar agent

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

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

Client-gebeurtenis aanroepen

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

Foutberichten

Hier volgen mogelijke foutberichten die gebruikers kunnen tegenkomen en hun mogelijke oorzaken.