Configurare le impostazioni rapporto

  • Articolo

Usando le API client di Power BI, è possibile incorporare l'analisi di Power BI nell'applicazione. Quando si usa questa libreria lato client per incorporare un report di Power BI, si forniscono all'API informazioni su tale report.

È possibile usare un oggetto di configurazione per archiviare informazioni sul report di Power BI. Quando si incorpora il report, si passa l'oggetto all'API.

Oltre a concedere all'API l'accesso al report, è anche possibile usare l'oggetto di configurazione per personalizzare l'aspetto e il comportamento del report. Ad esempio, è possibile modificare le impostazioni di visibilità, accesso alla navigazione e posizione del filtro nell'oggetto di configurazione.

Le sezioni seguenti illustrano come incorporare e configurare il contenuto di Power BI.

Specificare le informazioni di configurazione

L'interfaccia IReportLoadConfiguration visualizza le proprietà che un oggetto di configurazione può fornire alle API client di Power BI relative a un report:

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

Vedere Incorporare un report per una spiegazione dei parametri obbligatori di questa interfaccia e per esempi di codice che illustrano come incorporare un report.

Personalizzare le impostazioni

Le sezioni seguenti descrivono come usare la settings proprietà per modificare l'aspetto e il comportamento del report di Power BI incorporato. Per aggiornare le impostazioni del report quando il report è già caricato, utilizzare il report.updateSettings metodo . Per altre informazioni, vedere Aggiornare le impostazioni del report in fase di esecuzione.

Riquadri

Controllare l'aspetto di tutti i riquadri nel report di Power BI con una singola panes proprietà, come illustrato nel codice seguente:

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

Nella tabella seguente è possibile visualizzare i valori supportati da ogni panes proprietà:

Proprietà Visible Esteso
bookmarks ✔ ❌
fields ✔ ✔
filters ✔ ✔
pageNavigation ✔ ❌
selection ✔ ❌
syncSlicers ✔ ❌
visualizations ✔ ✔

Riquadro Filtro

Per impostazione predefinita, il riquadro filtro è visibile. Se si vuole nascondere questo riquadro, usare la filterPaneEnabled proprietà , come illustrato nel codice seguente:

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

Nota

La proprietà panes sostituisce la filterPaneEnabled proprietà . Per mantenere la compatibilità con le versioni precedenti, la filterPaneEnabled proprietà esiste ancora. Tuttavia, è consigliabile evitare di usare queste due proprietà insieme.

Riquadro di spostamento della pagina

Per impostazione predefinita, le frecce di spostamento della pagina sono visibili nei report incorporati. Per nascondere queste frecce, usare la navContentPaneEnabled proprietà , come illustrato nel codice seguente:

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

Nota

La proprietà panes sostituisce la navContentPaneEnabled proprietà . Per mantenere la compatibilità con le versioni precedenti, la navContentPaneEnabled proprietà esiste ancora. Tuttavia, è consigliabile evitare di usare queste due proprietà insieme.

Il riquadro di spostamento della pagina viene visualizzato nella parte inferiore del report per usare il nuovo riquadro pagine verticali che è possibile impostare la position proprietà :

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

Nota

Non è possibile modificare la posizione del riquadro di spostamento della pagina usando updateSettings.

Bars

Impostare la visibilità della barra delle azioni e della barra di stato usando la bars proprietà .

Barra delle azioni

Il codice seguente rende visibile la barra delle azioni:

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

In alternativa, in modalità di visualizzazione, è anche possibile usare il actionBarEnabled parametro URL:

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

Nota

In modalità di visualizzazione la barra delle azioni è supportata solo per l'incorporamento per lo scenario dell'organizzazione .

Per la barra delle azioni in modalità di visualizzazione è consigliabile abilitare l'autorizzazione UserState.ReadWrite.All per l'applicazione Azure AD. Questa autorizzazione è necessaria per consentire agli utenti finali di aggiungere il report ai preferiti e di abilitare segnalibri personali e filtri permanenti.

