HOWTO · JavaScript

Cómo usar la pantalla completa en JavaScript

Aprende a solicitar el modo de pantalla completa para un elemento con JavaScript, salir de él y responder a los cambios de estado de la pantalla completa.

En esta página

Usa la API de pantalla completa del navegador para solicitar el modo de pantalla completa para un elemento elegido, salir de él con document.exitFullscreen() y observar fullscreenchange para mantener sincronizada la interfaz. Invoca la solicitud a partir de una acción del usuario, como hacer clic en un botón, y gestiona su promesa, ya que el navegador puede rechazarla.

Comprender la API de pantalla completa

El modo de pantalla completa se aplica a un elemento, como un reproductor de vídeo, un juego, una presentación o un contenedor de página. El navegador expone el elemento activo mediante document.fullscreenElement; su valor es null cuando ningún elemento está en modo de pantalla completa. El navegador controla la API de pantalla completa, por lo que una solicitud puede no estar disponible o ser denegada según la acción del usuario, el contexto de navegación y el dispositivo.

Para consultar detalles sobre los métodos y eventos, visita la documentación de la API de pantalla completa de MDN.

Método 1: Usar requestFullscreen() para entrar en modo de pantalla completa

Selecciona el elemento que quieres ampliar e invoca requestFullscreen() como respuesta a un clic. La API de pantalla completa requiere un contexto seguro, normalmente HTTPS. Puede no estar disponible si la página no se sirve en un contexto seguro o si falta el método; también pueden denegar la solicitud si no se origina en una acción del usuario o si el contexto de navegación o el dispositivo no la permiten. El siguiente fragmento de página es un ejemplo estático para el navegador: el comportamiento de la API depende del navegador y no se presenta como una salida de ejecución.

<button id="enter-fullscreen">Enter full screen</button>
<button id="exit-fullscreen">Exit full screen</button>
<div id="player">Video or other content</div>
<p id="status" role="status"></p>
<script>
const enterButton = document.getElementById('enter-fullscreen');
const exitButton = document.getElementById('exit-fullscreen');
const player = document.getElementById('player');
const status = document.getElementById('status');

enterButton.addEventListener('click', async () => {
  if (typeof player.requestFullscreen !== 'function') {
    status.textContent = 'Full-screen mode is unavailable.';
    return;
  }

  try {
    await player.requestFullscreen();
  } catch (error) {
    status.textContent = 'The browser did not enter full-screen mode.';
  }
});

exitButton.addEventListener('click', async () => {
  if (!document.fullscreenElement) return;
  try {
    await document.exitFullscreen();
  } catch (error) {
    status.textContent = 'The browser did not exit full-screen mode.';
  }
});

document.addEventListener('fullscreenchange', () => {
  const active = document.fullscreenElement === player;
  status.textContent = active
    ? 'Player is full screen.'
    : document.fullscreenElement
      ? 'Another element is full screen.'
      : 'Full-screen mode has ended.';
  enterButton.disabled = active;
  exitButton.disabled = !document.fullscreenElement;
});
</script>

El ejemplo para el navegador anterior usa un elemento DOM real. Este otro ejemplo utiliza un sustituto para mostrar el flujo de la promesa y el mensaje que se devuelve cuando finaliza la solicitud. Ejecuta este ejemplo:

const element = {
  requestFullscreen: () => Promise.resolve()
};

async function enterFullscreen(target) {
  await target.requestFullscreen();
  return 'Full-screen request completed';
}

enterFullscreen(element).then(console.log);
Full-screen request completed

En tu página, mantén la solicitud dentro del controlador del clic para que se origine en una acción del usuario. No dependas de métodos con prefijos de proveedor como garantía de compatibilidad: comprueba que exista el método estándar y deja el resto de la interfaz utilizable si no está disponible o si se rechaza la promesa. Si la API parece no estar disponible, confirma también que la página se sirve en un contexto seguro, normalmente HTTPS.

Método 2: Salir del modo de pantalla completa con exitFullscreen()

Invoca document.exitFullscreen() para salir del modo de pantalla completa. Devuelve una promesa, así que gestiona su rechazo igual que al entrar. Los usuarios también pueden salir mediante los controles del navegador o del dispositivo; la interfaz debe reflejar ese cambio, sin dar por hecho que solo el botón de salida de la página puede terminar el modo.

Por ejemplo, en una página del navegador, añade un controlador de clic a un botón de salida e invoca document.exitFullscreen() cuando document.fullscreenElement tenga un valor. Si se rechaza la promesa, muestra un mensaje de estado útil. Esta descripción estática no ejecuta la interacción exacta con el navegador.

Método 3: Gestionar los eventos de cambio del modo de pantalla completa

Escucha fullscreenchange en document. El evento se dispara cuando cambia el estado de pantalla completa, incluso cuando el usuario sale mediante los controles del navegador. Consulta document.fullscreenElement cada vez: un valor distinto de null identifica el elemento que está actualmente en pantalla completa, mientras que null indica que el modo ha terminado. Usa ese estado para actualizar las etiquetas de los botones, el texto de estado u otros controles. La pseudoclase :fullscreen de CSS permite aplicar estilos a un elemento mientras el navegador lo muestra en modo de pantalla completa.

Conclusión

Invoca requestFullscreen() sobre el elemento elegido a partir de una acción del usuario y gestiona la promesa. Si ofreces un control para salir, usa document.exitFullscreen(). Observa fullscreenchange y consulta document.fullscreenElement para que la interfaz también responda a las salidas iniciadas fuera de la página. El comportamiento puede variar según el navegador y el dispositivo, así que ofrece una alternativa funcional fuera del modo de pantalla completa.

Preguntas frecuentes

  1. ¿Cómo puedo comprobar si un elemento está en modo de pantalla completa? Comprueba si document.fullscreenElement corresponde a ese elemento. Su valor es null cuando no hay ningún elemento activo.

  2. ¿Puede cualquier elemento entrar en modo de pantalla completa? La API acepta un elemento, pero las políticas del navegador y el contexto de navegación pueden afectar al éxito de la solicitud. Iníciala a partir de una acción del usuario y gestiona los errores.

  3. ¿Por qué podría fallar requestFullscreen()? El método puede no estar disponible, por ejemplo, si la página no se sirve en un contexto seguro, normalmente HTTPS. La solicitud también puede carecer de una acción del usuario o ser denegada por el contexto de navegación o el dispositivo. Comprueba que el método esté disponible y gestiona la promesa devuelta.

  4. ¿Cómo puedo aplicar estilos al contenido en pantalla completa? Usa la pseudoclase :fullscreen de CSS para aplicar estilos mientras un elemento está en modo de pantalla completa.