@ezuikit/player-theme 3.1.6-beta.1 → 3.1.6

package/dist/constant.js

@@ -1,6 +1,6 @@
 /*
-* @ezuikit/player-theme v3.1.6-beta.1
-* Copyright (c) 2026-09-16 19:24:27 Ezviz-OpenBiz
+* @ezuikit/player-theme v3.1.6
+* Copyright (c) 2026-09-18 12:22:27 Ezviz-OpenBiz
 * Released under the MIT License.
 */
 /**

package/dist/index.cjs

@@ -1,6 +1,6 @@
 /*
-* @ezuikit/player-theme v3.1.6-beta.1
-* Copyright (c) 2026-09-16 19:24:27 Ezviz-OpenBiz
+* @ezuikit/player-theme v3.1.6
+* Copyright (c) 2026-09-18 12:22:27 Ezviz-OpenBiz
 * Released under the MIT License.
 */
 'use strict';
@@ -2968,7 +2968,8 @@ var zh = {
     cancel: '取消',
     ok: '确定',
     close: '关闭',
-    BTN_REC_LIST_TITLE: '录像片段'
+    BTN_REC_LIST_TITLE: '录像片段',
+    UNKOWN_ISSUE: '未知问题 【{{scope}}】'
 };
 
 // 不要出现多层的的数据, 数据铺平