Status bar

La barra di stato contiene il controller di zoom dell'area di disegno, che consente di eseguire lo zoom sull'area di disegno.

Il codice seguente rende visibile la barra di stato:

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

Impostazioni locali

Utilizzare la localeSettings proprietà per specificare la lingua e la formattazione del report incorporato:

La language proprietà in localeSettings è costituita da due parti di due lettere, separate da un trattino:

  • il linguaggio definisce la lingua usata da Power BI per la localizzazione. Esempi di lingue includono en (inglese), es (spagnolo) e tr (turco).
  • le impostazioni locali definiscono la formattazione del testo usata da Power BI per date, valuta e altri contenuti correlati. Esempi di impostazioni locali includono Stati Uniti (inglese), ES (Spagna) e TR (Türkiye).

Per un elenco delle lingue e delle aree disponibili, vedere Lingue supportate.

Il codice seguente assegna valori specifici a questi localeSettings:

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

Nota

Le impostazioni locali non possono essere modificate dopo il caricamento del report. Per modificare le impostazioni locali del report, reimpostare l'iframe chiamando powerbi.reset(element)e quindi incorporare nuovamente il report.

Sfondo trasparente

Per impostazione predefinita, lo sfondo del contenuto incorporato è bianco con margini grigi. Se si preferisce, è possibile assegnare al contenuto incorporato uno sfondo trasparente. È quindi possibile applicare lo stile desiderato all'elemento HTML div che contiene il contenuto incorporato. Lo div stile dell'elemento diventa quindi visibile.

Usare questo codice per rendere trasparente lo sfondo del contenuto incorporato:

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

È possibile controllare il comportamento di un collegamento ipertestuale in una tabella o oggetti visivi predefiniti della matrice. Per impostazione predefinita, il collegamento ipertestuale aprirà una nuova finestra.

Di seguito sono elencate le modalità di comportamento disponibili:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}
  • Navigate - L'URL verrà caricato in un nuovo contesto di esplorazione.
  • NavigateAndRaiseEvent - L'URL verrà caricato in un nuovo contesto di esplorazione e genererà un dataHyperlinkClicked evento.
  • RaiseEvent - Impedisce il comportamento predefinito del clic url e genera evento dataHyperlinkClicked .

Usare questo codice per modificare il comportamento dei collegamenti per generare un evento:

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

Un dataHyperlinkClicked evento viene generato quando si fa clic su un collegamento ipertestuale su un oggetto visivo tabella o matrice predefinito e il comportamento è NavigateAndRaiseEvent o RaiseEvent.

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

Per altre informazioni sulla gestione degli eventi, vedere Come gestire gli eventi.

Eventi di cui è stato eseguito il rendering degli oggetti visivi

È possibile restare in ascolto di un evento per ogni oggetto visivo di cui è stato eseguito il rendering. Per impostazione predefinita, gli eventi di cui è stato eseguito il rendering dell'oggetto visivo sono disabilitati.

Usare questo codice per attivare gli visualRendered eventi:

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

Un visualRendered evento viene generato quando viene eseguito il rendering di un oggetto visivo e viene visualRenderedEvents abilitato nelle impostazioni del report.

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

Per altre informazioni sulla gestione degli eventi, vedere Come gestire gli eventi.

Nota

Poiché gli oggetti visivi potrebbero essere visualizzati a causa delle interazioni dell'utente, è consigliabile attivare questo evento solo quando necessario.

messaggi di errore

Se si desidera visualizzare messaggi di errore personalizzati nei report incorporati, usare la hideErrors proprietà per nascondere i messaggi di errore incorporati di Power BI predefiniti. Il codice può quindi gestire gli eventi di errore in modo da adattare alla progettazione dell'app. Per altre informazioni sull'override degli errori predefiniti, vedere Override dei messaggi di errore predefiniti .

Usare questo codice per nascondere i messaggi di errore predefiniti:

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

