Power Pages klientských rozhraní API (Preview)

[Tento článek je předběžným vydáním dokumentace a může se změnit.]

Power Pages klientská rozhraní API pomáhají vývojářům manipulovat s komponentami uživatelského rozhraní, spravovat formuláře a seznamy, zpracovávat ověřování uživatelů a interagovat s záznamy Dataverse prostřednictvím kódu programu. Rozhraní API klienta bude k dispozici, když se stránka načte a bude k němu možné přistupovat prostřednictvím globální proměnné s názvem, který zvolíte.

Tento článek používá název $pages proměnné v různých příkladech a doporučuje postupovat podle této konvence vytváření názvů pro konzistenci.

Pomocí klientských rozhraní API můžete:

Pomocí klientského $pages rozhraní API můžete:

• Načtení a úprava formulářů a ovládacích prvků formulářů
• Zobrazení nebo skrytí prvků uživatelského rozhraní
• Vytvoření a načtení záznamů pomocí webového rozhraní API
• Správa ověřování uživatelů
• Práce s vícejazyčným obsahem

Inicializace rozhraní API klienta

Rozhraní $pages API klienta se při načtení stránky neinicializuje okamžitě. Microsoft.Dynamic365.Portal.onPagesClientApiReady Pomocí funkce přiřaďte objekt rozhraní API proměnné$pages. Existují dva způsoby, jak inicializovat rozhraní API klienta:

Připravenost rozhraní API založené na zpětném volání

Použijte funkci zpětného volání, která přiřadí objekt rozhraní API proměnné, kterou definujete, když je připravená. Dva příklady ukazují, jak:

Pomocí anonymní funkce:

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

Pomocí pojmenované funkce:

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

Microsoft.Dynamic365.Portal.onPagesClientApiReady(start)

Připravenost rozhraní API na základě příslibu nebo očekávání

Pomocí operátoru await zpracuje příslib vrácený Microsoft.Dynamic365.Portal.onPagesClientApiReady funkcí pro čistější asynchronní tok.

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

Kdy použít jednotlivé přístupy

Následující tabulka popisuje, kdy použít jednotlivé přístupy.

kolekce $pages.currentPage.forms

Kolekce $pages.currentPage.forms obsahuje metody pro práci s prvky formuláře na stránce.

metody $pages.currentPage.forms

Pomocí těchto metod můžete vypsat formuláře a získat konkrétní instance formulářů.

příklady metod $pages.currentPage.forms

Tyto příklady ukazují, jak získat všechny formuláře a načíst konkrétní formuláře podle ID nebo názvu.

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

IForm – rozhraní

Rozhraní IForm představuje kontejner pro ovládací prvky a karty.

Vlastnosti IForm

Následující vlastnosti popisují formulář a jeho obsažené ovládací prvky a karty.

Metody IForm

Pomocí těchto metod můžete dotazovat viditelnost formuláře a přepínat, jestli je viditelný.

Příklad IForm

Následující příklad načte formulář podle ID a zaznamená jeho viditelnost, počet ovládacích prvků a karty.

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

Formulář s více kroky

Vícekrokový formulář je kontejner, který obsahuje více základních formulářů.

Vlastnosti formuláře s více kroky

Následující vlastnosti platí pro kontejner vícekrokového formuláře a popisují, co je k dispozici v aktuálně aktivním kroku.

Vícekrokové metody formulářů

Pomocí těchto metod můžete zkontrolovat viditelnost a přecházet mezi kroky ve vícekrokovém formuláři.

Příklad formuláře s více kroky

Tento příklad ukazuje, jak načíst formulář s více kroky, zkontrolovat ho a přejít k dalšímu kroku.

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

A Tab obsahuje jeden nebo více oddílů ve formuláři.

Vlastnost tabulátoru Sections

Pole oddílů na kartě

Metody tabulátoru

Pomocí těchto metod můžete zkontrolovat viditelnost karty, načíst jeho název a přepnout, jestli je viditelná.

Příklad tabulátoru

Tento příklad načte formulář, vyčíslí jeho karty a zaznamená název první karty.

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

Oddíl

Oddíly seskupují ovládací prvky na kartě.

Controls Section – vlastnost

Pole ovládacích prvků v rámci oddílu

Metody oddílů

Pomocí těchto metod můžete přečíst název oddílu a řídit jeho viditelnost.

Příklad oddílu

Tento příklad načte oddíly z první karty formuláře a zaznamenává základní podrobnosti.

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

Ovládací prvek

Ovládací prvky představují jednotlivé prvky formuláře.

Řídicí metody

Tyto metody slouží k načtení nebo aktualizaci hodnoty, viditelnosti a zakázaného stavu ovládacího prvku.

Příklad ovládacího prvku

Tento příklad načte formulář, zkontroluje viditelnost prvního ovládacího prvku a pak ho skryje.

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

Podporované ovládací prvky

Všechny ovládací prvky implementují standardní metody řízení. Některé ovládací prvky poskytují více metod a mají různé podrobnosti implementace od standardních kontrolních metod. Seznamte se s dalšími metodami a rozdíly v implementaci pro různé typy ovládacích prvků.

kolekce $pages.currentPage.lists

Kolekce seznamů poskytuje metody pro práci s tradičními a moderními prvky seznamu na stránce.

metody $pages.currentPage.lists

Tyto metody slouží k vytvoření výčtu všech seznamů na stránce a získání konkrétního seznamu podle ID elementu HTML.

příklady $pages.currentPage.lists

Tyto příklady ukazují, jak vytvořit výčet všech seznamů na stránce a získat konkrétní seznam podle ID elementu HTML.

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

IList – rozhraní

Seznam představuje tabulkovou nebo mřížkovou datovou komponentu.

Vlastnosti IList

Tyto vlastnosti identifikují seznam a označují, jestli používá moderní model vykreslování.

Metody IList

Pomocí těchto metod můžete zkontrolovat viditelnost seznamu, přepnout, jestli je viditelný, a získat přístup k podkladovému elementu HTML.

Příklad IList

Následující příklad načte seznam podle ID a zaznamená jeho stav viditelnosti.

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

objekt $pages.user

Objekt $pages.user poskytuje metody pro přihlášení nebo odhlášení uživatele.

metody $pages.user

Tyto metody nevrací žádnou hodnotu.

objekt $pages.webAPI

Objekt $pages.webAPI poskytuje metody pro vytváření a načítání záznamů ze zdroje dat.

createRecord – metoda

Vytvoří nový záznam v zadané tabulce.

Syntaxe: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<object>
Vrátí: Příslib , který se přeloží na vytvořený záznam nebo výsledek operace.

createRecord – parametry metody

Zadejte cílovou tabulku a datový objekt představující záznam, který se má vytvořit.

createRecord – příklad metody

Tento příklad ukazuje volání createRecord s názvem sady entit a minimálním datovým objektem.

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

metoda retrieveRecord

Načte záznam podle jeho jedinečného identifikátoru.

Syntaxe: $pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
Vrátí: Příslib , který se přeloží na objekt záznamu.

retrieveRecord – parametry metody

Zadejte tabulku, ID záznamu a volitelné možnosti dotazu OData $select pro tvarování odpovědi.

příklad metody retrieveRecord

Tento příklad načte jeden záznam podle ID a omezí vrácené sloupce pomocí možnosti dotazu OData $select .

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

metoda retrieveMultipleRecords

Načte více záznamů na základě zadaných možností dotazu.

Syntaxe: $pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
Vrátí: Příslib , který se přeloží na pole objektů záznamů.

retrieveMultipleRecords – parametry metody

Zadejte tabulku a volitelný dotaz OData pro filtrování výsledků a omezení vrácených sloupců.

příklad metody retrieveMultipleRecords

Tento příklad načte více záznamů a používá OData $select a $top omezuje počet vrácených sloupců a řádků.

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

$pages.languages

Objekt $pages.languages poskytuje metody pro načtení seznamu dostupných jazyků pro web, získání aktuálně aktivního jazyka a nastavení nového aktivního jazyka.

metody $pages.languages

Tyto metody slouží ke čtení dostupných jazyků, kontrole aktuálního jazyka a změně webu.

Příklady metod $pages.languages

Tyto příklady ukazují, jak zobrazit seznam všech jazyků, číst aktivní jazyk a nastavit nový aktivní jazyk.

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

$pages.agent

Objekt $pages.agent poskytuje metody pro navázání komunikace mezi lokalitou a agentem Microsoft Copilot Studio dostupným aktuálnímu uživateli.

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

Návratový typ: void – funkce nic nevrací.

Objekt odpovědi od agenta přijatý v následujícím formátu:

Příklad

Metoda zpětného volání

Definujte funkce zpětného responseSubscribererrorSubscriber volání pro zpracování odpovědí a chyb agenta.

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

Odeslání zprávy agentu

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

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

Vyvolání události klienta

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

Chybové zprávy

Tady jsou možné chybové zprávy, se kterými se můžou uživatelé setkat, a jejich potenciální příčiny.