Visualizar arquivos no seu aplicativo

Aplica-se a: Desenvolvedor

Adicione experiências de visualização de arquivo para que os usuários possam inspecionar o conteúdo inserido do SharePoint sem baixar arquivos ou abrir uma experiência completa de edição do Office.

Conclua os arquivos do Office do seu aplicativo quando precisar de edição do Office. Use este artigo para versões prévias leves.

Entender o fluxo de visualização

O fluxo de visualização tem duas etapas:

Chame o ponto de extremidade de visualização DriveItem do Microsoft Graph.
Use a URL retornada em um iframe ou em uma nova página do navegador.

O ponto de extremidade do Graph é:

POST https://graph.microsoft.com/{version}/drives/{driveId}/items/{itemId}/preview

Onde:

{version} é a versão do Microsoft Graph, como v1.0.
{driveId} é a ID do contêiner que começa com b!.
{itemId} é a ID do DriveItem.

Para obter a referência da API canônica, consulte Visualizar um DriveItem.

Conheça os tipos de arquivo com suporte

O Microsoft 365 oferece suporte a visualizações para muitos tipos de arquivo, incluindo formatos comuns de documento, imagem, vídeo e PDF.

Os exemplos incluem:

arquivos PDF.
JPG e outros arquivos de imagem.
MP4 e outros arquivos de mídia suportados.
Arquivos do Office compatíveis com experiências de visualização do Microsoft 365.

Para obter a lista atual, consulte Tipos de arquivo com suporte para visualização de arquivos no OneDrive, SharePoint e Teams.

Observação

O suporte ao tipo de arquivo pode variar de acordo com a funcionalidade do serviço, a política do locatário e a experiência do cliente. Sempre lide com falhas de visualização normalmente.

Visualização em PDF nativo

A experiência de exibição de PDF nativo inserido do SharePoint dá suporte à pesquisa no arquivo, à exibição de comentários e notas autoadesivas inseridas no arquivo e à impressão (adicionada em março de 2026). Esses recursos estão disponíveis por meio da driveItem: API de visualizaçãonos pontos de extremidade beta e v1.0 do Microsoft Graph.

Aprimore o visualizador de PDF com parâmetros de consulta

Aprimore o pré-visualizador de PDF incorporado do SharePoint acrescentando parâmetros de consulta à propriedade do webUrl driveItem. Para obter webUrl, chame a API GET driveItem, por exemplo GET /drives/{drive-id}/items/{item-id}?$select=webUrl.

Passe parâmetros como uma cadeia de caracteres de consulta codificada embed em JSON. Você pode incluir um ou mais parâmetros no mesmo objeto.

<webUrl>?&embed={"<param1>":<value>,"<param2>":<value>}

Parâmetro	Effect
`mpp`	Habilita o ícone de impressão e a impressão Ctrl+P. Por exemplo, `<webUrl>?&embed={"mpp":true}`.
`mpsn`	Mostra o conteúdo da nota autoadesiva quando o PDF contém notas autoadesivas. Por exemplo, `<webUrl>?&embed={"mpsn":true}`.

Pré-requisitos

Antes de criar visualizações, verifique se:

O arquivo é armazenado em um contêiner do SharePoint Embedded.
Seu aplicativo conhece a ID do contêiner e a ID do DriveItem.
Seu aplicativo pode adquirir um token do Microsoft Graph.
O chamador tem permissão para ler o arquivo.
O tipo de arquivo é compatível com visualização.
Sua interface do usuário pode hospedar um iframe ou abrir uma nova página.

Criar um link de visualização

Chame o ponto de extremidade de visualização da camada de serviço.

Use este padrão do SDK do C#:

ItemPreviewInfo preview = await graphServiceClient.Drives[driveId].Items[itemId]
    .Preview
    .PostAsync(null);

A resposta inclui informações de URL de visualização:

{
  "getUrl": "https://www.onedrive.com/embed?foo=bar&bar=baz",
  "postParameters": "param1=value&param2=another%20value",
  "postUrl": "https://www.onedrive.com/embed_by_post"
}

Use getUrl quando disponível.

Cuidado

getUrl contém um token criptografado que só pode ser usado com seu aplicativo. Este comportamento pode mudar.

Adicione nb=true à URL obtida para remover a faixa na parte superior.

Exemplo:

https://contoso.sharepoint.com/restOfUrl/embed.aspx?param1=value&nb=true

Use esta opção somente quando ela atender aos requisitos de conformidade e experiência do usuário.

Inserir a visualização em um iframe

Crie uma página de aplicativo que hospede a URL de visualização.

Forma de exemplo:

<!DOCTYPE html>
<html>
  <body>
    <h2>Preview</h2>
    <p>Preview of {file name}:</p>
    <iframe src="{preview URL}" height="200" width="300" id="preview" title="File preview"></iframe>
  </body>
</html>

Em produção, também fornece:

Um título de iframe descritivo.
Dimensionamento responsivo.
Carregando estados.
Estados de erro.
Um download de fallback ou uma ação aberta.

Carregar visualizações dinamicamente

Não chame o Microsoft Graph diretamente de um script de navegador se isso criar problemas de compartilhamento de CORS (recursos de origem cruzada) ou expor tokens.

Use um ponto de extremidade do lado do servidor que:

Autentica o usuário.
Valida o acesso ao arquivo solicitado.
Adquire um token do Graph.
Chama o ponto de extremidade de visualização DriveItem.
Retorna a URL de visualização para o cliente.

Use este padrão do lado do servidor:

[HttpGet]
[AuthorizeForScopes(Scopes = new string[] { "FileStorageContainer.Selected" })]
public async Task<ActionResult<string>> GetPreviewUrl(string driveId, string itemId)
{
  return url + "&nb=true";
}

Em seguida, o cliente pode solicitar a URL e definir a fonte do iframe.

async function preview(driveId, itemId) {
  const url = `/GetPreviewUrl?driveId=${driveId}&itemId=${itemId}`;
  const response = await fetch(url, {
      credentials: 'include',
  }).then(response => response.text());
  document.getElementById('preview').src = response + "&nb=true";
}

Projetar a experiência de visualização

Uma boa experiência de visualização deve:

Mostrar o nome do arquivo.
Mostrar um indicador de carregamento.
Reserve espaço suficiente para o iframe.
Fornece uma ação de abertura no Office para arquivos do Office.
Forneça uma ação de download quando a visualização não estiver disponível.
Preserve a acessibilidade do teclado.
Evite capturar o foco dentro do quadro de visualização.
Explique os erros em uma linguagem amigável.

Lidar com erros de visualização

Falha	Manuseio
Tipo de arquivo incompatível	Em vez disso, mostra uma ação de download ou abertura.
Permissão ausente	Peça ao usuário para solicitar acesso ou entrar novamente.
URL expirada	Solicite uma nova URL de visualização.
Erro de CORS	Mova a chamada do Graph para o ponto de extremidade do lado do servidor.
Arquivo excluído	Atualize a lista de arquivos e remova seleções obsoletas.
Erro de serviço	Tente novamente uma vez e, em seguida, mostre um fallback estável.

Importante

Não armazene em cache URLs de visualização como identificadores duráveis. Armazene a ID do contêiner e a ID do DriveItem e, em seguida, crie uma nova URL de visualização quando necessário.

Solicitações de visualização seguras

Tratar a visualização como uma operação de leitura em conteúdo protegido.

Seu serviço deve:

Valide o usuário ou o contexto do serviço conectado.
Confirme se o chamador pode ler o conteúdo do contêiner.
Confirme se o item solicitado pertence ao contêiner esperado.
Evite expor tokens do Graph ao navegador.
Evite registrar em log URLs de visualização que incluem tokens confidenciais.
Expire as sessões de visualização do lado do aplicativo quando o usuário sair.

Validar a experiência de visualização

Teste com vários tipos de arquivo e usuários:

Carregue um arquivo PDF.
Carregue um arquivo de imagem.
Carregar um arquivo do Office.
Crie uma URL de visualização para cada arquivo.
Renderize cada visualização em um iframe.
Teste um usuário com acesso de leitura.
Teste um usuário sem acesso.
Exclua um arquivo e confirme se o erro foi tratado.
Atualizar uma URL de visualização expirada.
Confirme se a ação de fallback funciona.

Conectar-se à próxima tarefa de compilação

Depois que a visualização estiver funcionando, adicione experiências de descoberta para que os usuários possam encontrar conteúdo em contêineres e arquivos.

Continuar para Pesquisar contêineres e arquivos.

Próximas etapas

Pesquisar contêineres e arquivos

Last updated on 2026-08-24