Konfigurieren von Berichteinstellungen

Artikel
09/17/2023

Mithilfe der Power BI-Client-APIs können Sie Power BI-Analysen in Ihre Anwendung einbetten. Wenn Sie diese clientseitige Bibliothek zum Einbetten eines Power BI-Berichts verwenden, stellen Sie der API Informationen zu diesem Bericht bereit.

Sie können ein Konfigurationsobjekt verwenden, um Informationen zu Ihrem Power BI-Bericht zu speichern. Wenn Sie den Bericht einbetten, übergeben Sie dieses Objekt dann an die API.

Sie können der API nicht nur Zugriff auf den Bericht gewähren, sie können auch das Konfigurationsobjekt verwenden, um die Darstellung und das Verhalten Des Berichts anzupassen. Für instance können Sie die Filtersichtbarkeit, den Navigationszugriff und die Positionseinstellungen im Konfigurationsobjekt anpassen.

In den folgenden Abschnitten wird erläutert, wie Sie Power BI-Inhalte einbetten und konfigurieren.

Bereitstellen von Konfigurationsinformationen

Die IReportLoadConfiguration-Schnittstelle zeigt Eigenschaften an, die ein Konfigurationsobjekt für die Power BI-Client-APIs zu einem Bericht bereitstellen kann:

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    datasetBinding?: IDatasetBinding;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

Eine Erläuterung der erforderlichen Parameter dieser Schnittstelle und Codebeispiele zum Einbetten eines Berichts finden Sie unter Einbetten eines Berichts .

Einstellungen anpassen

In den folgenden Abschnitten wird beschrieben, wie Sie die settings -Eigenschaft verwenden können, um die Darstellung und das Verhalten Ihres eingebetteten Power BI-Berichts anzupassen. Verwenden Sie report.updateSettings die -Methode, um die Berichtseinstellungen zu aktualisieren, wenn der Bericht bereits geladen ist. Weitere Informationen finden Sie unter Aktualisieren von Berichtseinstellungen zur Laufzeit.

Bereiche

Steuern Sie die Darstellung aller Bereiche in Ihrem Power BI-Bericht mit einer einzelnen panes Eigenschaft, wie im folgenden Code gezeigt:

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

In der folgenden Tabelle können Sie sehen, welche Werte die einzelnen panes Eigenschaften unterstützen:

Eigenschaft	Sichtbar	Expanded
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

Filter (Bereich)

Standardmäßig ist der Filterbereich sichtbar. Wenn Sie diesen Bereich ausblenden möchten, verwenden Sie die filterPaneEnabled -Eigenschaft, wie im folgenden Code gezeigt:

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

Hinweis

Die panes-Eigenschaft ersetzt die filterPaneEnabled -Eigenschaft. Um die Abwärtskompatibilität zu gewährleisten, ist die filterPaneEnabled -Eigenschaft weiterhin vorhanden. Sie sollten jedoch vermeiden, diese beiden Eigenschaften zusammen zu verwenden.

Standardmäßig sind die Seitennavigationspfeile in eingebetteten Berichten sichtbar. Um diese Pfeile auszublenden, verwenden Sie die navContentPaneEnabled -Eigenschaft, wie im folgenden Code gezeigt:

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

Hinweis

Die panes-Eigenschaft ersetzt die navContentPaneEnabled -Eigenschaft. Um die Abwärtskompatibilität zu gewährleisten, ist die navContentPaneEnabled -Eigenschaft weiterhin vorhanden. Sie sollten jedoch vermeiden, diese beiden Eigenschaften zusammen zu verwenden.

Der Seitennavigationsbereich wird am unteren Rand des Berichts angezeigt, um den neuen vertikalen Seitenbereich zu verwenden, können Sie die position -Eigenschaft festlegen:

let embedConfig = {
    ...
    settings: {
        panes:{
            pageNavigation: {
                visible: true,
                position: PagesPosition.Left
            }
        }    
    }
};

Hinweis

Sie können die Position des Seitennavigationsbereichs updateSettingsmit nicht ändern.

Bars

Legen Sie die Sichtbarkeit der Aktionsleiste und status Leiste mithilfe der bars -Eigenschaft fest.

Aktionsleiste

Der folgende Code macht die Aktionsleiste sichtbar:

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

Alternativ kann im Ansichtsmodus auch der URL-Parameter verwendet werden actionBarEnabled :

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

Hinweis

Im Ansichtsmodus wird die Aktionsleiste nur für die Einbettung für Ihr organization Szenario unterstützt.

Für die Aktionsleiste im Ansichtsmodus wird empfohlen, die Berechtigung für Ihre Azure AD-Anwendung zu aktivieren UserState.ReadWrite.All . Diese Berechtigung ist erforderlich, damit Endbenutzer den Bericht ihren Favoriten hinzufügen und persönliche Lesezeichen und persistente Filter aktivieren können.

Statusleiste

Die status Leiste enthält den Canvas-Zoomcontroller, der die Möglichkeit zum Zoomen der Canvas bietet.

Der folgende Code macht die status Leiste sichtbar:

let embedConfig = {
    ...
    settings: {
        bars: {
            statusBar: {
                visible: true
            }
        }
    }
};

Gebietsschemaeinstellungen

Verwenden Sie die localeSettings -Eigenschaft, um die Sprache und die Formatierung des eingebetteten Berichts anzugeben:

Die language -Eigenschaft in localeSettings besteht aus zwei Teilen von jeweils zwei Buchstaben, die durch einen Bindestrich getrennt sind:

language definiert die Sprache, die Power BI für die Lokalisierung verwendet. Beispiele für Sprachen sind en (Englisch), es (Spanisch) und tr (Türkisch).
Gebietsschema definiert die Textformatierung, die Power BI für Datumsangaben, Währungen und andere verwandte Inhalte verwendet. Beispiele für Gebietsschemas sind US (Englisch), ES (Spanien) und TR (Türkiye).

Eine Liste der verfügbaren Sprachen und Regionen finden Sie unter Unterstützte Sprachen .

Der folgende Code weist diesen localeSettingseinen bestimmten Wert zu:

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en-us"
        }
    }
};

Hinweis

Gebietsschemaeinstellungen können nach dem Laden des Berichts nicht mehr geändert werden. Um die Gebietsschemaeinstellungen des Berichts zu ändern, setzen Sie den iframe zurück, indem Sie aufrufen powerbi.reset(element), und betten Sie den Bericht dann erneut ein.

Transparenter Hintergrund

Standardmäßig ist der Hintergrund des eingebetteten Inhalts weiß mit grauen Rändern. Wenn Sie möchten, können Sie dem eingebetteten Inhalt einen transparenten Hintergrund verleihen. Anschließend können Sie den gewünschten Stil auf das HTML-Element div anwenden, das den eingebetteten Inhalt enthält. Die div Formatierung des Elements wird dann sichtbar.

Verwenden Sie diesen Code, um den Hintergrund des eingebetteten Inhalts transparent zu machen:

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

Linkklickverhalten

Sie können das Verhalten eines Links in einer Tabelle oder in vordefinierten Visuals der Matrix steuern. Standardmäßig öffnet der Link ein neues Fenster.

Die verfügbaren Verhaltensmodi sind unten aufgeführt:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate – Die URL wird in einen neuen Browserkontext geladen.
NavigateAndRaiseEvent – Die URL wird in einen neuen Browserkontext geladen und löst ein Ereignis aus dataHyperlinkClicked .
RaiseEvent – Verhindert das Standardverhalten von URL-Klick und Auslösen dataHyperlinkClicked eines Ereignisses.

Verwenden Sie diesen Code, um das Verhalten von Links zum Auslösen eines Ereignisses zu ändern:

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

Ein dataHyperlinkClicked -Ereignis wird ausgelöst, wenn auf einen Link auf eine vordefinierte Tabelle oder Matrix-Visuals geklickt wird und das Verhalten entweder NavigateAndRaiseEvent oder RaiseEventlautet.

report.on('dataHyperlinkClicked', () => {
    ...
});

Weitere Informationen zum Behandeln von Ereignissen finden Sie unter Behandeln von Ereignissen.

Visual gerenderte Ereignisse

