Konfigurace nastavení sestavy

Článek
01/18/2024

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

K uložení informací o sestavě Power BI můžete použít objekt konfigurace. Když sestavu vložíte, předáte tento objekt do rozhraní API.

Kromě toho, že rozhraní API poskytne přístup k sestavě, můžete také pomocí objektu konfigurace přizpůsobit vzhled a chování sestavy. V konfiguračním objektu můžete například upravit viditelnost filtru, přístup k navigaci a nastavení umístění.

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 klientským rozhraním API 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 příklady 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í settings vlastnosti upravit vzhled a chování vložené sestavy Power BI. Pokud chcete aktualizovat nastavení sestavy, když už je sestava načtená, použijte metodu report.updateSettings . Další informace najdete v tématu Aktualizace nastavení sestavy za běhu.

Podokna

Pomocí jedné panes vlastnosti 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 jednotlivé panes vlastnosti podporují:

Vlastnost	Viditelné	Rozbaleno
`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 filterPaneEnabled vlastnost , jak je znázorněno v následujícím kódu:

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

Poznámka

Vlastnost panes nahrazuje filterPaneEnabled vlastnost . Aby byla zachována filterPaneEnabled zpětná kompatibilita, vlastnost stále existuje. Tyto dvě vlastnosti byste ale neměli používat společně.

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

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

Poznámka

Vlastnost panes nahrazuje navContentPaneEnabled vlastnost . Aby byla zachována navContentPaneEnabled zpětná kompatibilita, vlastnost stále existuje. Tyto dvě vlastnosti byste ale neměli používat společně.

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

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í updateSettingspříkazu .

Bary

Nastavte viditelnost panelu akcí a stavového řádku pomocí bars vlastnosti .

Panel akcí

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

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

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

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

Poznámka

V režimu zobrazení se panel akcí podporuje jenom ve scénáři vložení pro vaši organizaci .

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 potřeba k tomu, aby si koncoví uživatelé mohli přidat sestavu do oblíbených položek, a aby bylo možné povolit osobní záložky a trvalé filtry.

Stavovém

Na stavovém řádku je ovladač lupy plátna, který umožňuje přiblížení na plátně.

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

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

Nastavení národního prostředí

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

Vlastnost language v localeSettings se skládá ze dvou částí každého ze dvou písmen oddělených spojovníkem:

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).
Locale 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ří USA (angličtina), ES (Španělsko) a TR (Türkiye).

Seznam dostupných jazyků a oblastí najdete v tématu Podporované jazyky.

Následující kód přiřadí těmto objektům konkrétní hodnoty localeSettings:

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, resetujte prvek iframe voláním powerbi.reset(element)a pak sestavu znovu vložte.

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 nastavit jako průhledné pozadí. Pak můžete použít požadovaný styl na element HTML div , který obsahuje vložený obsah. Styl div elementu se pak zviditelní.

Pomocí tohoto kódu zprůhledníte 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 předefinovaných maticových vizuálů. Ve výchozím nastavení hypertextový odkaz otevře nové okno.

Dostupné režimy chování jsou uvedené níže:

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 – Zabrání výchozímu chování kliknutí na adresu URL a vyvolání dataHyperlinkClicked události.

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 při kliknutí na hypertextový odkaz na předefinované vizuály tabulky nebo matice a chování je buď NavigateAndRaiseEvent , nebo RaiseEvent.

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

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

Vizuálně vykreslené události

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

Pomocí tohoto kódu aktivujte visualRendered události:

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

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

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

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

Poznámka

Vzhledem k tomu, že se vizuály můžou vykreslovat kvůli interakci 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, pomocí hideErrors vlastnosti skryjte výchozí vložené chybové zprávy Power BI. 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 chyb najdete v tématu Přepsání výchozích chybových zpráv .

Pomocí tohoto kódu skryjte výchozí chybové zprávy:

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 zobrazí na začátku. 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í pageName vlastnosti a zadáním názvu stránky, kterou chcete zobrazit. Pokud ale v Power BI žádná stránka s tímto názvem neexistuje, žá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'
};

Filtry při načítání

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

Nakonfigurujte další filtry, které se použijí společně s uloženými filtry. Následující kód ukazuje, jak pomocí filters vlastnosti 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 při postupném vkládání, můžete přepsat filtry, které sestava původně použila. Další informace o vytváření filtrů a používání metody najdete v setFilters tématu Řízení filtrů sestav.

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

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

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

Další informace o změně stavu průřezu najdete v tématu Řízení průřezů sestav .

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

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

Záložku, která se má použít, můžete určit 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 určit záložku podle stavu:

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

Motivy a režim vysoký kontrast

Můžete řídit motiv a úroveň kontrastu, které vložený obsah používá. Ve výchozím nastavení se veškerý vložený obsah zobrazuje 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 jsou uvedené níže:

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 theme , ale toto nastavení ignoruje.

Ú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 vložená sestava zobrazí v režimu zobrazení. Toto chování ale můžete přepsat a sestavu otevřít 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 viewMode vlastnost společně s permissions vlastností .

Vlastnosti můžete přiřadit viewMode následující hodnoty:

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

Vlastnosti můžete přiřadit permissions tyto hodnoty:

Read – Uživatelé můžou sestavu zobrazit.
ReadWrite – Uživatelé můžou sestavu zobrazit, upravit a uložit.
Copy – Uživatelé můžou uložit kopii sestavy pomocí možnosti Uložit jako.
Create – Uživatelé můžou vytvořit novou sestavu.
All – Uživatelé můžou vytvářet, zobrazovat, upravovat, ukládat a ukládat kopii sestavy.

Když nakonfigurujete obsah tak, aby se otevřel v režimu úprav, přiřaďte permissions vlastnosti 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 jenom v případě, že token pro vložení, který jste získali, 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žimem úprav a zobrazení

Kromě určení režimu, ve kterém se má vložený obsah spouštět, 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 kód JavaScriptu:

// 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 kód JavaScriptu:

// 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:

Umístění navigace na stránce nejde změnit, když je panel akcí viditelný. Přečtěte si další informace o panelu akcí.
Když použijete bars vlastnost ve setting vlastnosti, jak je popsáno v části Bars, rozhraní API použije vaši konfiguraci pouze v případě, že je vložený obsah v režimu úprav. Pokud je obsah v režimu zobrazení, rozhraní API toto nastavení ignoruje bars .
Když použijete viewMode vlastnost k zobrazení obsahu v režimu úprav, musíte provést dva další kroky:
- Nakonfigurujte úroveň oprávnění pomocí permissions vlastnosti . Tato úroveň oprávnění musí uživateli poskytnout odpovídající přístup pro úpravy obsahu. Pokud například přiřadíte permissions hodnotu Read, uživatele, 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í se obsah v režimu úprav.
Vlastnost podokna nahrazuje následující settings vlastnosti:
- filterPaneEnabled
- navContentPaneEnabled
Pokud vlastnost používáte panes ke konfiguraci viditelnosti filtru nebo navigace na stránce, nepoužívejte filterPaneEnabled vlastnost nebo navContentPaneEnabled v aplikaci.
Rozhraní API nemůže u vloženého obsahu současně použít motiv a úroveň kontrastu. Pokud nakonfigurujete obě možnosti pomocí theme vlastností a contrastMode , rozhraní API použije vaši contrastMode hodnotu s vloženým obsahem. Rozhraní API ale toto nastavení ignoruje theme .
Pokud chcete na vloženou sestavu použít záložku bookmark , můžete použít vlastnost . Pokud k této vlastnosti zadáte název záložky, rozhraní API může záložku použít jenom v případě, že existuje s tímto názvem. Podobně pokud použijete pageName vlastnost 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řistupujícího objektu, jako je metoda Report getPages, a zkontrolujte, jestli součást existuje s tímto názvem.

Share via

Konfigurace nastavení sestavy

Zadání informací o konfiguraci

Přizpůsobení nastavení

Podokna

Podokno filtru

Podokno navigace na stránce

Bary

Panel akcí

Stavovém

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

Filtry při načítání

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

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

Motivy a režim vysoký kontrast

Úroveň přiblížení

Otevřít v režimu úprav

Konfigurace režimu úprav

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

Důležité informace a omezení

Další kroky

Další materiály