Pré-visualizar ficheiros na sua aplicação

Aplica-se a: Programador

Adicione a UX de pré-visualização de ficheiros para que os utilizadores possam inspecionar os conteúdos do SharePoint Embedded sem transferir ficheiros ou abrir uma experiência de edição completa do Office.

Conclua Abrir ficheiros do Office a partir da sua aplicação quando precisar de editar o Office. Utilize este artigo para pré-visualizações leves.

Compreender o fluxo de pré-visualização

O fluxo de pré-visualização tem dois passos:

  1. Chame o ponto final de pré-visualização do DriveItem do Microsoft Graph.
  2. Utilize o URL devolvido numa iframe ou nova página do browser.

O ponto final 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} é o ID de contentor que começa com b!.
  • {itemId} é o ID do DriveItem.

Para obter a referência de API canónica, veja Pré-visualizar um DriveItem.

Conhecer tipos de ficheiro suportados

O Microsoft 365 suporta pré-visualizações para muitos tipos de ficheiros, incluindo formatos de documento, imagem, vídeo e PDF comuns.

Os exemplos incluem:

  • Ficheiros PDF.
  • FICHEIRO JPG e outros ficheiros de imagem.
  • MP4 e outros ficheiros de multimédia suportados.
  • Ficheiros do Office suportados por experiências de pré-visualização do Microsoft 365.

Para obter a lista atual, consulte Tipos de ficheiro suportados para pré-visualizar ficheiros no OneDrive, SharePoint e Teams.

Observação

O suporte de tipo de ficheiro pode variar consoante a capacidade do serviço, a política de inquilino e a experiência do cliente. Processe sempre as falhas de pré-visualização corretamente.

Visualização nativa de PDF

A experiência de visualização de PDF nativa do SharePoint Embedded suporta a pesquisa no ficheiro, a visualização de comentários e notas autocolantes incorporadas no ficheiro e a impressão (adicionada em março de 2026). Estas capacidades estão disponíveis através do driveItem: API de pré-visualização nos pontos finais beta e v1.0 do Microsoft Graph.

Melhorar o pré-visualizador de PDF com parâmetros de consulta

Melhore o pré-visualizador de PDF do SharePoint Embedded ao acrescentar 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.

Transmita parâmetros como uma cadeia de consulta codificada embed em JSON. Pode incluir um ou mais parâmetros no mesmo objeto.

<webUrl>?&embed={"<param1>":<value>,"<param2>":<value>}
Parâmetro Effect
mpp Ativa o ícone de impressão e a impressão Ctrl+P. Por exemplo, <webUrl>?&embed={"mpp":true}.
mpsn Mostra conteúdos de notas autocolantes quando o PDF contém notas autocolantes. Por exemplo, <webUrl>?&embed={"mpsn":true}.

Pré-requisitos

Antes de criar pré-visualizações, certifique-se de que:

  • O ficheiro é armazenado num contentor do SharePoint Embedded.
  • A sua aplicação conhece o ID do contentor e o ID do DriveItem.
  • A sua aplicação pode adquirir um token do Microsoft Graph.
  • O autor da chamada tem permissão para ler o ficheiro.
  • O tipo de ficheiro é suportado para pré-visualização.
  • A IU pode alojar um iframe ou abrir uma nova página.

Chame o ponto final de pré-visualização a partir da camada de serviço.

Utilize este padrão de SDK C#:

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

A resposta inclui informações de URL de pré-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"
}

Utilize getUrl quando disponível.

Cuidado

getUrl atualmente contém um token encriptado que só pode ser utilizado com a sua aplicação. Este comportamento pode mudar.

Remover a faixa de pré-visualização

Adicione nb=true ao URL obtido para remover a faixa na parte superior.

Exemplo:

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

Utilize esta opção apenas quando se adequa à sua experiência de utilizador e aos requisitos de conformidade.

Incorporar a pré-visualização num iframe

Crie uma página de aplicação que aloje o URL de pré-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, forneça também:

  • Um título de iframe descritivo.

  • Dimensionamento reativo.

  • A carregar estados.

  • Estados de erro.

  • Uma transferência de contingência ou uma ação de abertura.

Carregar pré-visualizações dinamicamente

Não chame o Microsoft Graph diretamente a partir de um script do browser se isso criar problemas de CORS ou expor tokens.

Utilize um ponto final do lado do servidor que:

  1. Autentica o utilizador.
  2. Valida o acesso ao ficheiro pedido.
  3. Adquire um token do Graph.
  4. Chama o ponto final de pré-visualização do DriveItem.
  5. Devolve o URL de pré-visualização ao cliente.

Utilize este padrão do lado do servidor:

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

Em seguida, o cliente pode pedir o URL e definir a origem 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";
}

UX de pré-visualização de design

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

  • Mostrar o nome do ficheiro.
  • Mostrar um indicador de carregamento.
  • Reserve espaço suficiente para o iframe.
  • Forneça uma ação aberta no Office para ficheiros do Office.
  • Indique uma ação de transferência quando a pré-visualização não estiver disponível.
  • Preservar a acessibilidade do teclado.
  • Evite intercetar o foco dentro da moldura de pré-visualização.
  • Explicar erros no idioma amigável do utilizador.

Processar erros de pré-visualização

Falha Processamento
Tipo de ficheiro não suportado Em alternativa, mostre uma ação de transferência ou abertura.
Permissão em falta Peça ao utilizador para pedir acesso ou iniciar sessão novamente.
URL Expirado Peça um NOVO URL de pré-visualização.
Erro CORS Mova a chamada do Graph para o ponto final do lado do servidor.
Arquivo excluído Atualize a lista de ficheiros e remova as seleções obsoletas.
Erro de serviço Repita uma vez e, em seguida, mostre uma contingência estável.

Importante

Não coloque os URLs de pré-visualização em cache como identificadores duráveis. Armazene o ID do contentor e o ID do DriveItem e, em seguida, crie um NOVO URL de pré-visualização quando necessário.

Pedidos de pré-visualização seguros

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

O seu serviço deve:

  1. Valide o contexto de utilizador ou serviço com sessão iniciada.
  2. Confirme se o autor da chamada consegue ler o conteúdo do contentor.
  3. Confirme que o item pedido pertence ao contentor esperado.
  4. Evite expor tokens do Graph ao browser.
  5. Evite registar URLs de pré-visualização que incluam tokens confidenciais.
  6. Expirar sessões de pré-visualização do lado da aplicação quando o utilizador terminar sessão.

Validar a experiência de pré-visualização

Teste com vários tipos de ficheiro e utilizadores:

  1. Carregue um ficheiro PDF.
  2. Carregar um ficheiro de imagem.
  3. Carregue um ficheiro do Office.
  4. Crie um URL de pré-visualização para cada ficheiro.
  5. Componcione cada pré-visualização num iframe.
  6. Testar um utilizador com acesso de leitura.
  7. Testar um utilizador sem acesso.
  8. Elimine um ficheiro e confirme se o erro foi processado.
  9. Atualize um URL de pré-visualização expirado.
  10. Confirme se a ação de contingência funciona.

Ligar à tarefa de compilação seguinte

Depois de a pré-visualização estar a funcionar, adicione experiências de deteção para que os utilizadores possam encontrar conteúdos em contentores e ficheiros.

Continue para Procurar contentores e ficheiros.

Próximas etapas

  • Last updated on