alpha-video-player-js 1.1.0 → 1.2.0

package/README.md

@@ -27,6 +27,32 @@ import AlphaVideoPlayerJs from 'alpha-video-player-js'
 const player = new AlphaVideoPlayerJs(config)
 ```
 
+### TypeScript 类型
+
+主包与框架子路径会导出下列类型，便于标注 `ref`、`getPlayer()` 返回值等。
+
+**从 v1.2.0 起**：命令式 ref 类型统一为 **`IAlphaVideoPlayerRef`**；React 组件 props 为 **`IAlphaVideoPlayerProps`**（原 `AlphaVideoPlayerExpose` / 无 `I` 前缀的 `AlphaVideoPlayerRef`、`AlphaVideoPlayerProps` 已更名，升级时请全局替换）。
+
+| 包路径 | 导出类型 | 说明 |
+|--------|----------|------|
+| `alpha-video-player-js` | `IAlphaVideoPlayer` | 核心类实例（`new` 后的类型） |
+| | `IConfig`、`IOptionalConfig` | 构造 / `play()` 可选参数 |
+| | `IOrientation`、`ISide` | 拼合方向与 RGB 区域位置 |
+| `alpha-video-player-js/vue3`、`.../vue2` | `IAlphaVideoPlayer`、`IAlphaVideoPlayerRef` | 核心实例类型与组件 ref；**若同时用到二者，请从同一子路径导入**，避免与主包各有一份 `.d.ts` 时类型不兼容 |
+| `alpha-video-player-js/react` | `IAlphaVideoPlayerProps`、`IAlphaVideoPlayerRef` | 组件 props 与 ref |
+
+```ts
+import AlphaVideoPlayer from 'alpha-video-player-js/vue3'
+import type { IAlphaVideoPlayer, IAlphaVideoPlayerRef } from 'alpha-video-player-js/vue3'
+
+const playerRef = ref<IAlphaVideoPlayerRef | null>(null)
+
+let core: IAlphaVideoPlayer | null = null
+const onCanPlay = () => {
+  core = playerRef.value?.getPlayer() ?? null
+}
+```
+
 ### 实例参数
 
 | 参数          | 含义                               | 默认值    | 是否必传 |
@@ -139,8 +165,9 @@ import AlphaVideoPlayer from 'alpha-video-player-js/vue3'
 <script setup lang="ts">
 import { ref } from 'vue'
 import AlphaVideoPlayer from 'alpha-video-player-js/vue3'
+import type { IAlphaVideoPlayerRef } from 'alpha-video-player-js/vue3'
 
-const playerRef = ref()
+const playerRef = ref<IAlphaVideoPlayerRef | null>(null)
 const playbackRate = ref(1)
 
 const onReady = () => {
@@ -194,10 +221,10 @@ export default {
 ```tsx
 import { useRef } from 'react'
 import AlphaVideoPlayer from 'alpha-video-player-js/react'