@@ -3252,7 +3253,8 @@ var en = {
     cancel: 'Cancel',
     ok: 'Ok',
     close: 'Close',
-    BTN_REC_LIST_TITLE: 'Records'
+    BTN_REC_LIST_TITLE: 'Records',
+    UNKOWN_ISSUE: 'Unknown issue [{{scope}}]'
 };
 
 /**
@@ -10459,6 +10461,11 @@ function _unsupported_iterable_to_array(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
 }
+/**
+ * 语言包缺 key 时的兜底文案 key
+ *
+ * 拼写沿用语言包中既有的 `UNKOWN_ISSUE`（少了一个 N），改名属破坏性变更，故保持原样。
+ */ var UNKOWN_ISSUE_KEY = 'UNKOWN_ISSUE';
 var THEME_DEFAULT_OPTIONS = {
     dblClickFullscreen: true,
     language: 'zh',
@@ -10534,7 +10541,7 @@ var THEME_DEFAULT_OPTIONS = {
    */ _this._footerMoreControl = null, /** 头部控件 @since 0.0.1 @private */ _this._header = null, /** 低部控件 @since 0.0.1 @private */ _this._footer = null, /** 回放底部时间轴 @since 0.0.1 @private */ _this._recFooter = null, /**
    * 移动端扩展容器, 扩展的控件渲染在指定容器以外， 仅只用端适用， 为了可以放置大的控件和方便开发接入
    * @private
-   */ _this._mobileExtend = null, /**  @since 0.0.1 @private */ _this._interactiveResult = null, /**  @since 0.0.1 @private */ _this._themeData = null, _this._fullscreen = null, _this.zoomUtil = null, /** 清除屏幕旋转 */ _this._cleanupOrientation = null, /**  resizeObserver 监听销毁 */ _this._cleanUpResizeObserver = null, /** 容器的宽 */ _this._width = 0, /** 容器的高 */ _this._height = 0, /** 当前容器的全屏状态  true: 全屏， false: 非全屏 */ _this._isCurrentFullscreen = false, /** 屏幕旋转角度 0 ｜ 90 ｜ 180 ｜ 270 */ _this._orientationAngle = 0, _this._url = '', /** 是否播放中 @private */ _this._playing = false, /** @private 加载中 */ _this._loading = false, /** 音量 */ _this._volume = 0, /** 静音 */ _this._muted = false, /** 电子放大倍数 @private */ _this._zoom = 1, /** 放大中  true: 可缩放状态，false: 禁止缩放状态(不能缩放) @private */ _this._zooming = false, /** 录制中 @private */ _this._recording = false, /** 对讲中 @private */ _this._talking = false, /** 倍速 @private */ _this._speed = 1, /** 自定清晰度 @private */ _this._videoLevelAuto = false, /** 清晰度列表 */ _this.videoLevelList = [], /** 回放片段列表 */ _this.recordList = [], /**
+   */ _this._mobileExtend = null, /**  @since 0.0.1 @private */ _this._interactiveResult = null, /**  @since 0.0.1 @private */ _this._themeData = null, _this._fullscreen = null, _this.zoomUtil = null, /** 清除屏幕旋转 */ _this._cleanupOrientation = null, /**  resizeObserver 监听销毁 */ _this._cleanUpResizeObserver = null, /** 容器的宽 */ _this._width = 0, /** 容器的高 */ _this._height = 0, /** 当前容器的全屏状态  true: 全屏， false: 非全屏 */ _this._isCurrentFullscreen = false, /** 屏幕旋转角度 0 ｜ 90 ｜ 180 ｜ 270 */ _this._orientationAngle = 0, _this._url = '', /** 是否播放中 @private */ _this._playing = false, /** @private 加载中 */ _this._loading = false, /** 音量 */ _this._volume = 0, /** 静音 */ _this._muted = false, /** 正在兜底的原始 scope，非 null 表示处于兜底取值中（用于避免 customizeMissing 无限递归） */ _this._missingScope = null, /** 电子放大倍数 @private */ _this._zoom = 1, /** 放大中  true: 可缩放状态，false: 禁止缩放状态(不能缩放) @private */ _this._zooming = false, /** 录制中 @private */ _this._recording = false, /** 对讲中 @private */ _this._talking = false, /** 倍速 @private */ _this._speed = 1, /** 自定清晰度 @private */ _this._videoLevelAuto = false, /** 清晰度列表 */ _this.videoLevelList = [], /** 回放片段列表 */ _this.recordList = [], /**
    * 播放区间（片段分享），null 表示不约束。
    * 由 SDK 层在初始化时通过 props 下发，主题层据此决定日历/回放类型按钮
    * 是否渲染、片段进度条是否渲染。区间没有运行时变更入口。
@@ -10797,6 +10804,50 @@ var THEME_DEFAULT_OPTIONS = {
         }
     };
     /**
+   * 获取多语言文案
+   *
+   * 相比直接用 `theme.i18n.t()`：返回类型收窄为 `string`（底层签名是 `string | number`，
+   * 调用处不必再写 `as string`）。缺失 key 的兜底由 i18n 实例上的 `customizeMissing`
+   * 统一处理，因此两者在兜底行为上一致。
+   * @param scope 多语言 key
+   * @param variables 插值变量，如 `{ zoom: 8 }`；传 `defaultvalue` 可指定自己的兜底文案
+   * @returns 文案；scope 不存在时返回「未知问题 【scope】」
+   * @example
+   * ```ts
+   * theme.t('ZOOM_LIMIT_MAX', { zoom: 8 });
+   * theme.t('NOT_EXIST_KEY'); // 未知问题 【NOT_EXIST_KEY】
+   * theme.t('NOT_EXIST_KEY', { defaultvalue: '自定义兜底' }); // 自定义兜底
+   * ```
+   */ _proto.t = function t(scope, variables) {
+        return this.i18n.t(scope, variables);
+    };
+    /**
+   * 语言包缺 key 时的兜底文案（`customizeMissing` 的实现）
+   *
+   * 注意底层是把本方法的返回值「原样返回」、不再做插值，所以这里借
+   * `i18n.t(UNKOWN_ISSUE)` 完成插值。而这一次取值本身也可能缺失
+   * （如 `language` 传了不存在的语言，当前语言包整体不存在），
+   * 那会再次回调到这里造成无限递归，因此用重入标记兜住，退化为直接返回原始 scope。
+   *
+   * 注：`options.locales` 与内置语言包是深合并，无法移除内置的 UNKOWN_ISSUE，
+   * 因此正常配置下不会走到退化分支。
+   * @param scope 缺失的多语言 key
+   * @param variables 原始插值变量
+   */ _proto._missingText = function _missingText(scope, variables) {
+        // 兜底文案自身也缺失（如当前语言的语言包不存在）：直接返回最初的 scope，
+        // 而不是兜底 key 本身，否则用户看到的是 'UNKOWN_ISSUE' 这种无意义内容
+        if (this._missingScope !== null) return "" + this._missingScope;
+        this._missingScope = scope;
+        try {
+            // scope 放在最后，避免调用方传入同名变量把它覆盖掉
+            return this.i18n.t(UNKOWN_ISSUE_KEY, _extends({}, variables, {
+                scope: scope
+            }));
+        } finally{
+            this._missingScope = null;
+        }
+    };
+    /**
    * 销毁包括事件、控件 ...
    *
    * Destroy (including events, controls...)
@@ -10852,6 +10903,7 @@ var THEME_DEFAULT_OPTIONS = {
     // 私有方法
     // ==============================================================================================
     /** 初始化配置项 */ _proto._initOptions = function _initOptions(options) {
+        var _this = this;
         if (options === void 0) options = {};
         var _this_options_loggerOptions, _this_options_definitionOptions_list, _this_options_definitionOptions, _this_options_videoLevelList;
         // 先对模块级默认配置做一次深拷贝，得到全新的嵌套对象/数组，
@@ -10904,7 +10956,13 @@ var THEME_DEFAULT_OPTIONS = {
         });
         // prettier-ignore
         this.i18n = new I18n(locales, {
-            defaultLocale: language
+            defaultLocale: language,
+            // 语言包缺 key 时，底层默认返回 `[missing "zh.XXX" translation]`，
+            // 这种占位串一旦透到 UI 上对用户毫无意义。挂在 i18n 实例上统一兜底，
+            // 这样控件内直接调用 `i18n.t()` 的地方也能受益，无需逐处改造。
+            customizeMissing: function customizeMissing(scope, variables) {
+                return _this._missingText(scope, variables);
+            }
         });
         // 默认清晰度列表
         if (((_this_options_definitionOptions = this.options.definitionOptions) == null ? void 0 : (_this_options_definitionOptions_list = _this_options_definitionOptions.list) == null ? void 0 : _this_options_definitionOptions_list.length) > 0 || ((_this_options_videoLevelList = this.options.videoLevelList) == null ? void 0 : _this_options_videoLevelList.length) > 0) {
@@ -11929,7 +11987,7 @@ var THEME_DEFAULT_OPTIONS = {
     zh: zh,
     en: en
 };
-/** 版本号 @since 0.0.1 */ Theme.THEME_VERSION = '3.1.6-beta.1';
+/** 版本号 @since 0.0.1 */ Theme.THEME_VERSION = '3.1.6';
 
 exports.Control = Control;
 exports.EVENTS = EVENTS;

package/dist/index.esm.js

@@ -1,6 +1,6 @@
 /*
-* @ezuikit/player-theme v3.1.6-beta.1
-* Copyright (c) 2026-09-16 19:24:27 Ezviz-OpenBiz
+* @ezuikit/player-theme v3.1.6
+* Copyright (c) 2026-09-18 12:22:27 Ezviz-OpenBiz
 * Released under the MIT License.
 */
 import EventEmitter from 'eventemitter3';
@@ -2966,7 +2966,8 @@ var zh = {
     cancel: '取消',
     ok: '确定',
     close: '关闭',
-    BTN_REC_LIST_TITLE: '录像片段'
+    BTN_REC_LIST_TITLE: '录像片段',
+    UNKOWN_ISSUE: '未知问题 【{{scope}}】'
 };
 
 // 不要出现多层的的数据, 数据铺平
@@ -3250,7 +3251,8 @@ var en = {
     cancel: 'Cancel',
     ok: 'Ok',
     close: 'Close',
-    BTN_REC_LIST_TITLE: 'Records'
+    BTN_REC_LIST_TITLE: 'Records',
+    UNKOWN_ISSUE: 'Unknown issue [{{scope}}]'
 };
 
 /**
@@ -10457,6 +10459,11 @@ function _unsupported_iterable_to_array(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
 }
+/**
+ * 语言包缺 key 时的兜底文案 key
+ *
+ * 拼写沿用语言包中既有的 `UNKOWN_ISSUE`（少了一个 N），改名属破坏性变更，故保持原样。
+ */ var UNKOWN_ISSUE_KEY = 'UNKOWN_ISSUE';
 var THEME_DEFAULT_OPTIONS = {
     dblClickFullscreen: true,
     language: 'zh',
@@ -10532,7 +10539,7 @@ var THEME_DEFAULT_OPTIONS = {
    */ _this._footerMoreControl = null, /** 头部控件 @since 0.0.1 @private */ _this._header = null, /** 低部控件 @since 0.0.1 @private */ _this._footer = null, /** 回放底部时间轴 @since 0.0.1 @private */ _this._recFooter = null, /**
    * 移动端扩展容器, 扩展的控件渲染在指定容器以外， 仅只用端适用， 为了可以放置大的控件和方便开发接入
    * @private
-   */ _this._mobileExtend = null, /**  @since 0.0.1 @private */ _this._interactiveResult = null, /**  @since 0.0.1 @private */ _this._themeData = null, _this._fullscreen = null, _this.zoomUtil = null, /** 清除屏幕旋转 */ _this._cleanupOrientation = null, /**  resizeObserver 监听销毁 */ _this._cleanUpResizeObserver = null, /** 容器的宽 */ _this._width = 0, /** 容器的高 */ _this._height = 0, /** 当前容器的全屏状态  true: 全屏， false: 非全屏 */ _this._isCurrentFullscreen = false, /** 屏幕旋转角度 0 ｜ 90 ｜ 180 ｜ 270 */ _this._orientationAngle = 0, _this._url = '', /** 是否播放中 @private */ _this._playing = false, /** @private 加载中 */ _this._loading = false, /** 音量 */ _this._volume = 0, /** 静音 */ _this._muted = false, /** 电子放大倍数 @private */ _this._zoom = 1, /** 放大中  true: 可缩放状态，false: 禁止缩放状态(不能缩放) @private */ _this._zooming = false, /** 录制中 @private */ _this._recording = false, /** 对讲中 @private */ _this._talking = false, /** 倍速 @private */ _this._speed = 1, /** 自定清晰度 @private */ _this._videoLevelAuto = false, /** 清晰度列表 */ _this.videoLevelList = [], /** 回放片段列表 */ _this.recordList = [], /**
+   */ _this._mobileExtend = null, /**  @since 0.0.1 @private */ _this._interactiveResult = null, /**  @since 0.0.1 @private */ _this._themeData = null, _this._fullscreen = null, _this.zoomUtil = null, /** 清除屏幕旋转 */ _this._cleanupOrientation = null, /**  resizeObserver 监听销毁 */ _this._cleanUpResizeObserver = null, /** 容器的宽 */ _this._width = 0, /** 容器的高 */ _this._height = 0, /** 当前容器的全屏状态  true: 全屏， false: 非全屏 */ _this._isCurrentFullscreen = false, /** 屏幕旋转角度 0 ｜ 90 ｜ 180 ｜ 270 */ _this._orientationAngle = 0, _this._url = '', /** 是否播放中 @private */ _this._playing = false, /** @private 加载中 */ _this._loading = false, /** 音量 */ _this._volume = 0, /** 静音 */ _this._muted = false, /** 正在兜底的原始 scope，非 null 表示处于兜底取值中（用于避免 customizeMissing 无限递归） */ _this._missingScope = null, /** 电子放大倍数 @private */ _this._zoom = 1, /** 放大中  true: 可缩放状态，false: 禁止缩放状态(不能缩放) @private */ _this._zooming = false, /** 录制中 @private */ _this._recording = false, /** 对讲中 @private */ _this._talking = false, /** 倍速 @private */ _this._speed = 1, /** 自定清晰度 @private */ _this._videoLevelAuto = false, /** 清晰度列表 */ _this.videoLevelList = [], /** 回放片段列表 */ _this.recordList = [], /**
    * 播放区间（片段分享），null 表示不约束。
    * 由 SDK 层在初始化时通过 props 下发，主题层据此决定日历/回放类型按钮
    * 是否渲染、片段进度条是否渲染。区间没有运行时变更入口。
@@ -10795,6 +10802,50 @@ var THEME_DEFAULT_OPTIONS = {
         }
     };
     /**
+   * 获取多语言文案
+   *
+   * 相比直接用 `theme.i18n.t()`：返回类型收窄为 `string`（底层签名是 `string | number`，
+   * 调用处不必再写 `as string`）。缺失 key 的兜底由 i18n 实例上的 `customizeMissing`
+   * 统一处理，因此两者在兜底行为上一致。
+   * @param scope 多语言 key
+   * @param variables 插值变量，如 `{ zoom: 8 }`；传 `defaultvalue` 可指定自己的兜底文案
+   * @returns 文案；scope 不存在时返回「未知问题 【scope】」
+   * @example
+   * ```ts
+   * theme.t('ZOOM_LIMIT_MAX', { zoom: 8 });
+   * theme.t('NOT_EXIST_KEY'); // 未知问题 【NOT_EXIST_KEY】
+   * theme.t('NOT_EXIST_KEY', { defaultvalue: '自定义兜底' }); // 自定义兜底
+   * ```
+   */ _proto.t = function t(scope, variables) {
+        return this.i18n.t(scope, variables);
+    };
+    /**
+   * 语言包缺 key 时的兜底文案（`customizeMissing` 的实现）
+   *
+   * 注意底层是把本方法的返回值「原样返回」、不再做插值，所以这里借
+   * `i18n.t(UNKOWN_ISSUE)` 完成插值。而这一次取值本身也可能缺失
+   * （如 `language` 传了不存在的语言，当前语言包整体不存在），
+   * 那会再次回调到这里造成无限递归，因此用重入标记兜住，退化为直接返回原始 scope。
+   *
+   * 注：`options.locales` 与内置语言包是深合并，无法移除内置的 UNKOWN_ISSUE，
+   * 因此正常配置下不会走到退化分支。
+   * @param scope 缺失的多语言 key
+   * @param variables 原始插值变量
+   */ _proto._missingText = function _missingText(scope, variables) {
+        // 兜底文案自身也缺失（如当前语言的语言包不存在）：直接返回最初的 scope，
+        // 而不是兜底 key 本身，否则用户看到的是 'UNKOWN_ISSUE' 这种无意义内容
+        if (this._missingScope !== null) return "" + this._missingScope;
+        this._missingScope = scope;
+        try {
+            // scope 放在最后，避免调用方传入同名变量把它覆盖掉
+            return this.i18n.t(UNKOWN_ISSUE_KEY, _extends({}, variables, {
+                scope: scope
+            }));
+        } finally{
+            this._missingScope = null;
+        }
+    };
+    /**
    * 销毁包括事件、控件 ...
    *
    * Destroy (including events, controls...)
@@ -10850,6 +10901,7 @@ var THEME_DEFAULT_OPTIONS = {
     // 私有方法
     // ==============================================================================================
     /** 初始化配置项 */ _proto._initOptions = function _initOptions(options) {
+        var _this = this;
         if (options === void 0) options = {};
         var _this_options_loggerOptions, _this_options_definitionOptions_list, _this_options_definitionOptions, _this_options_videoLevelList;
         // 先对模块级默认配置做一次深拷贝，得到全新的嵌套对象/数组，
@@ -10902,7 +10954,13 @@ var THEME_DEFAULT_OPTIONS = {
         });
         // prettier-ignore
         this.i18n = new I18n(locales, {
-            defaultLocale: language
+            defaultLocale: language,
+            // 语言包缺 key 时，底层默认返回 `[missing "zh.XXX" translation]`，
+            // 这种占位串一旦透到 UI 上对用户毫无意义。挂在 i18n 实例上统一兜底，
+            // 这样控件内直接调用 `i18n.t()` 的地方也能受益，无需逐处改造。
+            customizeMissing: function customizeMissing(scope, variables) {
+                return _this._missingText(scope, variables);
+            }
         });
         // 默认清晰度列表
         if (((_this_options_definitionOptions = this.options.definitionOptions) == null ? void 0 : (_this_options_definitionOptions_list = _this_options_definitionOptions.list) == null ? void 0 : _this_options_definitionOptions_list.length) > 0 || ((_this_options_videoLevelList = this.options.videoLevelList) == null ? void 0 : _this_options_videoLevelList.length) > 0) {
@@ -11927,6 +11985,6 @@ var THEME_DEFAULT_OPTIONS = {
     zh: zh,
     en: en
 };
-/** 版本号 @since 0.0.1 */ Theme.THEME_VERSION = '3.1.6-beta.1';
+/** 版本号 @since 0.0.1 */ Theme.THEME_VERSION = '3.1.6';
 
 export { Control, EVENTS, Fullscreen, Loading, Message, Play, Poster, Rec, Theme, Utils, Volume };

package/dist/index.umd.js

@@ -1,6 +1,6 @@
 /*
-* @ezuikit/player-theme v3.1.6-beta.1
-* Copyright (c) 2026-09-16 19:24:27 Ezviz-OpenBiz
+* @ezuikit/player-theme v3.1.6
+* Copyright (c) 2026-09-18 12:22:27 Ezviz-OpenBiz
 * Released under the MIT License.
 */
 (function (global, factory) {
@@ -4455,7 +4455,8 @@
 	    cancel: '取消',
 	    ok: '确定',
 	    close: '关闭',
-	    BTN_REC_LIST_TITLE: '录像片段'
+	    BTN_REC_LIST_TITLE: '录像片段',
+	    UNKOWN_ISSUE: '未知问题 【{{scope}}】'
 	};
 
 	// 不要出现多层的的数据, 数据铺平
@@ -4739,7 +4740,8 @@
 	    cancel: 'Cancel',
 	    ok: 'Ok',
 	    close: 'Close',
-	    BTN_REC_LIST_TITLE: 'Records'
+	    BTN_REC_LIST_TITLE: 'Records',
+	    UNKOWN_ISSUE: 'Unknown issue [{{scope}}]'
 	};
 
 	/**
@@ -12458,6 +12460,11 @@
 	    if (n === "Map" || n === "Set") return Array.from(n);
 	    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
 	}
+	/**
+	 * 语言包缺 key 时的兜底文案 key
+	 *
+	 * 拼写沿用语言包中既有的 `UNKOWN_ISSUE`（少了一个 N），改名属破坏性变更，故保持原样。
+	 */ var UNKOWN_ISSUE_KEY = 'UNKOWN_ISSUE';
 	var THEME_DEFAULT_OPTIONS = {
 	    dblClickFullscreen: true,
 	    language: 'zh',
@@ -12533,7 +12540,7 @@
 	   */ _this._footerMoreControl = null, /** 头部控件 @since 0.0.1 @private */ _this._header = null, /** 低部控件 @since 0.0.1 @private */ _this._footer = null, /** 回放底部时间轴 @since 0.0.1 @private */ _this._recFooter = null, /**
 	   * 移动端扩展容器, 扩展的控件渲染在指定容器以外， 仅只用端适用， 为了可以放置大的控件和方便开发接入
 	   * @private
-	   */ _this._mobileExtend = null, /**  @since 0.0.1 @private */ _this._interactiveResult = null, /**  @since 0.0.1 @private */ _this._themeData = null, _this._fullscreen = null, _this.zoomUtil = null, /** 清除屏幕旋转 */ _this._cleanupOrientation = null, /**  resizeObserver 监听销毁 */ _this._cleanUpResizeObserver = null, /** 容器的宽 */ _this._width = 0, /** 容器的高 */ _this._height = 0, /** 当前容器的全屏状态  true: 全屏， false: 非全屏 */ _this._isCurrentFullscreen = false, /** 屏幕旋转角度 0 ｜ 90 ｜ 180 ｜ 270 */ _this._orientationAngle = 0, _this._url = '', /** 是否播放中 @private */ _this._playing = false, /** @private 加载中 */ _this._loading = false, /** 音量 */ _this._volume = 0, /** 静音 */ _this._muted = false, /** 电子放大倍数 @private */ _this._zoom = 1, /** 放大中  true: 可缩放状态，false: 禁止缩放状态(不能缩放) @private */ _this._zooming = false, /** 录制中 @private */ _this._recording = false, /** 对讲中 @private */ _this._talking = false, /** 倍速 @private */ _this._speed = 1, /** 自定清晰度 @private */ _this._videoLevelAuto = false, /** 清晰度列表 */ _this.videoLevelList = [], /** 回放片段列表 */ _this.recordList = [], /**
+	   */ _this._mobileExtend = null, /**  @since 0.0.1 @private */ _this._interactiveResult = null, /**  @since 0.0.1 @private */ _this._themeData = null, _this._fullscreen = null, _this.zoomUtil = null, /** 清除屏幕旋转 */ _this._cleanupOrientation = null, /**  resizeObserver 监听销毁 */ _this._cleanUpResizeObserver = null, /** 容器的宽 */ _this._width = 0, /** 容器的高 */ _this._height = 0, /** 当前容器的全屏状态  true: 全屏， false: 非全屏 */ _this._isCurrentFullscreen = false, /** 屏幕旋转角度 0 ｜ 90 ｜ 180 ｜ 270 */ _this._orientationAngle = 0, _this._url = '', /** 是否播放中 @private */ _this._playing = false, /** @private 加载中 */ _this._loading = false, /** 音量 */ _this._volume = 0, /** 静音 */ _this._muted = false, /** 正在兜底的原始 scope，非 null 表示处于兜底取值中（用于避免 customizeMissing 无限递归） */ _this._missingScope = null, /** 电子放大倍数 @private */ _this._zoom = 1, /** 放大中  true: 可缩放状态，false: 禁止缩放状态(不能缩放) @private */ _this._zooming = false, /** 录制中 @private */ _this._recording = false, /** 对讲中 @private */ _this._talking = false, /** 倍速 @private */ _this._speed = 1, /** 自定清晰度 @private */ _this._videoLevelAuto = false, /** 清晰度列表 */ _this.videoLevelList = [], /** 回放片段列表 */ _this.recordList = [], /**
 	   * 播放区间（片段分享），null 表示不约束。
 	   * 由 SDK 层在初始化时通过 props 下发，主题层据此决定日历/回放类型按钮
 	   * 是否渲染、片段进度条是否渲染。区间没有运行时变更入口。
@@ -12796,6 +12803,50 @@
 	        }
 	    };
 	    /**
+	   * 获取多语言文案
+	   *
+	   * 相比直接用 `theme.i18n.t()`：返回类型收窄为 `string`（底层签名是 `string | number`，
+	   * 调用处不必再写 `as string`）。缺失 key 的兜底由 i18n 实例上的 `customizeMissing`
+	   * 统一处理，因此两者在兜底行为上一致。
+	   * @param scope 多语言 key
+	   * @param variables 插值变量，如 `{ zoom: 8 }`；传 `defaultvalue` 可指定自己的兜底文案
+	   * @returns 文案；scope 不存在时返回「未知问题 【scope】」
+	   * @example
+	   * ```ts
+	   * theme.t('ZOOM_LIMIT_MAX', { zoom: 8 });
+	   * theme.t('NOT_EXIST_KEY'); // 未知问题 【NOT_EXIST_KEY】
+	   * theme.t('NOT_EXIST_KEY', { defaultvalue: '自定义兜底' }); // 自定义兜底
+	   * ```
+	   */ _proto.t = function t(scope, variables) {
+	        return this.i18n.t(scope, variables);
+	    };
+	    /**
+	   * 语言包缺 key 时的兜底文案（`customizeMissing` 的实现）
+	   *
+	   * 注意底层是把本方法的返回值「原样返回」、不再做插值，所以这里借
+	   * `i18n.t(UNKOWN_ISSUE)` 完成插值。而这一次取值本身也可能缺失
+	   * （如 `language` 传了不存在的语言，当前语言包整体不存在），
+	   * 那会再次回调到这里造成无限递归，因此用重入标记兜住，退化为直接返回原始 scope。
+	   *
+	   * 注：`options.locales` 与内置语言包是深合并，无法移除内置的 UNKOWN_ISSUE，
+	   * 因此正常配置下不会走到退化分支。
+	   * @param scope 缺失的多语言 key
+	   * @param variables 原始插值变量
+	   */ _proto._missingText = function _missingText(scope, variables) {
+	        // 兜底文案自身也缺失（如当前语言的语言包不存在）：直接返回最初的 scope，
+	        // 而不是兜底 key 本身，否则用户看到的是 'UNKOWN_ISSUE' 这种无意义内容
+	        if (this._missingScope !== null) return "" + this._missingScope;
+	        this._missingScope = scope;
+	        try {
+	            // scope 放在最后，避免调用方传入同名变量把它覆盖掉
+	            return this.i18n.t(UNKOWN_ISSUE_KEY, _extends({}, variables, {
+	                scope: scope
+	            }));
+	        } finally{
+	            this._missingScope = null;
+	        }
+	    };
+	    /**
 	   * 销毁包括事件、控件 ...
 	   *
 	   * Destroy (including events, controls...)
@@ -12851,6 +12902,7 @@
 	    // 私有方法
 	    // ==============================================================================================
 	    /** 初始化配置项 */ _proto._initOptions = function _initOptions(options) {
+	        var _this = this;
 	        if (options === void 0) options = {};
 	        var _this_options_loggerOptions, _this_options_definitionOptions_list, _this_options_definitionOptions, _this_options_videoLevelList;
 	        // 先对模块级默认配置做一次深拷贝，得到全新的嵌套对象/数组，
@@ -12903,7 +12955,13 @@
 	        });
 	        // prettier-ignore
 	        this.i18n = new I18n(locales, {
-	            defaultLocale: language
+	            defaultLocale: language,
+	            // 语言包缺 key 时，底层默认返回 `[missing "zh.XXX" translation]`，
+	            // 这种占位串一旦透到 UI 上对用户毫无意义。挂在 i18n 实例上统一兜底，
+	            // 这样控件内直接调用 `i18n.t()` 的地方也能受益，无需逐处改造。
+	            customizeMissing: function customizeMissing(scope, variables) {
+	                return _this._missingText(scope, variables);
+	            }
 	        });
 	        // 默认清晰度列表
 	        if (((_this_options_definitionOptions = this.options.definitionOptions) == null ? void 0 : (_this_options_definitionOptions_list = _this_options_definitionOptions.list) == null ? void 0 : _this_options_definitionOptions_list.length) > 0 || ((_this_options_videoLevelList = this.options.videoLevelList) == null ? void 0 : _this_options_videoLevelList.length) > 0) {
@@ -13928,7 +13986,7 @@
 	    zh: zh,
 	    en: en
 	};
-	/** 版本号 @since 0.0.1 */ Theme.THEME_VERSION = '3.1.6-beta.1';
+	/** 版本号 @since 0.0.1 */ Theme.THEME_VERSION = '3.1.6';
 
 	// 不要动这里的代码， 这个出口是为了编译成 umd 规范的文件
 

package/dist/style.js

@@ -1,6 +1,6 @@
 /*
-* @ezuikit/player-theme v3.1.6-beta.1
-* Copyright (c) 2026-09-16 19:24:27 Ezviz-OpenBiz
+* @ezuikit/player-theme v3.1.6
+* Copyright (c) 2026-09-18 12:22:27 Ezviz-OpenBiz
 * Released under the MIT License.
 */
 require("./style.css");

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import EventEmitter from 'eventemitter3';
 import Picker from '@skax/picker';
-import I18n, { I18nTranslation } from '@ezuikit/utils-i18n';
+import I18n, { TranslateVariables, I18nTranslation } from '@ezuikit/utils-i18n';
 import { LoggerCls, LoggerOptions } from '@ezuikit/utils-logger';
 import { BasePtzOptions } from '@ezuikit/control-ptz';
 import { RecListModalOptions } from '@ezuikit/control-rec-list-modal';
@@ -1525,18 +1525,14 @@ declare class Theme extends EventEmitter {
         readonly recDropdownChange: "recDropdownChange";
         readonly recListChange: "recListChange";
         readonly alarmMessageChange: "alarmMessageChange";
-        readonly setLoggerOptions: "setLoggerOptions"; /**
-         * 更多控件（footer more）
-         * @since 0.0.1
-         * @private
-         */
+        readonly setLoggerOptions: "setLoggerOptions";
         readonly records: "records";
         readonly ptzSpeedChange: "ptzSpeedChange";
         readonly setVideoLevelList: "setVideoLevelList";
         readonly currentVideoLevel: "currentVideoLevel";
         readonly currentVideoLevelAuto: "currentVideoLevelAuto";
         readonly setAllDayRecTimes: "setAllDayRecTimes";
-        readonly getOSDTime: "getOSDTime";
+        readonly getOSDTime: "getOSDTime"; /** 头部控件 @since 0.0.1 @private */
         readonly playbackEnd: "playbackEnd";
         readonly control: {
             readonly play: "Control.play";
@@ -1772,12 +1768,13 @@ declare class Theme extends EventEmitter {
             SPEED_CANCEL: string;
             GET_SPEED: string;
             MAX_SPEED_LIMIT: string;
+            /** 版本号 @since 0.0.1 */
             MIN_SPEED_LIMIT: string;
-            SPEED_SWITCH_ERRROR: string;
+            SPEED_SWITCH_ERRROR: string; /** 播放器配置项 */
             SPEED_SWITCH_NOT_SUPPORT: string;
             SEEK_CANNOT_CROSS_DAYS: string;
             SEEK_TIMEFORMAT_ERROR: string;
-            PAUSE: string;
+            PAUSE: string; /** 多语言对象 https://www.npmjs.com/package/@ezuikit/utils-i18n  @since 0.0.1 */
             PAUSE_FAILED: string;
             RESUME: string;
             RESUME_FAILED: string;
@@ -1786,7 +1783,7 @@ declare class Theme extends EventEmitter {
             NO_CLOUD_RECORD: string;
             CHANGE_VIDEO_LEVEL: string;
             CHANGE_VIDEO_LEVEL_FAIL: string;
-            GET_VIDEO_LEVEL_LIST: string; /** 消息提示控件 @since 0.0.1 @private */
+            GET_VIDEO_LEVEL_LIST: string;
             PLEASE_INPUT_RIGHT_VIDEO_LEVEL: string;
             VIDEO_LEVEL_NOT_SUPPORT: string;
             VIDEO_LEVEL_AUTO: string;
@@ -1796,6 +1793,10 @@ declare class Theme extends EventEmitter {
             VIDEO_LEVEL_SUPER: string;
             VIDEO_LEVEL_EXTREME: string;
             VIDEO_LEVEL_3K: string;
+            /**
+             * @since 0.0.1
+             * @private
+             */
             VIDEO_LEVEL_4k: string;
             RESET_THEME: string;
             BTN_PLAY: string;
@@ -1816,10 +1817,7 @@ declare class Theme extends EventEmitter {
             BTN_ZOOM: string;
             BTN_3D_ZOOM: string;
             BTN_PTZ: string;
-            BTN_GLOBAL_FULLSCREEN: string; /**
-             * 移动端扩展容器, 扩展的控件渲染在指定容器以外， 仅只用端适用， 为了可以放置大的控件和方便开发接入
-             * @private
-             */
+            BTN_GLOBAL_FULLSCREEN: string;
             BTN_EXIT_GLOBAL_FULLSCREEN: string;
             BTN_FULLSCREEN: string;
             BTN_EXIR_FULLSCREEN: string;
@@ -1843,10 +1841,9 @@ declare class Theme extends EventEmitter {
             RECORDS: string;
             OPEN_SOUND: string;
             CLOSE_SOUND: string;
-            SOUND_OPENED: string; /** 容器的宽 */
+            SOUND_OPENED: string;
             ZOOM: string;
             START_ZOOM: string;
-            /** 容器的高 */
             CLOSE_ZOOM: string;
             ZOOM_ADD: string;
             ZOOM_SUB: string;
@@ -1856,7 +1853,7 @@ declare class Theme extends EventEmitter {
             ZOOM_LIMIT_MIN: string;
             ZOOM_NOT_ENABLED: string;
             '3D_ZOOM': string;
-            '3D_ZOOM_DISABLE': string;
+            '3D_ZOOM_DISABLE': string; /** 屏幕旋转角度 0 ｜ 90 ｜ 180 ｜ 270 */
             '3D_ZOOM_FAILED': string;
             START_3D_ZOOM: string;
             CLOSE_3D_ZOOM: string;
@@ -1871,25 +1868,18 @@ declare class Theme extends EventEmitter {
             WEB_FULLSCREEN: string;
             WEB_FULLSCREEN_EXIT: string;
             DESTROY: string;
-            /** 回放片段列表 */
             GET_CAPACITY: string;
             GET_PTZ_STATUS: string;
             GET_PTZ_STATUS_FAILED: string;
             MOBILE_HIDE_PTZ: string;
             OPTION_PTZ_FAILED: string;
             MOBILE_PTZ_TIPS: string;
-            PTZ_FAST: string; /** 窗口尺寸变化时，设置窗口超出隐藏，防止出现滚动条 */
+            PTZ_FAST: string;
             PTZ_MID: string;
             PTZ_SLOW: string;
             PTZ_SPEED: string;
             DEVICE_ZOOM: string;
-            /**
-             * 录像回放的月份列表 @private
-             */
             DEVICE_FOCUS: string;
-            /**
-             * 录像回放的月份列表 @private
-             */
             NOT_SUPPORT_DEVICE_ZOOM: string;
             NOT_SUPPORT_FOCUS: string;
             MIRROR: string;
@@ -1903,13 +1893,19 @@ declare class Theme extends EventEmitter {
             GET_FEC_PARAMS: string;
             SET_FEC_PARAMS_FAILED: string;
             GET_FEC_PARAMS_FAILED: string;
-            GET_FEC_PARAMS_SUPPORT_VERSION: string;
+            /**
+             * 录像回放的月份列表 @private
+             */
+            GET_FEC_PARAMS_SUPPORT_VERSION: string; /**
+             * 录像回放的月份列表 @private
+             */
             SET_WATERMARK: string;
-            FETCH_THEME_FAILED: string;
+            FETCH_THEME_FAILED: string; /** 清理 header/footer 动画 定时器 @private */
             cancel: string;
             ok: string;
             close: string;
             BTN_REC_LIST_TITLE: string;
+            UNKOWN_ISSUE: string;
         };
         en: {
             391001: string;
@@ -1990,7 +1986,7 @@ declare class Theme extends EventEmitter {
             396506: string;
             396508: string;
             396509: string;
-            396510: string; /** 静音 */
+            396510: string;
             396511: string;
             396512: string;
             396513: string;
@@ -2000,24 +1996,19 @@ declare class Theme extends EventEmitter {
             396517: string;
             396518: string;
             396519: string;
-            /**
-             * 录像回放的月份列表 @private
-             */
             396520: string;
-            /**
-             * 录像回放的月份列表 @private
-             */
             396700: string;
-            /**
-             * 录像回放的月份列表 @private
-             */
             396701: string;
             397001: string;
             397002: string;
             397003: string;
             397004: string;
             397005: string;
-            397006: string;
+            397006: string; /**
+             * 首帧同步 Live/RecDropdown 激活态的监听器引用。
+             * 每次 `_renderTheme` 重新绑定前需先移除旧引用，避免 changeTheme 累积监听。
+             * @private
+             */
             397007: string;
             399000: string;
             399001: string;
@@ -2116,6 +2107,12 @@ declare class Theme extends EventEmitter {
             BTN_ZOOM: string;
             BTN_3D_ZOOM: string;
             BTN_PTZ: string;
+            /**
+             * 当前播放状态
+             * ```ts
+             * theme.playing // boolean
+             * ```
+             */
             BTN_GLOBAL_FULLSCREEN: string;
             BTN_EXIT_GLOBAL_FULLSCREEN: string;
             BTN_FULLSCREEN: string;
@@ -2175,9 +2172,7 @@ declare class Theme extends EventEmitter {
             MOBILE_HIDE_PTZ: string;
             OPTION_PTZ_FAILED: string;
             MOBILE_PTZ_TIPS: string;
-            PTZ_FAST: string; /**
-             * 是否在缩放中
-             */
+            PTZ_FAST: string;
             PTZ_MID: string;
             PTZ_SLOW: string;
             PTZ_SPEED: string;
@@ -2203,6 +2198,7 @@ declare class Theme extends EventEmitter {
             ok: string;
             close: string;
             BTN_REC_LIST_TITLE: string;
+            UNKOWN_ISSUE: string;
         };
     };
     /** 版本号 @since 0.0.1 */
@@ -2290,6 +2286,8 @@ declare class Theme extends EventEmitter {
     private _volume;
     /** 静音 */
     private _muted;
+    /** 正在兜底的原始 scope，非 null 表示处于兜底取值中（用于避免 customizeMissing 无限递归） */
+    private _missingScope;
     /** 电子放大倍数 @private */
     _zoom: number;
     /** 放大中  true: 可缩放状态，false: 禁止缩放状态(不能缩放) @private */
@@ -2631,6 +2629,37 @@ declare class Theme extends EventEmitter {
      * @param {0 | 1 | 2} scaleMode - 缩放模式， 0: 窗口铺满， 1: 等比缩放大边铺满， 2: 等比缩放小边铺满
      */
     setScaleMode(scaleMode: ThemeOptions['scaleMode']): void;
+    /**
+     * 获取多语言文案
+     *
+     * 相比直接用 `theme.i18n.t()`：返回类型收窄为 `string`（底层签名是 `string | number`，
+     * 调用处不必再写 `as string`）。缺失 key 的兜底由 i18n 实例上的 `customizeMissing`
+     * 统一处理，因此两者在兜底行为上一致。
+     * @param scope 多语言 key
+     * @param variables 插值变量，如 `{ zoom: 8 }`；传 `defaultvalue` 可指定自己的兜底文案
+     * @returns 文案；scope 不存在时返回「未知问题 【scope】」
+     * @example
+     * ```ts
+     * theme.t('ZOOM_LIMIT_MAX', { zoom: 8 });
+     * theme.t('NOT_EXIST_KEY'); // 未知问题 【NOT_EXIST_KEY】
+     * theme.t('NOT_EXIST_KEY', { defaultvalue: '自定义兜底' }); // 自定义兜底
+     * ```
+     */
+    t(scope: string | number, variables?: TranslateVariables): string;
+    /**
+     * 语言包缺 key 时的兜底文案（`customizeMissing` 的实现）
+     *
+     * 注意底层是把本方法的返回值「原样返回」、不再做插值，所以这里借
+     * `i18n.t(UNKOWN_ISSUE)` 完成插值。而这一次取值本身也可能缺失
+     * （如 `language` 传了不存在的语言，当前语言包整体不存在），
+     * 那会再次回调到这里造成无限递归，因此用重入标记兜住，退化为直接返回原始 scope。
+     *
+     * 注：`options.locales` 与内置语言包是深合并，无法移除内置的 UNKOWN_ISSUE，
+     * 因此正常配置下不会走到退化分支。
+     * @param scope 缺失的多语言 key
+     * @param variables 原始插值变量
+     */
+    private _missingText;
     /**
      * 销毁包括事件、控件 ...
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezuikit/player-theme",
-  "version": "3.1.6-beta.1",
+  "version": "3.1.6",
   "description": "player theme",
   "title": "theme",
   "main": "dist/index.cjs",
@@ -34,15 +34,15 @@
   "author": "Ezviz-OpenBiz",
   "license": "MIT",
   "dependencies": {
-    "@ezuikit/utils-i18n": "^2.0.1",
-    "@ezuikit/utils-logger": "^2.1.0",
-    "@ezuikit/utils-tools": "^2.0.7",
     "@ezuikit/control-date-picker": "2.1.2-beta.1",
-    "@ezuikit/control-time-line": "2.1.0",
     "@ezuikit/control-ptz": "1.0.0",
     "@ezuikit/control-rec-list-modal": "0.0.2",
     "@ezuikit/control-segment-progress": "0.0.1",
+    "@ezuikit/control-time-line": "2.1.0",
     "@ezuikit/control-zoom": "1.0.0-beta.4",
+    "@ezuikit/utils-i18n": "^2.0.1",
+    "@ezuikit/utils-logger": "^2.1.0",
+    "@ezuikit/utils-tools": "^2.0.7",
     "@juggle/resize-observer": "^3.4.0",
     "@skax/delegate": "4.0.2",
     "@skax/picker": "1.1.8",