@fu-css/fu-player 0.1.0 → 0.2.0

package/README.md

@@ -79,6 +79,8 @@ const head = applyFuPlayerSeoHead(videoSeo, {
   twitterPlayerHeight: 720 // SEO：Twitter 播放器高度
 });
 
+const contactPhoneHref = "tel:+861380013****";
+
 const player = createFuPlayer("#player", {
   sources: [{ src: videoUrl, type: "video/mp4" }], // 播放器：视频源
   poster: posterUrl, // 播放器：封面
@@ -97,13 +99,15 @@ const player = createFuPlayer("#player", {
     transcript: videoSeo.transcript // GEO：转写语义文本
   },
   renderGeoText: true, // GEO：渲染语义文本层；设为 false 可关闭
-  share: { targets: ["copy", "x", "facebook"] }, // 播放器：分享入口
-  rightMenu: {
-    actions: [
-      { kind: "phone", href: "tel:+8613800138000", label: "电话" },
-      { kind: "email", href: "mailto:hello@example.com", label: "邮箱" }
-    ]
-  } // 播放器：右侧快捷入口
+  display: {
+    share: { targets: ["copy", "x", "facebook"] }, // 播放器：分享入口
+    rightMenu: {
+      actions: [
+        { kind: "phone", href: contactPhoneHref, label: "电话" },
+        { kind: "email", href: "mailto:hello@example.com", label: "邮箱" }
+      ]
+    } // 播放器：右侧快捷入口
+  }
 });
 
 // 后续可更新或销毁
@@ -126,6 +130,66 @@ HTML 只需要一个容器：
 - `player.play()` / `player.pause()`：控制播放。
 - `player.destroy()`：移除 DOM、监听器、adapter 和内部计时器。
 - `applyFuPlayerSeoHead(seo, options)`：写入页面级 title、meta、canonical 等 head 标签，并返回可销毁句柄。
+- `mergeFuPlayerOptions(...configs)`：合并通用配置和个性化配置；对象递归合并，数组和基础值由后面的配置覆盖。
+- `buildFuPlayerOptionsFromDto(dto)`：把后端返回的 `commonOptions` / `personalizedOptions` DTO 转成播放器配置。
+
+## 配置分层
+
+通用配置放站点、客户或场景级默认值；个性化配置只放当前视频或页面自己的内容。最终在调用 `createFuPlayer` 前合并一次。
+
+```ts
+import { createFuPlayer, mergeFuPlayerOptions, type FuPlayerSimpleOptions } from "@fu-css/fu-player";
+
+function createCommonPlayerConfig(phoneHref: string): FuPlayerSimpleOptions {
+  if (!phoneHref) {
+    throw new Error("Missing required phoneHref for the default quick action.");
+  }
+
+  return {
+    aspectRatio: "16 / 9",
+    controls: true,
+    pauseOtherPlayers: true,
+    display: {
+      share: {
+        targets: ["copy", "x", "facebook"],
+        buttonLabel: "Share"
+      },
+      rightMenu: {
+        ariaLabel: "Quick actions",
+        actions: [
+          { kind: "phone", href: phoneHref, label: "Phone" },
+          { kind: "email", href: "mailto:hello@example.com", label: "Email" }
+        ]
+      }
+    }
+  };
+}
+
+const options = mergeFuPlayerOptions(createCommonPlayerConfig("tel:+861380013****"), {
+  sources: [{ src: "https://example.com/video.mp4", type: "video/mp4" }],
+  poster: "https://example.com/poster.webp",
+  seo: videoSeo,
+  display: {
+    share: {
+      title: videoSeo.name,
+      text: videoSeo.description
+    }
+  }
+});
+
+createFuPlayer("#player", options);
+```
+
+需要关闭通用显示配置里的对象能力时，传 `display: { share: false }` 或 `display: { rightMenu: false }` 显式覆盖。数组字段默认整体替换，例如 `display.share.targets` 和 `display.rightMenu.actions`。
+
+后端已经按 profile 返回 DTO 时，可以直接转换；DTO 的 `player` 只放可序列化播放行为，分享、右侧菜单等显示项统一放 `display`。DTO 显示配置使用 `actionKey` / `actionPayload` 表达自定义行为，前端运行态再绑定 `onClick`。
+
+```ts
+import { buildFuPlayerOptionsFromDto, createFuPlayer } from "@fu-css/fu-player";
+
+const options = buildFuPlayerOptionsFromDto(playerConfigDto);
+createFuPlayer("#player", options);
+```
 
 ## 常用配置
 
@@ -136,16 +200,16 @@ HTML 只需要一个容器：
 - `src` / `sources`：视频地址，`sources` 优先。
 - `poster`：视频封面；短调用可省略。
 - `seoMode`：`indexable` 默认直接创建 `<video>`；`lazy` 可先显示封面，播放或进入视口后创建视频元素。
-- `share`：`false` 关闭分享菜单；对象形式可配置分享目标、文案和 URL。
-- `rightMenu`：`false` 关闭右侧快捷入口；数组或对象形式可配置电话、邮箱、WhatsApp 或自定义入口。
+- `display.share`：`false` 关闭分享菜单；对象形式可配置分享目标、文案和 URL。
+- `display.rightMenu`：`false` 关闭右侧快捷入口；数组或对象形式可配置电话、邮箱、WhatsApp 或自定义入口。
 - `autoPlay`：开启后初始静音，以匹配浏览器自动播放策略。
-- `hideMenu` / `hideControls`：分别隐藏菜单入口和底部控制栏。
+- `display.hideMenu` / `display.hideControls`：分别隐藏菜单入口和底部控制栏。
 - `sourceAdapters`：接入 HLS、DASH 等非原生播放源。
 - `pauseOtherPlayers`：设为 `true` 时，当前实例开始播放会自动暂停页面上的其他 FuPlayer 实例。
 
 ## 自定义分享
 
-`share.targets` 支持三种写法：
+`display.share.targets` 支持三种写法：
 
 - 内置字符串：`"copy"`、`"x"`、`"facebook"`、`"linkedin"`、`"whatsapp"`。
 - 内置覆盖：使用 `{ preset: "x", ... }` 保留内置目标，同时覆盖图标、文案、链接或行为。
@@ -154,45 +218,47 @@ HTML 只需要一个容器：
 ```ts
 createFuPlayer("#player", "https://example.com/video.mp4", {
   title: "安装演示",
-  share: {
-    url: "https://example.com/video-page",
-    title: "安装演示",
-    text: "播放器安装和配置流程。",
-    buttonLabel: "分享视频",
-    buttonIcon: "享",
-    buttonClassName: "my-share-trigger",
-    menuLabel: "选择分享方式",
-    menuClassName: "my-share-menu",
-    targets: [
-      "copy",
-      {
-        preset: "x",
-        label: "发到 X",
-        iconPath: "M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z",
-        href: ({ url, title }) =>
-          `https://twitter.com/intent/tweet?url=${encodeURIComponent(url)}&text=${encodeURIComponent(title)}`
-      },
-      {
-        id: "wechat",
-        label: "微信",
-        ariaLabel: "分享到微信",
-        icon: "微",
-        className: "my-share-option",
-        iconClassName: "my-share-icon",
-        onClick: async (payload, event) => {
-          event.preventDefault();
-          window.dispatchEvent(new CustomEvent("wechat-share", { detail: payload }));
+  display: {
+    share: {
+      url: "https://example.com/video-page",
+      title: "安装演示",
+      text: "播放器安装和配置流程。",
+      buttonLabel: "分享视频",
+      buttonIcon: "享",
+      buttonClassName: "my-share-trigger",
+      menuLabel: "选择分享方式",
+      menuClassName: "my-share-menu",
+      targets: [
+        "copy",
+        {
+          preset: "x",
+          label: "发到 X",
+          iconPath: "M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z",
+          href: ({ url, title }) =>
+            `https://twitter.com/intent/tweet?url=${encodeURIComponent(url)}&text=${encodeURIComponent(title)}`
+        },
+        {
+          id: "wechat",
+          label: "微信",
+          ariaLabel: "分享到微信",
+          icon: "微",
+          className: "my-share-option",
+          iconClassName: "my-share-icon",
+          onClick: async (payload, event) => {
+            event.preventDefault();
+            window.dispatchEvent(new CustomEvent("wechat-share", { detail: payload }));
+          }
+        },
+        {
+          id: "download",
+          label: "下载",
+          icon: "↓",
+          href: "https://example.com/video.mp4",
+          target: "_blank",
+          rel: "noopener"
         }
-      },
-      {
-        id: "download",
-        label: "下载",
-        icon: "↓",
-        href: "https://example.com/video.mp4",
-        target: "_blank",
-        rel: "noopener"
-      }
-    ]
+      ]
+    }
   }
 });
 ```
@@ -209,42 +275,44 @@ createFuPlayer("#player", "https://example.com/video.mp4", {
 
 ## 自定义右侧菜单
 
-右侧菜单通过 `rightMenu.actions` 配置。每个 action 既可以是链接，也可以是纯行为按钮；`iconPath` 优先于 `icon`，`icon` 会覆盖内置图标。
+右侧菜单通过 `display.rightMenu.actions` 配置。每个 action 既可以是链接，也可以是纯行为按钮；`iconPath` 优先于 `icon`，`icon` 会覆盖内置图标。
 
 ```ts
 createFuPlayer("#player", "https://example.com/video.mp4", {
-  rightMenu: {
-    ariaLabel: "快捷操作",
-    actions: [
-      {
-        kind: "phone",
-        href: "tel:+8613800138000",
-        label: "电话",
-        iconPath: "M6.62 10.79c1.44 2.83 3.76 5.14 6.59 6.59l2.2-2.2c.27-.27.67-.36 1.02-.24 1.12.37 2.33.57 3.57.57.55 0 1 .45 1 1V20c0 .55-.45 1-1 1C10.61 21 3 13.39 3 4c0-.55.45-1 1-1h3.5c.55 0 1 .45 1 1 0 1.24.2 2.45.57 3.57.11.35.03.74-.25 1.02z",
-        className: "my-menu-phone"
-      },
-      {
-        kind: "help",
-        label: "帮助",
-        ariaLabel: "打开帮助面板",
-        icon: "?",
-        className: "my-menu-help",
-        style: { background: "#111827" },
-        iconStyle: { color: "#fff" },
-        onClick: (event) => {
-          event.preventDefault();
-          window.dispatchEvent(new CustomEvent("fu-player-help"));
+  display: {
+    rightMenu: {
+      ariaLabel: "快捷操作",
+      actions: [
+        {
+          kind: "phone",
+          href: "tel:+861380013****",
+          label: "电话",
+          iconPath: "M6.62 10.79c1.44 2.83 3.76 5.14 6.59 6.59l2.2-2.2c.27-.27.67-.36 1.02-.24 1.12.37 2.33.57 3.57.57.55 0 1 .45 1 1V20c0 .55-.45 1-1 1C10.61 21 3 13.39 3 4c0-.55.45-1 1-1h3.5c.55 0 1 .45 1 1 0 1.24.2 2.45.57 3.57.11.35.03.74-.25 1.02z",
+          className: "my-menu-phone"
+        },
+        {
+          kind: "help",
+          label: "帮助",
+          ariaLabel: "打开帮助面板",
+          icon: "?",
+          className: "my-menu-help",
+          style: { background: "#111827" },
+          iconStyle: { color: "#fff" },
+          onClick: (event) => {
+            event.preventDefault();
+            window.dispatchEvent(new CustomEvent("fu-player-help"));
+          }
+        },
+        {
+          kind: "docs",
+          href: "https://example.com/docs",
+          label: "文档",
+          icon: "D",
+          target: "_blank",
+          rel: "noopener noreferrer"
         }
-      },
-      {
-        kind: "docs",
-        href: "https://example.com/docs",
-        label: "文档",
-        icon: "D",
-        target: "_blank",
-        rel: "noopener noreferrer"
-      }
-    ]
+      ]
+    }
   }
 });
 ```