Client-API-Listen

Verwenden Sie Power Pages Client-API-Listen, um auf herkömmliche und moderne Listen zuzugreifen und diese anzupassen. In dieser Referenz wird erläutert, wie Sie mit Zeilen, Spalten, Zellen, Sichtbarkeit und Listenereignissen arbeiten.

$pages.currentPage.lists

Die Listenauflistung stellt Methoden zum Arbeiten mit herkömmlichen und modernen Listenelementen auf der Seite bereit.

methoden "$pages.currentPage.lists"

Verwenden Sie diese Methoden, um alle Listen auf der Seite auflisten und eine bestimmte Liste anhand der HTML-Element-ID abzurufen.

Methode Rückgabe Description
getAll Ilist[] Gibt alle Listen auf der aktuellen Seite zurück.
getListById(id: string) IList Ruft eine Liste anhand der HTML-Element-ID ab.

Beispiele für $pages.currentPage.lists

In diesen Beispielen wird gezeigt, wie Sie alle Listen auf der Seite aufzählen und eine bestimmte Liste anhand der HTML-Element-ID abrufen.

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

IList-Schnittstelle

Eine Liste stellt eine tabellarische oder rasterähnliche Datenkomponente dar.

IList-Eigenschaften

Diese Eigenschaften identifizieren die Liste und geben an, ob das moderne Renderingmodell verwendet wird.

Eigentum Type Description
id string Der eindeutige Bezeichner der Liste.
isModern boolesch Ein boolescher Wert, der für moderne Listen und andernfalls "false" zutrifft.
rows IRow[] Die Zeilen, die die Liste zurzeit veröffentlicht. Jedes Mal, wenn Sie diese Eigenschaft lesen, werden die neuesten Daten zurückgegeben. Lesen Sie sie also in einem loaded Ereignishandler, um sicherzustellen, dass die Daten verfügbar sind.
columns IColumn[] Die Spalten in der aktuellen Ansicht der Liste.

Note

Die und columns die rows Eigenschaften, die getColumn, onund off Methoden und alles, was sie zurückgeben, werden nur in modernen Listen unterstützt, wobei isModern wahr ist. In einer herkömmlichen Liste können sie sicher anrufen, aber nichts tun: rows und columns leere Arrays zurückgeben, getColumn nicht definiert und onoff nichts tun. Überprüfen Sie isModern , bevor Sie auf Listendaten zugreifen, oder verwenden Sie das loaded Ereignis, das nie für eine herkömmliche Liste auftritt.

IList-Methoden

Verwenden Sie diese Methoden, um die Listensichtbarkeit zu überprüfen, zu wechseln, ob es sichtbar ist, auf das zugrunde liegende HTML-Element zuzugreifen und mit Spalten und Ereignissen zu arbeiten.

Methode Rückgabe Description
getVisible boolean Gibt true zurück, wenn die Liste sichtbar ist.
setVisible(isVisible: boolean) void Legt die Sichtbarkeit der Liste fest.
getHtmlElement HTMLElement Gibt das zugrunde liegende HTML-Element für die Liste zurück.
getColumn(logicalName: string) IColumn | undefined Gibt die Spalte mit dem angegebenen logischen (Schema)-Namen zurück. Gibt nicht definiert zurück, wenn keine Spalten übereinstimmen.
on(event: string, handler: function) void Abonniert einen Handler für ein Listenereignis. Siehe Listenereignisse. Das Abonnieren desselben Handlers für dasselbe Ereignis hat mehr als einmal keine Auswirkung.
off(event: string, handler: function) void Gekündigt einen Handler, der bei on. Übergeben Sie denselben Funktionsverweis, an den Sie übergeben haben on. Ein anderer Verweis gekündigt den Handler nicht.

IList-Beispiel

Das folgende Beispiel ruft eine Liste nach ID ab, protokolliert den Sichtbarkeitsstatus und liest seine Daten, wenn das Raster geladen wird.

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

    // Modern list data is available only after the grid loads, so read it in a `loaded` handler.
    if (list.isModern) {
        list.on('loaded', () => {
            console.log(`List has ${list.rows.length} rows and ${list.columns.length} columns.`);
        });
    }
});

IRow-Schnittstelle

Die IRow Schnittstelle stellt eine einzelne Zeile in einer modernen Liste dar. Dient zum Abrufen einer Zeile aus der list.rows Eigenschaft oder aus einer Listenereignisnutzlast .

Die Methoden, die mit get der Rückgabe der Daten beginnen, die das Raster veröffentlicht hat. Die anderen Methoden legen fest, wie die Zeile angezeigt wird, z. B. formatieren, Klassennamen und Sichtbarkeit. Das Raster wendet diese Einstellungen an, wenn sie die Zeile rendert. Durch das Ausblenden einer Zeile wird nur die Darstellung der Zeile geändert; die zugrunde liegenden Daten werden nicht geändert.

