Migliorare l'esperienza degli utenti con i segnalibri

  • Articolo

I segnalibri del report in Power BI consentono di acquisire lo stato corrente di una pagina di report incorporata, inclusi tutti i filtri e lo stato degli oggetti visivi. Quando si apre il report in un secondo momento, è possibile selezionare il segnalibro per ripristinare il report nello stato salvato. Gli sviluppatori possono controllare l'esperienza utente usando le API client di Power BI per acquisire e applicare segnalibri.

Un segnalibro salvato può essere un segnalibro salvato come parte di un report o un segnalibro acquisito come stato in tempo reale di un report. Se si applica un segnalibro salvato quando si carica un report, è possibile specificare il segnalibro da usare specificando il nome del segnalibro o il relativo stato. Se si specifica un segnalibro per nome, il report deve contenere un segnalibro salvato con lo stesso nome.

Questo articolo illustra le diverse impostazioni dell'API necessarie per incorporare i report che supportano i segnalibri.

Nota

Nei report incorporati per l'organizzazione, i consumer di report creano segnalibri personali acquisiscendo lo stato del report e ritornando rapidamente a tale stato selezionando il segnalibro. Per altre informazioni, vedere Segnalibri personali .

Per informazioni su come creare un'esperienza simile nei report incorporati per i clienti, vedere la presentazione della visualizzazione report di acquisizione nel parco giochi di analisi incorporata di Power BI.

Per altre informazioni sull'uso dei segnalibri in Power BI, vedere Creare segnalibri in Power BI Desktop.

Per informazioni sull'uso di segnalibri personali durante l'incorporamento di Power BI, vedere Segnalibri personali.

Come usare i segnalibri del report

Le sezioni seguenti illustrano come usare le API client di Power BI per usare i segnalibri del report.

Gestire i segnalibri di un report

Per gestire i segnalibri di un report, usare la bookmarksManager proprietà di un'istanza di report incorporata.

La classe BookmarksManager include i metodi seguenti:

  • getBookmarks - Restituisce un elenco di segnalibri salvati associati al report.

  • apply - Applica per nome un segnalibro salvato in precedenza al report.

  • capture - Acquisisce e restituisce una stringa di serializzazione base64, che rappresenta lo stato corrente del report.

  • applyState Applica uno stato di serializzazione base64 acquisito in precedenza di un segnalibro al report.

  • play - Controlla la modalità presentazione diapositiva per i segnalibri del report.

Accedere a un segnalibro del report

Per accedere a un singolo segnalibro, usare il getBookmarks metodo per accedere a un elenco di ReportBookmark oggetti. La ReportBookmark classe ha le proprietà seguenti:

  • name - Identificatore univoco del segnalibro del report.

  • displayName - Nome visualizzato del segnalibro del report, visualizzato nel riquadro Segnalibri .

  • state - Serializzazione base64 dello stato del segnalibro del report. È possibile salvarlo e applicarlo a un report con il bookmarksManager.applyState metodo .

  • children - Elenco di oggetti che rappresentano un gruppo di ReportBookmark segnalibri del report, se presente.

Usare le API dei segnalibri del report

In un report incorporato gli sviluppatori possono:

Ottenere un elenco dei segnalibri del report salvati

Per ottenere l'elenco dei segnalibri salvati associati a un report, chiamare il getBookmarks metodo dell'oggetto BookmarksManager restituito dalla proprietà del bookmarksManager report.

Il getBookmarks metodo è definito come segue:

getBookmarks(): Promise<models.IReportBookmark[]>

Ad esempio:

let bookmarks = await report.bookmarksManager.getBookmarks();

Applicare un segnalibro salvato per nome al caricamento del report o durante una sessione

Per applicare un segnalibro salvato in precedenza a un report usando il nome del segnalibro, chiamare il apply metodo dell'oggetto BookmarksManager restituito dalla proprietà di bookmarksManager un report.

Per altre informazioni, vedere Configurare le impostazioni del report.

Il apply metodo è definito come segue:

apply(bookmarkName: string): Promise<void>

Ad esempio:

await report.bookmarksManager.apply("Bookmark1234");

Acquisire e ottenere una visualizzazione corrente come oggetto segnalibro

