Definir configurações de relatório

Usando as APIs de Cliente do Power BI, você pode inserir a análise do Power BI em seu aplicativo. Ao usar essa biblioteca do lado do cliente para inserir um relatório do Power BI, você fornece à API informações sobre esse relatório.

Você pode usar um objeto de configuração para armazenar informações sobre seu relatório do Power BI. Ao inserir o relatório, você passa esse objeto para a API.

Além de conceder à API acesso ao relatório, você também pode usar o objeto de configuração para personalizar a aparência e o comportamento do relatório. Por exemplo, você pode ajustar a visibilidade do filtro, o acesso de navegação e as configurações de local no objeto de configuração.

As seções a seguir explicam como inserir e configurar o conteúdo do Power BI.

Fornecer informações de configuração

A interface IReportLoadConfiguration exibe propriedades que um objeto de configuração pode fornecer às APIs do cliente do Power BI sobre um relatório:

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

Consulte Inserir um relatório para obter uma explicação dos parâmetros necessários dessa interface e para obter exemplos de código mostrando como inserir um relatório.

Personalizar configurações

As seções a seguir descrevem como você pode usar a propriedade settings para ajustar a aparência e o comportamento do relatório do Power BI inserido. Para atualizar as configurações de relatório quando o relatório já estiver carregado, use o método report.updateSettings. Para obter mais informações, consulte Atualizar configurações de relatório no runtime.

Painéis

Controle a aparência de todos os painéis em seu relatório do Power BI com uma única propriedade panes, conforme mostrado no código a seguir:

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

Na tabela a seguir, você pode ver quais valores cada propriedade panes dá suporte:

Propriedade	Visível	Expandido
bookmarks	✔	❌
fields	✔	✔
filters	✔	✔
pageNavigation	✔	❌
selection	✔	❌
syncSlicers	✔	❌
visualizations	✔	✔

Painel de filtro

Por padrão, o painel de filtro fica visível. Se você quiser ocultar esse painel, use a propriedade filterPaneEnabled, conforme mostrado no seguinte código:

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

Nota

A propriedade painéis substitui a propriedade filterPaneEnabled. Para manter a compatibilidade com versões anteriores, a propriedade filterPaneEnabled ainda existe. No entanto, você deve evitar usar essas duas propriedades juntas.

Painel de navegação de página

Por padrão, as setas de navegação da página ficam visíveis em relatórios inseridos. Para ocultar essas setas, use a propriedade navContentPaneEnabled, conforme mostrado no seguinte código:

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

Nota

A propriedade painéis substitui a propriedade navContentPaneEnabled. Para manter a compatibilidade com versões anteriores, a propriedade navContentPaneEnabled ainda existe. No entanto, você deve evitar usar essas duas propriedades juntas.

O painel de navegação da página aparece na parte inferior do relatório, para usar o novo painel de páginas verticais que você pode definir a propriedade position:

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

Nota

Não é possível alterar a posição do painel de navegação da página usando updateSettings.

Bares

Defina a visibilidade da barra de ações e da barra de status usando a propriedade bars.

Barra de ações

O código a seguir torna a barra de ações visível:

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

Como alternativa, no modo de exibição, também é possível usar o parâmetro de URL actionBarEnabled:

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

Nota

No modo de exibição, a barra de ações só tem suporte para o inserir para o cenário de da sua organização.

Para a barra de ações no modo de exibição, é recomendável habilitar UserState.ReadWrite.All permissão para seu aplicativo do Azure AD. Essa permissão é necessária para permitir que os usuários finais adicionem o relatório aos seus favoritos e para habilitar indicadores pessoais e filtros persistentes.

Barra de status

A barra de status contém o controlador de zoom de tela, que fornece a capacidade de ampliar a tela.

O código a seguir torna a barra de status visível:

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

Configurações de localidade

Use a propriedade localeSettings para especificar o idioma e a formatação do relatório inserido:

A propriedade language em localeSettings consiste em duas partes de duas letras cada, separadas por um hífen:

• idioma define o idioma que o Power BI usa para localização. Exemplos de idiomas incluem en (inglês), es (espanhol) e tr (turco).
• localidade define a formatação de texto que o Power BI usa para datas, moeda e outros conteúdos relacionados. Exemplos de localidades incluem dos EUA (inglês), ES (Espanha) e TR (Türkiye).

Consulte idiomas com suporte para obter uma lista de idiomas e regiões disponíveis.

O código a seguir atribui valores específicos a esses localeSettings:

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

Nota

As configurações de localidade não podem ser alteradas depois que o relatório é carregado. Para alterar as configurações de localidade do relatório, redefina o iframe chamando powerbi.reset(element)e insira o relatório novamente.

Plano de fundo transparente