Personalizzare le opzioni

Le sezioni seguenti descrivono come usare proprietà aggiuntive per personalizzare ulteriormente l'aspetto e il comportamento del report di Power BI incorporato.

Pagina predefinita

È possibile controllare la pagina del report incorporato visualizzata inizialmente. Per impostazione predefinita, la pagina iniziale è la pagina modificata più di recente, ovvero la pagina attiva l'ultima volta che è stato salvato il report. È possibile eseguire l'override di questo comportamento usando la pageName proprietà e specificandola con il nome della pagina da visualizzare. Tuttavia, se non esiste alcuna pagina con tale nome in Power BI, la richiesta di aprirla ha esito negativo.

Il codice seguente illustra come configurare l'app per visualizzare una pagina specifica:

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

Nei filtri di carico

È possibile controllare i filtri applicati all'app a un report incorporato. Per impostazione predefinita, il report usa inizialmente i filtri salvati nel report. Tuttavia, sono disponibili due opzioni per modificare i filtri:

  • Configurare filtri aggiuntivi da usare insieme ai filtri salvati. Il codice seguente illustra come usare la filters proprietà per aggiungere filtri aggiuntivi:

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

  • Sostituire i filtri salvati con un nuovo set. Il setFilters metodo consente di modificare dinamicamente i filtri di un report. Se si usa questo metodo durante l'incorporamento in fasi, è possibile eseguire l'override dei filtri applicati inizialmente dal report. Per altre informazioni sulla creazione di filtri e sull'uso del setFilters metodo, vedere Filtri del report di controllo.

Nei filtri dei dati di carico

È possibile controllare lo stato dei filtri dei dati applicati all'app a un report incorporato. Per impostazione predefinita, l'API usa i filtri dei dati salvati nel report. È tuttavia possibile usare la slicers proprietà per modificare lo stato dei filtri dei dati esistenti, come illustrato nel codice seguente:

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

Per altre informazioni sulla modifica dello stato di un filtro dei dati, vedere Controllare i filtri dei dati del report.

Nel segnalibro di caricamento

Usando la bookmark proprietà, è possibile applicare un segnalibro a un report incorporato. Per altre informazioni sull'uso dei segnalibri, vedere Segnalibri per acquisire la visualizzazione attualmente configurata delle pagine del report.

È possibile specificare il segnalibro da usare specificando il nome del segnalibro o lo stato. Se si specifica il nome del segnalibro, il report di Power BI deve contenere un segnalibro salvato con tale nome.

La proprietà è di tipo IApplyBookmarkRequest. Il bookmark codice seguente mostra la definizione di questo tipo:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Questo codice illustra come specificare un segnalibro in base al nome:

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

Questo codice illustra come specificare un segnalibro in base allo stato:

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

Temi e modalità a contrasto elevato

È possibile controllare il tema e il livello di contrasto usati dal contenuto incorporato. Per impostazione predefinita, qualsiasi contenuto incorporato viene visualizzato con il tema predefinito e senza contrasto. È possibile eseguire l'override di questo comportamento configurando un tema o un livello di contrasto specifico. Per altre informazioni sui temi, vedere Applicare temi del report.

Le modalità di contrasto disponibili sono elencate di seguito:

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

Usare il codice simile alle righe seguenti per configurare un tema specifico:

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

Il codice seguente illustra come eseguire l'override del livello di contrasto predefinito, None:

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

Nota

L'API non può applicare un tema e un livello di contrasto contemporaneamente. Se si configurano entrambe le proprietà, l'API usa il livello di contrasto specificato, ma ignora l'impostazione theme .

Livello di zoom

Per altre informazioni sulla modifica del livello di zoom del report, controllare il documento di accessibilità.

Aprire in modalità di modifica

Per impostazione predefinita, il report incorporato viene visualizzato in modalità visualizzazione. È tuttavia possibile eseguire l'override di questo comportamento per aprire il report in modalità di modifica. È anche possibile passare da una modalità all'altra.

