Referencia de API de <oim-player>

La interfaz del elemento personalizado (custom element) para renderizar imágenes de Object Interactive Media (OIM) y gestionar las superposiciones de capas dinámicas.

Registro del Elemento

El reproductor se registra bajo la etiqueta personalizada <oim-player>. Asegúrese de cargar el script del componente para registrarlo en el documento:

<script src="https://cdn.oim.media/oim-player.js"></script>

Atributos HTML

Atributo	Tipo	Predeterminado	Descripción
src	string	""	URL de origen del recurso .oim a renderizar.
lang	string	"es"	Código de idioma activo para resolver el contenido localizado de los slots.
fit	"contain" | "cover"	"contain"	Comportamiento de ajuste y escala del viewport en su contenedor.
align	"center" | "top" | "bottom"	"center"	Alineación vertical del lienzo de medios interactivos.
allow-lottie	boolean	true	Habilita o deshabilita la ejecución de animaciones vectoriales Lottie en los slots.
disable-animations	boolean	según mode	Pausa efectos hover, loops visuales y detiene animaciones Lottie en el fotograma 0.
mode	"image" | "full"	"image"	Preajuste de las dos banderas de capacidad. image es una imagen quieta con su idioma; full se mueve y responde. Un atributo explicito manda sobre el preajuste.
disable-actions	boolean	según mode	Suspende las acciones de clic y hover declaradas en el archivo. prefers-reduced-motion NO lo activa: es una preferencia vestibular sobre el movimiento, no una renuncia a poder interactuar.
auto-rotate-lang	number | "false"	"false"	Intervalo de rotación cíclica de idiomas en milisegundos.
placeholder	string	ninguno	Miniatura que se muestra hasta que el player pinta. Solo se usan URL http:, https:, blob: y data:image/.
activate-on	"visible" | "hover" | "manual"	"visible"	hover mueve el archivo solo bajo el puntero (en táctil se comporta como visible); manual lo deja a play() y pause().
palette	string	la del archivo	Nombre de una de las paletas del archivo. Los nombres desconocidos se ignoran.
show-slots	boolean	true	false dibuja solo la imagen base.

Propiedades y Métodos de JavaScript

Además de los atributos estándar de HTML, la siguiente interfaz de JS está disponible en el nodo del elemento:

Propiedades

• player.src: String (obtiene o establece la URL del recurso activo).
• player.lang: String (obtiene o establece el idioma activo).
• player.fit: String (obtiene o establece el modo de ajuste del viewport).

Métodos

• player.setLang(langTag: string): void - Actualiza el idioma en tiempo real.
• player.setZoom(scale: number): void - Configura el factor de escala del zoom (rango de 1.0 a 4.0).
• player.play(): void - Inicia el ciclo de rotación de idioma.
• player.pause(): void - Pausa el ciclo de rotación de idioma.

Eventos Personalizados

El componente emite eventos estándar ante cambios de estado clave:

oim:loaded

Se despacha cuando los metadatos se han extraído, validado e inyectado correctamente en el DOM del reproductor.

• Estructura del Payload (event.detail):

  {
    type: "image",
    metadata: OimMetadata
  }

• Ejemplo de Uso:

  player.addEventListener('oim:loaded', (e) => {
    console.log('OIM Cargado:', e.detail.metadata);
  });

oim:action

Se emite cuando se ejecuta una accion declarada en un slot. El archivo no puede provocar nada por su cuenta: no declara handler, ni URL, ni destino fuera de si mismo — solo se anuncia, y solo sirve si la pagina escucha.

• Carga (event.detail):

  {
    slot: string,      // id del slot — estable, es lo que usan los `targets`
    name?: string,     // el nombre de capa que puso el autor — el legible
    trigger: "click" | "hover",
    targets: string[], // ids de las capas afectadas
    types: string[]    // "show" | "hide" | "toggle" | "setText"
  }

• Cancelable: preventDefault() suprime el efecto local, asi que una pagina puede decidir clic a clic.

• Se emite en cualquier capa interactiva, aunque no declare acciones — una capa que el autor marco interactiva anuncia su clic con targets vacio. Los ids se generan, asi que escucha por name; los nombres no son unicos.

• Uso:

  player.addEventListener('oim:action', (e) => {
    // Si quieres que un clic navegue, decide la PAGINA — con su propia URL.
    if (e.detail.name === 'Comprar') window.location.href = '/producto/42';
  });