Per acquisire lo stato corrente di un report come stringa base64, chiamare il capture metodo di un oggetto BookmarksManager . Il capture metodo restituisce un oggetto, che rappresenta un IReportBookmark segnalibro non salvato in un report specifico. Utilizzare la IReportBookmark.state proprietà per restituire la stringa base64 che identifica lo stato del segnalibro, che è possibile applicare successivamente a un report durante il tempo di caricamento o di esecuzione.

Il capture metodo è definito come segue:

capture(options?:ICaptureBookmarkOptions): Promise<models.IReportBookmark>

Ad esempio:

let capturedBookmark = await report.bookmarksManager.capture();

Opzioni di acquisizione dei segnalibri

È anche possibile passare un ICaptureBookmarkOptions oggetto al capture metodo .

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages - Per impostazione predefinita, lo stato del segnalibro acquisito salva solo lo stato della pagina corrente. Per acquisire lo stato di tutte le pagine, chiamare capture il metodo con allPages l'opzione impostata su true.
  • personalizeVisuals - Per acquisire lo stato corrente con oggetti visivi personalizzati, chiamare il capture metodo con l'opzione personalizeVisuals impostata su true.

Ad esempio, il codice seguente acquisisce lo stato di tutte le pagine, inclusi gli oggetti visivi personalizzati:

let capturedBookmark = await report.bookmarksManager.capture({
    allPages: true,
    personalizeVisuals: true
});

Applicare uno stato del segnalibro acquisito sul carico del report o durante una sessione

Per applicare uno stato segnalibro acquisito in precedenza a un report, usare il applyState metodo di un oggetto BookmarksManager .

Per altre informazioni, vedere Configurare le impostazioni del report.

Il applyState metodo è definito come segue:

applyState(state: string): Promise<void>

Ad esempio:

await report.bookmarksManager.applyState(capturedBookmark.state);

Eseguire una logica aggiuntiva quando viene applicato un segnalibro del report

Per determinare quando è stato applicato un segnalibro del report, ascoltare l'evento chiamando il on metodo dell'oggetto bookmarkApplied report.

Ad esempio:

report.on("bookmarkApplied", (event) => {
    console.log(event.detail.name);
});

Visualizzare o nascondere il riquadro Segnalibri

Per visualizzare o nascondere il riquadro Segnalibri di Power BI, aggiornare la panes proprietà delle impostazioni del report.

Mostra il riquadro Segnalibri

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: true
        }
    }
};

Nascondere il riquadro Segnalibri

let embedConfig = {
    ...
    panes: {
        bookmarks: {
            visible: false
        }
    }
};

Per informazioni sull'aggiornamento delle impostazioni del report, vedere Configurare le impostazioni del report.

Immettere o uscire dalla modalità presentazione segnalibri

Per controllare la modalità presentazione della diapositiva per i segnalibri di un report, chiamare il play metodo di un oggetto BookmarksManager . Per altre informazioni, vedere Segnalibri come presentazione.

Il play metodo è definito come segue:

play(playMode: models.BookmarksPlayMode): Promise<void>

Nota

Prima di immettere la modalità presentazione segnalibri, assicurarsi che nel report sia presente almeno un segnalibro con l'API getBookmarks.

Immettere la modalità presentazione della presentazione

await report.bookmarksManager.play(models.BookmarksPlayMode.Presentation);

Esci dalla modalità presentazione presentazione

await report.bookmarksManager.play(models.BookmarksPlayMode.Off);

Limitazioni

  • Quando si usa l'API segnalibri, alcune modifiche apportate al report possono causare un errore o un risultato imprevisto. Un esempio di questo è la rimozione dei filtri del report dal report. Per evitare errori, le schede di filtro corrispondenti devono essere presenti. Anziché rimuovere i filtri, impostare i valori su All. Se non si conosce quali filtri sono stati eliminati o modificati, ricaptare il segnalibro dopo aver applicato le modifiche al report.

  • I filtri, ad esempio per i filtri di carico creati dalla sessione di incorporamento o aggiunti dall'operazione di aggiunta dei filtri di aggiornamento, vengono acquisiti nello stato del segnalibro, ma verranno applicati solo nella sessione corrente. Per superare questa limitazione, il filtro deve essere salvato nel report con il All valore e modificato nella sessione di incorporamento usando l'operazione di aggiornamento dei filtri di aggiornamento.

Passaggi successivi