Sie können ein Ereignis für jedes gerenderte Visual lauschen. Standardmäßig sind die visual gerenderten Ereignisse deaktiviert.

Verwenden Sie diesen Code, um die visualRendered Ereignisse auszulösen:

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

Ein visualRendered Ereignis wird ausgelöst, wenn ein Visual gerendert und in visualRenderedEvents den Berichtseinstellungen aktiviert ist.

report.on('visualRendered', () => {
    ...
});

Weitere Informationen zum Behandeln von Ereignissen finden Sie unter Behandeln von Ereignissen.

Hinweis

Da Visuals aufgrund von Benutzerinteraktionen möglicherweise gerendert werden, wird empfohlen, dieses Ereignis nur bei Bedarf zu aktivieren.

Fehlermeldungen

Wenn Sie benutzerdefinierte Fehlermeldungen in eingebetteten Berichten anzeigen möchten, verwenden Sie die hideErrors -Eigenschaft, um die in Power BI eingebetteten Standardfehlermeldungen auszublenden. Ihr Code kann dann Fehlerereignisse so behandeln, dass sie ihrem App-Design entspricht. Weitere Informationen zum Überschreiben von Standardfehlern finden Sie unter Überschreiben von Standardfehlern .

Verwenden Sie diesen Code, um Standardfehlermeldungen auszublenden:

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

Optionen anpassen

In den folgenden Abschnitten wird beschrieben, wie Sie zusätzliche Eigenschaften verwenden können, um die Darstellung und das Verhalten Ihres eingebetteten Power BI-Berichts weiter anzupassen.

Standardseite

Sie können steuern, welche Seite Ihres eingebetteten Berichts zunächst angezeigt wird. Standardmäßig ist die erste Seite die Seite, die Sie zuletzt geändert haben. Dies war die aktive Seite beim letzten Speichern des Berichts. Sie können dieses Verhalten überschreiben, indem Sie die pageName -Eigenschaft verwenden und sie mit dem Namen der Seite angeben, die Sie anzeigen möchten. Wenn jedoch keine Seite mit diesem Namen in Power BI vorhanden ist, schlägt die Anforderung zum Öffnen fehl.

Der folgende Code zeigt, wie Sie Ihre App so konfigurieren, dass eine bestimmte Seite angezeigt wird:

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

Bei Auslastungsfiltern

Sie können die Filter steuern, die Ihre App auf einen eingebetteten Bericht anwendet. Standardmäßig verwendet der Bericht zunächst die Filter, die Sie im Bericht gespeichert haben. Sie haben jedoch zwei Optionen, wenn Sie die Filter anpassen möchten:

Konfigurieren Sie zusätzliche Filter, die zusammen mit den gespeicherten Filtern verwendet werden sollen. Der folgende Code zeigt, wie Sie die filters -Eigenschaft verwenden, um zusätzliche Filter anzufügen:
```
let embedConfig = {
    ...
    filters: [...]
};
```
Ersetzen Sie die gespeicherten Filter durch einen neuen Satz. Die setFilters -Methode bietet eine Möglichkeit, die Filter eines Berichts dynamisch zu ändern. Wenn Sie diese Methode während der schrittweisen Einbettung verwenden, können Sie die Filter überschreiben, die der Bericht ursprünglich anwendet. Weitere Informationen zum Erstellen von Filtern und zum Verwenden der setFilters -Methode finden Sie unter Steuern von Berichtsfiltern.

Beim Laden von Slicern

Sie können den Status der Datenschnitte steuern, die Ihre App auf einen eingebetteten Bericht anwendet. Standardmäßig verwendet die API die Datenschnitte, die Sie im Bericht gespeichert haben. Sie können jedoch die slicers -Eigenschaft verwenden, um den Zustand der vorhandenen Datenschnitte zu ändern, wie der folgende Code veranschaulicht:

embedConfig = {
    ...
    slicers: slicerArray,
};

Weitere Informationen zum Ändern des Status eines Datenschnitts finden Sie unter Steuern von Berichtsschnitten .

Beim Laden des Lesezeichens

Mithilfe der bookmark -Eigenschaft können Sie ein Lesezeichen auf einen eingebetteten Bericht anwenden. Weitere Informationen zur Verwendung von Lesezeichen zum Erfassen der aktuell konfigurierten Ansicht von Berichtsseiten finden Sie unter Lesezeichen.