Configurare la modalità di modifica

Per aprire un report incorporato in modalità di modifica, usare la viewMode proprietà insieme alla permissions proprietà .

È possibile assegnare la proprietà ai viewMode valori seguenti:

  • View - Apre il report in modalità visualizzazione.
  • Edit - Apre il report in modalità di modifica.

È possibile assegnare la permissions proprietà questi valori:

  • Read - Gli utenti possono visualizzare il report.
  • ReadWrite - Gli utenti possono visualizzare, modificare e salvare il report.
  • Copy - Gli utenti possono salvare una copia del report usando Salva con nome.
  • Create - Gli utenti possono creare un nuovo report.
  • All - Gli utenti possono creare, visualizzare, modificare, salvare e salvare una copia del report.

Quando si configura il contenuto per aprire in modalità di modifica, assegnare la proprietà un valore appropriato per la permissions modifica, come illustrato nel codice seguente:

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

Nota

Il permissions valore configurato funziona solo se il token di incorporamento acquisito ha privilegi sufficienti. Per altre informazioni sui token di incorporamento, vedere Creare il token di incorporamento.

Passare tra le modalità di modifica e visualizzazione

Oltre a specificare una modalità per l'avvio del contenuto incorporato, è anche possibile passare tra le modalità di modifica e visualizzazione in modo dinamico.

Se il contenuto è in modalità di modifica e si vuole passare alla modalità di visualizzazione, usare questo codice JavaScript:

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

...

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

Se il contenuto è in modalità di visualizzazione e si vuole passare alla modalità di modifica, usare questo codice JavaScript:

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

...

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

Considerazioni e limitazioni

Prendere in considerazione i punti seguenti quando si configura il contenuto incorporato:

  • La posizione di spostamento della pagina non può essere modificata quando la barra delle azioni è visibile. Altre informazioni sulla barra delle azioni.

  • Quando si usa la bars proprietà nella setting proprietà, come descritto in Barre, l'API si applica solo se il contenuto incorporato è in modalità di modifica. Se il contenuto è in modalità visualizzazione, l'API ignora l'impostazione bars .

  • Quando si usa la proprietà per visualizzare il viewMode contenuto in modalità di modifica, è necessario eseguire due passaggi aggiuntivi:

    • Configurare un livello di autorizzazione con la permissions proprietà . Tale livello di autorizzazione deve concedere all'utente l'accesso appropriato per modificare il contenuto. Ad esempio, se si assegna un permissions valore dell'utente Read, non sarà in grado di modificare il contenuto.
    • Assicurarsi che il token di incorporamento generato disponga di privilegi che supportano la modifica. Ad esempio, se si acquisisce un token con un accessLevel valore dell'API view, non sarà possibile visualizzare il contenuto in modalità di modifica.

  • La proprietà riquadro sostituisce le proprietà seguenti settings :

    • filterPaneEnabled
    • navContentPaneEnabled

    Se si usa la proprietà per configurare la panes visibilità del filtro o della pagina, non usare la filterPaneEnabled proprietà o navContentPaneEnabled nell'app.

  • L'API non può applicare un tema e un livello di contrasto al contenuto incorporato contemporaneamente. Se si configurano entrambe le opzioni usando le theme proprietà e contrastMode , l'API usa il contrastMode valore con il contenuto incorporato. Tuttavia, l'API ignora l'impostazione theme .

  • Se si vuole applicare un segnalibro a un report incorporato, è possibile usare la bookmark proprietà . Se si specifica un nome di segnalibro con tale proprietà, l'API può usare solo il segnalibro se esiste con tale nome. Analogamente, se si usa la pageName proprietà per specificare una pagina di apertura, l'API può visualizzare tale pagina solo se esiste con il nome specificato. Prima di configurare un nome, prendere in considerazione l'uso di un metodo di accesso, ad esempio il metodo GetPages report, per verificare se esiste un componente con tale nome.

Passaggi successivi