Por padrão, a tela de fundo do conteúdo inserido é branca com margens cinzas. Se preferir, você pode dar ao conteúdo inserido uma tela de fundo transparente. Em seguida, você pode aplicar o estilo desejado ao elemento html div que contém o conteúdo inserido. O estilo do elemento div se torna visível.

Use este código para tornar a tela de fundo do conteúdo inserido transparente:

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

Comportamento de clique do hiperlink

Você pode controlar o comportamento de um hiperlink em uma tabela ou visuais prontos para uso de matriz. Por padrão, o hiperlink abre uma nova janela.

Os modos de comportamento disponíveis:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

• Navigate - A URL é carregada em um novo contexto de navegação.
• NavigateAndRaiseEvent - A URL é carregada em um novo contexto de navegação e gera um evento dataHyperlinkClicked.
• RaiseEvent – impede o comportamento padrão do clique de URL e gera dataHyperlinkClicked evento.

Use este código para alterar o comportamento dos links para gerar um evento:

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

Um evento dataHyperlinkClicked é acionado quando um hiperlink é clicado em uma tabela ou visuais de matriz prontos para uso e o comportamento é NavigateAndRaiseEvent ou RaiseEvent.

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

Para obter mais informações sobre como lidar com eventos, consulte Como lidar com eventos.

Eventos renderizados visualmente

Você pode ouvir um evento para cada visual renderizado. Por padrão, os eventos renderizados visuais são desabilitados.

Use este código para tornar os eventos de visualRendered disparados:

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

Um evento visualRendered é acionado quando um visual é renderizado e o visualRenderedEvents está habilitado nas configurações do relatório.

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

Para obter mais informações sobre como lidar com eventos, consulte Como lidar com eventos.

Nota

Como os visuais podem ser renderizados devido às interações do usuário, é recomendável ativar esse evento somente quando necessário.

Mensagens de erro

Se você quiser exibir mensagens de erro personalizadas em relatórios inseridos, use a propriedade hideErrors para ocultar as mensagens de erro inseridas padrão do Power BI. Em seguida, seu código pode lidar com eventos de erro de uma maneira que atenda ao design do aplicativo. Consulte Substituir mensagens de erro padrão para obter mais informações sobre como substituir erros padrão.

Use este código para ocultar mensagens de erro padrão:

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

Personalizar opções

As seções a seguir descrevem como você pode usar mais propriedades para personalizar ainda mais a aparência e o comportamento do relatório do Power BI inserido.

Página padrão

Você pode controlar qual página do relatório inserido aparece inicialmente. Por padrão, a página inicial é a página que você modificou mais recentemente, que foi a página ativa na última vez que você salvou o relatório. Você pode substituir esse comportamento usando a propriedade pageName e fornecendo-a com o nome da página que deseja exibir. No entanto, se nenhuma página com esse nome existir no Power BI, a solicitação para abri-la falhará.

O código a seguir mostra como configurar seu aplicativo para exibir uma página específica:

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

Em filtros de carga

Você pode controlar os filtros que seu aplicativo aplica a um relatório inserido. Por padrão, o relatório usa inicialmente os filtros que você salvou no relatório. No entanto, você terá duas opções se quiser ajustar os filtros:

• Configure mais filtros para usar junto com os filtros salvos. O código a seguir mostra como usar a propriedade filters para acrescentar mais filtros:

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

• Substitua os filtros salvos por um novo conjunto. O método setFilters fornece uma maneira de alterar dinamicamente os filtros de um relatório. Se você usar esse método durante a inserção em fases, poderá substituir os filtros que o relatório aplica inicialmente. Para obter mais informações sobre como construir filtros e usar o método setFilters, consulte Filtros de relatório de controle.

Em segmentações de carga

Você pode controlar o estado das segmentações de dados que seu aplicativo aplica a um relatório inserido. Por padrão, a API usa as segmentações que você salvou no relatório. No entanto, você pode usar a propriedade slicers para modificar o estado das segmentações existentes, como demonstra o código a seguir:

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

Consulte as segmentações de relatório Control para obter mais informações sobre como modificar o estado de uma segmentação de dados.

No indicador de carga

Usando a propriedade bookmark, você pode aplicar um indicador a um relatório inserido. Consulte Indicadores para obter mais informações sobre como usar indicadores para capturar a exibição atualmente configurada de páginas de relatório.

Você pode especificar o indicador a ser usado fornecendo o nome do indicador ou o estado. Se você fornecer o nome do indicador, o relatório do Power BI precisará conter um indicador salvo com esse nome.

A propriedade bookmark é do tipo IApplyBookmarkRequest. O código a seguir mostra a definição desse tipo:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Este código mostra como especificar um indicador por nome:

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

Este código mostra como especificar um indicador por estado:

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

Temas e modo de alto contraste

Você pode controlar o tema e o nível de contraste que o conteúdo inserido usa. Por padrão, qualquer conteúdo que você insira aparece com o tema padrão e com contraste zero. Você pode substituir esse comportamento configurando um tema específico ou um nível de contraste. Para obter mais informações sobre temas, consulte Aplicar temas de relatório.

Os modos de contraste disponíveis:

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

Para configurar um tema específico, use um código semelhante às seguintes linhas:

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

O código a seguir mostra como substituir o nível de contraste padrão, None:

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

Nota

A API não pode aplicar um tema e um nível de contraste ao mesmo tempo. Se você configurar ambas as propriedades, a API usará o nível de contraste especificado, mas ignorará a configuração de theme.

Nível de zoom

Para saber mais sobre como ajustar o nível de zoom do relatório, verifique o documento de acessibilidade .

Abrir no modo de edição

Por padrão, o relatório que você inseri aparece no modo de exibição. No entanto, você pode substituir esse comportamento para abrir o relatório no modo de edição. Você também pode alternar entre os modos.

Configurar o modo de edição

Para abrir um relatório inserido no modo de edição, use a propriedade viewMode junto com a propriedade permissions.

Você pode atribuir à propriedade viewMode os seguintes valores:

• View - Abre o relatório no modo de exibição.
• Edit - Abre o relatório no modo de edição.

Você pode atribuir a propriedade permissions estes valores:

• Read – os usuários podem exibir o relatório.
• ReadWrite - Os usuários podem exibir, editar e salvar o relatório.
• Copy – os usuários podem salvar uma cópia do relatório usando Salvar como.
• Create – os usuários podem criar um novo relatório.
• All - Os usuários podem criar, exibir, editar, salvar e salvar uma cópia do relatório.

Ao configurar o conteúdo para abrir no modo de edição, atribua à propriedade permissions um valor apropriado para edição, como demonstra o código a seguir:

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

Nota

O valor permissions configurado só funcionará se o token de inserção que você adquiriu tiver privilégios suficientes. Para obter mais informações sobre tokens de inserção, consulte Criar o token de inserção.

Alternar entre os modos de edição e exibição

Além de especificar um modo para o conteúdo inserido iniciar, você também pode alternar entre os modos de edição e exibição dinamicamente.

Se o conteúdo estiver no modo de edição e você quiser alternar para o modo de exibição, use este código JavaScript:

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

...

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

Se o conteúdo estiver no modo de exibição e você quiser alternar para o modo de edição, use este código JavaScript:

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

...

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

Considerações e limitações

Considere os seguintes pontos ao configurar o conteúdo inserido:

• A posição de navegação da página não pode ser alterada quando a barra de ações está visível. Saiba mais sobre a barra de ações .

• Quando você usa a propriedade bars na propriedade setting, conforme descrito em Barras, a API só aplica sua configuração se o conteúdo inserido estiver no modo de edição. Se o conteúdo estiver no modo de exibição, a API ignorará a configuração de bars.

• Ao usar a propriedade viewMode para exibir o conteúdo no modo de edição, você precisará executar duas etapas adicionais:

  • Configure um nível de permissão com a propriedade permissions. Esse nível de permissão precisa dar ao usuário acesso apropriado para modificar o conteúdo. Por exemplo, se você atribuir um valor permissions de Read, o usuário não poderá editar o conteúdo.
  • Verifique se o token de inserção gerado tem privilégios que dão suporte à edição. Por exemplo, se você adquirir um token com um valor accessLevel de view, a API não exibirá o conteúdo no modo de edição.

• A propriedade de painéis substitui as seguintes propriedades de settings:

  • filterPaneEnabled
  • navContentPaneEnabled

  Se você usar a propriedade panes para configurar a visibilidade de navegação de página ou filtro, não use a propriedade filterPaneEnabled ou navContentPaneEnabled em seu aplicativo.

• A API não pode aplicar um tema e um nível de contraste ao conteúdo inserido ao mesmo tempo. Se você configurar ambas as opções usando as propriedades theme e contrastMode, a API usará seu valor contrastMode com o conteúdo inserido. No entanto, a API ignora a configuração de theme.

• Se você quiser aplicar um indicador a um relatório inserido, poderá usar a propriedade bookmark. Se você fornecer um nome de indicador com essa propriedade, a API só poderá usar o indicador se existir um com esse nome. Da mesma forma, se você usar a propriedade pageName para especificar uma página de abertura, a API só poderá exibir essa página se existir um com o nome fornecido. Antes de configurar um nome, considere usar um método acessador, como o método Report getPages, para verificar se existe um componente com esse nome.

Conteúdo relacionado

• aprimorar a experiência dos usuários com indicadores
• Aplicar temas de relatório no Power BI
• filtros de relatório de controle de
• segmentações de relatório de controle de