-import type { AlphaVideoPlayerRef } from 'alpha-video-player-js/react'
+import type { IAlphaVideoPlayerRef } from 'alpha-video-player-js/react'
 
 function App() {
-  const playerRef = useRef<AlphaVideoPlayerRef>(null)
+  const playerRef = useRef<IAlphaVideoPlayerRef>(null)
 
   return (
     <AlphaVideoPlayer

package/dist/alpha-video-player-js.d.ts

@@ -55,5 +55,7 @@ declare class Render {
     setLoop(loop: boolean): void;
     setPlaybackRate(playbackRate: number): void;
 }
+/** 核心类实例类型（`new Render(...)` 的实例），便于业务侧标注 ref / getPlayer() 等 */
+type IAlphaVideoPlayer = InstanceType<typeof Render>;
 
-export { type IConfig, Render as default };
+export { type IAlphaVideoPlayer, type IConfig, type IOptionalConfig, type IOrientation, type ISide, Render as default };

package/dist/react.d.ts

@@ -57,8 +57,26 @@ declare class Render {
     setLoop(loop: boolean): void;
     setPlaybackRate(playbackRate: number): void;
 }
+/** 核心类实例类型（`new Render(...)` 的实例），便于业务侧标注 ref / getPlayer() 等 */
+type IAlphaVideoPlayer = InstanceType<typeof Render>;
 
-interface AlphaVideoPlayerProps {
+/**
+ * Vue 2 / Vue 3 的 template ref、React 的 `useRef` 所指向的命令式 API 形状（与 `expose` / `useImperativeHandle` 一致）。
+ */
+type IAlphaVideoPlayerRef = {
+    play: () => Promise<void> | undefined;
+    pause: () => void;
+    destroy: () => void;
+    reset: () => void;
+    setSrc: (src: string) => void;
+    setCurrentTime: (time: number) => void;
+    setMute: (muted: boolean) => void;
+    setLoop: (loop: boolean) => void;
+    setPlaybackRate: (rate: number) => void;
+    getPlayer: () => IAlphaVideoPlayer | null;
+};
+
+interface IAlphaVideoPlayerProps {
     src?: string;
     width?: number;
     height?: number;
@@ -88,18 +106,6 @@ interface AlphaVideoPlayerProps {
     className?: string;
     style?: React.CSSProperties;
 }
-interface AlphaVideoPlayerRef {
-    play: () => Promise<void> | undefined;
-    pause: () => void;
-    destroy: () => void;
-    reset: () => void;
-    setSrc: (src: string) => void;
-    setCurrentTime: (time: number) => void;
-    setMute: (muted: boolean) => void;
-    setLoop: (loop: boolean) => void;
-    setPlaybackRate: (rate: number) => void;
-    getPlayer: () => Render | null;
-}
-declare const AlphaVideoPlayer: React.ForwardRefExoticComponent<AlphaVideoPlayerProps & React.RefAttributes<AlphaVideoPlayerRef>>;
+declare const AlphaVideoPlayer: React.ForwardRefExoticComponent<IAlphaVideoPlayerProps & React.RefAttributes<IAlphaVideoPlayerRef>>;
 
-export { type AlphaVideoPlayerProps, type AlphaVideoPlayerRef, AlphaVideoPlayer as default };
+export { type IAlphaVideoPlayerProps, type IAlphaVideoPlayerRef, AlphaVideoPlayer as default };

package/dist/vue2.d.ts

@@ -1,3 +1,79 @@
 declare const AlphaVideoPlayer: any;
 
-export { AlphaVideoPlayer as default };
+interface IConfig {
+    container: HTMLElement;
+    width?: number;
+    height?: number;
+    src?: string;
+    /** 跨域视频资源；默认 anonymous */
+    crossOrigin?: 'anonymous' | 'use-credentials';
+    muted?: boolean;
+    loop?: boolean;
+    playbackRate?: number;
+    fps?: number;
+    orientation?: IOrientation;
+    side?: ISide;
+    videoFrame?: boolean;
+    debug?: boolean;
+    autoShow?: boolean;
+    autoClear?: boolean;
+    autoDestroy?: boolean;
+    /**
+     * 视频加载后按比例自适应 canvas 尺寸（默认 'contain'）。
+     * - 'contain'：自动判断，确保视频完整填入 canvas 盒子（类似 object-fit: contain）
+     * - 'width'：固定宽度，按视频比例自动调整高度
+     * - 'height'：固定高度，按视频比例自动调整宽度
+     * - false：不自适应，canvas 保持初始尺寸
+     */
+    autoResize?: 'width' | 'height' | 'contain' | false;
+    onInitSuccess?: () => void;
+    onInitError?: (e: ErrorEvent) => void;
+    onLoad?: () => void;
+    onCanPlay?: () => void;
+    onPlay?: () => void;
+    onLoop?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    /** 媒体 error 事件或 play() 拒绝等，原样传入 */
+    onError?: (e: unknown) => void;
+    onDestroy?: () => void;
+}
+type IOptionalConfig = Omit<IConfig, 'container' | 'src'> & Partial<Pick<IConfig, 'container' | 'src'>>;
+type IOrientation = 'landscape' | 'portrait';
+type ISide = 'front' | 'back';
+
+declare class Render {
+    private render;
+    constructor(config: IConfig);
+    get playing(): boolean;
+    get loop(): boolean;
+    play(config?: IOptionalConfig): Promise<void>;
+    pause(): void;
+    destroy(): void;
+    reset(): void;
+    setSrc(src: string): void;
+    setCurrentTime(time: number): void;
+    setMute(muted: boolean): void;
+    setLoop(loop: boolean): void;
+    setPlaybackRate(playbackRate: number): void;
+}
+/** 核心类实例类型（`new Render(...)` 的实例），便于业务侧标注 ref / getPlayer() 等 */
+type IAlphaVideoPlayer = InstanceType<typeof Render>;
+
+/**
+ * Vue 2 / Vue 3 的 template ref、React 的 `useRef` 所指向的命令式 API 形状（与 `expose` / `useImperativeHandle` 一致）。
+ */
+type IAlphaVideoPlayerRef = {
+    play: () => Promise<void> | undefined;
+    pause: () => void;
+    destroy: () => void;
+    reset: () => void;
+    setSrc: (src: string) => void;
+    setCurrentTime: (time: number) => void;
+    setMute: (muted: boolean) => void;
+    setLoop: (loop: boolean) => void;
+    setPlaybackRate: (rate: number) => void;
+    getPlayer: () => IAlphaVideoPlayer | null;
+};
+
+export { type IAlphaVideoPlayer, type IAlphaVideoPlayerRef, AlphaVideoPlayer as default };

package/dist/vue3.d.ts

@@ -1,6 +1,45 @@
 import * as vue from 'vue';
 import { PropType } from 'vue';
 
+interface IConfig {
+    container: HTMLElement;
+    width?: number;
+    height?: number;
+    src?: string;
+    /** 跨域视频资源；默认 anonymous */
+    crossOrigin?: 'anonymous' | 'use-credentials';
+    muted?: boolean;
+    loop?: boolean;
+    playbackRate?: number;
+    fps?: number;
+    orientation?: IOrientation;
+    side?: ISide;
+    videoFrame?: boolean;
+    debug?: boolean;
+    autoShow?: boolean;
+    autoClear?: boolean;
+    autoDestroy?: boolean;
+    /**
+     * 视频加载后按比例自适应 canvas 尺寸（默认 'contain'）。
+     * - 'contain'：自动判断，确保视频完整填入 canvas 盒子（类似 object-fit: contain）
+     * - 'width'：固定宽度，按视频比例自动调整高度
+     * - 'height'：固定高度，按视频比例自动调整宽度
+     * - false：不自适应，canvas 保持初始尺寸
+     */
+    autoResize?: 'width' | 'height' | 'contain' | false;
+    onInitSuccess?: () => void;
+    onInitError?: (e: ErrorEvent) => void;
+    onLoad?: () => void;
+    onCanPlay?: () => void;
+    onPlay?: () => void;
+    onLoop?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    /** 媒体 error 事件或 play() 拒绝等，原样传入 */
+    onError?: (e: unknown) => void;
+    onDestroy?: () => void;
+}
+type IOptionalConfig = Omit<IConfig, 'container' | 'src'> & Partial<Pick<IConfig, 'container' | 'src'>>;
 type IOrientation = 'landscape' | 'portrait';
 type ISide = 'front' | 'back';
 
@@ -166,4 +205,38 @@ declare const _default: vue.DefineComponent<vue.ExtractPropTypes<{
     autoResize: false | "width" | "height" | "contain";
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
-export { _default as default };
+declare class Render {
+    private render;
+    constructor(config: IConfig);
+    get playing(): boolean;
+    get loop(): boolean;
+    play(config?: IOptionalConfig): Promise<void>;
+    pause(): void;
+    destroy(): void;
+    reset(): void;
+    setSrc(src: string): void;
+    setCurrentTime(time: number): void;
+    setMute(muted: boolean): void;
+    setLoop(loop: boolean): void;
+    setPlaybackRate(playbackRate: number): void;
+}
+/** 核心类实例类型（`new Render(...)` 的实例），便于业务侧标注 ref / getPlayer() 等 */
+type IAlphaVideoPlayer = InstanceType<typeof Render>;
+
+/**
+ * Vue 2 / Vue 3 的 template ref、React 的 `useRef` 所指向的命令式 API 形状（与 `expose` / `useImperativeHandle` 一致）。
+ */
+type IAlphaVideoPlayerRef = {
+    play: () => Promise<void> | undefined;
+    pause: () => void;
+    destroy: () => void;
+    reset: () => void;
+    setSrc: (src: string) => void;
+    setCurrentTime: (time: number) => void;
+    setMute: (muted: boolean) => void;
+    setLoop: (loop: boolean) => void;
+    setPlaybackRate: (rate: number) => void;
+    getPlayer: () => IAlphaVideoPlayer | null;
+};
+
+export { type IAlphaVideoPlayer, type IAlphaVideoPlayerRef, _default as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alpha-video-player-js",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Web 视频动画特效播放 sdk",
   "main": "dist/alpha-video-player-js.js",
   "types": "dist/alpha-video-player-js.d.ts",