Configurare le impostazioni del report

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à del filtro, accesso alla navigazione e posizione 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 proprietà settings per regolare l'aspetto e il comportamento del report di Power BI incorporato. Per aggiornare le impostazioni del report quando il report è già caricato, utilizzare il metodo report.updateSettings. 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 proprietà panes, 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 proprietà panes:

Riquadro filtro

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

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

Riquadro di spostamento pagina

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

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

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

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

Bar

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

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 parametro URL actionBarEnabled:

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

Barra di stato

La barra di stato contiene il controller di zoom canvas, 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 proprietà localeSettings per specificare la lingua e la formattazione del report incorporato:

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

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

Vedere lingue supportate per un elenco delle lingue e delle aree disponibili.

Il codice seguente assegna valori specifici a questi localeSettings:

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

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 stile dell'elemento div diventa quindi visibile.

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

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

Comportamento clic collegamento ipertestuale

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

Le modalità di comportamento disponibili:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

• Navigate: l'URL viene caricato in un nuovo contesto di esplorazione.
• NavigateAndRaiseEvent: l'URL viene caricato in un nuovo contesto di esplorazione e genera un evento dataHyperlinkClicked.
• RaiseEvent: impedisce il comportamento predefinito del clic url e genera dataHyperlinkClicked evento.

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

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

Un evento dataHyperlinkClicked 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 visualizzati dall'oggetto visivo

È possibile restare in ascolto di un evento per ogni oggetto visivo sottoposto a rendering. Per impostazione predefinita, gli eventi visualizzati vengono disabilitati.

Usare questo codice per attivare gli eventi visualRendered:

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

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

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

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

Messaggi di errore

Se si desidera visualizzare messaggi di errore personalizzati nei report incorporati, usare la proprietà hideErrors per nascondere i messaggi di errore predefiniti incorporati di Power BI. Il codice può quindi gestire gli eventi di errore in modo da adattarsi alla progettazione dell'app. Per altre informazioni sull'override degli errori predefiniti, vedere override degli errori 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 altre proprietà 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 proprietà pageName e specificando il nome della pagina che si desidera 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 caricamento

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

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

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

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

In caso di caricamento dei filtri dei dati

È possibile controllare lo stato dei filtri dei dati applicati dall'app a un report incorporato. Per impostazione predefinita, l'API usa i filtri dei dati salvati nel report. Tuttavia, è possibile usare la proprietà slicers 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 dei report.

Al caricamento del segnalibro

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

È 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à bookmark è di tipo IApplyBookmarkRequest. Il 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, tutti i contenuti da incorporare vengono visualizzati con il tema predefinito e con un contrasto zero. È 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:

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

Per configurare un tema specifico, usare codice simile alle righe seguenti:

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

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

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

Livello di zoom

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

Apri in modalità di modifica

Per impostazione predefinita, il report incorporato viene visualizzato in modalità di 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, utilizzare la proprietà viewMode insieme alla proprietà permissions.

È possibile assegnare la proprietà viewMode i valori seguenti:

• View : apre il report in modalità di visualizzazione.
• Edit : apre il report in modalità di modifica.

È possibile assegnare la proprietà permissions 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 l'apertura in modalità di modifica, assegnare alla proprietà permissions un valore appropriato per la modifica, come illustrato nel codice seguente:

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

Passare da una modalità di modifica a quella di visualizzazione

Oltre a specificare una modalità per l'avvio del contenuto incorporato, è anche possibile passare da modalità di modifica a visualizzazione dinamica.

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

Quando si configura il contenuto incorporato, tenere presente quanto segue:

• Non è possibile modificare posizione della pagina quando la barra delle azioni è visibile. Altre informazioni sulla barra delle azioni .

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

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

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

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

  • filterPaneEnabled
  • navContentPaneEnabled

  Se usi la proprietà panes per configurare la visibilità del filtro o della pagina, non usa la proprietà filterPaneEnabled o navContentPaneEnabled nella tua 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 proprietà theme e contrastMode, l'API usa il valore contrastMode con il contenuto incorporato. Tuttavia, l'API ignora l'impostazione theme.

• Se si desidera applicare un segnalibro a un report incorporato, è possibile utilizzare la proprietà bookmark. Se si specifica un nome di segnalibro con tale proprietà, l'API può usare il segnalibro solo se ne esiste uno con tale nome. Analogamente, se si usa la proprietà pageName per specificare una pagina di apertura, l'API può visualizzare tale pagina solo se esistente con il nome specificato. Prima di configurare un nome, è consigliabile usare un metodo di accesso, ad esempio il metodo getPages del report , per verificare se un componente esiste con tale nome.

Contenuto correlato

• Migliorare l'esperienza degli utenti con i segnalibri
• Applicare temi del report in Power BI
• i filtri dei report di controllo
• Controllare i filtri dei dati dei report