Reproductores Multimedia

Xingluo integra APlayer (audio) y DPlayer (video), admitiendo dos formas de crear reproductores en Markdown y MDX, todos con carga diferida.

Habilitación

Active cada reproductor según sea necesario en features.players en xingluo.config.ts:

ts
features: {
  players: {
    aplayer: true,  // Activar reproductor de audio APlayer
    dplayer: true,  // Activar reproductor de video DPlayer
  },
}

Los dos son independientes. Cuando están desactivados:

• El plugin remarkPlayers no se inyecta (las cercas MD no se analizan)
• El script del cliente del reproductor no se carga
• La salida de compilación no tiene chunks de aplayer / dplayer

Dos modos de uso

Ambos modos producen la misma estructura de div placeholder (<div class="xng-aplayer|xng-dplayer" data-config>), cargada de forma diferida e instanciada por src/scripts/players.ts.

Reproductor de audio APlayer

Cerca MD

markdown
```aplayer
{
  "audio": [
    {
      "name": "Canción",
      "artist": "Artista",
      "url": "/audio/song.mp3",
      "cover": "/images/cover.jpg",
      "lrc": "[00:00.00] Primera línea de letra"
    }
  ],
  "theme": "#b7daff",
  "loop": "all",
  "autoplay": false
}
```

Componente MDX

mdx
import { APlayer } from "@/components/mdx";

<APlayer
  audio={[
    {
      name: "Canción",
      artist: "Artista",
      url: "/audio/song.mp3",
      cover: "/images/cover.jpg",
    },
  ]}
  theme="#b7daff"
  loop="all"
/>

Opciones

Objeto audio

Reproductor de video DPlayer

Cerca MD

markdown
```dplayer
{
  "video": {
    "url": "/videos/demo.mp4",
    "pic": "/images/video-cover.jpg",
    "type": "auto"
  },
  "theme": "#b7daff",
  "autoplay": false,
  "loop": false
}
```

Componente MDX

mdx
import { DPlayer } from "@/components/mdx";

<DPlayer
  video={{ url: "/videos/demo.mp4", pic: "/images/video-cover.jpg" }}
  theme="#b7daff"
  subtitle={{ url: "/subtitles.vtt", type: "webvtt" }}
/>

Opciones

Objeto video

Objeto subtitle

Objeto danmaku

Mecanismo de carga diferida

Los reproductores se cargan de forma diferida mediante IntersectionObserver: el div placeholder importa dinámicamente el módulo del reproductor y los estilos, y solo se instancia cuando está dentro de 200px del viewport.

• APlayer: import("aplayer") dinámico + import("aplayer/dist/APlayer.min.css")
• DPlayer: import("dplayer") dinámico (los estilos están incrustados en JS; no se necesita CSS separado)

La carga de módulos utiliza un caché Promise compartido para evitar importaciones dinámicas repetidas. La reinstanciación se previene mediante marcadores dataset (xng-init, xng-observed).

Adaptación de View Transitions

El script del reproductor escucha astro:page-load y reescanea los divs placeholder después de cada carga de página. Después de un cambio de página con View Transitions, los placeholders del reproductor de la nueva página se vuelven a observar y se cargan de forma diferida.

Rendimiento

• Paquete cero cuando los reproductores están desactivados (plugin remark no inyectado, script de cliente no cargado)
• Ejecución cero cuando están activados pero no hay reproductores en una página (el script se carga pero no se instancia)
• Los módulos de reproductor son chunks independientes, cargados bajo demanda solo en las páginas que los usan
• CSS y JS se importan por separado para garantizar que los estilos estén listos antes de la instanciación

Declaraciones de tipos

APlayer y DPlayer no tienen tipos TypeScript oficiales; Xingluo proporciona declaraciones de módulo flexibles en src/types/aplayer.d.ts y src/types/dplayer.d.ts, con campos de opciones opcionales para compatibilidad con spread. Los Props de componentes MDX tienen restricciones de tipo completas.