Mengonfigurasi pengaturan laporan

Artikel
07/17/2024

Dengan menggunakan API Klien Power BI, Anda bisa menyematkan analitik Power BI di aplikasi Anda. Saat Anda menggunakan pustaka sisi klien ini untuk menyematkan laporan Power BI, Anda menyediakan API dengan informasi tentang laporan tersebut.

Anda bisa menggunakan objek konfigurasi untuk menyimpan informasi tentang laporan Power BI Anda. Saat Anda menyematkan laporan, Anda kemudian meneruskan objek tersebut ke API.

Selain memberikan akses API ke laporan, Anda juga dapat menggunakan objek konfigurasi untuk menyesuaikan tampilan dan perilaku laporan Anda. Misalnya, Anda dapat menyesuaikan visibilitas filter, akses navigasi, dan pengaturan lokasi di objek konfigurasi.

Bagian berikut menjelaskan cara menyematkan dan mengonfigurasi konten Power BI.

Menyediakan informasi konfigurasi

Antarmuka IReportLoadConfiguration menampilkan properti yang dapat disediakan objek konfigurasi ke API Klien Power BI tentang laporan:

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

Lihat Menyematkan laporan untuk penjelasan parameter antarmuka ini yang diperlukan dan untuk contoh kode yang menunjukkan cara menyematkan laporan.

Mengkustomisasi pengaturan

Bagian berikut ini menjelaskan cara menggunakan properti settings untuk menyesuaikan tampilan dan perilaku laporan Power BI yang disematkan. Untuk memperbarui pengaturan laporan saat laporan sudah dimuat, gunakan metode report.updateSettings. Untuk informasi selengkapnya, lihat Memperbarui pengaturan laporan saat runtime.

Panel

Kontrol tampilan semua panel dalam laporan Power BI Anda dengan satu properti panes, seperti yang diperlihatkan dalam kode berikut:

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

Dari tabel berikut, Anda dapat melihat nilai mana yang didukung setiap properti panes:

Harta benda	Terlihat	Diperluas
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

Panel filter

Secara default, panel filter terlihat. Jika Anda ingin menyembunyikan panel ini, gunakan properti filterPaneEnabled, seperti yang diperlihatkan dalam kode berikut:

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

Nota

Properti panel menggantikan properti filterPaneEnabled. Untuk mempertahankan kompatibilitas mundur, properti filterPaneEnabled masih ada. Namun, Anda harus menghindari penggunaan kedua properti ini bersama-sama.

Secara default, panah navigasi halaman terlihat pada laporan yang disematkan. Untuk menyembunyikan panah ini, gunakan properti navContentPaneEnabled, seperti yang diperlihatkan dalam kode berikut:

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

Nota

Properti panel menggantikan properti navContentPaneEnabled. Untuk mempertahankan kompatibilitas mundur, properti navContentPaneEnabled masih ada. Namun, Anda harus menghindari penggunaan kedua properti ini bersama-sama.

Panel navigasi halaman muncul di bagian bawah laporan, untuk menggunakan panel halaman vertikal baru, Anda bisa mengatur properti position:

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

Nota

Anda tidak dapat mengubah posisi panel navigasi halaman menggunakan updateSettings.

Bar

Atur visibilitas bilah tindakan dan bilah status dengan menggunakan properti bars.

Bilah tindakan

Kode berikut membuat bilah tindakan terlihat:

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

Atau, dalam mode tampilan, dimungkinkan juga untuk menggunakan parameter URL actionBarEnabled:

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

Nota

Dalam mode tampilan, bilah tindakan hanya didukung untuk yang disematkan untuk skenario organisasi Anda.

Untuk bilah tindakan dalam mode tampilan, disarankan untuk mengaktifkan izin UserState.ReadWrite.All untuk aplikasi Microsoft Azure AD Anda. Izin ini diperlukan untuk memungkinkan pengguna akhir menambahkan laporan ke favorit mereka, dan untuk mengaktifkan bookmark pribadi dan filter persisten .

Bilah status

Bilah status memegang pengontrol zoom kanvas, yang menyediakan kemampuan untuk memperbesar pada kanvas.

Kode berikut membuat bilah status terlihat:

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

Pengaturan lokal

Gunakan properti localeSettings untuk menentukan bahasa dan pemformatan laporan yang disematkan:

Properti language dalam localeSettings terdiri dari dua bagian dari masing-masing dua huruf, dipisahkan oleh tanda hubung:

bahasa menentukan bahasa yang digunakan Power BI untuk pelokalan. Contoh bahasa termasuk en (Inggris), es (Spanyol), dan tr (Turki).
lokal menentukan pemformatan teks yang digunakan Power BI untuk tanggal, mata uang, dan konten terkait lainnya. Contoh lokal termasuk AS (Inggris), ES (Spanyol), dan TR (Türkiye).

Lihat Bahasa yang didukung untuk daftar bahasa dan wilayah yang tersedia.

Kode berikut menetapkan nilai tertentu ke localeSettingsini :

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

Nota

Pengaturan lokal tidak dapat diubah setelah laporan dimuat. Untuk mengubah pengaturan lokal laporan, reset iframe dengan memanggil powerbi.reset(element), lalu sematkan laporan lagi.

Latar belakang transparan

Secara default, latar belakang konten yang disematkan berwarna putih dengan margin abu-abu. Jika mau, Anda dapat memberi konten yang disematkan latar belakang transparan. Kemudian Anda dapat menerapkan gaya yang Anda inginkan ke elemen html div yang berisi konten yang disematkan. Gaya elemen div kemudian menjadi terlihat.

Gunakan kode ini untuk membuat latar belakang konten yang disematkan transparan:

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

Perilaku klik hyperlink

Anda bisa mengontrol perilaku hyperlink dalam tabel, atau visual out-of-the-box matriks. Secara default, hyperlink membuka jendela baru.

Mode perilaku tersedia:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate - URL dimuat ke dalam konteks penjelajahan baru.
NavigateAndRaiseEvent - URL dimuat ke dalam konteks penjelajahan baru, dan menimbulkan peristiwa dataHyperlinkClicked.
RaiseEvent - Mencegah perilaku default klik URL, dan menaikkan peristiwa dataHyperlinkClicked.

Gunakan kode ini untuk mengubah perilaku tautan untuk menaikkan peristiwa:

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

Peristiwa dataHyperlinkClicked diaktifkan saat hyperlink diklik pada tabel out-of-the-box atau visual matriks dan perilakunya NavigateAndRaiseEvent atau RaiseEvent.

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

Untuk informasi selengkapnya tentang menangani peristiwa, lihat Cara menangani peristiwa.

Peristiwa yang dirender visual

Anda dapat mendengarkan acara untuk setiap visual yang dirender. Secara default, peristiwa visual yang dirender dinonaktifkan.

Gunakan kode ini untuk membuat peristiwa visualRendered dipicu:

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

Peristiwa visualRendered diaktifkan saat visual dirender dan visualRenderedEvents diaktifkan pada pengaturan laporan.

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

Untuk informasi selengkapnya tentang menangani peristiwa, lihat Cara menangani peristiwa.

Nota

Karena visual mungkin dirender karena interaksi pengguna, disarankan untuk mengaktifkan peristiwa ini hanya jika diperlukan.

Pesan kesalahan

Jika Anda ingin menampilkan pesan kesalahan yang dikustomisasi dalam laporan yang disematkan, gunakan properti hideErrors untuk menyembunyikan pesan kesalahan yang disematkan Power BI default. Kode Anda kemudian dapat menangani peristiwa kesalahan dengan cara yang sesuai dengan desain aplikasi Anda. Lihat Mengambil alih pesan kesalahan default untuk informasi selengkapnya tentang menimpa kesalahan default.

Gunakan kode ini untuk menyembunyikan pesan kesalahan default:

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

Mengkustomisasi opsi

Bagian berikut ini menjelaskan cara menggunakan lebih banyak properti untuk mengkustomisasi tampilan dan perilaku laporan Power BI yang disematkan lebih lanjut.

Halaman default

Anda dapat mengontrol halaman mana dari laporan tersemat Anda yang muncul pada awalnya. Secara default, halaman awal adalah halaman yang terakhir kali Anda ubah, yang merupakan halaman aktif terakhir kali Anda menyimpan laporan. Anda dapat mengambil alih perilaku ini dengan menggunakan properti pageName dan menyediakannya dengan nama halaman yang ingin Anda tampilkan. Namun, jika tidak ada halaman dengan nama tersebut yang ada di Power BI, permintaan untuk membukanya gagal.

Kode berikut menunjukkan cara mengonfigurasi aplikasi Anda untuk menampilkan halaman tertentu:

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

Pada filter beban

Anda dapat mengontrol filter yang diterapkan aplikasi Anda ke laporan yang disematkan. Secara default, laporan awalnya menggunakan filter yang Anda simpan ke laporan. Namun, Anda memiliki dua opsi jika Anda ingin menyesuaikan filter:

Konfigurasikan lebih banyak filter untuk digunakan bersama dengan filter yang disimpan. Kode berikut menunjukkan cara menggunakan properti filters untuk menambahkan lebih banyak filter:
```
let embedConfig = {
    ...
    filters: [...]
};
```
Ganti filter yang disimpan dengan set baru. Metode setFilters menyediakan cara untuk mengubah filter laporan secara dinamis. Jika Anda menggunakan metode ini selama penyematan bertahap, Anda dapat mengambil alih filter yang awalnya diterapkan laporan. Untuk informasi selengkapnya tentang membuat filter dan menggunakan metode setFilters, lihat filter laporan Kontrol .

Pada pemotong beban

Anda dapat mengontrol status pemotong yang diterapkan aplikasi Anda ke laporan yang disematkan. Secara default, API menggunakan pemotong yang Anda simpan ke laporan. Namun, Anda dapat menggunakan properti slicers untuk memodifikasi status pemotong yang ada, seperti yang ditunjukkan kode berikut:

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

Lihat pemotong laporan Kontrol untuk informasi selengkapnya tentang memodifikasi status pemotong.

Pada bookmark beban

Dengan menggunakan properti bookmark, Anda dapat menerapkan bookmark ke laporan yang disematkan. Lihat Bookmark untuk informasi selengkapnya tentang menggunakan marka buku untuk mengambil tampilan halaman laporan yang saat ini dikonfigurasi.

Anda dapat menentukan marka buku yang akan digunakan dengan memberikan nama marka buku atau status. Jika Anda memberikan nama marka buku, laporan Power BI Anda harus berisi marka buku yang disimpan dengan nama tersebut.

Properti bookmark berjenis IApplyBookmarkRequest. Kode berikut menunjukkan definisi jenis ini:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Kode ini menunjukkan cara menentukan marka buku berdasarkan nama:

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

Kode ini menunjukkan cara menentukan marka buku menurut status:

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

Tema dan mode kontras tinggi

Anda dapat mengontrol tema dan tingkat kontras yang digunakan konten tersemat Anda. Secara default, konten apa pun yang Anda sematkan muncul dengan tema default dan tanpa kontras. Anda dapat mengambil alih perilaku ini dengan mengonfigurasi tema atau tingkat kontras tertentu. Untuk informasi selengkapnya tentang tema, lihat Menerapkan tema laporan.

Mode kontras yang tersedia:

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

Untuk mengonfigurasi tema tertentu, gunakan kode yang mirip dengan baris berikut:

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

Kode berikut menunjukkan cara mengambil alih tingkat kontras default, None:

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

Nota

API tidak dapat menerapkan tema dan tingkat kontras secara bersamaan. Jika Anda mengonfigurasi kedua properti, API menggunakan tingkat kontras yang Anda tentukan tetapi mengabaikan pengaturan theme.

Tingkat perbesar tampilan

Untuk mempelajari selengkapnya tentang menyesuaikan tingkat zoom laporan, periksa dokumen aksesibilitas .

Buka dalam mode edit

Secara default, laporan yang Anda sematkan muncul dalam mode tampilan. Namun, Anda dapat mengambil alih perilaku ini untuk membuka laporan dalam mode edit. Anda juga dapat beralih antar mode.

Mengonfigurasi mode edit

Untuk membuka laporan yang disematkan dalam mode edit, gunakan properti viewMode bersama dengan properti permissions.

Anda bisa menetapkan properti viewMode nilai berikut:

View - Membuka laporan dalam mode tampilan.
Edit - Membuka laporan dalam mode edit.

Anda dapat menetapkan properti permissions nilai-nilai ini:

Read - Pengguna dapat melihat laporan.
ReadWrite - Pengguna dapat melihat, mengedit, dan menyimpan laporan.
Copy - Pengguna dapat menyimpan salinan laporan dengan menggunakan Simpan Sebagai.
Create - Pengguna dapat membuat laporan baru.
All - Pengguna dapat membuat, menampilkan, mengedit, menyimpan, dan menyimpan salinan laporan.

Saat Anda mengonfigurasi konten untuk dibuka dalam mode edit, tetapkan properti permissions nilai yang sesuai untuk pengeditan, seperti yang ditunjukkan kode berikut:

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

Nota

Nilai permissions yang Anda konfigurasi hanya berfungsi jika token semat yang Anda peroleh memiliki hak istimewa yang memadai. Untuk informasi selengkapnya tentang token semat, lihat Membuat token yang disematkan.

Beralih antara mode edit dan tampilan

