Konfigurace nastavení sestavy

Článek
07/17/2024

Pomocí rozhraní API klienta Power BI můžete do své aplikace vkládat analýzy Power BI. Když tuto knihovnu na straně klienta použijete k vložení sestavy Power BI, poskytnete rozhraní API s informacemi o této sestavě.

Konfigurační objekt můžete použít k ukládání informací o sestavě Power BI. Když sestavu vložíte, předáte ho do rozhraní API.

Kromě udělení přístupu rozhraní API k sestavě můžete také použít objekt konfigurace k přizpůsobení vzhledu a chování sestavy. Můžete například upravit viditelnost filtru, navigační přístup a nastavení umístění v objektu konfigurace.

Následující části vysvětlují, jak vložit a nakonfigurovat obsah Power BI.

Zadání informací o konfiguraci

Rozhraní IReportLoadConfiguration zobrazuje vlastnosti, které objekt konfigurace může poskytnout rozhraní API klienta Power BI o sestavě:

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

Vysvětlení požadovaných parametrů tohoto rozhraní a ukázek kódu ukazující, jak vložit sestavu, najdete v tématu Vložení sestavy.

Přizpůsobení nastavení

Následující části popisují, jak můžete pomocí vlastnosti settings upravit vzhled a chování vložené sestavy Power BI. Chcete-li aktualizovat nastavení sestavy při již načtené sestavě, použijte metodu report.updateSettings. Další informace najdete v tématu Aktualizace nastavení sestavy za běhu.

Okenní tabulky

Pomocí jedné vlastnosti panes můžete řídit vzhled všech podoken v sestavě Power BI, jak je znázorněno v následujícím kódu:

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

V následující tabulce vidíte, které hodnoty každá vlastnost panes podporuje:

Vlastnost	Viditelný	Rozšířený
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

Podokno filtru

Ve výchozím nastavení je podokno filtru viditelné. Pokud chcete toto podokno skrýt, použijte vlastnost filterPaneEnabled, jak je znázorněno v následujícím kódu:

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

Poznámka

Vlastnost podokna nahradí vlastnost filterPaneEnabled. Chcete-li zachovat zpětnou kompatibilitu, vlastnost filterPaneEnabled stále existuje. Měli byste se však vyhnout společnému použití těchto dvou vlastností.

Ve výchozím nastavení jsou šipky navigace na stránce viditelné ve vložených sestavách. Pokud chcete tyto šipky skrýt, použijte vlastnost navContentPaneEnabled, jak je znázorněno v následujícím kódu:

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

Poznámka

Vlastnost podokna nahradí vlastnost navContentPaneEnabled. Chcete-li zachovat zpětnou kompatibilitu, vlastnost navContentPaneEnabled stále existuje. Měli byste se však vyhnout společnému použití těchto dvou vlastností.

Navigační podokno stránky se zobrazí v dolní části sestavy, abyste mohli použít nové podokno svislých stránek, můžete nastavit vlastnost position:

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

Poznámka

Umístění navigačního podokna stránky nelze změnit pomocí updateSettings.

Tyče

Pomocí vlastnosti bars nastavte viditelnost panelu akcí a stavového řádku.

Panel akcí

Následující kód zviditelní panel akcí:

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

V režimu zobrazení je také možné použít parametr adresy URL actionBarEnabled:

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

Poznámka

V režimu zobrazení je panel akcí podporován pouze pro vložení pro vaši organizaci scénář.

Pro panel akcí v režimu zobrazení se doporučuje povolit UserState.ReadWrite.All oprávnění pro aplikaci Azure AD. Toto oprávnění je vyžadováno, aby koncoví uživatelé mohli sestavu přidat do oblíbených položek a povolit osobní záložky a trvalých filtrů.

Stavový řádek

Stavový řádek obsahuje ovladač lupy plátna, který umožňuje přiblížit plátno.

Následující kód zviditelní stavový řádek:

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

Nastavení národního prostředí

Pomocí vlastnosti localeSettings určete jazyk a formátování vložené sestavy:

Vlastnost language v localeSettings se skládá ze dvou částí dvou písmen, které jsou oddělené pomlčkou:

jazyk definuje jazyk, který Power BI používá k lokalizaci. Mezi příklady jazyků patří en (angličtina), es (španělština) a tr (turečtina).
národní prostředí definuje formátování textu, které Power BI používá pro kalendářní data, měnu a další související obsah. Mezi příklady národních prostředí patří US (angličtina), ES (Španělsko) a TR (Türkiye).

Seznam dostupných jazyků a oblastí najdete v podporovaných jazycích.

Následující kód přiřadí těmto localeSettingskonkrétní hodnoty:

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

Poznámka

Nastavení národního prostředí nelze po načtení sestavy změnit. Pokud chcete změnit nastavení národního prostředí sestavy, obnovte element iframe zavoláním powerbi.reset(element)a opětovným vložením sestavy.

Průhledné pozadí

Ve výchozím nastavení je pozadí vloženého obsahu bílé s šedými okraji. Pokud chcete, můžete vložený obsah dát průhledné pozadí. Pak můžete použít styl, který chcete použít u elementu HTML div, který obsahuje vložený obsah. Styl div prvku se pak zobrazí.

Pomocí tohoto kódu zprůhlední pozadí vloženého obsahu:

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

Chování kliknutí na hypertextový odkaz

Můžete řídit chování hypertextového odkazu v tabulce nebo matici předem zadaných vizuálů. Ve výchozím nastavení hypertextový odkaz otevře nové okno.

Dostupné režimy chování:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate – adresa URL se načte do nového kontextu procházení.
NavigateAndRaiseEvent – Adresa URL se načte do nového kontextu procházení a vyvolá dataHyperlinkClicked událost.
RaiseEvent – Zabraňuje výchozímu chování kliknutí na adresu URL a vyvolání události dataHyperlinkClicked.

Pomocí tohoto kódu můžete změnit chování odkazů pro vyvolání události:

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

Událost dataHyperlinkClicked se aktivuje, když se hypertextový odkaz klikne na předefinované tabulky nebo maticové vizuály a chování je buď NavigateAndRaiseEvent, nebo RaiseEvent.

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

Další informace o zpracování událostí naleznete v tématu Zpracování událostí.

Vizuální vykreslené události

Pro každý vykreslený vizuál můžete naslouchat události. Ve výchozím nastavení jsou vykreslené události vizuálu zakázané.

Tento kód použijte k aktivaci visualRendered událostí:

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

Událost visualRendered se aktivuje při vykreslení vizuálu a visualRenderedEvents se povolí v nastavení sestavy.

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

Další informace o zpracování událostí naleznete v tématu Zpracování událostí.

Poznámka

Protože se vizuály můžou vykreslit z důvodu interakcí uživatelů, doporučujeme tuto událost zapnout jenom v případě potřeby.

Chybové zprávy

Pokud chcete ve vložených sestavách zobrazit přizpůsobené chybové zprávy, použijte vlastnost hideErrors a skryjte výchozí chybové zprávy Power BI Embedded. Kód pak může zpracovávat chybové události způsobem, který odpovídá návrhu vaší aplikace. Další informace o přepsání výchozích chybových zpráv najdete v tématu Přepsání výchozích chyb.

Tento kód slouží ke skrytí výchozích chybových zpráv:

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

Přizpůsobení možností

Následující části popisují, jak můžete pomocí dalších vlastností dále přizpůsobit vzhled a chování vložené sestavy Power BI.

Výchozí stránka

Můžete určit, která stránka vložené sestavy se zpočátku zobrazí. Ve výchozím nastavení je počáteční stránkou stránka, kterou jste naposledy upravili, což byla aktivní stránka při posledním uložení sestavy. Toto chování můžete přepsat pomocí vlastnosti pageName a zadáním názvu stránky, kterou chcete zobrazit. Pokud ale v Power BI neexistuje žádná stránka s tímto názvem, žádost o otevření se nezdaří.

Následující kód ukazuje, jak nakonfigurovat aplikaci tak, aby zobrazovala konkrétní stránku:

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

Při načítání filtrů

Můžete řídit filtry, které aplikace použije pro vloženou sestavu. Ve výchozím nastavení sestava zpočátku používá filtry, které jste uložili do sestavy. Pokud ale chcete filtry upravit, máte dvě možnosti:

Nakonfigurujte další filtry tak, aby se používaly společně s uloženými filtry. Následující kód ukazuje, jak pomocí vlastnosti filters připojit další filtry:
```
let embedConfig = {
    ...
    filters: [...]
};
```
Nahraďte uložené filtry novou sadou. Metoda setFilters poskytuje způsob, jak dynamicky měnit filtry sestavy. Pokud tuto metodu použijete během postupného vkládání, můžete přepsat filtry, které sestava původně použije. Další informace o vytváření filtrů a použití metody setFilters naleznete v tématu Control report filters.

Při načítání průřezů

Můžete řídit stav průřezů, které vaše aplikace použije pro vloženou sestavu. Ve výchozím nastavení rozhraní API používá průřezy, které jste uložili do sestavy. Pomocí vlastnosti slicers však můžete změnit stav existujících průřezů, jak ukazuje následující kód:

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

Další informace o změně stavu průřezu průřezu najdete v tématu Ovládací prvky sestavy.

Při načtení záložky

Pomocí vlastnosti bookmark můžete použít záložku na vloženou sestavu. Další informace o použití záložek k zachycení aktuálně nakonfigurovaného zobrazení stránek sestavy najdete v Záložky.

Záložku, kterou chcete použít, můžete zadat zadáním názvu záložky nebo stavu. Pokud zadáte název záložky, musí sestava Power BI obsahovat uloženou záložku s tímto názvem.

Vlastnost bookmark je typu IApplyBookmarkRequest. Následující kód ukazuje definici tohoto typu:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Tento kód ukazuje, jak zadat záložku podle názvu:

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

Tento kód ukazuje, jak zadat záložku podle stavu:

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

Motivy a režim vysokého kontrastu

Můžete řídit úroveň motivu a kontrastu, kterou vložený obsah používá. Ve výchozím nastavení se veškerý obsah, který vložíte, zobrazí s výchozím motivem a s nulovým kontrastem. Toto chování můžete přepsat konfigurací konkrétního motivu nebo úrovně kontrastu. Další informace o motivech najdete v tématu Použití motivů sestav.

Dostupné režimy kontrastu:

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

Ke konfiguraci konkrétního motivu použijte kód podobný následujícím řádkům:

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

Následující kód ukazuje, jak přepsat výchozí úroveň kontrastu None:

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

Poznámka

Rozhraní API nemůže použít motiv a úroveň kontrastu současně. Pokud nakonfigurujete obě vlastnosti, rozhraní API použije zadanou úroveň kontrastu, ale ignoruje nastavení theme.

Úroveň přiblížení

Další informace o úpravě úrovně přiblížení sestavy najdete v dokumentu přístupnosti.

Otevřít v režimu úprav

Ve výchozím nastavení se sestava, kterou vložíte, zobrazí v režimu zobrazení. Toto chování však můžete přepsat a otevřít sestavu v režimu úprav. Můžete také přepínat mezi režimy.

Konfigurace režimu úprav

Pokud chcete otevřít vloženou sestavu v režimu úprav, použijte vlastnost viewMode společně s vlastností permissions.

Vlastnost viewMode můžete přiřadit následujícími hodnotami:

View – otevře sestavu v režimu zobrazení.
Edit – otevře sestavu v režimu úprav.

Vlastnost permissions můžete přiřadit těmito hodnotami:

Read – Uživatelé můžou sestavu zobrazit.
ReadWrite – Uživatelé můžou sestavu zobrazit, upravit a uložit.
Copy – Uživatelé mohou uložit kopii sestavy pomocí Uložit jako.
Create – Uživatelé můžou vytvořit novou sestavu.
All – uživatelé můžou vytvořit, zobrazit, upravit, uložit a uložit kopii sestavy.

Při konfiguraci obsahu pro otevření v režimu úprav přiřaďte vlastnost permissions hodnotu, která je vhodná pro úpravy, jak ukazuje následující kód:

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

Poznámka

Hodnota permissions, kterou nakonfigurujete, funguje pouze v případě, že získaný token pro vložení má dostatečná oprávnění. Další informace o tokenech pro vložení najdete v tématu Vytvoření tokenu pro vložení.

Přepínání mezi režimy úprav a zobrazení

