مشغلات الوسائط

يدمج Xingluo APlayer (صوت) و DPlayer (فيديو)، ويدعم طريقتين لإنشاء المشغلات في Markdown و MDX، جميعها محملة ببطء.

التفعيل

قم بتبديل كل مشغل حسب الحاجة في features.players في xingluo.config.ts:

ts
features: {
  players: {
    aplayer: true,  // تفعيل مشغل الصوت APlayer
    dplayer: true,  // تفعيل مشغل الفيديو DPlayer
  },
}

الاثنان مستقلان. عند التعطيل:

• لا يتم حقن إضافة remarkPlayers (لا يتم تحليل حواجز MD)
• لا يتم تحميل سكريبت عميل المشغل
• لا يحتوي مخرجات البناء على أجزاء aplayer / dplayer

وضعي الاستخدام

كلا الوضعين ينتجان في النهاية نفس بنية div النائب (<div class="xng-aplayer|xng-dplayer" data-config>)، الذي يتم تحميله بتكاسل وإنشاء مثيل له بواسطة src/scripts/players.ts.

مشغل APlayer الصوتي

سياج MD

markdown
```aplayer
{
  "audio": [
    {
      "name": "أغنية",
      "artist": "فنان",
      "url": "/audio/song.mp3",
      "cover": "/images/cover.jpg",
      "lrc": "[00:00.00] سطر الكلمات الأول"
    }
  ],
  "theme": "#b7daff",
  "loop": "all",
  "autoplay": false
}
```

مكون MDX

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

<APlayer
  audio={[
    {
      name: "أغنية",
      artist: "فنان",
      url: "/audio/song.mp3",
      cover: "/images/cover.jpg",
    },
  ]}
  theme="#b7daff"
  loop="all"
/>

الخيارات

كائن الصوت (audio)

مشغل DPlayer الفيديو

سياج MD

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

مكون 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" }}
/>

الخيارات

كائن الفيديو (video)

كائن الترجمة (subtitle)

كائن الدانماكو (danmaku)

آلية التحميل البطيء

يتم تحميل المشغلات بتكاسل عبر IntersectionObserver: div النائب يستورد ديناميكياً وحدة المشغل والأنماط ويقوم بإنشاء المثيل فقط عندما يكون ضمن 200 بكسل من منفذ العرض.

• APlayer: استيراد ديناميكي import("aplayer") + import("aplayer/dist/APlayer.min.css")
• DPlayer: استيراد ديناميكي import("dplayer") (الأنماط مضمنة في JS؛ لا حاجة لـ CSS منفصل)

يستخدم تحميل الوحدات ذاكرة تخزين مؤقت مشتركة للـ Promise لتجنب عمليات الاستيراد الديناميكي المتكررة. يتم منع إعادة إنشاء المثيل عبر علامات dataset (xng-init، xng-observed).

التكيف مع View Transitions

يستمع سكريبت المشغل إلى astro:page-load ويعيد مسح أقسام div النائبة بعد كل تحميل صفحة. بعد تبديل الصفحة باستخدام View Transitions، يتم إعادة مراقبة أقسام div النائبة للمشغل في الصفحة الجديدة وتحميلها بتكاسل.

الأداء

• حزمة صفرية عند تعطيل المشغلات (إضافة remark غير محقونة، السكريبت العميل غير محمل)
• تشغيل صفري عند التمكين ولكن لا توجد مشغلات في الصفحة (السكريبت يُحمّل لكن لا يُنشئ مثيلات)
• وحدات المشغل هي أجزاء مستقلة، تُحمّل عند الطلب فقط في الصفحات التي تستخدمها
• CSS و JS يُستوردان بشكل منفصل لضمان جاهزية الأنماط قبل الإنشاء

إعلانات الأنواع

APlayer و DPlayer ليس لديهما أنواع TypeScript رسمية؛ يوفر Xingluo إعلانات وحدة مرنة في src/types/aplayer.d.ts و src/types/dplayer.d.ts، مع تعيين حقول الخيارات كاختيارية للتوافق مع الانتشار. مكونات MDX Props لها قيود نوع كاملة.