Sie können das zu verwendende Lesezeichen angeben, indem Sie entweder den Lesezeichennamen oder den Status angeben. Wenn Sie den Lesezeichennamen angeben, muss Ihr Power BI-Bericht ein gespeichertes Lesezeichen mit diesem Namen enthalten.

Die bookmark Eigenschaft ist vom Typ IApplyBookmarkRequest. Der folgende Code zeigt die Definition dieses Typs:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Dieser Code zeigt, wie Sie ein Lesezeichen nach Name angeben:

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

Dieser Code zeigt, wie Sie ein Lesezeichen nach Status angeben:

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

Designs und Modus mit hohem Kontrast

Sie können das Design und die Kontrastebene steuern, die Ihre eingebetteten Inhalte verwenden. Standardmäßig werden alle Inhalte, die Sie einbetten, mit dem Standarddesign und dem Kontrastwert null angezeigt. Sie können dieses Verhalten außer Kraft setzen, indem Sie ein bestimmtes Design oder ein bestimmtes Kontrastniveau konfigurieren. Weitere Informationen zu Designs finden Sie unter Anwenden von Berichtsdesigns.

Die verfügbaren Kontrastmodi sind unten aufgeführt:

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

Verwenden Sie Code ähnlich den folgenden Zeilen, um ein bestimmtes Design zu konfigurieren:

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

Der folgende Code zeigt, wie die Standardkontraststufe außer Kraft gesetzt wird: None

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

Hinweis

Die API kann kein Design und eine Kontrastebene gleichzeitig anwenden. Wenn Sie beide Eigenschaften konfigurieren, verwendet die API die von Ihnen angegebene Kontraststufe, ignoriert aber die theme Einstellung.

Zoomfaktor

Weitere Informationen zum Anpassen der Berichtszoomstufe finden Sie im Dokument zur Barrierefreiheit.

Öffnen im Bearbeitungsmodus

Standardmäßig wird der von Ihnen eingebettete Bericht im Ansichtsmodus angezeigt. Sie können dieses Verhalten jedoch überschreiben, um den Bericht im Bearbeitungsmodus zu öffnen. Sie können auch zwischen den Modi wechseln.

Konfigurieren des Bearbeitungsmodus

Um einen eingebetteten Bericht im Bearbeitungsmodus zu öffnen, verwenden Sie die viewMode -Eigenschaft zusammen mit der permissions -Eigenschaft.

Sie können der viewMode Eigenschaft die folgenden Werte zuweisen:

View – Öffnet den Bericht im Ansichtsmodus.
Edit – Öffnet den Bericht im Bearbeitungsmodus.

Sie können der Eigenschaft die permissions folgenden Werte zuweisen:

Read – Benutzer können den Bericht anzeigen.
ReadWrite – Benutzer können den Bericht anzeigen, bearbeiten und speichern.
Copy – Benutzer können eine Kopie des Berichts speichern, indem Sie Speichern unter verwenden.
Create – Benutzer können einen neuen Bericht erstellen.
All – Benutzer können eine Kopie des Berichts erstellen, anzeigen, bearbeiten, speichern und speichern.

Wenn Sie Inhalte für das Öffnen im Bearbeitungsmodus konfigurieren, weisen Sie der Eigenschaft einen Wert zu, der permissions für die Bearbeitung geeignet ist, wie im folgenden Code veranschaulicht:

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

Hinweis

Der permissions von Ihnen konfigurierte Wert funktioniert nur, wenn das von Ihnen erworbene Einbettungstoken über ausreichende Berechtigungen verfügt. Weitere Informationen zu Einbettungstoken finden Sie unter Erstellen des Einbettungstokens.

Wechseln zwischen Bearbeitungs- und Ansichtsmodi

Sie können nicht nur einen Modus angeben, in dem eingebettete Inhalte gestartet werden sollen, sie können auch dynamisch zwischen Bearbeitungs- und Ansichtsmodi wechseln.

Wenn sich der Inhalt im Bearbeitungsmodus befindet und Sie in den Ansichtsmodus wechseln möchten, verwenden Sie diesen JavaScript-Code:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