Selain menentukan mode untuk konten yang disematkan untuk memulai, Anda juga dapat beralih antara mode edit dan tampilan secara dinamis.

Jika konten dalam mode edit, dan Anda ingin beralih ke mode tampilan, gunakan kode JavaScript ini:

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

...

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

Jika konten dalam mode tampilan, dan Anda ingin beralih ke mode edit, gunakan kode JavaScript ini:

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

...

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

Pertimbangan dan batasan

Pertimbangkan poin-poin berikut saat Anda mengonfigurasi konten yang disematkan:

Navigasi halaman posisi tidak dapat diubah saat bilah tindakan terlihat. Pelajari selengkapnya tentang bilah tindakan .
Saat Anda menggunakan properti bars di properti setting, seperti yang dijelaskan di Bilah, API hanya menerapkan konfigurasi Anda jika konten yang disematkan dalam mode edit. Jika konten Anda dalam mode tampilan, API mengabaikan pengaturan bars.
Saat Anda menggunakan properti viewMode untuk menampilkan konten dalam mode edit, Anda perlu mengambil dua langkah tambahan:
- Konfigurasikan tingkat izin dengan properti permissions. Tingkat izin tersebut perlu memberi pengguna akses yang sesuai untuk memodifikasi konten. Misalnya, jika Anda menetapkan nilai permissionsRead, pengguna tidak akan dapat mengedit konten.
- Pastikan bahwa token disematkan yang Anda hasilkan memiliki hak istimewa yang mendukung pengeditan. Misalnya, jika Anda memperoleh token dengan nilai accessLevelview, API gagal menampilkan konten dalam mode edit.
Properti panel menggantikan properti settings berikut ini:
- filterPaneEnabled
- navContentPaneEnabled
Jika Anda menggunakan properti panes untuk mengonfigurasi visibilitas navigasi filter atau halaman, jangan gunakan properti filterPaneEnabled atau navContentPaneEnabled di aplikasi Anda.
API tidak dapat menerapkan tema dan tingkat kontras untuk konten yang disematkan secara bersamaan. Jika Anda mengonfigurasi kedua opsi dengan menggunakan properti theme dan contrastMode, API menggunakan nilai contrastMode Anda dengan konten yang disematkan. Namun, API mengabaikan pengaturan theme.
Jika Anda ingin menerapkan bookmark ke laporan yang disematkan, Anda bisa menggunakan properti bookmark. Jika Anda memberikan nama bookmark dengan properti tersebut, API hanya dapat menggunakan marka buku jika ada dengan nama tersebut. Demikian juga, jika Anda menggunakan properti pageName untuk menentukan halaman pembukaan, API hanya dapat menampilkan halaman tersebut jika ada dengan nama yang diberikan. Sebelum mengonfigurasi nama, pertimbangkan untuk menggunakan metode aksesor, seperti metode Laporkan getPages, untuk memeriksa apakah komponen ada dengan nama tersebut.

Tingkatkan pengalaman pengguna Anda dengan bookmark
Menerapkan tema laporan di Power BI
filter laporan Kontrol
pemotong laporan Kontrol

Bagikan melalui

Mengonfigurasi pengaturan laporan

Menyediakan informasi konfigurasi

Mengkustomisasi pengaturan

Panel

Panel filter

Panel navigasi halaman

Bar

Bilah tindakan

Bilah status

Pengaturan lokal

Latar belakang transparan

Perilaku klik hyperlink

Peristiwa yang dirender visual

Pesan kesalahan

Mengkustomisasi opsi

Halaman default

Pada filter beban

Pada pemotong beban

Pada bookmark beban

Tema dan mode kontras tinggi

Tingkat perbesar tampilan

Buka dalam mode edit

Mengonfigurasi mode edit

Beralih antara mode edit dan tampilan

Pertimbangan dan batasan

Sumber Daya Tambahan:

Bagikan melalui

Mengonfigurasi pengaturan laporan

Menyediakan informasi konfigurasi

Mengkustomisasi pengaturan

Panel

Panel filter

Panel navigasi halaman

Bar

Bilah tindakan

Bilah status

Pengaturan lokal

Latar belakang transparan

Perilaku klik hyperlink

Peristiwa yang dirender visual

Pesan kesalahan

Mengkustomisasi opsi

Halaman default

Pada filter beban

Pada pemotong beban

Pada bookmark beban

Tema dan mode kontras tinggi

Tingkat perbesar tampilan

Buka dalam mode edit

Mengonfigurasi mode edit

Beralih antara mode edit dan tampilan

Pertimbangan dan batasan

Konten terkait

Sumber Daya Tambahan: