Vista previa de archivos en la aplicación

Se aplica a: Desarrollador

Agregue la experiencia de usuario de vista previa de archivos para que los usuarios puedan inspeccionar el contenido de SharePoint Embedded sin descargar archivos ni abrir una experiencia de edición completa de Office.

Complete Abrir archivos de Office desde la aplicación cuando necesite la edición de Office. Use este artículo para versiones preliminares ligeras.

Descripción del flujo de vista previa

El flujo de vista previa tiene dos pasos:

  1. Llame al punto de conexión de la versión preliminar de DriveItem de Microsoft Graph.
  2. Use la dirección URL devuelta en un iframe o en una nueva página del explorador.

El punto de conexión de Graph es:

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

Donde:

  • {version} es la versión de Microsoft Graph, como v1.0.
  • {driveId} es el identificador de contenedor que comienza por b!.
  • {itemId} es el id. de DriveItem.

Para obtener la referencia de API canónica, consulte Vista previa de un driveItem.

Conocer los tipos de archivo admitidos

Microsoft 365 admite vistas previas para muchos tipos de archivo, incluidos los formatos comunes de documento, imagen, vídeo y PDF.

Algunos ejemplos son:

  • Archivos PDF.
  • JPG y otros archivos de imagen.
  • MP4 y otros archivos multimedia compatibles.
  • Archivos de Office compatibles con las experiencias en versión preliminar de Microsoft 365.

Para obtener la lista actual, vea Tipos de archivo compatibles con la vista previa de archivos en OneDrive, SharePoint y Teams.

Nota:

La compatibilidad con tipos de archivo puede variar según la funcionalidad del servicio, la directiva de inquilino y la experiencia del cliente. Controle siempre correctamente los errores de vista previa.

Visualización de PDF nativo

La experiencia de visualización nativa de PDF de SharePoint Embedded admite la búsqueda en el archivo, la visualización de comentarios y notas pegajosas incrustadas en el archivo y la impresión (agregada en marzo de 2026). Estas funcionalidades están disponibles a través de la API driveItem: preview en los puntos de conexión de Microsoft Graph beta y v1.0 .

Mejora de la vista previa de PDF con parámetros de consulta

Mejore la vista previa de PDF de SharePoint Embedded anexando parámetros de consulta a la propiedad driveItem webUrl . Para obtener webUrl, llame a la API GET driveItem, por ejemplo GET /drives/{drive-id}/items/{item-id}?$select=webUrl.

Pase los parámetros como una cadena de consulta codificada en embed JSON. Puede incluir uno o varios parámetros en el mismo objeto.

<webUrl>?&embed={"<param1>":<value>,"<param2>":<value>}
Parámetro Efecto
mpp Habilita el icono de impresión y la impresión Ctrl+P. Por ejemplo, <webUrl>?&embed={"mpp":true}.
mpsn Muestra el contenido de las notas pegajosos cuando el PDF contiene notas pegajosos. Por ejemplo, <webUrl>?&embed={"mpsn":true}.

Requisitos previos

Antes de crear vistas previas, asegúrese de lo siguiente:

  • El archivo se almacena en un contenedor de SharePoint Embedded.
  • La aplicación conoce el identificador de contenedor y el identificador de DriveItem.
  • La aplicación puede adquirir un token de Microsoft Graph.
  • El autor de la llamada tiene permiso para leer el archivo.
  • El tipo de archivo es compatible con la versión preliminar.
  • La interfaz de usuario puede hospedar un iframe o abrir una página nueva.

Llame al punto de conexión de vista previa desde la capa de servicio.

Use este patrón del SDK de C#:

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

La respuesta incluye información de dirección URL de vista previa:

{
  "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 cuando esté disponible.

Precaución

getUrl actualmente contiene un token cifrado que solo se puede usar con la aplicación. Este comportamiento puede cambiar.

Quitar el banner de vista previa

Agregue nb=true a la dirección URL obtenida para quitar el banner en la parte superior.

Ejemplo:

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

Úselo solo cuando se ajuste a la experiencia del usuario y a los requisitos de cumplimiento.

Inserción de la vista previa en un iframe

Cree una página de aplicación que hospede la dirección URL de vista previa.

Forma de ejemplo:

<!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>

En producción, también proporcione lo siguiente:

  • Un título descriptivo de iframe.

  • Tamaño con capacidad de respuesta.

  • Estados de carga.

  • Estados de error.

  • Una acción de descarga o apertura de reserva.

Cargar vistas previas dinámicamente

No llame a Microsoft Graph directamente desde un script del explorador si crea problemas de CORS o expone tokens.

Use un punto de conexión del lado servidor que:

  1. Autentica al usuario.
  2. Valida el acceso al archivo solicitado.
  3. Adquiere un token de Graph.
  4. Llama al punto de conexión de vista previa de DriveItem.
  5. Devuelve la dirección URL de vista previa al cliente.

Use este patrón del lado servidor:

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

A continuación, el cliente puede solicitar la dirección URL y establecer el origen de 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";
}

Experiencia de usuario de la versión preliminar de diseño

Una buena experiencia de usuario en versión preliminar debería:

  • Mostrar el nombre de archivo.
  • Mostrar un indicador de carga.
  • Reserva suficiente espacio para el iframe.
  • Proporcione una acción de apertura en Office para archivos de Office.
  • Proporcione una acción de descarga cuando la versión preliminar no esté disponible.
  • Conservar la accesibilidad del teclado.
  • Evite interceptar el foco dentro del marco de vista previa.
  • Explicar errores en un lenguaje fácil de usar.

Control de errores de vista previa

Error Control
Tipo de archivo no admitido En su lugar, muestra una acción de descarga o apertura.
Falta el permiso Pida al usuario que solicite acceso o vuelva a iniciar sesión.
Dirección URL expirada Solicitar una dirección URL de vista previa nueva.
Error de CORS Mueva la llamada de Graph al punto de conexión del lado servidor.
Archivo eliminado Actualice la lista de archivos y quite las selecciones obsoletas.
Error del servicio Vuelva a intentarlo una vez y, a continuación, muestre una reserva estable.

Importante

No almacene en caché las direcciones URL de vista previa como identificadores duraderos. Almacene el identificador de contenedor y el identificador de DriveItem y, a continuación, cree una dirección URL de vista previa nueva cuando sea necesario.

Solicitudes de versión preliminar seguras

Trate la versión preliminar como una operación de lectura en contenido protegido.

El servicio debe:

  1. Valide el contexto de usuario o servicio que ha iniciado sesión.
  2. Confirme que el autor de la llamada puede leer el contenido del contenedor.
  3. Confirme que el elemento solicitado pertenece al contenedor esperado.
  4. Evite exponer tokens de Graph al explorador.
  5. Evite registrar direcciones URL de vista previa que incluyan tokens confidenciales.
  6. Expire las sesiones en versión preliminar del lado de la aplicación cuando el usuario cierre la sesión.

Validación de la experiencia de vista previa

Pruebe con varios tipos de archivo y usuarios:

  1. Cargue un archivo PDF.
  2. Cargue un archivo de imagen.
  3. Cargue un archivo de Office.
  4. Cree una dirección URL de vista previa para cada archivo.
  5. Representar cada vista previa en un iframe.
  6. Pruebe un usuario con acceso de lectura.
  7. Pruebe un usuario sin acceso.
  8. Elimine un archivo y confirme que se controla el error.
  9. Actualice una dirección URL de vista previa expirada.
  10. Confirme que la acción de reserva funciona.

Conexión a la siguiente tarea de compilación

Una vez que la versión preliminar funciona, agregue experiencias de detección para que los usuarios puedan encontrar contenido entre contenedores y archivos.

Continúe con la búsqueda de contenedores y archivos.

Pasos siguientes

  • Last updated on