@ray-js/ipc-player-integration 0.0.49 → 0.0.50-beta.0

package/lib/widgets/zoomTurntable/zoomTurntableDock.js

@@ -0,0 +1,228 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+import "core-js/modules/esnext.iterator.constructor.js";
+import "core-js/modules/esnext.iterator.for-each.js";
+import "core-js/modules/esnext.iterator.map.js";
+import "core-js/modules/esnext.iterator.some.js";
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { View, getCurrentPages, usePageEvent } from '@ray-js/ray';
+import clsx from 'clsx';
+import { useMemoizedFn } from 'ahooks';
+import { useStore } from '../../ctx/store';
+import { PlayState } from '../../interface';
+import { pauseTimeToHideAllComponent, playerTap } from '../../ui/constant';
+import { useLensZoom } from './useLensZoom';
+import ZoomTurntable from './turntable';
+import { CROP_RATIO_BOTTOM, CROP_RATIO_RIGHT, RELAYOUT_DELAYS, STYLE_OPTIONS_BOTTOM, STYLE_OPTIONS_RIGHT, VIBRATE_THROTTLE, zoomTurntableClose } from './constants';
+import './zoomTurntableDock.less';
+/**
+ * 当前页面 id，ty.nativeDisabled 需要它定位要禁用手势分发的页面。
+ * 各宿主暴露的字段名不统一，逐个兜底取；取不到时传空串，由宿主按当前页处理。
+ */
+const getPageId = () => {
+  try {
+    var _ref, _ref2, _ref3, _page$__wxWebviewId__;
+    const pages = getCurrentPages();
+    const page = pages === null || pages === void 0 ? void 0 : pages[pages.length - 1];
+    const pageId = (_ref = (_ref2 = (_ref3 = (_page$__wxWebviewId__ = page === null || page === void 0 ? void 0 : page.__wxWebviewId__) !== null && _page$__wxWebviewId__ !== void 0 ? _page$__wxWebviewId__ : page === null || page === void 0 ? void 0 : page.__webviewId__) !== null && _ref3 !== void 0 ? _ref3 : page === null || page === void 0 ? void 0 : page.__id__) !== null && _ref2 !== void 0 ? _ref2 : page === null || page === void 0 ? void 0 : page.pageId) !== null && _ref !== void 0 ? _ref : '';
+    return String(pageId);
+  } catch (err) {
+    console.warn('[zoomTurntable] 获取 pageId 失败', err);
+    return '';
+  }
+};
+
+/**
+ * 焦距转盘浮层。
+ *
+ * 必须由 CoverView 承载（Entry 里 addContent 不设 absoluteNoCoverView）：
+ * 播放器是原生组件、层级高于普通 View，放在普通 View 里的 canvas 会被它盖住，
+ * touchstart 到不了 canvas，转盘完全滑不动（实测 setupEventListeners 成功但无任何 touch 日志）。
+ * 定位与层级由承载的 CoverView 通过 absolutePosition 提供。
+ */
+export const ZoomTurntableDock = props => {
+  const {
+    event,
+    className
+  } = props;
+  const {
+    screenType,
+    playState
+  } = useStore({
+    screenType: props.screenType,
+    playState: props.playState
+  });
+  const {
+    multiLensReady,
+    curM,
+    min,
+    max,
+    step,
+    marks,
+    ticks,
+    beginDrag,
+    applyZoom
+  } = useLensZoom(_objectSpread(_objectSpread({}, props), {}, {
+    skipLoad: true
+  }));
+  const isRight = screenType !== 'vertical';
+  /** 横竖屏切换要重建 canvas 尺寸：换 key 强制 rjs 组件重新 attached/ready */
+  const [remountKey, setRemountKey] = useState(0);
+  const relayoutTimersRef = useRef([]);
+  /** 是否已禁用原生手势，避免重复调用与漏恢复 */
+  const nativeDisabledRef = useRef(false);
+  /** 上次震动时间与上次震动对应的倍率，用于节流与跨刻度判定 */
+  const lastVibrateAtRef = useRef(0);
+  const lastVibrateValueRef = useRef(curM);
+  const requestClose = useMemoizedFn(() => {
+    event.emit(zoomTurntableClose);
+  });
+
+  /**
+   * 转盘操作期间禁用异层渲染的手势分发，否则播放器原生层会抢走 touch 序列。
+   * 成对调用，且在 touchcancel、卸载路径上都要恢复，否则播放器手势会永久失效。
+   */
+  const setNativeDisabled = useMemoizedFn(disabled => {
+    var _ty;
+    if (nativeDisabledRef.current === disabled) return;
+    if (typeof ((_ty = ty) === null || _ty === void 0 ? void 0 : _ty.nativeDisabled) !== 'function') return;
+    nativeDisabledRef.current = disabled;
+    try {
+      ty.nativeDisabled({
+        nativeDisabled: disabled,
+        pageId: getPageId(),
+        fail: err => {
+          console.warn('[zoomTurntable] nativeDisabled fail', JSON.stringify(err));
+        }
+      });
+    } catch (err) {
+      console.warn('[zoomTurntable] nativeDisabled 调用异常', err);
+    }
+  });
+
+  // 展开期间转盘常驻，不做空闲自动收起；
+  // 自动隐藏倒计时已由 Entry 在 openDock 时 emit(pauseTimeToHideAllComponent) 暂停。
+  useEffect(() => {
+    event.emit(pauseTimeToHideAllComponent);
+    return () => {
+      relayoutTimersRef.current.forEach(timer => clearTimeout(timer));
+      relayoutTimersRef.current = [];
+      // 卸载兜底：手指还按着就被收起时，必须恢复原生手势
+      setNativeDisabled(false);
+    };
+  }, []);
+
+  // 点击播放器 → 收起转盘。
+  // ui.tsx 的 handPlayerTap 会在此时把其余控件重新显示出来（componentHideState → false）
+  // 并 emit(playerTap)，所以这里只需负责关掉转盘。
+  useEffect(() => {
+    event.on(playerTap, requestClose);
+    return () => {
+      event.off(playerTap, requestClose);
+    };
+  }, [event, requestClose]);
+
+  // 横竖屏切换：重建画布
+  useEffect(() => {
+    setRemountKey(key => key + 1);
+  }, [screenType]);
+
+  /** 原生层布局沉降滞后，onShow / onResize 后延时重建画布兜底 */
+  const scheduleRelayout = useMemoizedFn(() => {
+    relayoutTimersRef.current.forEach(timer => clearTimeout(timer));
+    relayoutTimersRef.current = RELAYOUT_DELAYS.map(delay => setTimeout(() => setRemountKey(key => key + 1), delay));
+  });
+  usePageEvent('onShow', scheduleRelayout);
+  usePageEvent('onResize', scheduleRelayout);
+  usePageEvent('onHide', () => {
+    relayoutTimersRef.current.forEach(timer => clearTimeout(timer));
+    relayoutTimersRef.current = [];
+    requestClose();
+  });
+
+  /** 震动反馈：跨主刻度用 medium，普通刻度用 light 且节流 */
+  const vibrate = useMemoizedFn(type => {
+    var _ty2;
+    if (typeof ((_ty2 = ty) === null || _ty2 === void 0 ? void 0 : _ty2.vibrateShort) !== 'function') return;
+    try {
+      ty.vibrateShort({
+        type
+      });
+    } catch (err) {
+      console.warn('[zoomTurntable] vibrateShort 调用失败', err);
+    }
+  });
+  const handleChange = useMemoizedFn(value => {
+    const prev = lastVibrateValueRef.current;
+    lastVibrateValueRef.current = value;
+    beginDrag(value);
+
+    // 跨过主刻度（各镜头光学倍数 / 上限）时给更明显的反馈，形成挡位感
+    const crossedMark = marks.some(mark => prev < mark.value && value >= mark.value || prev > mark.value && value <= mark.value);
+    const now = Date.now();
+    if (crossedMark) {
+      lastVibrateAtRef.current = now;
+      vibrate('medium');
+      return;
+    }
+    if (now - lastVibrateAtRef.current >= VIBRATE_THROTTLE) {
+      lastVibrateAtRef.current = now;
+      vibrate('light');
+    }
+  });
+  const handleChangeEnd = useMemoizedFn(value => {
+    applyZoom(value);
+  });
+  const handleTouchStart = useMemoizedFn(() => {
+    setNativeDisabled(true);
+    // 每次按下重置震动基准，避免用上一次拖动结束时的值误判跨刻度
+    lastVibrateValueRef.current = curM;
+    lastVibrateAtRef.current = 0;
+    // 触摸期间同样保持暂停，避免其他控件在此期间重启倒计时
+    event.emit(pauseTimeToHideAllComponent);
+  });
+  const handleTouchEnd = useMemoizedFn(() => {
+    setNativeDisabled(false);
+  });
+
+  // 定位由承载的 CoverView 负责（absolutePosition），这里只做布局容器。
+  const turntableStyle = useMemo(() => ({
+    width: isRight ? 'auto' : '100%',
+    height: '100%',
+    display: 'flex',
+    flexDirection: isRight ? 'row' : 'column',
+    alignItems: 'center',
+    justifyContent: 'flex-end'
+  }), [isRight]);
+  if (!multiLensReady || playState !== PlayState.PLAYING) {
+    return null;
+  }
+
+  // 不要在外层套「铺满 + onClick」的遮罩层：父级 tap 手势识别器会 cancel 掉
+  // canvas 在 render 线程里的 touch 序列，转盘就滑不动了。
+  // 「点播放器收起」改为监听 ui.tsx 的 playerTap 事件（见上面的 effect）。
+  return /*#__PURE__*/React.createElement(View, {
+    className: clsx(className, 'ipc-player-plugin-zoom-turntable-dock', {
+      'ipc-player-plugin-zoom-turntable-dock-right': isRight
+    }),
+    style: turntableStyle
+  }, /*#__PURE__*/React.createElement(ZoomTurntable, {
+    key: `${isRight ? 'right' : 'bottom'}-${remountKey}`,
+    value: curM,
+    defaultValue: curM,
+    min: min,
+    max: max,
+    step: step,
+    marks: marks,
+    ticks: ticks,
+    curve: 1,
+    scale: 1,
+    orientation: isRight ? 'right' : 'bottom',
+    cropRatio: isRight ? CROP_RATIO_RIGHT : CROP_RATIO_BOTTOM,
+    activeColor: "#FFFFFF",
+    styleOptions: isRight ? STYLE_OPTIONS_RIGHT : STYLE_OPTIONS_BOTTOM,
+    onChange: handleChange,
+    onChangeEnd: handleChangeEnd,
+    onTouchStart: handleTouchStart,
+    onTouchEnd: handleTouchEnd
+  }));
+};