Wenn sich der Inhalt im Ansichtsmodus befindet und Sie in den Bearbeitungsmodus wechseln möchten, verwenden Sie diesen JavaScript-Code:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

Überlegungen und Einschränkungen

Berücksichtigen Sie beim Konfigurieren eingebetteter Inhalte die folgenden Punkte:

Die Seitennavigationsposition kann nicht geändert werden, wenn die Aktionsleiste sichtbar ist. Erfahren Sie mehr über die Aktionsleiste.
Wenn Sie die bars -Eigenschaft in der setting -Eigenschaft verwenden, wie in Bars beschrieben, wendet die API Ihre Konfiguration nur an, wenn sich der eingebettete Inhalt im Bearbeitungsmodus befindet. Wenn sich Ihre Inhalte im Ansichtsmodus befinden, ignoriert die API die bars Einstellung.
Wenn Sie die -Eigenschaft zum Anzeigen von viewMode Inhalten im Bearbeitungsmodus verwenden, müssen Sie zwei zusätzliche Schritte ausführen:
- Konfigurieren Sie eine Berechtigungsstufe mit der permissions -Eigenschaft. Diese Berechtigungsstufe muss dem Benutzer den entsprechenden Zugriff zum Ändern von Inhalten gewähren. Wenn Sie für instance einen permissions Wert des Read, Benutzers zuweisen, kann der Inhalt nicht bearbeitet werden.
- Stellen Sie sicher, dass das von Ihnen generierte Einbettungstoken Über Berechtigungen verfügt, die die Bearbeitung unterstützen. Wenn Sie instance ein Token mit einem accessLevel Wert der view, API abrufen, kann der Inhalt nicht im Bearbeitungsmodus angezeigt werden.
Die Panes-Eigenschaft ersetzt die folgenden settings Eigenschaften:
- filterPaneEnabled
- navContentPaneEnabled
Wenn Sie die -Eigenschaft zum Konfigurieren der panes Filter- oder Seitennavigationssicht verwenden, verwenden Sie nicht die filterPaneEnabled Eigenschaft oder navContentPaneEnabled in Ihrer App.
Die API kann kein Design und keine Kontrastebene gleichzeitig auf eingebettete Inhalte anwenden. Wenn Sie beide Optionen mit der theme - und contrastMode -Eigenschaft konfigurieren, verwendet die API Ihren contrastMode Wert mit dem eingebetteten Inhalt. Die API ignoriert die theme Einstellung jedoch.
Wenn Sie ein Lesezeichen auf einen eingebetteten Bericht anwenden möchten, können Sie die bookmark -Eigenschaft verwenden. Wenn Sie einen Lesezeichennamen mit dieser Eigenschaft angeben, kann die API das Lesezeichen nur verwenden, wenn sie mit diesem Namen vorhanden ist. Wenn Sie die pageName -Eigenschaft zum Angeben einer öffnenden Seite verwenden, kann die API diese Seite nur anzeigen, wenn sie mit dem angegebenen Namen vorhanden ist. Bevor Sie einen Namen konfigurieren, sollten Sie eine Accessormethode wie die Report getPages-Methode verwenden, um zu überprüfen, ob eine Komponente mit diesem Namen vorhanden ist.

Konfigurieren von Berichteinstellungen

Bereitstellen von Konfigurationsinformationen

Einstellungen anpassen

Bereiche

Filter (Bereich)

Seitennavigationsbereich

Bars

Aktionsleiste

Statusleiste

Gebietsschemaeinstellungen

Transparenter Hintergrund

Linkklickverhalten

Visual gerenderte Ereignisse

Fehlermeldungen

Optionen anpassen

Standardseite

Bei Auslastungsfiltern

Beim Laden von Slicern

Beim Laden des Lesezeichens

Designs und Modus mit hohem Kontrast

Zoomfaktor

Öffnen im Bearbeitungsmodus

Konfigurieren des Bearbeitungsmodus

Wechseln zwischen Bearbeitungs- und Ansichtsmodi

Überlegungen und Einschränkungen

Nächste Schritte

Zusätzliche Ressourcen