Konfigurowanie ustawień raportu

Za pomocą interfejsów API klienta usługi Power BI możesz osadzić analizę usługi Power BI w aplikacji. Jeśli używasz tej biblioteki po stronie klienta do osadzania raportu usługi Power BI, podaj interfejs API z informacjami o tym raporcie.

Obiekt konfiguracji umożliwia przechowywanie informacji o raporcie usługi Power BI. Po osadzeniu raportu przekazujesz ten obiekt do interfejsu API.

Oprócz nadania interfejsowi API dostępu do raportu można również użyć obiektu konfiguracji, aby dostosować wygląd i zachowanie raportu. Można na przykład dostosować widoczność filtru, dostęp do nawigacji i ustawienia lokalizacji w obiekcie konfiguracji.

W poniższych sekcjach opisano sposób osadzania i konfigurowania zawartości usługi Power BI.

Podaj informacje o konfiguracji

Interfejs IReportLoadConfiguration wyświetla właściwości, które obiekt konfiguracji może dostarczyć do interfejsów API klienta usługi Power BI dotyczących raportu:

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

Zobacz Osadzanie raportu, aby uzyskać wyjaśnienie wymaganych parametrów tego interfejsu oraz przykłady kodu pokazujące sposób osadzania raportu.

Dostosowywanie ustawień

W poniższych sekcjach opisano sposób używania właściwości settings w celu dostosowania wyglądu i zachowania osadzonego raportu usługi Power BI. Aby zaktualizować ustawienia raportu, gdy raport jest już załadowany, użyj metody report.updateSettings. Aby uzyskać więcej informacji, zobacz Aktualizowanie ustawień raportu w czasie wykonywania.

Okienka

Kontroluj wygląd wszystkich okienek w raporcie usługi Power BI przy użyciu jednej właściwości panes, jak pokazano w poniższym kodzie:

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

W poniższej tabeli można zobaczyć, które wartości obsługuje każda właściwość panes:

Okienko filtru

Domyślnie okienko filtru jest widoczne. Jeśli chcesz ukryć to okienko, użyj właściwości filterPaneEnabled, jak pokazano w poniższym kodzie:

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

Okienko nawigacji strony

Domyślnie strzałki nawigacji strony są widoczne w raportach osadzonych. Aby ukryć te strzałki, użyj właściwości navContentPaneEnabled, jak pokazano w poniższym kodzie:

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

Okienko nawigacji strony jest wyświetlane w dolnej części raportu, aby użyć nowego okienka stron pionowych, można ustawić właściwość position:

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

Krata

Ustaw widoczność paska akcji i paska stanu przy użyciu właściwości bars.

Pasek akcji

Poniższy kod sprawia, że pasek akcji jest widoczny:

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

Alternatywnie w trybie wyświetlania można również użyć parametru adresu URL actionBarEnabled:

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

Pasek stanu

Pasek stanu zawiera kontroler powiększenia kanwy, który umożliwia powiększanie kanwy.

Poniższy kod powoduje, że pasek stanu jest widoczny:

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

Ustawienia ustawień regionalnych

Użyj właściwości localeSettings, aby określić język i formatowanie osadzonego raportu:

Właściwość language w localeSettings składa się z dwóch części dwóch liter, z których każda jest oddzielona łącznikiem:

• język definiuje język używany przez usługę Power BI do lokalizacji. Przykłady języków to en (angielski), es (hiszpański) i tr (turecki).
• ustawień regionalnych definiuje formatowanie tekstu używane przez usługę Power BI dla dat, waluty i innej powiązanej zawartości. Przykładami ustawień regionalnych są USA (angielski), ES (Hiszpania) i TR (Türkiye).

Aby uzyskać listę dostępnych języków i regionów, zobacz Obsługiwane języki.

Poniższy kod przypisuje określone wartości do tych localeSettings:

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

Przezroczyste tło

Domyślnie tło osadzonej zawartości jest białe z szarymi marginesami. Jeśli wolisz, możesz nadać osadzonej zawartości przezroczyste tło. Następnie możesz zastosować styl, który chcesz zastosować do elementu div HTML zawierającego osadzoną zawartość. Styl elementu div staje się widoczny.

Użyj tego kodu, aby ustawić tło osadzonej zawartości jako przezroczystą:

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

Zachowanie kliknięcia hiperłącza

Możesz kontrolować zachowanie hiperlinku w tabeli lub gotowe wizualizacje macierzy. Domyślnie hiperłącze otwiera nowe okno.

Dostępne tryby zachowania:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

• Navigate — adres URL jest ładowany do nowego kontekstu przeglądania.
• NavigateAndRaiseEvent — adres URL jest ładowany do nowego kontekstu przeglądania i zgłasza zdarzenie dataHyperlinkClicked.
• RaiseEvent — zapobiega domyślnemu zachowaniu kliknięcia adresu URL i zgłasza zdarzenie dataHyperlinkClicked.

Użyj tego kodu, aby zmienić zachowanie linków w celu wywołania zdarzenia:

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

Zdarzenie dataHyperlinkClicked jest uruchamiane po kliknięciu hiperlinku na gotowej tabeli lub wizualizacji macierzy, a zachowanie jest NavigateAndRaiseEvent lub RaiseEvent.

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

Aby uzyskać więcej informacji na temat obsługi zdarzeń, zobacz Jak obsługiwać zdarzenia.

Zdarzenia renderowane wizualizacji

Możesz nasłuchiwać zdarzenia dla każdej renderowanej wizualizacji. Domyślnie zdarzenia renderowane w wizualizacji są wyłączone.

Użyj tego kodu, aby wyzwolić zdarzenia visualRendered:

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

Zdarzenie visualRendered jest uruchamiane, gdy wizualizacja jest renderowana, a visualRenderedEvents jest włączona w ustawieniach raportu.

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

Aby uzyskać więcej informacji na temat obsługi zdarzeń, zobacz Jak obsługiwać zdarzenia.

Komunikaty o błędach

Jeśli chcesz wyświetlić dostosowane komunikaty o błędach w raportach osadzonych, użyj właściwości hideErrors, aby ukryć domyślne komunikaty o błędach osadzone w usłudze Power BI. Kod może następnie obsługiwać zdarzenia błędów w sposób pasujący do projektu aplikacji. Zobacz Przesłanianie domyślnych komunikatów o błędach, aby uzyskać więcej informacji na temat zastępowania błędów domyślnych.

Użyj tego kodu, aby ukryć domyślne komunikaty o błędach:

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

Dostosowywanie opcji

W poniższych sekcjach opisano sposób używania większej liczby właściwości w celu dalszego dostosowywania wyglądu i zachowania osadzonego raportu usługi Power BI.

Strona domyślna

Możesz kontrolować, która strona osadzonego raportu jest wyświetlana początkowo. Domyślnie początkowa strona to ostatnio zmodyfikowana strona, która była stroną aktywną ostatnio zapisaną w raporcie. To zachowanie można zastąpić za pomocą właściwości pageName i podać ją nazwą strony, którą chcesz wyświetlić. Jeśli jednak żadna strona o tej nazwie nie istnieje w usłudze Power BI, żądanie jego otwarcia zakończy się niepowodzeniem.

Poniższy kod przedstawia sposób konfigurowania aplikacji pod kątem wyświetlania określonej strony:

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

Filtry obciążenia

Możesz kontrolować filtry stosowane przez aplikację do osadzonego raportu. Domyślnie raport początkowo używa filtrów zapisanych w raporcie. Istnieją jednak dwie opcje, jeśli chcesz dostosować filtry:

• Skonfiguruj więcej filtrów do użycia razem z zapisanymi filtrami. Poniższy kod pokazuje, jak używać właściwości filters do dołączania większej liczby filtrów:

  let embedConfig = {
      ...
      filters: [...]
  };
  

• Zastąp zapisane filtry nowym zestawem. Metoda setFilters umożliwia dynamiczne zmienianie filtrów raportu. Jeśli używasz tej metody podczas osadzania etapowego, możesz zastąpić filtry, które początkowo stosuje raport. Aby uzyskać więcej informacji na temat konstruowania filtrów i używania metody setFilters, zobacz Filtry raportów kontroli.

W przypadku fragmentatorów ładowania

Możesz kontrolować stan fragmentatorów, które aplikacja ma zastosowanie do osadzonego raportu. Domyślnie interfejs API używa fragmentatorów zapisanych w raporcie. Można jednak użyć właściwości slicers, aby zmodyfikować stan istniejących fragmentatorów, jak pokazano w poniższym kodzie:

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

Aby uzyskać więcej informacji na temat modyfikowania stanu fragmentatora, zobacz Kontrolka fragmentatorów.

Przy ładowaniu zakładki

Za pomocą właściwości bookmark można zastosować zakładkę do raportu osadzonego. Zobacz Zakładki, aby uzyskać więcej informacji na temat używania zakładek do przechwytywania aktualnie skonfigurowanego widoku stron raportu.

Możesz określić zakładkę do użycia, podając nazwę zakładki lub stan. Jeśli podasz nazwę zakładki, raport usługi Power BI musi zawierać zapisaną zakładkę o tej nazwie.

Właściwość bookmark jest typu IApplyBookmarkRequest. Poniższy kod przedstawia definicję tego typu:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Ten kod pokazuje, jak określić zakładkę według nazwy:

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

Ten kod pokazuje, jak określić zakładkę według stanu:

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

Motywy i tryb dużego kontrastu

Możesz kontrolować motyw i poziom kontrastu używany przez osadzoną zawartość. Domyślnie każda osadzona zawartość jest wyświetlana z motywem domyślnym i zerowym kontrastem. To zachowanie można zastąpić, konfigurując określony motyw lub poziom kontrastu. Aby uzyskać więcej informacji na temat motywów, zobacz Zastosuj motywy raportów.

