@ray-js/ray-ipc-player 2.1.0 → 2.1.1-beta.2

package/lib/hooks/usePlayerProps.js

@@ -43,8 +43,10 @@ export const usePlayerProps = props => {
     hideHelpButton = false,
     hideFeedBackButton = false,
     playerRoute = '',
-    defaultAutoPlay = true,
-    limitFlow = false
+    previewEnabled,
+    onPreviewEnabledChange,
+    limitFlow = false,
+    autoWakeUp = false
   } = props;
 
   // 解构 playerStyle
@@ -83,8 +85,10 @@ export const usePlayerProps = props => {
     hideHelpButton,
     hideFeedBackButton,
     playerRoute,
-    defaultAutoPlay,
+    previewEnabled,
+    onPreviewEnabledChange,
     limitFlow,
+    autoWakeUp,
     // 样式相关
     borderRadius,
     bgColor,

package/lib/index.js

@@ -54,8 +54,10 @@ const Player = props => {
     hideHelpButton,
     hideFeedBackButton,
     playerRoute,
-    defaultAutoPlay,
+    previewEnabled,
+    onPreviewEnabledChange,
     limitFlow,
+    autoWakeUp,
     borderRadius,
     bgColor,
     borderStyle,
@@ -94,8 +96,9 @@ const Player = props => {
   const privateLowPowerDeviceTimeOutRef = useRef(null);
   const privateWakeOutTimeRef = useRef(null);
   const privateDeviceWakeNeedPublishTimeRef = useRef(null);
-  // 内部维护首次组件渲染时，自动播放状态，一旦调用重试，触发拉流后，将其状态设为true
-  const [autoPlay, setAutoPlay] = useState(defaultAutoPlay);
+  /** 传入 previewEnabled 为受控；未传时 previewOn 为 true（自动拉流） */
+  const isPreviewControlled = previewEnabled !== undefined;
+  const previewOn = previewEnabled !== null && previewEnabled !== void 0 ? previewEnabled : true;
 
   // connectChangeRef
   useRef(null);
@@ -103,6 +106,8 @@ const Player = props => {
 
   // 标记是否进入内存缓存/后台（onPause、onHide 设为 true，onShow 还原为 false），拉流时若为 true 则拦截
   const isInBackgroundRef = useRef(false);
+  /** 受控 previewEnabled：因 onHide/onPause 已通知父级 false，回到前台时需恢复 true 并拉流 */
+  const previewPausedByLifecycleRef = useRef(false);
 
   // 自定义计时老低功耗方案设备在线状态, 用于短暂时间报上下线的UI展示兼容 待实现
   const [lowPowerDeviceOnlineState, setLowPowerDeviceOnlineState] = useState(onlineStatus);
@@ -171,6 +176,66 @@ const Player = props => {
       });
     }
   });
+
+  /**
+   * 实际发起拉流（隐私唤醒 + P2P/预览），与是否受控无关
+   */
+  const runPullStream = useMemoizedFn(() => {
+    phoneNetworkConnect && onlineStatus && privateState && (!isLowPowerDevice || isVirtualDevice) && handleReWakeCamera();
+    phoneNetworkConnect && onlineStatus && privateState && isLowPowerDevice && !isVirtualDevice && handleReWakeCameraLowPowerDevice();
+    phoneNetworkConnect && onlineStatus && !privateState && _retry();
+  });
+  const retry = useMemoizedFn(() => {
+    console.log('重新拉流启动');
+    // 任何重试拉流时, 将播放器状态还原为loading状态
+    setVideoErrCode('');
+    setPlayState(d => {
+      d.loadingState = true;
+      d.errorState = false;
+      d.errorMsg = '';
+    });
+    //  排除默认值为"",不等于播放器路由时, 不进行重试拉流
+
+    if (playerRoute !== '' && playerRoute !== getPlayerRoute()) {
+      console.log('不在播放器路由内, 不进行拉流');
+      return;
+    }
+    if (isInBackgroundRef.current) {
+      console.log('处于后台/内存缓存，拦截拉流');
+      ipcTTTOperatorLog('VID: isInBackground, block retry');
+      return;
+    }
+    if (isPreviewControlled) {
+      onPreviewEnabledChange === null || onPreviewEnabledChange === void 0 || onPreviewEnabledChange(true);
+      if (previewEnabled) {
+        runPullStream();
+      }
+      return;
+    }
+    runPullStream();
+  });
+
+  /**
+   * 命令式开关：受控走 onPreviewEnabledChange；未传 previewEnabled 时 previewOn 恒为 true，仅支持开启拉流（retry）
+   */
+  const setPreviewEnabledCommand = useMemoizedFn(enabled => {
+    if (isPreviewControlled) {
+      onPreviewEnabledChange === null || onPreviewEnabledChange === void 0 || onPreviewEnabledChange(enabled);
+      return;
+    }
+    if (enabled) {
+      retry();
+    }
+  });
+
+  // 创建ipc实例
+  const createIpcCtx = () => {
+    onCtx && onCtx({
+      ctx: ipcCtx.current,
+      retry,
+      setPreviewEnabled: setPreviewEnabledCommand
+    });
+  };
   usePageEvent('onShow', useMemoizedFn(async () => {
     isInBackgroundRef.current = false;
     getNetworkType({
@@ -187,8 +252,18 @@ const Player = props => {
       onChangeIgnoreHideStopPreview && onChangeIgnoreHideStopPreview(false);
       return;
     }
+    // 受控 preview：后台/隐藏时已把父级置为 false，前台先恢复意图再拉流（不依赖同一帧 previewOn）
+    if (previewPausedByLifecycleRef.current && isPreviewControlled) {
+      previewPausedByLifecycleRef.current = false;
+      onPreviewEnabledChange === null || onPreviewEnabledChange === void 0 || onPreviewEnabledChange(true);
+      if (phoneNetworkConnect && playState.initLy && ipcCtx.current && onlineStatus && !privateState && !limitFlow) {
+        ipcTTTOperatorLog('VID: onShow_resume_after_hide_pause');
+        runPullStream();
+      }
+      return;
+    }
     // 视图准备就绪
-    if (phoneNetworkConnect && playState.initLy && ipcCtx.current && onlineStatus && !privateState && !limitFlow && autoPlay) {
+    if (phoneNetworkConnect && playState.initLy && ipcCtx.current && onlineStatus && !privateState && !limitFlow && previewOn) {
       ipcTTTOperatorLog('VID: onShow_event_to_retry');
       retry();
     }
@@ -210,7 +285,7 @@ const Player = props => {
 
   // 针对limitFlow
   useEffect(() => {
-    if (limitFlow || !autoPlay) {
+    if (limitFlow || !previewOn) {
       setPlayState(d => {
         return _objectSpread(_objectSpread({}, d), {}, {
           loadingState: false,
@@ -218,13 +293,13 @@ const Player = props => {
           errorMessage: ''
         });
       });
-      ipcTTTOperatorLog("limitFlow ~~~~ ".concat(limitFlow, " autoPlay ~~~ ").concat(autoPlay));
+      ipcTTTOperatorLog("limitFlow ~~~~ ".concat(limitFlow, " previewOn ~~~ ").concat(previewOn));
       if (playState.initLy && ipcCtx.current) {
         stopPreview();
         disconnect();
       }
     }
-  }, [limitFlow, autoPlay, playState.initLy, ipcCtx.current]);
+  }, [limitFlow, previewOn, playState.initLy, ipcCtx.current]);
   useEffect(() => {
     registerDeviceListListener({
       deviceIdList: [devId],
@@ -260,6 +335,10 @@ const Player = props => {
     if (ignoreHideStopPreview) {
       return;
     }
+    if (isPreviewControlled && previewOn) {
+      previewPausedByLifecycleRef.current = true;
+      onPreviewEnabledChange === null || onPreviewEnabledChange === void 0 || onPreviewEnabledChange(false);
+    }
     setPlayState(d => {
       d.loadingState = true;
     });
@@ -271,6 +350,10 @@ const Player = props => {
     isInBackgroundRef.current = true;
     console.log('onPause, 重新拉流');
     ipcTTTOperatorLog('VID: onPause stopPreview');
+    if (!ignoreHideStopPreview && isPreviewControlled && previewOn) {
+      previewPausedByLifecycleRef.current = true;
+      onPreviewEnabledChange === null || onPreviewEnabledChange === void 0 || onPreviewEnabledChange(false);
+    }
     stopPreview();
     disconnect();
   }));
@@ -375,6 +458,20 @@ const Player = props => {
     };
   }, [stopPreview, disconnect]);
 
+  /**
+   * autoWakeUp 模式：视图就绪后立即开始唤醒设备，但不拉流
+   */
+  useEffect(() => {
+    if (!(autoWakeUp && isLowPowerDevice && playState.initLy && !awakeStatus)) {
+      return undefined;
+    }
+    setEnableWakeUpInterval(true);
+    const timeout = setTimeout(() => {
+      setEnableWakeUpInterval(false);
+    }, 30000);
+    return () => clearTimeout(timeout);
+  }, [autoWakeUp, isLowPowerDevice, playState.initLy, awakeStatus]);
+
   /**
    *  唤醒设备TTT能力
    */
@@ -384,6 +481,15 @@ const Player = props => {
     intervalTime: 300
   });
 
+  /**
+   * autoWakeUp 模式下，设备进入唤醒状态后停止继续下发唤醒指令
+   */
+  useEffect(() => {
+    if (autoWakeUp && isLowPowerDevice && awakeStatus) {
+      setEnableWakeUpInterval(false);
+    }
+  }, [awakeStatus, isLowPowerDevice, autoWakeUp]);
+
   /**
    * 监听设备休眠状态变化
    * 当检测到设备上报休眠后，触发重新连接
@@ -460,7 +566,7 @@ const Player = props => {
           d.errorState = true;
           d.errorMsg = limitFlow ? Strings.getLang('ipc_player_traffic_load_offline_limit_tip') : Strings.getLang('ipc_player_device_offline');
         });
-      } else if (!autoPlay) {
+      } else if (!previewOn) {
         setPlayState(d => {
           d.errorState = true;
           d.errorMsg = '设备处于休眠中';
@@ -472,50 +578,18 @@ const Player = props => {
         });
       } else if (playState.initLy && !privateState) {
         ipcTTTOperatorLog("VID: privateState_status_change: ".concat(privateState));
-        retry();
+        if (isPreviewControlled) {
+          runPullStream();
+        } else {
+          retry();
+        }
       } else if (playState.initLy && privateState) {
         stopPreview();
         // 如果隐私模式为true, 主动推一波流变化的状态码，适配ios不触发connectChange的情况
         onChangeStreamStatus && onChangeStreamStatus(-1001);
       }
     }
-  }, [phoneNetworkConnect, onlineStatus, playState.initLy, privateState, limitFlow, autoPlay]);
-  const retry = useMemoizedFn(() => {
-    console.log('重新拉流启动');
-    setAutoPlay(true);
-    // 任何重试拉流时, 将播放器状态还原为loading状态
-    setVideoErrCode('');
-    setPlayState(d => {
-      d.loadingState = true;
-      d.errorState = false;
-      d.errorMsg = '';
-    });
-    //  排除默认值为"",不等于播放器路由时, 不进行重试拉流
-
-    if (playerRoute !== '' && playerRoute !== getPlayerRoute()) {
-      console.log('不在播放器路由内, 不进行拉流');
-      return;
-    }
-    if (isInBackgroundRef.current) {
-      console.log('处于后台/内存缓存，拦截拉流');
-      ipcTTTOperatorLog('VID: isInBackground, block retry');
-      return;
-    }
-    phoneNetworkConnect && onlineStatus && privateState && (!isLowPowerDevice || isVirtualDevice) && handleReWakeCamera();
-
-    // 低功耗设备隐私模式需单独处理，先进行下发唤醒, 唤醒后再进行下发DP
-    phoneNetworkConnect && onlineStatus && privateState && isLowPowerDevice && !isVirtualDevice && handleReWakeCameraLowPowerDevice();
-    phoneNetworkConnect && onlineStatus && !privateState && _retry();
-    // }, [isLowPowerDevice, phoneNetworkConnect && playState.connectState, privateState, onlineStatus]);
-  });
-
-  // 创建ipc实例
-  const createIpcCtx = () => {
-    onCtx && onCtx({
-      ctx: ipcCtx.current,
-      retry
-    });
-  };
+  }, [phoneNetworkConnect, onlineStatus, playState.initLy, privateState, limitFlow, previewOn, isPreviewControlled, previewEnabled, runPullStream, retry]);
 
   // 视图层准备就绪，开始建立连接
 
@@ -693,7 +767,7 @@ const Player = props => {
     hideFeedBackButton: hideFeedBackButton,
     isShare: isShare,
     limitFlow: limitFlow,
-    autoPlay: autoPlay
+    autoPlay: previewOn
   }), /*#__PURE__*/React.createElement(FullScreenBackButton, {
     isVisible: screenType === 'landscape' && (playState.loadingState || playState.errorState),
     getClassName: getClassName,

package/lib/typings/index.d.ts

@@ -98,10 +98,14 @@ export type IProps = {
   onCameraNotifyWeakNetwork?: (data) => void;
   /**
    * @description.en onCtx
-   * @description.zh 获取ipcPlayer实例ctx以及重试方法retry
+   * @description.zh 获取 ipcPlayer 实例 ctx、retry，以及 setPreviewEnabled（与 previewEnabled 受控配合或独立命令式开关拉流）
    * @default (playerRef) => void
    */
-  onCtx?: (playerRef) => void;
+  onCtx?: (playerRef: {
+    ctx: any;
+    retry: () => void;
+    setPreviewEnabled: (enabled: boolean) => void;
+  }) => void;
   /**
    * @description.en onInitPreview
    * @description.zh 初始化预览成功通知
@@ -217,15 +221,27 @@ export type IProps = {
    */
   playerRoute?: string;
   /**
-   * @description.en Autoplay by default
-   * @description.zh 默认是否自动播放
-   * @default true
+   * @description.en Whether to pull preview. If omitted, treated as true (previewOn = previewEnabled ?? true). If passed, controlled mode (isPreviewControlled = true); pair with onPreviewEnabledChange for retry/lifecycle.
+   * @description.zh 是否拉流；未传等价 true；传入则为受控（与 onPreviewEnabledChange 配合）。
+   * @default undefined
+   */
+  previewEnabled?: boolean;
+  /**
+   * @description.en Required for controlled previewEnabled when user retries or lifecycle syncs preview state
+   * @description.zh 传入 previewEnabled 受控时建议配置：重试开流、hide/pause 与父级状态同步依赖此回调
+   * @default undefined
    */
-  defaultAutoPlay?: boolean;
+  onPreviewEnabledChange?: (enabled: boolean) => void;
   /**
    * @description.en Limit flow for the player
    * @description.zh 播放器是否限流
    * @default false
    */
   limitFlow?: boolean;
+  /**
+   * @description.en Auto wake up device on init (low power device only)
+   * @description.zh 初始化时是否自动唤醒设备（仅低功耗设备生效），需配合 defaultAutoPlay=false 使用实现"唤醒但不拉流"
+   * @default false
+   */
+  autoWakeUp?: boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/ray-ipc-player",
-  "version": "2.1.0",
+  "version": "2.1.1-beta.2",
   "description": "ray小程序播放器",
   "keywords": [
     "tuya-miniapp",