package/lib/widgets/zoomTurntable/zoomTurntableDock.less

@@ -0,0 +1,11 @@
+// 转盘浮层。
+// 定位与层级由承载它的 CoverView 提供（absolutePosition，见 Entry 的 addContent），
+// 这里只负责把 canvas 在容器内对齐，不再自己 position: absolute。
+.ipc-player-plugin-zoom-turntable-dock {
+  overflow: visible;
+}
+
+// 横屏：贴右侧竖向展开
+.ipc-player-plugin-zoom-turntable-dock-right {
+  height: 100%;
+}

package/lib/widgets/zoomTurntable/zoomTurntableEntry.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import { ComponentConfigProps } from '../../interface';
+import { ZoomSkill } from './lensSkill';
+import './zoomTurntableEntry.less';
+type Props = ComponentConfigProps & {
+    className?: string;
+    /** 业务侧的功能开关；实际是否渲染仍由 ipc_multi_zoom 解析出的 cnt 决定 */
+    showZoomTurntable?: boolean;
+    /** 调试用：直接注入镜头能力，跳过 ipc_multi_zoom DP 解析 */
+    mockZoomSkill?: ZoomSkill | boolean;
+    /** 长按判定时长，默认 500ms */
+    longPressDuration?: number;
+    /** 关闭圈选引导 */
+    disableTip?: boolean;
+};
+/**
+ * 焦距转盘入口：左下角工具条中的图标，长按弹出转盘。
+ * 仅 cnt > 1 的多镜头设备渲染；单镜头设备倍率交互仍由 RealTimeMagnification 承担。
+ */
+export declare const ZoomTurntableEntry: (props: Props) => React.JSX.Element | null;
+export {};