IRow-Methoden

Verwenden Sie diese Methoden, um die Daten einer Zeile zu lesen und die Darstellung der Zeile zu ändern.

Methode Rückgabe Description
getId string Gibt die Dataverse-Datensatz-ID der Zeile als GUID-Zeichenfolge zurück.
getValue(logicalName: string) string | number | boolean | Date | null Gibt einen unformatierten Zeichenfolgen-, Zahlen-, booleschen, gültigen Datums- oder numerischen Optionswert für die Spalte zurück, die den angegebenen logischen (Schema)-Namen enthält. Gibt NULL zurück, wenn sich die Spalte nicht in der Zeile befindet oder der rohe Wert ein nicht unterstützter komplexer Wert ist, einschließlich eines nachschlageförmigen Objekts. Wird verwendet getDisplayValue , wenn der unformatierte komplexe Wert nicht verfügbar ist.
getDisplayValue(logicalName: string) string Gibt den Wert der Spalte zurück, die für das aktuelle Gebietsschema formatiert ist. Gibt eine leere Zeichenfolge zurück, wenn sich die Spalte nicht in der Zeile befindet.
getPrivileges object | undefined Gibt die Berechtigungen zurück, die der Server für den Datensatz ausgewertet hat: , , , canDelete, und . canAppendcanAppendTocanWritecanRead Gibt nicht definiert zurück, wenn der Server sie nicht bereitstellt. Verwenden Sie diese Werte, um zu ändern, wie Daten angezeigt werden, nicht um die Sicherheit zu erzwingen.
getState object | undefined Gibt die Werte und statusCode Werte stateCode des Datensatzes zurück. Gibt nicht definiert zurück, wenn der Server sie nicht bereitstellt.
setStyle(style: object) void Führt Inline-CSS-Formatvorlagen in der Zeile zusammen. Jeder Aufruf fügt die bereits festgelegten Formatvorlagen hinzu.
setClassName(className: string) void Ersetzt die CSS-Klassennamen der Zeile durch die von Ihnen angegebenen leerzeichentrennten Klassennamen.
addClassName(className: string) void Fügt der Zeile mindestens einen durch Leerzeichen getrennten CSS-Klassennamen hinzu.
removeClassName(className: string) void Entfernt einen oder mehrere durch Leerzeichen getrennte CSS-Klassennamen aus der Zeile.
setVisible(visible: boolean) void Blendet die Zeile ein oder aus. Diese Methode ändert nur, wie die Zeile angezeigt wird.
getCell(logicalName: string) ICell Gibt ein Handle zurück, das Sie verwenden, um zu ändern, wie eine der Zellen der Zeile angezeigt wird.

IRow-Beispiel

In diesem Beispiel werden abgebrochene Datensätze hervorgehoben und inaktive Datensätze ausgeblendet.

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

    list.on('loaded', () => {
        list.rows.forEach((row) => {
            // Highlight canceled records where statuscode is 6.
            if (row.getValue('statuscode') === 6) {
                row.setStyle({ backgroundColor: '#fde7e9', color: '#a80000' });
            }
            // Hide inactive records where statecode is 1.
            if (row.getValue('statecode') === 1) {
                row.setVisible(false);
            }
        });
    });
});

IColumn-Schnittstelle

Die IColumn Schnittstelle stellt eine einzelne Spalte in einer modernen Liste dar. Dient zum Abrufen einer Spalte aus der list.columns Eigenschaft oder aus der list.getColumn Methode. Sie können die Kopfzeile, Sichtbarkeit und QuickInfo unabhängig voneinander festlegen.

Die get Methoden geben die Quelldaten und nicht die von Ihnen festgelegten Werte zurück. Gibt beispielsweise getDisplayName den konfigurierten Anzeigenamen auch nach dem Aufruf setHeaderzurück, genau wie row.getDisplayValue der Wert, den der Server selbst nach dem Aufruf cell.setDisplayTextformatiert hat. Dieses Verhalten sorgt dafür, dass Ihr Code mehr als einmal ausgeführt werden kann, da der loaded Handler jedes Mal erneut ausgeführt wird, wenn die Liste Daten abruft, sortiert, filtert oder seitent. Erzeugt beispielsweise jedes Mal dasselbe Ergebnis, column.setHeader(column.getDisplayName() + ' *') anstatt ein weiteres Sternchen hinzuzufügen. Lesen Sie den Quellwert, und leiten Sie dann den von Ihnen festgelegten Wert ab.

IColumn-Methoden

Verwenden Sie diese Methoden, um die Namen einer Spalte zu lesen und die Darstellung der Spalte zu ändern.

