Konfigurieren von Berichtseinstellungen

Artikel
07/17/2024

Mithilfe der Power BI-Client-APIs können Sie Power BI-Analysen in Ihre Anwendung einbetten. Wenn Sie diese clientseitige Bibliothek verwenden, um einen Power BI-Bericht einzubetten, stellen Sie die API mit 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.

Neben der Gewährung des API-Zugriffs auf den Bericht können Sie auch das Konfigurationsobjekt verwenden, um die Darstellung und das Verhalten Ihres Berichts anzupassen. Sie können beispielsweise die Filtersichtbarkeit, den Navigationszugriff und die Standorteinstellungen im Konfigurationsobjekt anpassen.

In den folgenden Abschnitten wird erläutert, wie Power BI-Inhalte eingebettet und konfiguriert werden.

Bereitstellen von Konfigurationsinformationen

Die IReportLoadConfiguration Schnittstelle zeigt Eigenschaften an, die ein Konfigurationsobjekt den 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.

Anpassen von Einstellungen

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. Um die Berichtseinstellungen zu aktualisieren, wenn der Bericht bereits geladen wurde, verwenden Sie die report.updateSettings-Methode. Weitere Informationen finden Sie unter Aktualisieren der Berichtseinstellungen zur Laufzeit.

Scheiben

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 jede panes-Eigenschaft unterstützt:

Eigentum	Sichtbar	Erweitert
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

Filterbereich

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

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

Anmerkung

Die eigenschaft panes ersetzt die eigenschaft filterPaneEnabled. Um die Abwärtskompatibilität aufrechtzuerhalten, ist die filterPaneEnabled-Eigenschaft weiterhin vorhanden. Sie sollten diese beiden Eigenschaften jedoch nicht zusammen 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
    }
};

Anmerkung

Die eigenschaft panes ersetzt die eigenschaft navContentPaneEnabled. Um die Abwärtskompatibilität aufrechtzuerhalten, ist die navContentPaneEnabled-Eigenschaft weiterhin vorhanden. Sie sollten diese beiden Eigenschaften jedoch nicht zusammen verwenden.

Der Seitennavigationsbereich wird unten im Bericht angezeigt, um den neuen vertikalen Seitenbereich zu verwenden, den Sie für die eigenschaft position festlegen können:

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

Anmerkung

Sie können die Position des Seitennavigationsbereichs nicht mithilfe von updateSettingsändern.

Gitter

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

Aktionsleiste

Der folgende Code macht die Aktionsleiste sichtbar:

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

Alternativ können Sie im Ansichtsmodus auch den actionBarEnabled URL-Parameter verwenden:

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

Anmerkung

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

Für die Aktionsleiste im Ansichtsmodus wird empfohlen, UserState.ReadWrite.All Berechtigung für Ihre Azure AD-Anwendung zu aktivieren. Diese Berechtigung ist erforderlich, um Endbenutzern das Hinzufügen des Berichts zu ihren Favoriten zu ermöglichen und persönliche Lesezeichen und persistenten Filterzu aktivieren.

Statusleiste

Die Statusleiste enthält den Canvaszoomcontroller, der die Möglichkeit zum Zoomen auf der Canvas bietet.

Der folgende Code macht die Statusleiste sichtbar:

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

Gebietsschemaeinstellungen

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

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

Sprache 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ützten Sprachen.

Der folgende Code weist diesen localeSettingsbestimmte Werte zu:

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

Anmerkung

Gebietsschemaeinstellungen können nach dem Laden des Berichts nicht mehr geändert werden. Wenn Sie die Gebietsschemaeinstellungen des Berichts ändern möchten, setzen Sie den iFrame zurück, indem Sie powerbi.reset(element)aufrufen und dann den Bericht erneut einbetten.

Transparenter Hintergrund

Standardmäßig ist der Hintergrund des eingebetteten Inhalts weiß mit grauen Rändern. Bei Bedarf können Sie dem eingebetteten Inhalt einen transparenten Hintergrund verleihen. Anschließend können Sie die Formatvorlage auf das HTML-div-Element anwenden, das den eingebetteten Inhalt enthält. Die Formatierung des div 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 vordefinierte visuelle Elemente einer Matrix steuern. Standardmäßig öffnet der Link ein neues Fenster.

Die verfügbaren Verhaltenmodi:

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 dataHyperlinkClicked Ereignis aus.
RaiseEvent – Verhindert das Standardverhalten des URL-Klicks und löst dataHyperlinkClicked Ereignis aus.

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 ein Link auf eine vordefinierte Tabelle oder Matrix-Visualisierung geklickt wird und das Verhalten entweder NavigateAndRaiseEvent oder RaiseEventist.

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

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

Visuelle gerenderte Ereignisse

Sie können auf ein Ereignis für jedes gerenderte visuelle Element lauschen. Standardmäßig sind die visuellen 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 visuelles Element gerendert wird und die visualRenderedEvents in den Berichtseinstellungen aktiviert ist.

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

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

Anmerkung

Da visuelle Elemente aufgrund von Benutzerinteraktionen möglicherweise gerendert werden, empfiehlt es sich, dieses Ereignis nur bei Bedarf zu aktivieren.

Fehlermeldungen

Wenn Sie angepasste Fehlermeldungen in eingebetteten Berichten anzeigen möchten, verwenden Sie die hideErrors-Eigenschaft, um die standardmäßigen eingebetteten Power BI-Fehlermeldungen auszublenden. Ihr Code kann dann Fehlerereignisse auf eine Weise behandeln, die ihrem App-Design entspricht. Weitere Informationen zum Überschreiben von Standardfehlern finden Sie unter Außerkraftsetzen von Standardfehlern.

Verwenden Sie diesen Code, um Standardfehlermeldungen auszublenden:

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

Anpassen von Optionen

In den folgenden Abschnitten wird beschrieben, wie Sie weitere Eigenschaften verwenden können, um das Aussehen und Verhalten Ihres eingebetteten Power BI-Berichts weiter anzupassen.

Standardseite

Sie können steuern, welche Seite des eingebetteten Berichts anfänglich angezeigt wird. Standardmäßig ist die Anfangsseite 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 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'
};

Beim Laden von Filtern

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 weitere Filter, die zusammen mit den gespeicherten Filtern verwendet werden sollen. Der folgende Code zeigt, wie Sie die eigenschaft filters verwenden, um weitere 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 phasenweisen Einbettung verwenden, können Sie die Filter überschreiben, die der Bericht anfänglich anwendet. Weitere Informationen zum Erstellen von Filtern und verwenden der setFilters-Methode finden Sie unter Steuerelementberichtfilter.

Beim Laden von Datenschnitten

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 Status der vorhandenen Datenschnitte zu ändern, wie der folgende Code veranschaulicht:

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

Weitere Informationen zum Ändern des Zustands eines Datenschnitts finden Sie unter Steuerelementbericht-Datenschnitte.

Beim Laden einer Textmarke

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

Sie können die zu verwendende Textmarke angeben, indem Sie entweder den Namen der Textmarke oder den Status angeben. Wenn Sie den Namen der Textmarke 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 eine Textmarke anhand des Namens angeben:

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

Dieser Code zeigt, wie Sie eine Textmarke 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 Nullkontrast angezeigt. Sie können dieses Verhalten außer Kraft setzen, indem Sie ein bestimmtes Design oder eine bestimmte Kontraststufe konfigurieren. Weitere Informationen zu Designs finden Sie unter Anwenden von Berichtsdesigns.

Die verfügbaren Kontrastmodi:

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

Um ein bestimmtes Design zu konfigurieren, verwenden Sie Code ähnlich wie in den folgenden Zeilen:

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

Der folgende Code zeigt, wie sie die Standardkontraststufe außer Kraft setzen, None:

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

Anmerkung

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

Zoomfaktor

Weitere Informationen zum Anpassen des Berichtszoomfaktors finden Sie im Barrierefreiheitsdokument.

Im Bearbeitungsmodus öffnen

Standardmäßig wird der bericht, den Sie einbetten, im Ansichtsmodus angezeigt. Sie können dieses Verhalten jedoch außer Kraft setzen, um den Bericht im Bearbeitungsmodus zu öffnen. Sie können auch zwischen den Modi wechseln.

Bearbeitungsmodus konfigurieren

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

Sie können die viewMode Eigenschaft den folgenden Werten zuweisen:

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

Sie können die permissions Eigenschaft den folgenden Werten 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 mithilfe von Speichern unterspeichern.
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 so konfigurieren, dass sie im Bearbeitungsmodus geöffnet werden, weisen Sie der permissions Eigenschaft einen Wert zu, der für die Bearbeitung geeignet ist, wie der folgende Code veranschaulicht:

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

Anmerkung

Der permissions Wert, den Sie konfigurieren, 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

Neben der Angabe eines Modus für eingebettete Inhalte, in dem sie gestartet werden sollen, können Sie auch dynamisch zwischen Bearbeitungs- und Ansichtsmodi wechseln.

Wenn sich der Inhalt im Bearbeitungsmodus befindet und Sie zum 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 zum 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 von eingebetteten Inhalten die folgenden Punkte:

Die Seitennavigation Position kann nicht geändert werden, wenn die Aktionsleiste sichtbar ist. Erfahren Sie mehr über die Aktionsleiste.
Wenn Sie die eigenschaft bars in der eigenschaft setting verwenden, wie in Barsbeschrieben, 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 viewMode verwenden, um Inhalte im Bearbeitungsmodus anzuzeigen, müssen Sie zwei zusätzliche Schritte ausführen:
- Konfigurieren Sie eine Berechtigungsstufe mit der permissions-Eigenschaft. Diese Berechtigungsstufe muss dem Benutzer einen geeigneten Zugriff zum Ändern von Inhalten gewähren. Wenn Sie beispielsweise einen permissions Wert von Read, zuweisen, kann der Benutzer inhalte nicht bearbeiten.
- Stellen Sie sicher, dass das Einbettungstoken, das Sie generieren, über Berechtigungen verfügt, die die Bearbeitung unterstützen. Wenn Sie z. B. ein Token mit einem accessLevel Wert von view, abrufen, zeigt die API inhalte nicht im Bearbeitungsmodus an.
Die Eigenschaft Bereiche ersetzt die folgenden settings Eigenschaften:
- filterPaneEnabled
- navContentPaneEnabled
Wenn Sie die panes-Eigenschaft verwenden, um die Sichtbarkeit von Filtern oder Seitennavigationen zu konfigurieren, verwenden Sie nicht die filterPaneEnabled- oder navContentPaneEnabled-Eigenschaft in Ihrer App.
Die API kann ein Design und eine Kontrastebene nicht gleichzeitig auf eingebettete Inhalte anwenden. Wenn Sie beide Optionen mithilfe der eigenschaften theme und contrastMode konfigurieren, verwendet die API Ihren contrastMode Wert mit dem eingebetteten Inhalt. Die API ignoriert jedoch die theme Einstellung.
Wenn Sie eine Textmarke auf einen eingebetteten Bericht anwenden möchten, können Sie die eigenschaft bookmark verwenden. Wenn Sie einen Textmarkennamen für diese Eigenschaft angeben, kann die API nur die Textmarke verwenden, wenn sie mit diesem Namen vorhanden ist. Ebenso kann die API, wenn Sie die eigenschaft pageName verwenden, um eine Öffnenseite anzugeben, diese Seite nur anzeigen, wenn eine mit dem angegebenen Namen vorhanden ist. Bevor Sie einen Namen konfigurieren, sollten Sie eine Accessormethode wie die Report getPages-Methodeverwenden, um zu überprüfen, ob eine Komponente mit diesem Namen vorhanden ist.

Freigeben über

Konfigurieren von Berichtseinstellungen

Bereitstellen von Konfigurationsinformationen

Anpassen von Einstellungen

Scheiben

Filterbereich

Seitennavigationsbereich

Gitter

Aktionsleiste

Statusleiste

Gebietsschemaeinstellungen

Transparenter Hintergrund

Linkklickverhalten

Visuelle gerenderte Ereignisse

Fehlermeldungen

Anpassen von Optionen

Standardseite

Beim Laden von Filtern

Beim Laden von Datenschnitten

Beim Laden einer Textmarke

Designs und Modus mit hohem Kontrast

Zoomfaktor

Im Bearbeitungsmodus öffnen

Bearbeitungsmodus konfigurieren

Wechseln zwischen Bearbeitungs- und Ansichtsmodi

Überlegungen und Einschränkungen

Zusätzliche Ressourcen

Freigeben über

Konfigurieren von Berichtseinstellungen

Bereitstellen von Konfigurationsinformationen

Anpassen von Einstellungen

Scheiben

Filterbereich

Seitennavigationsbereich

Gitter

Aktionsleiste

Statusleiste

Gebietsschemaeinstellungen

Transparenter Hintergrund

Linkklickverhalten

Visuelle gerenderte Ereignisse

Fehlermeldungen

Anpassen von Optionen

Standardseite

Beim Laden von Filtern

Beim Laden von Datenschnitten

Beim Laden einer Textmarke

Designs und Modus mit hohem Kontrast

Zoomfaktor

Im Bearbeitungsmodus öffnen

Bearbeitungsmodus konfigurieren

Wechseln zwischen Bearbeitungs- und Ansichtsmodi

Überlegungen und Einschränkungen

Verwandte Inhalte

Zusätzliche Ressourcen