package/lib/widgets/zoomTurntable/zoomTurntableEntry.js

@@ -0,0 +1,253 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+import "core-js/modules/esnext.iterator.constructor.js";
+import "core-js/modules/esnext.iterator.map.js";
+import React, { useContext, useEffect, useRef, useState } from 'react';
+import { View, Text } from '@ray-js/ray';
+import clsx from 'clsx';
+import { useMemoizedFn } from 'ahooks';
+import { useStore } from '../../ctx/store';
+import { UIEventContext } from '../../ui/context';
+import { PlayState } from '../../interface';
+import { bottomLeftContentResize, hideAllComponent, pauseTimeToHideAllComponent, showAllComponent, startTimeToHideAllComponent, widgetClick, widgetLabs } from '../../ui/constant';
+import { Storage } from '../../utils/storage';
+import { useLensZoom } from './useLensZoom';
+import { ZoomTurntableDock } from './zoomTurntableDock';
+import { ZoomTurntableTip } from './zoomTurntableTip';
+import { measureEntryVisible } from './measureVisible';
+import { ZOOM_ENTRY_ANCHOR_CLS } from './entryAnchor';
+import { LONG_PRESS_MS, MOVE_TOLERANCE, ZOOM_DOCK_BOTTOM, ZOOM_DOCK_HEIGHT, ZOOM_DOCK_RIGHT, ZOOM_DOCK_Z_INDEX, zoomTurntableClose, zoomTurntableDockId, zoomTurntableOpen, zoomTurntableTipId } from './constants';
+import './zoomTurntableEntry.less';
+/**
+ * 焦距转盘入口：左下角工具条中的图标，长按弹出转盘。
+ * 仅 cnt > 1 的多镜头设备渲染；单镜头设备倍率交互仍由 RealTimeMagnification 承担。
+ */
+export const ZoomTurntableEntry = props => {
+  var _props$event;
+  const {
+    devId,
+    className,
+    addContent,
+    deleteContent,
+    hasContent,
+    longPressDuration = LONG_PRESS_MS,
+    disableTip = false
+  } = props;
+  const {
+    event: ctxEvent
+  } = useContext(UIEventContext);
+  const event = (_props$event = props.event) !== null && _props$event !== void 0 ? _props$event : ctxEvent;
+  const {
+    playState,
+    screenType,
+    brandColor
+  } = useStore({
+    playState: props.playState,
+    screenType: props.screenType,
+    brandColor: props.brandColor
+  });
+  const {
+    multiLensReady,
+    lenses,
+    lensIndex,
+    curM,
+    switchToLens
+  } = useLensZoom(props);
+  const [dockVisible, setDockVisible] = useState(false);
+  const timerRef = useRef();
+  const startRef = useRef();
+  /** 长按已触发：用于抑制紧跟其后的 tap（部分宿主 longpress 后仍派发 tap） */
+  const firedRef = useRef(false);
+  /** 本次触摸已被判为横滑：既不出转盘也不切镜头 */
+  const cancelledRef = useRef(false);
+  const dockVisibleRef = useRef(false);
+  const tipCheckedRef = useRef(false);
+  const clearTimer = () => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = undefined;
+    }
+  };
+  const closeDock = useMemoizedFn(() => {
+    if (!dockVisibleRef.current) return;
+    dockVisibleRef.current = false;
+    setDockVisible(false);
+    deleteContent('absolute', zoomTurntableDockId);
+    event.emit(showAllComponent);
+    event.emit(startTimeToHideAllComponent);
+  });
+  const openDock = useMemoizedFn(() => {
+    if (dockVisibleRef.current) {
+      closeDock();
+      return;
+    }
+    event.emit(widgetClick, {
+      widgetId: widgetLabs.ZOOM_TURNTABLE
+    });
+    // PTZ 与转盘都占底部 / 右侧，互斥
+    event.emit('ptzControlHide');
+    // 其余元素隐藏并暂停自动隐藏倒计时。
+    // 不要 emit('disablePlayerTap', true)：点播放器收起转盘依赖 ui.tsx 正常派发 playerTap。
+    event.emit(hideAllComponent);
+    event.emit(pauseTimeToHideAllComponent);
+    if (!hasContent('absolute', zoomTurntableDockId)) {
+      // 必须用 CoverView 承载（不能设 absoluteNoCoverView）：播放器是原生组件、层级更高，
+      // 普通 View 里的 canvas 会被它盖住，touchstart 到不了 canvas，转盘滑不动。
+      addContent('absolute', {
+        id: zoomTurntableDockId,
+        content: dockProps => /*#__PURE__*/React.createElement(ZoomTurntableDock, dockProps),
+        absolutePosition: screenType === 'full' ? {
+          top: 0,
+          right: ZOOM_DOCK_RIGHT,
+          bottom: 0,
+          zIndex: ZOOM_DOCK_Z_INDEX
+        } : {
+          left: 0,
+          right: 0,
+          bottom: ZOOM_DOCK_BOTTOM,
+          height: ZOOM_DOCK_HEIGHT,
+          zIndex: ZOOM_DOCK_Z_INDEX
+        },
+        initProps: _objectSpread(_objectSpread({}, props), {}, {
+          skipLoad: true
+        })
+      });
+    }
+    dockVisibleRef.current = true;
+    setDockVisible(true);
+    event.emit(zoomTurntableOpen);
+  });
+
+  // 转盘展开时 PTZ 被唤起 → 收起转盘
+  useEffect(() => {
+    const onPtzShow = () => closeDock();
+    event.on(zoomTurntableClose, closeDock);
+    event.on('ptzControlShow', onPtzShow);
+    return () => {
+      event.off(zoomTurntableClose, closeDock);
+      event.off('ptzControlShow', onPtzShow);
+    };
+  }, [event, closeDock]);
+
+  // 卸载 / 停流时兜底收起
+  useEffect(() => {
+    if (playState !== PlayState.PLAYING && dockVisibleRef.current) {
+      closeDock();
+    }
+  }, [playState, closeDock]);
+  useEffect(() => {
+    return () => {
+      clearTimer();
+      if (dockVisibleRef.current) {
+        deleteContent('absolute', zoomTurntableDockId);
+      }
+    };
+  }, []);
+
+  // 入口延迟出现：DP 异步到达才翻 multiLensReady，而 bottomLeftContent.length 不变，
+  // 左下角测不到宽度变化，横滑箭头与右边缘淡出会算错，需主动通知重测。tab 数量变化同理。
+  useEffect(() => {
+    event.emit(bottomLeftContentResize);
+  }, [multiLensReady, lenses.length, event]);
+
+  // ---------------- 圈选引导 ----------------
+  // 入口在横向 ScrollView 内可能被裁掉，只有真正可见时才提示；能力异步就绪，故判定在 multiLensReady 之后
+  useEffect(() => {
+    if (disableTip || !multiLensReady || playState !== PlayState.PLAYING) return undefined;
+    if (tipCheckedRef.current) return undefined;
+    let cancelled = false;
+    const storage = new Storage(devId);
+    (async () => {
+      // key 不存在时 getStorage 会 fail，这里不能让它把整条链路带崩
+      const read = await storage.get(zoomTurntableTipId).catch(() => null);
+      if (cancelled || read) return;
+      const rect = await measureEntryVisible();
+      if (cancelled || !rect) return;
+      tipCheckedRef.current = true;
+      addContent('absolute', {
+        id: zoomTurntableTipId,
+        content: tipProps => /*#__PURE__*/React.createElement(ZoomTurntableTip, tipProps),
+        absoluteContentClassName: 'ipc-player-plugin-zoom-turntable-tip-wrap',
+        initProps: _objectSpread(_objectSpread({}, props), {}, {
+          anchorRect: rect
+        })
+      });
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [disableTip, multiLensReady, playState, screenType, devId]);
+
+  // ---------------- 长按 / 短按识别 ----------------
+  // 长按任意 tab → 弹转盘；短按 → 切到该镜头。
+  // 不用 onLongPress：入口在横向 ScrollView 内，原生 longpress 在部分宿主上不稳。
+  const onTouchStart = useMemoizedFn(e => {
+    var _e$touches$, _e$touches, _e$changedTouches, _touch$clientX, _touch$clientY;
+    const touch = (_e$touches$ = e === null || e === void 0 || (_e$touches = e.touches) === null || _e$touches === void 0 ? void 0 : _e$touches[0]) !== null && _e$touches$ !== void 0 ? _e$touches$ : e === null || e === void 0 || (_e$changedTouches = e.changedTouches) === null || _e$changedTouches === void 0 ? void 0 : _e$changedTouches[0];
+    startRef.current = {
+      x: (_touch$clientX = touch === null || touch === void 0 ? void 0 : touch.clientX) !== null && _touch$clientX !== void 0 ? _touch$clientX : 0,
+      y: (_touch$clientY = touch === null || touch === void 0 ? void 0 : touch.clientY) !== null && _touch$clientY !== void 0 ? _touch$clientY : 0
+    };
+    firedRef.current = false;
+    cancelledRef.current = false;
+    event.emit(pauseTimeToHideAllComponent);
+    clearTimer();
+    timerRef.current = setTimeout(() => {
+      firedRef.current = true;
+      openDock();
+    }, longPressDuration);
+  });
+  const onTouchMove = useMemoizedFn(e => {
+    var _e$touches2;
+    const touch = e === null || e === void 0 || (_e$touches2 = e.touches) === null || _e$touches2 === void 0 ? void 0 : _e$touches2[0];
+    if (!touch || !startRef.current) return;
+    const moved = Math.abs(touch.clientX - startRef.current.x) > MOVE_TOLERANCE || Math.abs(touch.clientY - startRef.current.y) > MOVE_TOLERANCE;
+    if (moved) {
+      // 判定为工具条横滑：既不出转盘，也不切镜头
+      cancelledRef.current = true;
+      clearTimer();
+    }
+  });
+  const onTouchEnd = useMemoizedFn(index => {
+    clearTimer();
+    // firedRef：长按已出转盘，不再当作点击处理
+    if (!firedRef.current && !cancelledRef.current) {
+      if (index !== lensIndex) {
+        event.emit(widgetClick, {
+          widgetId: widgetLabs.ZOOM_TURNTABLE
+        });
+        switchToLens(index);
+      }
+      event.emit(startTimeToHideAllComponent);
+    }
+  });
+  if (playState !== PlayState.PLAYING || !multiLensReady) {
+    return null;
+  }
+  return /*#__PURE__*/React.createElement(View, {
+    className: clsx(className, ZOOM_ENTRY_ANCHOR_CLS)
+  }, /*#__PURE__*/React.createElement(View, {
+    className: clsx('ipc-player-plugin-zoom-turntable-tabs', {
+      'ipc-player-plugin-zoom-turntable-tabs-full': screenType === 'full'
+    })
+  }, lenses.map((lens, index) => {
+    const active = index === lensIndex;
+    // 当前镜头实时显示画面绝对倍率（手势放大时 1.0X → 2.5X），其余显示各自光学倍数
+    const text = `${(active ? curM : lens.basicRatio).toFixed(1)}X`;
+    return /*#__PURE__*/React.createElement(View, {
+      key: lens.id,
+      className: clsx('ipc-player-plugin-zoom-turntable-tab', {
+        'ipc-player-plugin-zoom-turntable-tab-full': screenType === 'full',
+        'ipc-player-plugin-zoom-turntable-tab-active': active
+      }),
+      style: active && dockVisible ? {
+        backgroundColor: brandColor
+      } : undefined,
+      onTouchStart: onTouchStart,
+      onTouchMove: onTouchMove,
+      onTouchEnd: () => onTouchEnd(index),
+      onTouchCancel: () => onTouchEnd(index)
+    }, /*#__PURE__*/React.createElement(Text, {
+      className: clsx('ipc-player-plugin-zoom-turntable-tab-text')
+    }, text));
+  })));
+};

package/lib/widgets/zoomTurntable/zoomTurntableEntry.less

@@ -0,0 +1,51 @@
+// 倍率 tab 组：按协议 zoom_skill.lenses 渲染 N 个，
+// 当前镜头高亮并实时显示画面绝对倍率，其余显示各自光学倍数。
+//
+// 视觉上是「一个整体胶囊」：圆角与阴影收在外层容器并 overflow 裁剪，
+// 各 tab 自身不带圆角、不留间隔，靠底色深浅区分选中态。
+// stretch 让各 tab 等高，避免选中/未选中因字重渲染差异出现半像素错位。
+.ipc-player-plugin-zoom-turntable-tabs {
+  display: flex;
+  flex-direction: row;
+  align-items: stretch;
+  border-radius: calc(4px * var(--ipc-player-size-scale, 1));
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+  overflow: hidden;
+}
+
+.ipc-player-plugin-zoom-turntable-tabs-full {
+  border-radius: calc(5px * var(--ipc-player-size-scale, 1));
+}
+
+// 与 RealTimeMagnification / Resolution 完全同构：
+// 不声明 height / min-height，也不声明 line-height，
+// 高度由 padding + 文字默认行盒撑开，这样才能和左下角其他控件逐像素齐平。
+// （曾用 line-height: 1.2 + min-height 兜，反而比默认行高矮 2px）
+.ipc-player-plugin-zoom-turntable-tab {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  padding: calc(4px * var(--ipc-player-size-scale, 1)) calc(5px * var(--ipc-player-size-scale, 1));
+  background-color: rgba(255, 255, 255, 0.3);
+
+  .ipc-player-plugin-zoom-turntable-tab-text {
+    color: var(--iconColor);
+    font-weight: 600;
+    font-size: calc(12px * var(--ipc-player-size-scale, 1));
+  }
+}
+
+// 横屏：左右 padding 放宽，同 RealTimeMagnification 的 full 态
+.ipc-player-plugin-zoom-turntable-tab-full {
+  padding-left: calc(8px * var(--ipc-player-size-scale, 1));
+  padding-right: calc(8px * var(--ipc-player-size-scale, 1));
+}
+
+// 选中态：白底黑字（须在基础态之后定义，同优先级下后者生效）
+.ipc-player-plugin-zoom-turntable-tab-active {
+  background-color: rgba(255, 255, 255, 0.92);
+
+  .ipc-player-plugin-zoom-turntable-tab-text {
+    color: #000;
+  }
+}

package/lib/widgets/zoomTurntable/zoomTurntableTip.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { ComponentConfigProps } from '../../interface';
+import { AnchorRect } from './measureVisible';
+import './zoomTurntableTip.less';
+type Props = ComponentConfigProps & {
+    /** 入口图标的视口 rect，由 measureEntryVisible 测得 */
+    anchorRect?: AnchorRect;
+};
+/**
+ * 焦距入口圈选引导（一次性）。
+ *
+ * 与 multiCamera 的 tileTip 同一套视觉（虚线圈 + 超大扩散阴影压暗 + 引线 + 文案 + 知道了），
+ * 差别在于入口位于横向 ScrollView 内、位置不固定，所以圈选框坐标由 JS 内联注入而非写死。
+ */
+export declare const ZoomTurntableTip: (props: Props) => React.JSX.Element | null;
+export {};

package/lib/widgets/zoomTurntable/zoomTurntableTip.js

@@ -0,0 +1,76 @@
+import React, { useEffect, useState } from 'react';
+import { CoverView, Text, View } from '@ray-js/ray';
+import clsx from 'clsx';
+import { useStore } from '../../ctx/store';
+import { PlayState } from '../../interface';
+import { widgetClick, widgetLabs } from '../../ui/constant';
+import { Storage } from '../../utils/storage';
+import Strings from '../../i18n';
+import { measurePlayerRect } from './measureVisible';
+import { TIP_RING_SIZE, zoomTurntableTipId } from './constants';
+import './zoomTurntableTip.less';
+/**
+ * 焦距入口圈选引导（一次性）。
+ *
+ * 与 multiCamera 的 tileTip 同一套视觉（虚线圈 + 超大扩散阴影压暗 + 引线 + 文案 + 知道了），
+ * 差别在于入口位于横向 ScrollView 内、位置不固定，所以圈选框坐标由 JS 内联注入而非写死。
+ */
+export const ZoomTurntableTip = props => {
+  const {
+    devId,
+    deleteContent,
+    anchorRect
+  } = props;
+  const {
+    playState
+  } = useStore({
+    playState: props.playState
+  });
+  const [ringStyle, setRingStyle] = useState(null);
+
+  // 把入口的视口坐标换算成播放器容器内坐标
+  useEffect(() => {
+    if (!anchorRect) return undefined;
+    let cancelled = false;
+    measurePlayerRect().then(player => {
+      if (cancelled || !player) return;
+      const centerX = anchorRect.left - player.left + anchorRect.width / 2;
+      setRingStyle({
+        left: `${centerX - TIP_RING_SIZE / 2}px`,
+        bottom: `${player.bottom - anchorRect.bottom - (TIP_RING_SIZE - anchorRect.height) / 2}px`,
+        width: `${TIP_RING_SIZE}px`,
+        height: `${TIP_RING_SIZE}px`
+      });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [anchorRect]);
+  if (playState !== PlayState.PLAYING || !ringStyle) {
+    return null;
+  }
+  return /*#__PURE__*/React.createElement(CoverView, null, /*#__PURE__*/React.createElement(View, {
+    className: clsx('ipc-player-plugin-zoom-turntable-tip-ring'),
+    style: ringStyle
+  }), /*#__PURE__*/React.createElement(Text, {
+    className: clsx('ipc-player-plugin-zoom-turntable-tip-text'),
+    style: {
+      left: ringStyle.left,
+      bottom: `calc(${ringStyle.bottom} + 116px)`
+    }
+  }, Strings.getLang('ipc_player_zoom_turntable_tip_text')), /*#__PURE__*/React.createElement(View, {
+    className: clsx('ipc-player-plugin-zoom-turntable-tip-button'),
+    style: {
+      left: ringStyle.left,
+      bottom: `calc(${ringStyle.bottom} + 56px)`
+    },
+    onClick: () => {
+      props.event.emit(widgetClick, {
+        widgetId: widgetLabs.ZOOM_TURNTABLE_TIP
+      });
+      deleteContent('absolute', zoomTurntableTipId);
+      const storage = new Storage(devId);
+      storage.set(zoomTurntableTipId, true);
+    }
+  }, Strings.getLang('ipc_player_tip_confirm')));
+};