@ray-js/ray-ipc-player 2.1.1-beta.1 → 2.1.1-beta.3

package/lib/components/ErrorOverlay.d.ts

@@ -22,7 +22,8 @@ interface ErrorOverlayProps {
     hideFeedBackButton: boolean;
     isShare: boolean;
     limitFlow: boolean;
-    autoPlay: boolean;
+    /** 是否开启预览拉流，与 Player 内 previewOn 一致（previewEnabled ?? true） */
+    previewOn: boolean;
 }
 declare const ErrorOverlay: React.FC<ErrorOverlayProps>;
 export default ErrorOverlay;

package/lib/components/ErrorOverlay.js

@@ -31,7 +31,7 @@ const ErrorOverlay = _ref => {
     hideFeedBackButton,
     isShare,
     limitFlow,
-    autoPlay
+    previewOn
   } = _ref;
   /**
    * 获取错误展示内容
@@ -54,8 +54,8 @@ const ErrorOverlay = _ref => {
       return Strings.getLang('ipc_player_traffic_load_online_zero_tip');
     }
 
-    // 未自动播放
-    if (!autoPlay) {
+    // 未开启预览拉流（休眠态提示）
+    if (!previewOn) {
       return Strings.getLang('ipc_player_sleep_tip');
     }
     if (!isLowPowerDevice && onlineStatus && privateState) {
@@ -83,7 +83,7 @@ const ErrorOverlay = _ref => {
       return "".concat(Strings.getLang("ipc_player_error_common"), "(").concat(videoErrCode, ")");
     }
     return playStateErrorMsg;
-  }, [phoneNetworkConnect, onlineStatus, privateState, isLowPowerDevice, lowPowerDeviceOnlineState, lowPrivateOutTimeFlag, device4GIsFreeze, deviceFreezeReason, limitFlow, autoPlay, videoErrCode, playStateErrorMsg]);
+  }, [phoneNetworkConnect, onlineStatus, privateState, isLowPowerDevice, lowPowerDeviceOnlineState, lowPrivateOutTimeFlag, device4GIsFreeze, deviceFreezeReason, limitFlow, previewOn, videoErrCode, playStateErrorMsg]);
 
   /**
    * 根据自定义类型获取错误码展示内容
@@ -142,7 +142,7 @@ const ErrorOverlay = _ref => {
         if (limitFlow) {
           return Strings.getLang('ipc_player_recharge_flow_btn');
         }
-        if (!autoPlay) {
+        if (!previewOn) {
           return Strings.getLang('ipc_player_open_sleep_mode');
         }
         if (privateState) {
@@ -194,7 +194,7 @@ const ErrorOverlay = _ref => {
       default:
         return false;
     }
-  }, [hideSuggestedText, privateState, limitFlow, phoneNetworkConnect, isLowPowerDevice, onlineStatus, lowPowerDeviceOnlineState, isShare, device4GIsFreeze, deviceFreezeReason, hideHelpButton, hideFeedBackButton]);
+  }, [hideSuggestedText, privateState, limitFlow, phoneNetworkConnect, isLowPowerDevice, onlineStatus, lowPowerDeviceOnlineState, isShare, device4GIsFreeze, deviceFreezeReason, hideHelpButton, hideFeedBackButton, previewOn]);
 
   /**
    * 跳转4G流量充值页面
@@ -248,11 +248,11 @@ const ErrorOverlay = _ref => {
     if (limitFlow && onlineStatus) {
       return 'err-icon-flow-limit';
     }
-    if (!autoPlay) {
+    if (!previewOn) {
       return 'err-icon-sleep';
     }
     return 'err-icon';
-  }, [autoPlay, limitFlow, onlineStatus]);
+  }, [previewOn, limitFlow, onlineStatus]);
   if (!isError) return null;
   return /*#__PURE__*/React.createElement(CoverView, {
     style: {

package/lib/hooks/usePlayerProps.js

@@ -43,7 +43,8 @@ export const usePlayerProps = props => {
     hideHelpButton = false,
     hideFeedBackButton = false,
     playerRoute = '',
-    defaultAutoPlay = true,
+    previewEnabled,
+    onPreviewEnabledChange,
     limitFlow = false,
     autoWakeUp = false
   } = props;
@@ -84,7 +85,8 @@ export const usePlayerProps = props => {
     hideHelpButton,
     hideFeedBackButton,
     playerRoute,
-    defaultAutoPlay,
+    previewEnabled,
+    onPreviewEnabledChange,
     limitFlow,
     autoWakeUp,
     // 样式相关

package/lib/index.js

@@ -54,7 +54,8 @@ const Player = props => {
     hideHelpButton,
     hideFeedBackButton,
     playerRoute,
-    defaultAutoPlay,
+    previewEnabled,
+    onPreviewEnabledChange,
     limitFlow,
     autoWakeUp,
     borderRadius,
@@ -95,15 +96,16 @@ const Player = props => {
   const privateLowPowerDeviceTimeOutRef = useRef(null);
   const privateWakeOutTimeRef = useRef(null);
   const privateDeviceWakeNeedPublishTimeRef = useRef(null);
-  // 内部维护首次组件渲染时，自动播放状态，一旦调用重试，触发拉流后，将其状态设为true
-  const [autoPlay, setAutoPlay] = useState(defaultAutoPlay);
-
-  // connectChangeRef
+  /** 传入 previewEnabled 为受控；未传时 previewOn 为 true（自动拉流） */
+  const isPreviewControlled = previewEnabled !== undefined;
+  const previewOn = previewEnabled !== null && previewEnabled !== void 0 ? previewEnabled : true;
   useRef(null);
   const firstPreviewTimeRef = useRef(false);
 
   // 标记是否进入内存缓存/后台（onPause、onHide 设为 true，onShow 还原为 false），拉流时若为 true 则拦截
   const isInBackgroundRef = useRef(false);
+  /** 网络/在线等早于 onShow 触发拉流时 isInBackgroundRef 仍为 true，记一次待回到前台后补拉 */
+  const pendingForegroundPullRef = useRef(false);
 
   // 自定义计时老低功耗方案设备在线状态, 用于短暂时间报上下线的UI展示兼容 待实现
   const [lowPowerDeviceOnlineState, setLowPowerDeviceOnlineState] = useState(onlineStatus);
@@ -172,8 +174,104 @@ 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');
+      pendingForegroundPullRef.current = true;
+      return;
+    }
+    pendingForegroundPullRef.current = false;
+    if (isPreviewControlled) {
+      onPreviewEnabledChange === null || onPreviewEnabledChange === void 0 || onPreviewEnabledChange(true);
+      if (previewEnabled) {
+        runPullStream();
+      }
+      return;
+    }
+    runPullStream();
+  });
+
+  /** 回到前台后补拉：解决 onNetworkStatusChange 等早于 onShow 触发 retry 被拦的问题 */
+  const flushPendingForegroundPull = useMemoizedFn(() => {
+    if (!pendingForegroundPullRef.current) {
+      return;
+    }
+    if (!previewOn) {
+      pendingForegroundPullRef.current = false;
+      ipcTTTOperatorLog('VID: flush_pending_cleared_preview_off');
+      return;
+    }
+    if (!phoneNetworkConnect || !playState.initLy || !ipcCtx.current || !onlineStatus || privateState || limitFlow || !previewOn) {
+      ipcTTTOperatorLog('VID: flush_pending_skip_not_ready');
+      return;
+    }
+    pendingForegroundPullRef.current = false;
+    ipcTTTOperatorLog('VID: flush_pending_foreground_pull');
+    if (isPreviewControlled) {
+      runPullStream();
+    } else {
+      retry();
+    }
+  });
+
+  /**
+   * 命令式开关：受控走 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 () => {
+    const wasBackground = isInBackgroundRef.current;
     isInBackgroundRef.current = false;
+    if (wasBackground && !ignoreHideStopPreview) {
+      setVideoErrCode('');
+      if (previewOn) {
+        setPlayState(d => {
+          d.loadingState = true;
+          d.errorState = false;
+          d.errorMsg = '';
+        });
+      }
+    }
     getNetworkType({
       success: res => {
         console.log('网络类型', res);
@@ -189,10 +287,11 @@ const Player = props => {
       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();
     }
+    flushPendingForegroundPull();
   }));
   usePageEvent('onResize', sizeData => {
     const {
@@ -209,23 +308,24 @@ const Player = props => {
     }
   });
 
-  // 针对limitFlow
+  // 针对limitFlow / 未拉流：休眠态 UI
   useEffect(() => {
-    if (limitFlow || !autoPlay) {
-      setPlayState(d => {
-        return _objectSpread(_objectSpread({}, d), {}, {
-          loadingState: false,
-          errorState: true,
-          errorMessage: ''
-        });
+    if (!(limitFlow || !previewOn)) {
+      return;
+    }
+    setPlayState(d => {
+      return _objectSpread(_objectSpread({}, d), {}, {
+        loadingState: false,
+        errorState: true,
+        errorMessage: ''
       });
-      ipcTTTOperatorLog("limitFlow ~~~~ ".concat(limitFlow, " autoPlay ~~~ ").concat(autoPlay));
-      if (playState.initLy && ipcCtx.current) {
-        stopPreview();
-        disconnect();
-      }
+    });
+    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],
@@ -484,7 +584,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 = '设备处于休眠中';
@@ -496,50 +596,24 @@ const Player = props => {
         });
       } else if (playState.initLy && !privateState) {
         ipcTTTOperatorLog("VID: privateState_status_change: ".concat(privateState));
-        retry();
+        // 网络/在线等回调可能早于页面 onShow，此时 isInBackgroundRef 仍为 true，避免 retry 被误拦；等 onShow 再拉流
+        if (isInBackgroundRef.current) {
+          ipcTTTOperatorLog('VID: skip_pull_in_status_effect_while_background');
+          pendingForegroundPullRef.current = true;
+          return;
+        }
+        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]);
 
   // 视图层准备就绪，开始建立连接
 
@@ -717,7 +791,7 @@ const Player = props => {
     hideFeedBackButton: hideFeedBackButton,
     isShare: isShare,
     limitFlow: limitFlow,
-    autoPlay: autoPlay
+    previewOn: 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,11 +221,17 @@ 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 播放器是否限流

package/package.json

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