Methode Rückgabe Description
getLogicalName string Gibt den logischen (Schema)-Namen der Spalte zurück.
getDisplayName string Gibt den konfigurierten Anzeigenamen der Spalte zurück. setHeader ändert diesen Wert nicht.
setHeader(header: string) void Überschreibt den Text in der Spaltenüberschrift.
setVisible(visible: boolean) void Blendet die gesamte Spalte ein oder aus.
setTooltip(tooltip: string) void Legt die QuickInfo für die Spaltenüberschrift fest. Die QuickInfo wird angezeigt, wenn jemand über die Kopfzeile bewegt wird, und Bildschirmsprachausgaben verwenden sie als barrierefreien Namen der Kopfzeile.

IColumn-Beispiel

In diesem Beispiel wird der Kopfzeilentext und die QuickInfo für eine Spalte festgelegt.

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

    list.on('loaded', () => {
        const column = list.getColumn('name');
        if (column) {
            column.setHeader('Account name');
            column.setTooltip('The primary name of the account');
        }
    });
});

ICell-Schnittstelle

Die ICell Schnittstelle stellt eine einzelne Zelle dar, bei der es sich um die Schnittmenge einer Zeile und einer Spalte handelt. Rufen Sie eine Zelle aus der row.getCell Methode ab. Eine Zelle ist vom Entwurf aus schreibgeschützt. Um den Wert einer Zelle zu lesen, verwenden Sie die getValue oder getDisplayValue die Methode der Zeile , die sie enthält.

ICell-Methoden

Verwenden Sie diese Methoden, um den Text und die Formatvorlage einer Zelle zu ändern.

Methode Rückgabe Description
setDisplayText(text: string) void Ersetzt den Text, der in der Zelle angezeigt wird. Verwenden Sie diese Methode, um anzeigefreundlichen Text anstelle eines Codes anzuzeigen, einen Wert zu maskieren oder ein Signal anzuzeigen.
setStyle(style: object) void Führt inline-CSS-Formatvorlagen in der Zelle zusammen. Jeder Aufruf fügt die bereits festgelegten Formatvorlagen hinzu.

Beispiel für ICell

In diesem Beispiel wird der Text und die Formatvorlage einer Zelle in jeder Zeile geändert.

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

    list.on('loaded', () => {
        list.rows.forEach((row) => {
            const cell = row.getCell('statuscode');
            cell.setDisplayText('Active');
            cell.setStyle({ fontWeight: 'bold', backgroundColor: '#fff4ce' });
        });
    });
});

Ereignisse auflisten

Moderne Listen lösen Ereignisse aus, die Sie mithilfe der list.on Methode abonniert haben, und kündigen sie mithilfe der list.off Methode ab. Da diese Ereignisse Zeilenobjekte bereitstellen, empfiehlt es sich auch, Zeilendaten zu lesen oder zu formatieren. Die Daten sind verfügbar, nachdem das loaded Ereignis eintritt.

Event Wenn dies geschieht Nutzlast
loaded Nachdem die Liste die Zeilendaten abgerufen und veröffentlicht hat. Dieses Ereignis tritt bei jeder Aktualisierung der Liste oder seitendaten erneut auf. { rows: IRow[] }
rowclick Jemand wählt eine Zeile aus. { row: IRow, event: MouseEvent }
cellclick Jemand wählt eine Zelle aus. Wenn ein cellclick Handler registriert ist, tritt das Ereignis für diese rowclick Auswahl nicht auf. { row: IRow, columnName: string, event: MouseEvent }

Wichtig

Wenn sowohl rowclickcellclick Handler als auch Handler registriert sind, wird beim Auswählen einer Zelle nur der cellclick Handler aufgerufen. Der rowclick Handler wird nicht für dieselbe Auswahl aufgerufen.

Beispiel für Listenereignisse

In diesem Beispiel werden die Ereignisse und cellclick ereignisse rowclick abonniert.

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

    const onRowClick = (e) => {
        console.log('Selected row:', e.row.getId());
        e.row.setStyle({ outline: '2px solid #0078d4' });
    };

    list.on('rowclick', onRowClick);

    list.on('cellclick', (e) => {
        console.log('Selected cell:', e.row.getId(), 'column:', e.columnName);
        e.row.getCell(e.columnName).setStyle({ backgroundColor: '#e5f1fb' });
    });

    // Define a cleanup function, and call it when your code no longer needs
    // the events. Pass the same handler reference that you passed to the on method.
    const stopListening = () => {
        list.off('rowclick', onRowClick);
    };
});

Übergeben Sie zum Kündigen des Abonnements denselben Funktionsverweis auf die off Methode, die Sie an die on Methode übergeben haben. Ein anderer Verweis gekündigt den Handler nicht.