@ray-js/ipc-player-integration 0.0.35-beta.30 → 0.0.35-beta.31

package/lib/features/initPlayerWidgets/index.js

@@ -24,7 +24,7 @@ export async function initPlayerWidgets(ctx, options) {
     var _options$hideSmartIma;
     // @ts-ignore
     newDefaultBottomLeftContent[tryExperienceIndex].initProps = {
-      hideTryExperienceMenu: (_options$hideSmartIma = options.hideSmartImageQualityState) !== null && _options$hideSmartIma !== void 0 ? _options$hideSmartIma : true
+      hideSmartImageQualityState: (_options$hideSmartIma = options.hideSmartImageQualityState) !== null && _options$hideSmartIma !== void 0 ? _options$hideSmartIma : true
     };
   }
   if (resolutionIndex !== -1) {

package/lib/ui/bottomLeftContent.d.ts

@@ -10,6 +10,12 @@ type Props = {
      */
     reservedRight?: number | string;
     canOpenSettings?: boolean;
+    /**
+     * 横滑提示箭头的交互模式：
+     * - 'button': 白色小圆底 + 黑色箭头，溢出后常显、可点击滑动（不随拖动消失）
+     * - 'pulse' : 旧版渐隐渐显提示箭头，拖动一次后当前屏幕模式不再展示
+     */
+    scrollHintMode?: 'button' | 'pulse';
 };
-declare const BottomLeftContent: ({ ctx, children, reservedRight, canOpenSettings }: Props) => React.JSX.Element;
+declare const BottomLeftContent: ({ ctx, children, reservedRight, canOpenSettings, scrollHintMode, }: Props) => React.JSX.Element;
 export default BottomLeftContent;

package/lib/ui/bottomLeftContent.js

@@ -1,31 +1,27 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import "core-js/modules/esnext.iterator.constructor.js";
 import "core-js/modules/esnext.iterator.find.js";
-import React, { useMemo } from 'react';
-import { CoverView, View } from '@ray-js/ray';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { CoverView, ScrollView, View } from '@ray-js/ray';
 import clsx from 'clsx';
 import { useStore } from '../ctx/store';
 import { useComponentHideState } from './hooks';
 import { TrialBadge, useTrialBadge } from '../widgets/trialBadge';
-/**
- * 右侧透明渐变 mask，用于提示横向可滑动。
- * - 竖屏容器窄，48px 渐变区已足够明显
- * - 横屏容器约占 65% 宽度（≥ 500px），且单个按钮就有 ~72px，
- *   渐变区需大于一个按钮宽度才能让最右侧按钮"半隐半现"，
- *   暗示后面还有内容
- */
-const getFadeMask = screenType => {
-  const fadeWidth = screenType === 'vertical' ? 60 : 120;
-  return `linear-gradient(to right, #000 calc(100% - ${fadeWidth}px), transparent 100%)`;
-};
+import { pauseTimeToHideAllComponent, startTimeToHideAllComponent } from './constant';
+
+// 用唯一 className 在 createSelectorQuery 中区分多个实例，避免互相干扰
+let scrollClsSeq = 0;
 const BottomLeftContent = _ref => {
   let {
     ctx,
     children,
     reservedRight = 0,
-    canOpenSettings = true
+    canOpenSettings = true,
+    scrollHintMode = 'button'
   } = _ref;
   const {
     screenType,
+    playState,
     brandColor,
     bottomLeftContent
   } = useStore({
@@ -37,7 +33,7 @@ const BottomLeftContent = _ref => {
   const showSmartImageQuality = useMemo(() => {
     var _tryExp$initProps;
     const tryExp = bottomLeftContent === null || bottomLeftContent === void 0 ? void 0 : bottomLeftContent.find(item => item.id === 'TryExperience');
-    return !(tryExp !== null && tryExp !== void 0 && (_tryExp$initProps = tryExp.initProps) !== null && _tryExp$initProps !== void 0 && _tryExp$initProps.hideTryExperienceMenu);
+    return !(tryExp !== null && tryExp !== void 0 && (_tryExp$initProps = tryExp.initProps) !== null && _tryExp$initProps !== void 0 && _tryExp$initProps.hideSmartImageQualityState);
   }, [bottomLeftContent]);
   const trialRemainingSec = useMemo(() => {
     var _trialRemainingSec, _tryExp$initProps2;
@@ -65,14 +61,155 @@ const BottomLeftContent = _ref => {
     handleTrialSubscribe,
     handleCountdownEnd
   } = useTrialBadge(ctx.event, ctx.devId, trialRemainingSec);
+
+  // 横向滚动状态：内容溢出且未滑到对应边缘时，显示左 / 右箭头提示
+  const idRef = useRef(++scrollClsSeq);
+  const scrollCls = `ipc-bl-scroll-${idRef.current}`;
+  const contentCls = `ipc-bl-scroll-content-${idRef.current}`;
+  // 内容末尾哨兵节点：用它的真实横坐标反推子项总宽，避免内容容器被撑满导致测不出溢出
+  const endCls = `ipc-bl-scroll-end-${idRef.current}`;
+  const [scrollLeft, setScrollLeft] = useState(0);
+  const [clientWidth, setClientWidth] = useState(0);
+  const [contentWidth, setContentWidth] = useState(0);
+  // 点击箭头时的受控滚动目标；仅在程序化滚动期间为数值，结束后置回 undefined，
+  // 避免持续受控导致用户手动拖动被回弹
+  const [scrollTo, setScrollTo] = useState(undefined);
+  // 横竖屏切换后，强制 ScrollView 重新挂载并把滚动状态重置为初始值
+  const [scrollResetKey, setScrollResetKey] = useState(0);
+  // 用户在某种屏幕模式下拖动过一次之后，该模式不再展示箭头（竖屏 / 横屏各自独立记录）
+  const [dismissed, setDismissed] = useState({
+    vertical: false,
+    full: false
+  });
+
+  // 滑动期间暂停整体的自动隐藏，滑动停止后再恢复（无原生 scrollend，用防抖判定结束）
+  const scrollingRef = useRef(false);
+  const scrollEndTimerRef = useRef();
+  // 测量时需要叠加当前滚动量，用 ref 避免闭包拿到过期值
+  const scrollLeftRef = useRef(0);
+  useEffect(() => {
+    setScrollResetKey(k => k + 1);
+    setScrollLeft(0);
+    setScrollTo(undefined);
+  }, [screenType]);
+
+  // 程序化滚动目标只在动画期间短暂受控，之后释放为非受控，避免回弹影响手动拖动
+  useEffect(() => {
+    if (scrollTo === undefined) {
+      return undefined;
+    }
+    const t = setTimeout(() => setScrollTo(undefined), 600);
+    return () => clearTimeout(t);
+  }, [scrollTo]);
   const paddingLeftPx = screenType === 'vertical' ? 0 : 25;
+  // 滚动末端的安全距离：滑到最右时最后一个元素与右边缘留更宽松的间距（横屏更宽）
+  const paddingRightPx = screenType === 'vertical' ? 22 : 32;
+  const paddingBottomPx = screenType === 'vertical' ? 0 : 25;
   const showBadge = showSmartImageQuality && showTrialBadge && canOpenSettings && gRawData && !isLowPhone && buttonState === 1 && trialRemainingSec > 0;
+
+  // 测量滚动容器可视宽度与内部内容宽度。
+  // 首屏漏判溢出的根因：左下角子元素（画质菜单 / 试用角标等）是异步加载的，宽度会在
+  // 首次测量之后才“长大”，而固定几次延时跑完就不再测，导致 contentWidth 偏小、判不出溢出。
+  // 这里在一段时间窗内持续轮询（每 400ms 测一次，约 6s），每次都用最新读数更新；
+  // 值未变化时 React 会自动跳过重渲染，因此持续轮询不会带来额外开销，
+  // 同时能兜住异步内容撑开与 overlay 布局滞后导致的尺寸变化。
+  useEffect(() => {
+    let timer;
+    let attempts = 0;
+    const measure = () => {
+      const query = ty.createSelectorQuery();
+      query.select(`.${scrollCls}`).boundingClientRect();
+      query.select(`.${contentCls}`).boundingClientRect();
+      query.select(`.${endCls}`).boundingClientRect();
+      query.exec(res => {
+        const scrollRect = res === null || res === void 0 ? void 0 : res[0];
+        const contentRect = res === null || res === void 0 ? void 0 : res[1];
+        const endRect = res === null || res === void 0 ? void 0 : res[2];
+        const cw = (scrollRect === null || scrollRect === void 0 ? void 0 : scrollRect.width) || 0;
+        if (cw) {
+          setClientWidth(cw);
+        }
+
+        // 优先用末尾哨兵反推子项真实总宽：
+        //   哨兵视口 x = 滚动容器左 + 左padding + 子项总宽 - 当前 scrollLeft
+        //   => 子项总宽 = 哨兵.left - 滚动容器.left - 左padding + scrollLeft
+        // 这样即使内容容器被撑满到可视内盒宽，也能拿到真实内容宽；哨兵不可用时回退到容器宽。
+        let tw = 0;
+        if (scrollRect && endRect && typeof endRect.left === 'number') {
+          tw = endRect.left - scrollRect.left - paddingLeftPx + scrollLeftRef.current;
+        }
+        if (!(tw > 0)) {
+          tw = (contentRect === null || contentRect === void 0 ? void 0 : contentRect.width) || 0;
+        }
+        if (tw > 0) {
+          setContentWidth(tw);
+        }
+        attempts += 1;
+        // 最多轮询 15 次（约 6s）兜底，避免无限轮询
+        if (attempts >= 15) {
+          return;
+        }
+        timer = setTimeout(measure, 400);
+      });
+    };
+    timer = setTimeout(measure, 200);
+    return () => {
+      if (timer) clearTimeout(timer);
+    };
+  }, [screenType,
+  // reservedRight 决定 ScrollView 可视宽度（右下角内容异步加载后会从 0 变为实际宽度）
+  reservedRight,
+  // playState：视频就绪后 overlay 可能重新布局，需重新测量
+  playState, bottomLeftContent === null || bottomLeftContent === void 0 ? void 0 : bottomLeftContent.length, shouldHide, showBadge, scrollCls, contentCls, scrollResetKey]);
+  // 卸载时清理防抖定时器；若仍处于滑动中则恢复自动隐藏，避免遗留暂停态
+  useEffect(() => {
+    return () => {
+      if (scrollEndTimerRef.current) {
+        clearTimeout(scrollEndTimerRef.current);
+      }
+      if (scrollingRef.current) {
+        var _ctx$event3;
+        scrollingRef.current = false;
+        (_ctx$event3 = ctx.event) === null || _ctx$event3 === void 0 || _ctx$event3.emit(startTimeToHideAllComponent);
+      }
+    };
+  }, [ctx.event]);
+
+  // ScrollView 的实际可滚动宽度 = 左右 padding + 子元素总宽
+  const totalContentWidth = contentWidth > 0 ? paddingLeftPx + contentWidth + paddingRightPx : 0;
+  const isOverflow = totalContentWidth > clientWidth + 1;
+  const atEnd = !isOverflow || scrollLeft + clientWidth >= totalContentWidth - 2;
+  const isDismissed = dismissed[screenType];
+  const isButtonHint = scrollHintMode === 'button';
+  // button 模式：溢出且未到末端即常显（不受 dismissed 影响）；pulse 模式：保留拖动后消失的旧逻辑
+
+  // 右侧还有未滚到头的内容时，启用右边缘淡出，把没完全露出的元素渐隐隐藏（横竖屏都生效）
+
+  // 点击右箭头：直接滚动到最右端。
+  // 给一个足够大的目标值，交由 ScrollView 自身夹取到真实最右端，避免测量误差导致滚不到底。
+
   const coverHeight = screenType === 'vertical' ? shouldHide ? 49 : 48 : shouldHide ? 84 : 83;
   const containerHeight = screenType === 'vertical' ? 48 : 58;
 
   // reservedRight 兼容 number（px）与 string（任意 CSS 长度，例如 "35%"）
   const rightCss = typeof reservedRight === 'number' ? `${reservedRight}px` : reservedRight;
-  const fadeMask = getFadeMask(screenType);
+
+  // 与 bottomRightContent 对齐：bottomRight 的 icon 行是贴在 wrap 顶部（不居中）的，
+  // 这里 wrap 用 flex-start，让 ScrollView 也贴顶；icon 在 ScrollView 内通过 align-items
+  // 居中到可视行中线，从而和右侧 icon 在同一水平线上。
+  // hintBottom 锚定 wrap 底部：
+  //   icon 中心到 wrap 底部 = (wrap底部→SV底部空隙) + SV的paddingBottom + 可视行高/2
+  //   竖屏:  0  + 0  + 24   = 24，箭头 16 → bottom = 16
+  //   横屏:  25 + 25 + 16.5 = 66.5，箭头 16 → bottom = 58
+
+  const hintBottom = screenType === 'vertical' ? 16 : 58;
+  // button 模式用半透明圆做点击热区，比 pulse 提示大；下移半个差值以保持图标中心不变
+  const hintSize = isButtonHint ? 26 : 16;
+  // 竖屏 button 模式给 ScrollView 右侧留一条较窄的“箭头槽”：只裁掉内容最右一小段，
+  // 箭头压住最后一个元素的少量边缘（不完全遮挡），整体更贴近内容
+  const arrowGutter = isButtonHint && screenType === 'vertical' ? 12 : 0;
+  // 箭头贴右边缘放置（竖屏 4px / 横屏 6px），不再随 gutter 居中
+  const hintRight = arrowGutter > 0 ? 4 : 6;
   return /*#__PURE__*/React.createElement(CoverView, {
     className: clsx('ipc-player-bottom-left-content-wrap'),
     style: {
@@ -80,7 +217,7 @@ const BottomLeftContent = _ref => {
       height: showBadge ? `${coverHeight + 30}px` : `${coverHeight}px`,
       display: 'flex',
       flexDirection: 'column',
-      justifyContent: 'center',
+      justifyContent: 'flex-start',
       opacity: shouldHide ? 0 : 1,
       pointerEvents: shouldHide ? 'none' : 'auto'
     }
@@ -94,22 +231,102 @@ const BottomLeftContent = _ref => {
     trialRemainingSec: trialRemainingSec,
     onSubscribe: handleTrialSubscribe,
     onCountdownEnd: handleCountdownEnd
-  })), /*#__PURE__*/React.createElement(View, {
+  })), /*#__PURE__*/React.createElement(ScrollView, {
+    key: scrollResetKey,
+    scrollX: true,
+    scrollLeft: scrollTo,
+    scrollWithAnimation: true,
+    onScroll: e => {
+      var _e$detail;
+      // 滑动开始时暂停自动隐藏（仅在一次滑动会话内触发一次），滑动停止后恢复
+      if (!scrollingRef.current) {
+        var _ctx$event;
+        scrollingRef.current = true;
+        (_ctx$event = ctx.event) === null || _ctx$event === void 0 || _ctx$event.emit(pauseTimeToHideAllComponent);
+      }
+      if (scrollEndTimerRef.current) {
+        clearTimeout(scrollEndTimerRef.current);
+      }
+      scrollEndTimerRef.current = setTimeout(() => {
+        var _ctx$event2;
+        scrollingRef.current = false;
+        (_ctx$event2 = ctx.event) === null || _ctx$event2 === void 0 || _ctx$event2.emit(startTimeToHideAllComponent);
+      }, 200);
+
+      // Ray ScrollView 在不同实现下，scrollLeft 可能直接挂在事件上，也可能在 detail 内
+      const sl = typeof (e === null || e === void 0 ? void 0 : e.scrollLeft) === 'number' ? e.scrollLeft : e === null || e === void 0 || (_e$detail = e.detail) === null || _e$detail === void 0 ? void 0 : _e$detail.scrollLeft;
+      if (typeof sl === 'number') {
+        scrollLeftRef.current = sl;
+        setScrollLeft(sl);
+        // 一旦真的拖动过（>2px 阈值过滤抖动 / 重置触发的 0 值），当前屏幕模式下不再展示箭头
+        if (sl > 2 && !dismissed[screenType]) {
+          setDismissed(d => _objectSpread(_objectSpread({}, d), {}, {
+            [screenType]: true
+          }));
+        }
+      }
+    },
+    className: clsx(scrollCls, {
+      'ipc-player-bottom-left-scroll-fademask': isOverflow && !atEnd
+    }),
     style: {
-      paddingBottom: screenType === 'vertical' ? 0 : '25px',
+      paddingBottom: `${paddingBottomPx}px`,
       paddingLeft: `${paddingLeftPx}px`,
-      paddingRight: '16px',
-      width: '100%',
+      paddingRight: `${paddingRightPx}px`,
+      width: arrowGutter > 0 ? `calc(100% - ${arrowGutter}px)` : '100%',
       height: `${containerHeight}px`,
       marginTop: showBadge ? '-2px' : 0,
-      overflowX: 'auto',
-      overflowY: 'hidden',
-      whiteSpace: 'nowrap',
-      WebkitOverflowScrolling: 'touch',
-      WebkitMaskImage: fadeMask,
-      maskImage: fadeMask
+      whiteSpace: 'nowrap'
+    }
+  }, /*#__PURE__*/React.createElement(View, {
+    className: clsx('ipc-player-bottom-left-content-container', contentCls),
+    style: {
+      display: 'inline-flex',
+      flexDirection: 'row',
+      height: `${containerHeight - paddingBottomPx}px`,
+      alignItems: 'center'
+    }
+  }, children, /*#__PURE__*/React.createElement(View, {
+    className: endCls,
+    style: {
+      width: '1px',
+      height: '1px',
+      flexShrink: 0
+    }
+  }))), isOverflow && !atEnd && (isButtonHint || !isDismissed) && /*#__PURE__*/React.createElement(CoverView, {
+    className: clsx('ipc-player-bottom-left-scroll-hint', {
+      'ipc-player-bottom-left-scroll-hint--button': isButtonHint
+    }),
+    style: {
+      position: 'absolute',
+      right: `${hintRight}px`,
+      bottom: `${hintBottom - (hintSize - 16) / 2}px`,
+      width: `${hintSize}px`,
+      height: `${hintSize}px`,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      pointerEvents: isButtonHint ? 'auto' : 'none'
     },
-    className: clsx('ipc-player-bottom-left-content-container')
-  }, children));
+    onClick: isButtonHint ? () => {
+      if (!isOverflow) {
+        return;
+      }
+      setScrollTo(totalContentWidth + clientWidth + 9999);
+    } : undefined
+  }, /*#__PURE__*/React.createElement(View, {
+    className: clsx('ipc-player-bottom-left-scroll-hint-arrow', {
+      'ipc-player-bottom-left-scroll-hint-arrow--right': true,
+      'ipc-player-bottom-left-scroll-hint-arrow--light': isButtonHint,
+      'ipc-player-bottom-left-scroll-hint-arrow--static': isButtonHint
+    })
+    // 右向 chevron 由 top+right 描边旋转而成，视觉重心偏右；放大并整体左移使其在圆内居中
+    ,
+    style: isButtonHint ? {
+      width: '9px',
+      height: '9px',
+      transform: 'translate(-1px, 0) rotate(45deg)'
+    } : undefined
+  })));
 };
 export default BottomLeftContent;

package/lib/ui/ui.d.ts

@@ -32,12 +32,13 @@ type Props = {
     awakeStatus?: boolean | undefined;
     eventRef?: React.RefObject<EventInstance>;
     onPlayerTap?: (data: any) => void;
-    defaultAutoPlay?: boolean;
     limitFlow?: boolean;
     showFlowLowTip?: boolean;
     extend?: Record<string, any>;
     refreshElement?: boolean;
     autoWakeUp?: boolean;
+    previewEnabled?: boolean;
+    onPreviewEnabledChange?: (enabled: boolean) => void;
 };
 export declare const IPCPlayerIntegration: React.MemoExoticComponent<(props: Props) => React.JSX.Element>;
 export {};

package/lib/ui/ui.js

@@ -1,6 +1,7 @@
 import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import "core-js/modules/esnext.iterator.constructor.js";
 import "core-js/modules/esnext.iterator.filter.js";
+import "core-js/modules/esnext.iterator.find.js";
 import "core-js/modules/esnext.iterator.map.js";
 import React, { useContext, useState, useRef, useMemo, useEffect, useImperativeHandle } from 'react';
 import { View, CoverView, getSystemInfoSync, usePageEvent, setNavigationBarBack, setPageOrientation, getCurrentPages } from '@ray-js/ray';
@@ -64,12 +65,13 @@ export const IPCPlayerIntegration = /*#__PURE__*/React.memo(props => {
     awakeStatus = undefined,
     onPlayerTap,
     playerRoute = 'pages/home/index',
-    defaultAutoPlay = true,
     limitFlow = false,
     showFlowLowTip = false,
     extend = {},
     refreshElement = false,
-    autoWakeUp = false
+    autoWakeUp = false,
+    previewEnabled = undefined,
+    onPreviewEnabledChange
   } = props;
   const {
     event
@@ -215,7 +217,8 @@ export const IPCPlayerIntegration = /*#__PURE__*/React.memo(props => {
     return () => {
       var _ty3;
       if (typeof ((_ty3 = ty) === null || _ty3 === void 0 ? void 0 : _ty3.offOrientationChange) === 'function') {
-        ty.offOrientationChange(handleOrientationChange);
+        var _ty4;
+        (_ty4 = ty) === null || _ty4 === void 0 || _ty4.offOrientationChange(handleOrientationChange);
       }
     };
   }, []);
@@ -444,7 +447,19 @@ export const IPCPlayerIntegration = /*#__PURE__*/React.memo(props => {
     setBrandColor(brandColor);
     setVerticalMic(verticalMic);
   }, [brandColor, verticalMic]);
+
+  // 是否隐藏画质（试用）功能：取 TryExperience widget 的 hideSmartImageQualityState
+  // （由 initPlayerWidgets 的 hideSmartImageQualityState ?? true 映射而来）
+  const hideSmartImageQualityState = useMemo(() => {
+    var _hideSmartImageQualit, _tryExp$initProps;
+    const tryExp = bottomLeftContent === null || bottomLeftContent === void 0 ? void 0 : bottomLeftContent.find(item => item.id === 'TryExperience');
+    return (_hideSmartImageQualit = tryExp === null || tryExp === void 0 || (_tryExp$initProps = tryExp.initProps) === null || _tryExp$initProps === void 0 ? void 0 : _tryExp$initProps.hideSmartImageQualityState) !== null && _hideSmartImageQualit !== void 0 ? _hideSmartImageQualit : true;
+  }, [bottomLeftContent]);
   const refreshSmartImageQuality = useMemoizedFn(async () => {
+    // 隐藏画质功能时直接跳过，不发起请求与更新
+    console.log('hideSmartImageQualityState');
+    if (hideSmartImageQualityState) return;
+    console.log('refreshSmartImageQuality');
     const res = await getSmartImageQualityState(devId);
     if (!res) return;
     // 调试时使用
@@ -465,17 +480,12 @@ export const IPCPlayerIntegration = /*#__PURE__*/React.memo(props => {
       isLowPhone: isLowPhoneRef.current
     });
   });
-  const siqInitRef = useRef(false);
+
+  // 首次进入即执行；hideSmartImageQualityState 变化时重新执行。
+  // 是否隐藏的判定在 refreshSmartImageQuality 内部，hide 为 true 时方法内直接 return。
   useEffect(() => {
-    if (playState === PlayState.PLAYING) {
-      if (!siqInitRef.current) {
-        siqInitRef.current = true;
-        refreshSmartImageQuality();
-      }
-    } else {
-      siqInitRef.current = false;
-    }
-  }, [instance, playState]);
+    refreshSmartImageQuality();
+  }, [hideSmartImageQualityState]);
   const refreshBottomLeft = () => {
     event.current.emit(startTimeToHideAllComponent);
     event.current.emit(showAllComponent);
@@ -512,6 +522,33 @@ export const IPCPlayerIntegration = /*#__PURE__*/React.memo(props => {
     setIsSmallScreen(computeIsSmallScreen());
   });
 
+  // 页面是否处于前台；自动隐藏倒计时要等播放器正常出流（PLAYING）后再启动
+  const pageShownRef = useRef(false);
+  // 用 ref 同步最新 playState，避免 usePageEvent 回调闭包拿到过期值
+  const playStateRef = useRef(playState);
+  playStateRef.current = playState;
+  usePageEvent('onShow', () => {
+    pageShownRef.current = true;
+    // 回到前台时刷新画质（试用）状态（方法内部会按 hideSmartImageQualityState 自行短路）
+    refreshSmartImageQuality();
+    // 已经在出流就直接启动；否则等 playState 变为 PLAYING 的 effect 再启动
+    if (playStateRef.current === PlayState.PLAYING) {
+      eventRef.current.emit(startTimeToHideAllComponent);
+    }
+  });
+  // 进入后台 停止播放器元素动画计时
+  usePageEvent('onHide', () => {
+    pageShownRef.current = false;
+    eventRef.current.emit(pauseTimeToHideAllComponent);
+  });
+
+  // 播放器正常出流后再开始自动隐藏倒计时（仅在前台时）
+  useEffect(() => {
+    if (pageShownRef.current && playState === PlayState.PLAYING) {
+      eventRef.current.emit(startTimeToHideAllComponent);
+    }
+  }, [playState]);
+
   /**
    * 监听屏幕布局变化
    */
@@ -680,12 +717,12 @@ export const IPCPlayerIntegration = /*#__PURE__*/React.memo(props => {
 
   /**
    * 右下角可见按钮数 → 右下角组件宽度（左下角同时用作右侧预留宽度）
-   * - 横屏: 固定 35%（用百分比，左下角自动按 100% - 35% = 65% 可视，溢出走横向滚动）
+   * - 横屏: 固定 40%（用百分比，左下角自动按 100% - 40% = 60% 可视，溢出走横向滚动）
    * - 竖屏: 1 个按钮 115px / 2+ 个按钮 132px / 0 个按钮 0
    */
   const bottomRightWidth = useMemo(() => {
     if (screenType === 'full') {
-      return '35%';
+      return '40%';
     }
     const visibleCount = (bottomRightContent || []).filter(item => !item.hidden).length;
     if (visibleCount <= 0) return 0;
@@ -979,7 +1016,8 @@ export const IPCPlayerIntegration = /*#__PURE__*/React.memo(props => {
     ,
     brandColor: brandColor,
     playerRoute: playerRoute,
-    defaultAutoPlay: defaultAutoPlay,
+    previewEnabled: previewEnabled,
+    onPreviewEnabledChange: onPreviewEnabledChange,
     limitFlow: limitFlow,
     autoWakeUp: autoWakeUp,
     extend: _objectSpread(_objectSpread({

package/lib/ui/ui.less

@@ -160,6 +160,70 @@
     flex-direction: row;
   }
 
+  // 左下角横滑提示箭头：仅在内容溢出且未滑到对应边缘时由 JS 控制显示
+  .ipc-player-bottom-left-scroll-hint-arrow {
+    width: 7px;
+    height: 7px;
+    animation: ipc-player-bottom-left-scroll-hint-pulse 1.4s ease-in-out infinite;
+  }
+
+  .ipc-player-bottom-left-scroll-hint-arrow--right {
+    border-top: 2px solid rgba(255, 255, 255, 0.95);
+    border-right: 2px solid rgba(255, 255, 255, 0.95);
+    transform: rotate(45deg);
+  }
+
+  .ipc-player-bottom-left-scroll-hint-arrow--left {
+    border-top: 2px solid rgba(255, 255, 255, 0.95);
+    border-left: 2px solid rgba(255, 255, 255, 0.95);
+    transform: rotate(-45deg);
+  }
+
+  // button 模式：半透明黑圆底（点击热区）
+  .ipc-player-bottom-left-scroll-hint--button {
+    background: rgba(0, 0, 0, 0.45);
+    border-radius: 50%;
+  }
+
+  // button 模式：白色箭头
+  .ipc-player-bottom-left-scroll-hint-arrow--light {
+    border-top-color: rgba(255, 255, 255, 0.95);
+    border-right-color: rgba(255, 255, 255, 0.95);
+    border-left-color: rgba(255, 255, 255, 0.95);
+  }
+
+  // button 模式：常显、不做渐隐渐显动画
+  .ipc-player-bottom-left-scroll-hint-arrow--static {
+    animation: none;
+    opacity: 1;
+  }
+
+  // 右边缘淡出：把没完全露出的元素渐隐到透明。写成静态类，避免内联 mask 在原生层反复重绘闪烁
+  .ipc-player-bottom-left-scroll-fademask {
+    -webkit-mask-image: linear-gradient(
+      to right,
+      #000 calc(100% - 72px),
+      rgba(0, 0, 0, 0.25) calc(100% - 24px),
+      transparent 100%
+    );
+    mask-image: linear-gradient(
+      to right,
+      #000 calc(100% - 72px),
+      rgba(0, 0, 0, 0.25) calc(100% - 24px),
+      transparent 100%
+    );
+  }
+
+  @keyframes ipc-player-bottom-left-scroll-hint-pulse {
+    0%,
+    100% {
+      opacity: 0.55;
+    }
+    50% {
+      opacity: 1;
+    }
+  }
+
   // 右下角子元素内容区域样式
   .ipc-player-bottom-right-content-container {
     display: flex;
@@ -233,20 +297,20 @@
 
   // 左下角全屏子元素容器
   .bottom-left-item-full-container {
-    padding: 0 24px !important;
+    padding: 0 20px !important;
     flex-shrink: 0;
   }
 
   .bottom-left-item-full-container:first-of-type {
-    padding: 0 24px 0 16px !important;
+    padding: 0 20px 0 12px !important;
   }
 
   .bottom-left-item-full-container:last-of-type {
-    padding: 0 0 0 24px !important;
+    padding: 0 0 0 20px !important;
   }
 
   .bottom-left-item-full-container:only-of-type {
-    padding: 0 0 0 16px !important;
+    padding: 0 0 0 12px !important;
   }
 
   // 右下角子元素容器

package/lib/widgets/tryExperience/tryExperience.d.ts

@@ -3,7 +3,7 @@ import { ComponentConfigProps } from '../../interface';
 import './tryExperience.less';
 type Props = ComponentConfigProps & {
     className?: string;
-    hideTryExperienceMenu?: boolean;
+    hideSmartImageQualityState?: boolean;
     buttonState?: number;
     trialRemainingSec?: number;
     isPurchase?: boolean;

package/lib/widgets/tryExperience/tryExperience.js

@@ -44,7 +44,7 @@ const pickIconByStatus = buttonState => {
 export const TryExperience = props => {
   const {
     className,
-    hideTryExperienceMenu,
+    hideSmartImageQualityState,
     buttonState,
     trialRemainingSec,
     isPurchase,
@@ -145,7 +145,7 @@ export const TryExperience = props => {
       lockRef.current = false;
     }
   }, [buttonState, recording, isPurchase, trialRemainingSec]);
-  if (hideTryExperienceMenu) {
+  if (hideSmartImageQualityState) {
     return null;
   }
   if (!imgSrc || !canOpenSettings || !gRawData) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/ipc-player-integration",
-  "version": "0.0.35-beta.30",
+  "version": "0.0.35-beta.31",
   "description": "IPC 融合播放器",
   "main": "lib/index",
   "files": [
@@ -37,7 +37,7 @@
   "dependencies": {
     "@ray-js/direction-control": "^0.0.8",
     "@ray-js/ipc-ptz-zoom": "^0.0.3",
-    "@ray-js/ray-ipc-player": "^2.1.1",
+    "@ray-js/ray-ipc-player": "^2.1.2",
     "@ray-js/ray-ipc-utils": "^1.1.15",
     "@ray-js/svg": "0.2.0",
     "clsx": "^1.2.1",