Reprodutores de Mídia

Xingluo integra APlayer (áudio) e DPlayer (vídeo), suportando duas maneiras de criar players em Markdown e MDX, todos com carregamento tardio.

Ativação

Alterne cada player conforme necessário em features.players no xingluo.config.ts:

ts
features: {
  players: {
    aplayer: true,  // Ativar player de áudio APlayer
    dplayer: true,  // Ativar player de vídeo DPlayer
  },
}

Os dois são independentes. Quando desativados:

• O plugin remarkPlayers não é injetado (cercas MD não são analisadas)
• O script do player cliente não é carregado
• A saída da build não tem chunks aplayer / dplayer

Dois Modos de Uso

Ambos os modos produzem a mesma estrutura de div placeholder (<div class="xng-aplayer|xng-dplayer" data-config>), carregada tardiamente e instanciada por src/scripts/players.ts.

Player de Áudio APlayer

MD Fence

markdown
```aplayer
{
  "audio": [
    {
      "name": "Song",
      "artist": "Artist",
      "url": "/audio/song.mp3",
      "cover": "/images/cover.jpg",
      "lrc": "[00:00.00] First lyric line"
    }
  ],
  "theme": "#b7daff",
  "loop": "all",
  "autoplay": false
}
```

MDX Component

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

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

Opções

Objeto audio

DPlayer Video Player

MD Fence

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

MDX Component

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" }}
/>

Opções

Objeto video

Objeto subtitle

Objeto danmaku

Lazy Loading Mechanism

Players are lazy-loaded via IntersectionObserver: the placeholder div dynamically imports the player module and styles and instantiates only when within 200px of the viewport.

• APlayer: dynamic import("aplayer") + import("aplayer/dist/APlayer.min.css")
• DPlayer: dynamic import("dplayer") (styles are inlined in JS; no separate CSS needed)

Module loading uses a shared Promise cache to avoid repeated dynamic imports. Re-instantiation is prevented via dataset markers (xng-init, xng-observed).

View Transitions Adaptation

The player script listens for astro:page-load and re-scans placeholder divs after each page load. After a View Transitions page switch, the new page’s player placeholders are re-observed and lazy-loaded.

Performance

• Pacote zero quando os players estão desativados (plugin remark não injetado, script do cliente não carregado)
• Runtime zero quando ativado mas sem players na página (script carrega mas não instancia)
• Módulos de player são chunks independentes, carregados sob demanda apenas nas páginas que os usam
• CSS e JS são importados separadamente para garantir que os estilos estejam prontos antes da instanciação

Declarações de tipo

APlayer e DPlayer não têm tipos TypeScript oficiais; o Xingluo fornece declarações de módulo flexíveis em src/types/aplayer.d.ts e src/types/dplayer.d.ts, com campos de opções definidos como opcionais para compatibilidade com spread. Os componentes MDX têm restrições de tipo completas nas Props.