Kromě určení režimu, ve kterém se má vložený obsah spustit, můžete také dynamicky přepínat mezi režimy úprav a zobrazení.

Pokud je obsah v režimu úprav a chcete přepnout do režimu zobrazení, použijte tento javascriptový kód:

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

...

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

Pokud je obsah v režimu zobrazení a chcete přepnout do režimu úprav, použijte tento javascriptový kód:

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

...

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

Důležité informace a omezení

Při konfiguraci vloženého obsahu zvažte následující body:

Navigační stránky umístění nejde změnit, když je panel akcí viditelný. Přečtěte si další informace o panelu akcí.
Pokud použijete vlastnost bars ve vlastnosti setting, jak je popsáno v pruhy, rozhraní API použije konfiguraci pouze v případě, že vložený obsah je v režimu úprav. Pokud je váš obsah v režimu zobrazení, rozhraní API ignoruje nastavení bars.
Pokud k zobrazení obsahu v režimu úprav použijete vlastnost viewMode, musíte provést dva další kroky:
- Nakonfigurujte úroveň oprávnění pomocí vlastnosti permissions. Tato úroveň oprávnění musí uživateli udělit odpovídající přístup pro úpravy obsahu. Pokud například přiřadíte permissions hodnotu Read, uživatel nebude moct upravovat obsah.
- Ujistěte se, že token pro vložení , který vygenerujete, má oprávnění, která podporují úpravy. Pokud například získáte token s accessLevel hodnotou view, rozhraní API nezobrazí obsah v režimu úprav.
Vlastnost podokna nahrazuje následující vlastnosti settings:
- filterPaneEnabled
- navContentPaneEnabled
Pokud ke konfiguraci viditelnosti filtru nebo navigace na stránce použijete vlastnost panes, nepoužívejte v aplikaci filterPaneEnabled ani navContentPaneEnabled vlastnost.
Rozhraní API nemůže použít motiv a úroveň kontrastu pro vložený obsah současně. Pokud nakonfigurujete obě možnosti pomocí vlastností theme a contrastMode, rozhraní API použije hodnotu contrastMode s vloženým obsahem. Rozhraní API ale ignoruje nastavení theme.
Pokud chcete na vloženou sestavu použít záložku, můžete použít vlastnost bookmark. Pokud zadáte název záložky s danou vlastností, rozhraní API může záložku použít pouze v případě, že existuje s tímto názvem. Podobně pokud použijete vlastnost pageName k určení úvodní stránky, rozhraní API může tuto stránku zobrazit pouze v případě, že existuje s daným názvem. Před konfigurací názvu zvažte použití metody příslušenství, jako je například metoda Report getPages, a zkontrolujte, zda součást existuje s tímto názvem.

Sdílet prostřednictvím

Konfigurace nastavení sestavy

Zadání informací o konfiguraci

Přizpůsobení nastavení

Okenní tabulky

Podokno filtru

Navigační podokno stránky

Tyče

Panel akcí

Stavový řádek

Nastavení národního prostředí

Průhledné pozadí

Chování kliknutí na hypertextový odkaz

Vizuální vykreslené události

Chybové zprávy

Přizpůsobení možností

Výchozí stránka

Při načítání filtrů

Při načítání průřezů

Při načtení záložky

Motivy a režim vysokého kontrastu

Úroveň přiblížení

Otevřít v režimu úprav

Konfigurace režimu úprav

Přepínání mezi režimy úprav a zobrazení

Důležité informace a omezení

Další materiály

Sdílet prostřednictvím

Konfigurace nastavení sestavy

Zadání informací o konfiguraci

Přizpůsobení nastavení

Okenní tabulky

Podokno filtru

Navigační podokno stránky

Tyče

Panel akcí

Stavový řádek

Nastavení národního prostředí

Průhledné pozadí

Chování kliknutí na hypertextový odkaz

Vizuální vykreslené události

Chybové zprávy

Přizpůsobení možností

Výchozí stránka

Při načítání filtrů

Při načítání průřezů

Při načtení záložky

Motivy a režim vysokého kontrastu

Úroveň přiblížení

Otevřít v režimu úprav

Konfigurace režimu úprav

Přepínání mezi režimy úprav a zobrazení

Důležité informace a omezení

Související obsah

Další materiály