Condividi tramite

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 del 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 lo stato salvato del report. 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 in base al nome, il report deve contenere un segnalibro salvato con lo stesso nome.

Questo articolo illustra le diverse impostazioni api necessarie per incorporare report che supportano i segnalibri.

Nota

Nei report incorporati per l'organizzazione, i consumer di report creano segnalibri personali acquisendo lo stato del report e restituendo 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 playground 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, utilizzare la proprietà bookmarksManager di un'istanza del 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, utilizzare il metodo getBookmarks per accedere a un elenco di oggetti ReportBookmark. La classe ReportBookmark ha le proprietà seguenti:

  • name: identificatore univoco del segnalibro del report.

  • : 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 metodo bookmarksManager.applyState.

  • children: elenco di oggetti ReportBookmark che rappresentano un gruppo di segnalibri del report, se esistente.

Usare le API dei segnalibri del report

In un report incorporato gli sviluppatori possono:

Ottenere un elenco di segnalibri del report salvati

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

Il metodo getBookmarks viene definito come segue:

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

Per 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 utilizzando il nome del segnalibro, chiamare il metodo dell'oggetto BookmarksManager restituito dalla proprietà di un report.

Per altre informazioni, vedere Configurare le impostazioni del report.

Il metodo apply viene definito come segue:

apply(bookmarkName: string): Promise<void>

Per 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 metodo di un oggetto BookmarksManager . Il metodo capture restituisce un oggetto IReportBookmark, che rappresenta un segnalibro non salvato in un report specifico. Utilizzare la proprietà IReportBookmark.state per restituire la stringa base64 che identifica lo stato del segnalibro, che in seguito è possibile applicare a un report durante il tempo di caricamento o di runtime.

Il metodo capture viene definito come segue:

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

Per esempio:

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

Opzioni di acquisizione segnalibro

È anche possibile passare un oggetto ICaptureBookmarkOptions al metodo capture.

interface ICaptureBookmarkOptions {
    allPages?: boolean;
    personalizeVisuals?: boolean;
}
  • allPages: per impostazione predefinita, lo stato del segnalibro acquisito salverà solo lo stato della pagina corrente. Per acquisire lo stato di tutte le pagine, chiamare capture metodo con allPages opzione impostata su true.
  • personalizeVisuals: per acquisire lo stato corrente con oggetti visivi personalizzati, chiamare il metodo capture 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 al caricamento del report o durante una sessione

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

Per altre informazioni, vedere Configurare le impostazioni del report.

Il metodo applyState viene definito come segue:

applyState(state: string): Promise<void>

Per esempio:

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

Eseguire logica aggiuntiva quando viene applicato un segnalibro del report

Per determinare quando è stato applicato un segnalibro del report, restare in ascolto dell'evento chiamando il metodo dell'oggetto report .

Per 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 proprietà delle impostazioni del report.

Visualizzare 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 diapositiva per i segnalibri di un report, chiamare il metodo di un oggetto BookmarksManager . Per altre informazioni, vedere Segnalibri come presentazione.

Il metodo play viene definito come segue:

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

Nota

Prima di accedere alla modalità presentazione dei segnalibri, assicurarsi che nel report sia presente almeno un segnalibro con 'API getBookmarks.

Immettere la modalità presentazione diapositiva

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

Uscire dalla modalità presentazione diapositiva

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

Considerazioni e limitazioni

  • Quando si usa l'API segnalibri, alcune modifiche apportate al report possono causare un errore o un risultato imprevisto. Un esempio è la rimozione dei filtri del report dal report. Per evitare errori, è necessario che siano presenti le schede di filtro corrispondenti. Anziché rimuovere i filtri, impostare i relativi valori su All. Se non si conoscono i filtri eliminati o modificati, ricapitolare il segnalibro dopo l'applicazione delle modifiche al report.

  • I filtri come sui filtri di carico creati dalla sessione di incorporamento o aggiunti dal filtri di aggiornamento aggiungono l'operazione, 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 valore All e modificato nella sessione di incorporamento usando l'operazione di aggiornamento dei filtri di aggiornamento .

Contenuto correlato