Accéder à une page générative et en revenir à l’aide de l’API cliente

Cet article fournit des exemples de navigation vers des pages générées dans des applications basées sur des modèles à l’aide d’API clientes. Découvrez comment ouvrir des pages génératives inline, dans une boîte de dialogue ou dans un volet latéral d’application ; passer des paramètres d’entrée tels qu’un ID d’enregistrement ou des données personnalisées ; et retourner des valeurs d’une boîte de dialogue au script appelant.

Note

Cette méthode est uniquement prise en charge sur Unified Interface.

Rechercher l’ID de page

Chacun des exemples suivants nécessite l’ID de la page générative cible. Pour rechercher l’ID de page :

  1. Ouvrez l’application pilotée par modèle contenant la page générative dans le concepteur d’application.
  2. Sélectionnez la page générative dans la liste des pages.
  3. Dans le volet des propriétés, copiez le GUID affiché dans le champ Page Générative.

Ouvrir une page générative inline sans paramètres

Ouvre une page générative en tant qu’affichage inline de page complète sans paramètres d’entrée.

var pageInput = {
    pageType: "generative",
    pageId: "<genPageID>"
};
var navigationOptions = {
    target: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions)
    .then(
        function () {
            // Called when page opens
        }
    ).catch(
        function (error) {
            // Handle error
        }
    );

Ouvrir une page de génération en ligne avec le contexte d'enregistrement

Passe un recordId et entityName à la page générative pour que la page puisse charger et afficher un enregistrement spécifique. Configurez la page générative cible pour accepter ces paramètres.

var pageInput = {
    pageType: "generative",
    pageId: "<genPageID>",
    entityName: "account",
    recordId: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee" // replace with actual record GUID
};
var navigationOptions = {
    target: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions)
    .then(
        function () {
            // Called when page opens
        }
    ).catch(
        function (error) {
            // Handle error
        }
    );

Ouvrir une page générative inline avec des données personnalisées

Transmet un data objet contenant des paires clé-valeur personnalisées à la page générative. Configurez la page générative cible pour accepter ces paramètres.

var pageInput = {
    pageType: "generative",
    pageId: "<genPageID>",
    data: { status: "active", category: "premium" }
};
var navigationOptions = {
    target: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions)
    .then(
        function () {
            // Called when page opens
        }
    ).catch(
        function (error) {
            // Handle error
        }
    );

Ouvrir une page générative en tant que boîte de dialogue centrée

Ouvre une page générative dans une boîte de dialogue centrée, en passant le contexte d’enregistrement et les données personnalisées. Ajustez width et height, le cas échéant.

var pageInput = {
    pageType: "generative",
    pageId: "<genPageID>",
    entityName: "account",
    recordId: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", // replace with actual record GUID
    data: { view: "summary" }
};
var navigationOptions = {
    target: 2,
    position: 1,
    width: { value: 70, unit: "%" },
    height: { value: 80, unit: "%" },
    title: "<dialog title>"
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions)
    .then(
        function (result) {
            // Called when the dialog closes.
            // result.returnValue contains the value set by dataApi.setPageOutput.
        }
    ).catch(
        function (error) {
            // Handle error
        }
    );

Ouvrir une page générative comme boîte de dialogue latérale

Ouvre une page générative en tant que boîte de dialogue latérale à l’aide de position: 2.

var pageInput = {
    pageType: "generative",
    pageId: "<genPageID>"
};
var navigationOptions = {
    target: 2,
    position: 2,
    width: { value: 500, unit: "px" },
    title: "<dialog title>"
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions)
    .then(
        function (result) {
            // Called when the dialog closes.
            // result.returnValue contains the value set by dataApi.setPageOutput.
        }
    ).catch(
        function (error) {
            // Handle error
        }
    );

Ouvrir une page générative dans un volet latéral

Utilisez Xrm.App.sidePanes.createPane() pour créer un volet latéral d’application, puis utilisez la méthode navigate du volet pour afficher une page générative.

const pane = await Xrm.App.sidePanes.createPane({
    title: "My Generative Page",
    paneId: "GenPage",
    canClose: true,
    width: 400
});

await pane.navigate({
    pageType: "generative",
    pageId: "<genPageID>",
    entityName: "account",
    recordId: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    data: { view: "summary" }
});

Dans la page générative cible, lisez ces entrées à partir de pageInput.entityName, pageInput.recordIdet pageInput.data.

Le script appelant capture les entrées lorsque vous appelez pane.navigate. La modification de l’enregistrement sélectionné dans la page appelante ne met pas automatiquement à jour une page générative ouverte. Pour mettre à jour le volet latéral, appelez pane.navigate à nouveau avec les nouvelles valeurs d’entrée.

Un volet latéral reste ouvert indépendamment du script appelant. Le retour d’une valeur par le biais d’une promise navigateTo est pris en charge pour les dialogues, mais pas pour les volets côté application.

Retourner une valeur à partir d’une boîte de dialogue de page générative

Une page générative ouverte en tant que boîte de dialogue peut retourner une valeur au script qui l’a ouvert. Dans la page générée, appelez dataApi.setPageOutput(value) avant de fermer la boîte de dialogue avec Xrm.Navigation.navigateBack().

Par exemple, la page générative peut retourner un enregistrement sélectionné :

async function handleSelection(accountId: string, accountName: string): Promise<void> {
    dataApi.setPageOutput({
        action: "selected",
        accountId,
        accountName
    });

    const xrm = (window as any).Xrm;
    await xrm.Navigation.navigateBack();
}

setPageOutput stocke la valeur, mais ne ferme pas la boîte de dialogue ni ne met à jour la page appelante. Lorsque la boîte de dialogue se ferme, la promesse retournée par Xrm.Navigation.navigateTo se résout avec un objet dont la propriété returnValue contient la valeur stockée la plus récente. Si la page ne définit pas de valeur de sortie, la fermeture de la boîte de dialogue en sélectionnant Annuler ou le bouton fermer entraîne un returnValue non défini.

Le script appelant peut traiter le résultat :

const result = await Xrm.Navigation.navigateTo(
    {
        pageType: "generative",
        pageId: "<genPageID>"
    },
    {
        target: 2,
        position: 1,
        width: { value: 70, unit: "%" },
        height: { value: 80, unit: "%" },
        title: "Select an account"
    }
);

const output = result?.returnValue;
if (
    output &&
    typeof output === "object" &&
    output.action === "selected" &&
    typeof output.accountId === "string" &&
    typeof output.accountName === "string"
) {
    console.log("Selected account: " + output.accountName);
}

Utiliser la valeur retournée dans le script de formulaire

Un script de formulaire peut accéder à la valeur retournée et l’utiliser pour mettre à jour le formulaire actif. Le renvoi d’un enregistrement à partir de la boîte de dialogue ne modifie pas automatiquement les valeurs de formulaire ou la ligne sélectionnée dans une grille. Le script appelant doit appliquer explicitement la valeur retournée.

async function openAccountSelector(executionContext) {
    const formContext = executionContext.getFormContext();

    const result = await Xrm.Navigation.navigateTo(
        {
            pageType: "generative",
            pageId: "<genPageID>"
        },
        {
            target: 2,
            position: 1,
            width: { value: 70, unit: "%" },
            height: { value: 80, unit: "%" }
        }
    );

    const output = result?.returnValue;
    if (
        output &&
        typeof output === "object" &&
        output.action === "selected" &&
        typeof output.accountId === "string" &&
        typeof output.accountName === "string"
    ) {
        const attribute = formContext.getAttribute("new_selectedaccountid");
        attribute?.setValue([
            {
                id: output.accountId,
                name: output.accountName,
                entityType: "account"
            }
        ]);

        // Call attribute.fireOnChange() if form logic must respond
        // immediately to this programmatic update.
    }
}

Naviguer à partir d’une page générative à l’aide de l’API cliente

Lorsque vous naviguez à l’intérieur d’un composant de page générative, utilisez (window as any).Xrm cette option pour accéder à l’objet Xrm, car l’étendue du composant React ne fournit pas d’accès direct à celui-ci.

Accédez à une autre page générative avec le contexte d’enregistrement et les données personnalisées

const xrm = (window as any).Xrm;
xrm.Navigation.navigateTo({
    pageType: "generative",
    pageId: targetPageId,
    entityName: "account",
    recordId: selectedRecordId,
    data: { view: "summary" }
});

Note

Lorsque vous naviguez dans des applications basées sur des modèles, évitez de construire des URL brutes ou de manipuler window.location.

Accédez à une page générative via l’URL (appelants externes uniquement)

Vous pouvez accéder à une page générative en construisant une URL avec la structure suivante :

https://<your-org>.crm.dynamics.com/main.aspx?appid={app-id}&pagetype=genux&id={page-id}&recordid={recordId}&entityname={entityName}&data={encoded-json}

Vous devez encoder le paramètre data en URL au format JSON. Par exemple, pour passer un objet de filtre personnalisé :

https://<your-org>.crm.dynamics.com/main.aspx?appid={app-id}&pagetype=genux&id={page-id}&data=%7B%22status%22%3A%22active%22%7D

Vous devez configurer la page générative cible pour accepter ces paramètres.

  • Dernière mise à jour :