Dostępne tryby kontrastu:

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

Aby skonfigurować konkretny motyw, użyj kodu podobnego do następujących wierszy:

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

Poniższy kod pokazuje, jak zastąpić domyślny poziom kontrastu, None:

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

Poziom powiększenia

Aby dowiedzieć się więcej na temat dostosowywania poziomu powiększenia raportu, sprawdź dokument ułatwień dostępu.

Otwieranie w trybie edycji

Domyślnie osadzony raport jest wyświetlany w trybie wyświetlania. Można jednak zastąpić to zachowanie, aby otworzyć raport w trybie edycji. Można również przełączać się między trybami.

Konfigurowanie trybu edycji

Aby otworzyć osadzony raport w trybie edycji, użyj właściwości viewMode wraz z właściwością permissions.

Możesz przypisać właściwość viewMode następujące wartości:

• View — otwiera raport w trybie wyświetlania.
• Edit — otwiera raport w trybie edycji.

Możesz przypisać właściwość permissions następujące wartości:

• Read — użytkownicy mogą wyświetlać raport.
• ReadWrite — użytkownicy mogą wyświetlać, edytować i zapisywać raport.
• Copy — użytkownicy mogą zapisywać kopię raportu przy użyciu Zapisz jako.
• Create — użytkownicy mogą utworzyć nowy raport.
• All — użytkownicy mogą tworzyć, wyświetlać, edytować, zapisywać i zapisywać kopię raportu.

Podczas konfigurowania zawartości do otwierania w trybie edycji przypisz właściwość permissions wartość odpowiednią do edycji, jak pokazano w poniższym kodzie:

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

Przełączanie między trybami edycji i wyświetlania

Oprócz określania trybu uruchamiania osadzonej zawartości można również dynamicznie przełączać się między trybami edycji i wyświetlania.

Jeśli zawartość jest w trybie edycji i chcesz przełączyć się do trybu wyświetlania, użyj tego kodu JavaScript:

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

...

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

Jeśli zawartość jest w trybie wyświetlania i chcesz przełączyć się do trybu edycji, użyj tego kodu JavaScript:

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

...

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

Zagadnienia i ograniczenia

Podczas konfigurowania osadzonej zawartości należy wziąć pod uwagę następujące kwestie:

• Nie można zmienić położenia nawigacji strony, gdy pasek akcji jest widoczny. Dowiedz się więcej o pasku akcji .

• Jeśli używasz właściwości bars we właściwości setting zgodnie z opisem w Bary, interfejs API stosuje konfigurację tylko wtedy, gdy osadzona zawartość jest w trybie edycji. Jeśli zawartość jest w trybie wyświetlania, interfejs API ignoruje ustawienie bars.

• Jeśli używasz właściwości viewMode do wyświetlania zawartości w trybie edycji, należy wykonać dwa dodatkowe kroki:

  • Skonfiguruj poziom uprawnień z właściwością permissions. Ten poziom uprawnień musi przyznać użytkownikowi odpowiedni dostęp do modyfikowania zawartości. Jeśli na przykład przypiszesz wartość permissionsRead, użytkownik nie będzie mógł edytować zawartości.
  • Upewnij się, że token osadzania wygenerowany ma uprawnienia obsługujące edytowanie. Jeśli na przykład uzyskasz token z wartością accessLevelview, interfejs API nie będzie wyświetlać zawartości w trybie edycji.

• Właściwość okienka zastępuje następujące właściwości :

  • filterPaneEnabled
  • navContentPaneEnabled

  Jeśli używasz właściwości panes do konfigurowania widoczności nawigacji filtru lub strony, nie używaj właściwości filterPaneEnabled ani navContentPaneEnabled w aplikacji.

• Interfejs API nie może jednocześnie zastosować motywu i poziomu kontrastu do osadzonej zawartości. Jeśli skonfigurujesz obie opcje przy użyciu właściwości theme i contrastMode, interfejs API używa wartości contrastMode z osadzoną zawartością. Jednak interfejs API ignoruje ustawienie theme.

• Jeśli chcesz zastosować zakładkę do raportu osadzonego, możesz użyć właściwości bookmark. Jeśli podasz nazwę zakładki z tą właściwością, interfejs API może używać zakładki tylko wtedy, gdy istnieje z tą nazwą. Podobnie, jeśli używasz właściwości pageName do określenia strony otwierającej, interfejs API może wyświetlać tę stronę tylko wtedy, gdy istnieje z daną nazwą. Przed skonfigurowaniem nazwy rozważ użycie metody dostępu, takiej jak metoda getPages raportu , aby sprawdzić, czy składnik istnieje o tej nazwie.

Powiązana zawartość

• ulepszanie środowiska użytkowników za pomocą zakładek
• stosowanie motywów raportów w usłudze Power BI
• filtry raportów kontroli
• fragmentatory raportów kontroli