@ray-js/ipc-player-integration 0.0.50-beta.2 → 0.0.50-beta.4

package/lib/widgets/zoomTurntable/zoomTurntableDock.js

@@ -12,7 +12,7 @@ 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, ZOOM_CANVAS_OVERSHOOT_BOTTOM, STYLE_OPTIONS_BOTTOM, STYLE_OPTIONS_RIGHT, VIBRATE_THROTTLE, zoomTurntableClose } from './constants';
+import { CROP_RATIO_BOTTOM, CROP_RATIO_RIGHT, RELAYOUT_DELAYS, VIBRATE_FAST_STEPS, getStyleOptionsBottom, getVerticalPlayerHeight, getZoomLayoutDebugPx, getZoomVisibleHeightBottom, STYLE_OPTIONS_RIGHT, VIBRATE_THROTTLE, zoomTurntableClose } from './constants';
 import './zoomTurntableDock.less';
 /**
  * 当前页面 id，ty.nativeDisabled 需要它定位要禁用手势分发的页面。
@@ -47,11 +47,20 @@ export const ZoomTurntableDock = props => {
   } = props;
   const {
     screenType,
-    playState
+    playState,
+    isVerticalFullLayout
   } = useStore({
     screenType: props.screenType,
-    playState: props.playState
+    playState: props.playState,
+    isVerticalFullLayout: props.isVerticalFullLayout
   });
+
+  /**
+   * 竖屏全屏：底部工具条常驻，转盘停在它之上（canvas 底部不留触摸余量，否则会盖住按钮）。
+   * 普通竖屏：工具条已被 Entry 藏掉，转盘贴播放器底边（余量上下对称，底部那份沉到播放器外）。
+   * 判断必须与 Entry 的 absolutePosition 用同一套，否则 canvas 高度与 dock 位置对不上。
+   */
+  const isVerticalFull = screenType === 'vertical' && isVerticalFullLayout;
   const {
     multiLensReady,
     curM,
@@ -61,7 +70,8 @@ export const ZoomTurntableDock = props => {
     marks,
     ticks,
     beginDrag,
-    applyZoom
+    applyZoom,
+    endDrag
   } = useLensZoom(_objectSpread(_objectSpread({}, props), {}, {
     skipLoad: true
   }));
@@ -76,13 +86,14 @@ export const ZoomTurntableDock = props => {
   const lastVibrateValueRef = useRef(curM);
 
   /**
-   * 转盘起始值：只在打开转盘 / 重建画布时取一次，之后不再跟随 curM 回写。
-   *
-   * curM 会因为切镜头收尾、画面回读而变，受控回写会在拖动中把指针拽走 ——
-   * 转盘自己维护值、只在落位时把结果下发出去，手感才连续。
+   * 转盘起始值：只在打开转盘 / 重建画布时取一次，作为首帧的 defaultValue。
    *
    * 取值时机要等镜头能力就绪：能力没就绪时 curM 只是 D_MIN 占位，
-   * 拿它当起点会让转盘停在错误刻度（非受控之后没有回写能纠正了）。
+   * 拿它当起点会让转盘停在错误刻度。
+   *
+   * 稳态读数由下面的受控 `value={curM}` 负责跟随（手势缩放画面时读数要跟着动）。
+   * 早先只传 defaultValue、完全不回写，是担心「回写在拖动中把指针拽走」——
+   * 而 rjs 的 setValue 本身就有拖动中 + 松手后 300ms 冷却期的双重忽略，这个顾虑不成立。
    */
   const initialValueRef = useRef(null);
   const lastRemountRef = useRef(remountKey);
@@ -130,38 +141,58 @@ export const ZoomTurntableDock = props => {
       relayoutTimersRef.current = [];
       // 卸载兜底：手指还按着就被收起时，必须恢复原生手势
       setNativeDisabled(false);
+      // 拖动中被收起的话 onChangeEnd 不会来，draggingRef 会挂着 true 把后续的
+      // zoomLevelChange 全丢掉（手势缩放读数就不动了），这里补一次复位
+      endDrag();
     };
   }, []);
 
-  // 诊断：把浮层与 canvas 的真实布局打出来，核对可拖区域到底覆盖到哪。
-  // 期望（竖屏 HIT_PADDING_Y=56）：dock 高 296、canvas 高 288，canvas 顶距 dock 顶约 8px。
-  // 若 canvas 实际高度远小于 288，说明 rjs 的 canvasWidth/Height 没随 styleOptions 更新，
-  // 上半部分自然收不到 touch，会直接落到播放器上。
+  // 诊断：把浮层、canvas 与播放器容器的真实布局打出来，逐项核对两类历史坑：
+  //   1. dock 实测高 ≈ 期望_dock高 → absolutePosition 的 rpx 换算对了
+  //      （曾经给 194 只量到 101px，dock 只有 canvas 一半高，canvas 顶部被裁、收不到 touch）
+  //   2. canvas 实测高 ≈ 期望_canvas高 → rjs/index.js 的 computeCanvasViewport 读到了 ellipseRx/Ry
+  //      （曾经它硬编码 258×175.5，DOM 208 高、绘制 186 高，画面被拉伸且顶部溢出被裁）
+  // canvas顶溢出 > 0 就是「手势不生效」的直接信号：溢出 dock 的那部分收不到 touch。
+  // canvas底距播底 应 ≈ 48（让出底部工具条）：小于它就说明 canvas 压在按钮上、会吃掉按钮点击。
   useEffect(() => {
     const timer = setTimeout(() => {
       const query = ty.createSelectorQuery();
       query.select('.ipc-player-plugin-zoom-turntable-dock').boundingClientRect();
       query.select('.ipc-zoom-turntable-canvas').boundingClientRect();
-      query.selectViewport().boundingClientRect();
+      query.select('.ipc-player-content').boundingClientRect();
       query.exec(res => {
         const dock = res === null || res === void 0 ? void 0 : res[0];
         const canvas = res === null || res === void 0 ? void 0 : res[1];
-        const viewport = res === null || res === void 0 ? void 0 : res[2];
+        const player = res === null || res === void 0 ? void 0 : res[2];
+        const visibleH = getZoomVisibleHeightBottom();
+        const expect = getZoomLayoutDebugPx(isVerticalFull);
         console.log('[zoomTurntable] 浮层布局诊断', JSON.stringify({
           dock: dock && {
             top: dock.top,
-            left: dock.left,
             w: dock.width,
             h: dock.height
           },
           canvas: canvas && {
             top: canvas.top,
-            left: canvas.left,
             w: canvas.width,
             h: canvas.height
           },
-          canvas顶距dock顶: dock && canvas ? canvas.top - dock.top : null,
-          viewportH: viewport === null || viewport === void 0 ? void 0 : viewport.height
+          player: player && {
+            w: player.width,
+            h: player.height
+          },
+          // 16:9 推导值 vs 实测值，两者差得多说明容器不是满宽 16:9
+          播放器高_推导: Math.round(getVerticalPlayerHeight()),
+          竖屏全屏: isVerticalFull,
+          期望_dock高: expect.dock高,
+          期望_canvas高: expect.canvas高,
+          背景带高: visibleH,
+          背景带占比: player !== null && player !== void 0 && player.height ? +(visibleH / player.height).toFixed(3) : null,
+          // 竖屏全屏期望 ≈ 底部工具条高度（canvas 底边 = 工具条顶边）；
+          // 普通竖屏期望 ≈ -HIT_PADDING_Y（沉到播放器底边以下）
+          canvas底距播底: canvas && player ? +(player.bottom - canvas.bottom).toFixed(1) : null,
+          // > 0 说明 canvas 顶部露在 dock 外被裁，那部分收不到 touch
+          canvas顶溢出: dock && canvas ? +(dock.top - canvas.top).toFixed(1) : null
         }));
       });
     }, 300);
@@ -213,7 +244,8 @@ export const ZoomTurntableDock = props => {
     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) {
@@ -221,10 +253,17 @@ export const ZoomTurntableDock = props => {
       vibrate('medium');
       return;
     }
-    if (now - lastVibrateAtRef.current >= VIBRATE_THROTTLE) {
-      lastVibrateAtRef.current = now;
-      vibrate('light');
-    }
+
+    // 距上一次震动太近就跳过。也顺带给 medium 留出静默期：
+    // 刚过主刻度又紧跟一下 light，会把挡位那一下的辨识度糊掉
+    if (now - lastVibrateAtRef.current < VIBRATE_THROTTLE) return;
+
+    // 一次 onChange 跨了好几格 = 正在快速甩动，逐格震分辨不出来，只会连成一片。
+    // 这时不震普通刻度，把反馈让给主刻度的挡位感
+    const movedSteps = step > 0 ? Math.abs(value - prev) / step : 1;
+    if (movedSteps > VIBRATE_FAST_STEPS) return;
+    lastVibrateAtRef.current = now;
+    vibrate('light');
   });
   const handleChangeEnd = useMemoizedFn(value => {
     applyZoom(value);
@@ -241,6 +280,18 @@ export const ZoomTurntableDock = props => {
     setNativeDisabled(false);
   });
 
+  /**
+   * 点在转盘空白处（未命中刻度带）= 点画面 → 收起转盘。
+   *
+   * canvas 覆盖了播放器下部很大一片，且 touch 事件被它 preventDefault + stopPropagation，
+   * 播放器收不到这一下 tap，「点画面收起」在转盘范围内整个失效 ——
+   * 表现就是第一次点没反应、第二次点（落到画面上部）才收起。
+   */
+  const handleBlankTap = useMemoizedFn(() => {
+    setNativeDisabled(false);
+    requestClose();
+  });
+
   // 定位由承载的 CoverView 负责（absolutePosition），这里只做布局容器。
   const turntableStyle = useMemo(() => ({
     width: isRight ? 'auto' : '100%',
@@ -252,18 +303,19 @@ export const ZoomTurntableDock = props => {
   }), [isRight]);
 
   /**
-   * canvas 的承载层。竖屏用负 margin 让 canvas 底边探出播放器底边，
-   * 浮层本身则贴底不下沉 —— 这样 canvas 顶部（刻度线那一带）才不会被 CoverView 裁掉，
-   * 而绘制内容的视觉位置与探出效果都和原来一致。
+   * canvas 的承载层：只负责居中，不再用负 margin 把 canvas 往下推 ——
+   * 实测负 margin 在 CoverView 里不生效，探出去的那截会原地显示出来，
+   * 转盘整体被顶高一截、底边还留一条透明缝。
+   * 现在椭圆截面精确等于可见高度（CROP_RATIO_BOTTOM），整体下沉交给 dock 的
+   * dock 的 bottom（竖屏全屏为正、普通竖屏为负），canvas 尺寸与命中区保持原样，手势不受影响。
    */
-  const canvasHolderStyle = useMemo(() => isRight ? {
+  const canvasHolderStyle = useMemo(() => ({
     display: 'flex',
     justifyContent: 'center'
-  } : {
-    display: 'flex',
-    justifyContent: 'center',
-    marginBottom: `-${ZOOM_CANVAS_OVERSHOOT_BOTTOM}px`
-  }, [isRight]);
+  }), []);
+
+  /** 竖屏几何按容器 16:9 推导（转盘占播放器高的 1/3），横屏沿用设计稿比例 */
+  const styleOptions = useMemo(() => isRight ? STYLE_OPTIONS_RIGHT : getStyleOptionsBottom(isVerticalFull), [isRight, isVerticalFull]);
   if (!multiLensReady || playState !== PlayState.PLAYING) {
     return null;
   }
@@ -280,7 +332,12 @@ export const ZoomTurntableDock = props => {
     style: canvasHolderStyle
   }, /*#__PURE__*/React.createElement(ZoomTurntable, {
     key: `${isRight ? 'right' : 'bottom'}-${remountKey}`,
-    defaultValue: initialValue,
+    defaultValue: initialValue
+    // 受控回写：手势缩放画面时读数要跟着走。
+    // rjs 的 setValue 自带保护 —— 拖动中、以及松手后 300ms 冷却期内一律忽略回写，
+    // 所以不会出现「拖动被回写拽走」（那正是当初只传 defaultValue 的顾虑）。
+    ,
+    value: curM,
     min: min,
     max: max,
     step: step,
@@ -291,10 +348,11 @@ export const ZoomTurntableDock = props => {
     orientation: isRight ? 'right' : 'bottom',
     cropRatio: isRight ? CROP_RATIO_RIGHT : CROP_RATIO_BOTTOM,
     activeColor: "#FFFFFF",
-    styleOptions: isRight ? STYLE_OPTIONS_RIGHT : STYLE_OPTIONS_BOTTOM,
+    styleOptions: styleOptions,
     onChange: handleChange,
     onChangeEnd: handleChangeEnd,
     onTouchStart: handleTouchStart,
-    onTouchEnd: handleTouchEnd
+    onTouchEnd: handleTouchEnd,
+    onBlankTap: handleBlankTap
   })));
 };

package/lib/widgets/zoomTurntable/zoomTurntableEntry.js

@@ -2,7 +2,7 @@ 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 { View, Text, usePageEvent } from '@ray-js/ray';
 import clsx from 'clsx';
 import { useMemoizedFn } from 'ahooks';
 import { useStore } from '../../ctx/store';
@@ -13,9 +13,9 @@ import { Storage } from '../../utils/storage';
 import { useLensZoom } from './useLensZoom';
 import { ZoomTurntableDock } from './zoomTurntableDock';
 import { ZoomTurntableTip } from './zoomTurntableTip';
-import { measureEntryVisible } from './measureVisible';
+import { measureBottomBarHeight, 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 { FORCE_SHOW_ZOOM_TIP, LONG_PRESS_MS, MOVE_TOLERANCE, TIP_RESHOW_DELAY, getZoomDockBottom, getZoomDockHeight, getZoomDockRight, ZOOM_DOCK_Z_INDEX, zoomTurntableClose, zoomTurntableDockId, zoomTurntableOpen, zoomTurntableTipId } from './constants';
 import './zoomTurntableEntry.less';
 /**
  * 焦距转盘入口：左下角工具条中的图标，长按弹出转盘。
@@ -39,12 +39,22 @@ export const ZoomTurntableEntry = props => {
   const {
     playState,
     screenType,
-    brandColor
+    isVerticalFullLayout
   } = useStore({
     playState: props.playState,
     screenType: props.screenType,
-    brandColor: props.brandColor
+    isVerticalFullLayout: props.isVerticalFullLayout
   });
+
+  /**
+   * 竖屏两种布局，转盘的落位与是否让路完全不同：
+   * - 竖屏全屏（isVerticalFullLayout）：底部工具条常驻在屏幕底部，转盘停在工具条**之上**，
+   *   工具条保持可见（能看到当前镜头、能直接点右下角那排按钮）；
+   * - 普通竖屏：播放器只是页面顶部的一块，长按 tab 时把底部元素藏掉，
+   *   转盘**贴播放器底边**显示。
+   * 两种方式下转盘都落在播放器的底部区域。
+   */
+  const isVerticalFull = screenType === 'vertical' && isVerticalFullLayout;
   const {
     multiLensReady,
     lenses,
@@ -82,22 +92,39 @@ export const ZoomTurntableEntry = props => {
     dockVisibleRef.current = false;
     setDockVisible(false);
     deleteContent('absolute', zoomTurntableDockId);
+    // 竖屏没藏过，这一发是幂等的（横屏才真正需要它恢复右侧控件）
     event.emit(showAllComponent);
     event.emit(startTimeToHideAllComponent);
   });
-  const openDock = useMemoizedFn(() => {
+  const openDock = useMemoizedFn(async () => {
     if (dockVisibleRef.current) {
       closeDock();
       return;
     }
+    /**
+     * 竖屏全屏要让出底部工具条，高度按**实测**取：ui.tsx 给它写的是 48px，
+     * 而 `-full` 变体在 less 里还叠了 `padding-bottom: env(safe-area-inset-bottom)`，
+     * 实际占位跟机型 safe-area 有关，硬编码必然对不上。
+     * 长按本身已经等了 500ms，这里再等一帧测量，体感无差别；测不到就退回 48。
+     */
+    const barHeight = isVerticalFull ? await measureBottomBarHeight() : null;
     event.emit(widgetClick, {
       widgetId: widgetLabs.ZOOM_TURNTABLE
     });
     // PTZ 与转盘都占底部 / 右侧，互斥
     event.emit('ptzControlHide');
-    // 其余元素隐藏并暂停自动隐藏倒计时。
-    // 不要 emit('disablePlayerTap', true)：点播放器收起转盘依赖 ui.tsx 正常派发 playerTap。
-    event.emit(hideAllComponent);
+    /**
+     * 只有竖屏全屏**不隐藏**其余元素：底部工具条常驻，转盘停在它上方 ——
+     * 这样能看到当前在哪个镜头，也能直接点右下角那排按钮，收起不必先点画面。
+     *
+     * 普通竖屏与横屏仍旧先藏：前者转盘要贴播放器底边、正压在工具条位置上，
+     * 后者转盘占右侧、与右侧控件正面重叠。
+     *
+     * 不要 emit('disablePlayerTap', true)：点播放器收起转盘依赖 ui.tsx 正常派发 playerTap。
+     */
+    if (!isVerticalFull) {
+      event.emit(hideAllComponent);
+    }
     event.emit(pauseTimeToHideAllComponent);
     if (!hasContent('absolute', zoomTurntableDockId)) {
       // 必须用 CoverView 承载（不能设 absoluteNoCoverView）：播放器是原生组件、层级更高，
@@ -107,14 +134,17 @@ export const ZoomTurntableEntry = props => {
         content: dockProps => /*#__PURE__*/React.createElement(ZoomTurntableDock, dockProps),
         absolutePosition: screenType === 'full' ? {
           top: 0,
-          right: ZOOM_DOCK_RIGHT,
+          right: getZoomDockRight(),
           bottom: 0,
           zIndex: ZOOM_DOCK_Z_INDEX
         } : {
           left: 0,
           right: 0,
-          bottom: ZOOM_DOCK_BOTTOM,
-          height: ZOOM_DOCK_HEIGHT,
+          // 一律是带单位的 px 字符串 —— 裸数字会被当 rpx，见 constants 里 px() 的说明。
+          // 竖屏全屏让出底部工具条（实测高度，避免与 ui.tsx 的写死值不同步）；
+          // 普通竖屏工具条已藏，直接下沉一份底部触摸余量贴住播放器底边。
+          bottom: getZoomDockBottom(isVerticalFull, barHeight),
+          height: getZoomDockHeight(isVerticalFull),
           zIndex: ZOOM_DOCK_Z_INDEX
         },
         initProps: _objectSpread(_objectSpread({}, props), {}, {
@@ -138,6 +168,17 @@ export const ZoomTurntableEntry = props => {
     };
   }, [event, closeDock]);
 
+  /**
+   * 横竖屏切换、竖屏布局切换（展开/收起竖屏全屏）时都先收起转盘。
+   *
+   * dock 的 absolutePosition 只在 addContent 那一刻定死，三套落位差别很大
+   * （横屏右侧 / 竖屏全屏的工具条之上 / 普通竖屏贴播放器底边），
+   * 不收起的话浮层会留在旧位置上 —— 横竖屏之间尤其明显，连朝向都不对。
+   */
+  useEffect(() => {
+    if (dockVisibleRef.current) closeDock();
+  }, [screenType, isVerticalFull, closeDock]);
+
   // 卸载 / 停流时兜底收起
   useEffect(() => {
     if (playState !== PlayState.PLAYING && dockVisibleRef.current) {
@@ -160,19 +201,58 @@ export const ZoomTurntableEntry = props => {
   }, [multiLensReady, lenses.length, event]);
 
   // ---------------- 圈选引导 ----------------
+
+  /**
+   * 把引导收起，并允许之后重新判定一次。
+   *
+   * 引导是挂在 absolute 槽位的浮层，停流 / 进入后台时它还留在最上层 ——
+   * 回到前台会先看见它盖在画面上，紧接着重新拉流把 playState 打断，它又消失，
+   * 观感就是「闪一下」。所以离开时主动收起，等重新出流稳定后再按可见性重新判定。
+   * 注意不写已读标记：用户还没点「知道了」，下次仍应提示。
+   */
+  const dismissTipForRestart = useMemoizedFn(() => {
+    if (!hasContent('absolute', zoomTurntableTipId)) return;
+    deleteContent('absolute', zoomTurntableTipId);
+    tipCheckedRef.current = false;
+  });
+
+  // 进入后台：先收起，避免回前台的第一帧就看到它压在重连画面上
+  usePageEvent('onHide', dismissTipForRestart);
+
+  // 停流 / 重连：同样先收起，等回到 PLAYING 再重新判定
+  useEffect(() => {
+    if (playState !== PlayState.PLAYING) {
+      dismissTipForRestart();
+    }
+  }, [playState, dismissTipForRestart]);
+
+  // 横竖屏切换：入口位置整个变了，旧引导的圈选坐标已失效，必须先收起再按新布局重测。
+  // 不收的话横屏、竖屏两套引导会同时留在屏幕上（absolute 槽位不会自动清理）。
+  useEffect(() => {
+    dismissTipForRestart();
+  }, [screenType, dismissTipForRestart]);
+
   // 入口在横向 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 () => {
+    // 刚出流时布局还在沉降（左下角元素陆续渲染、宽度还在长），等一小会儿再测再展示，
+    // 免得引导刚画好就因为入口位置变化而歪掉，也避免出流瞬间弹出来
+    const timer = setTimeout(async () => {
       // key 不存在时 getStorage 会 fail，这里不能让它把整条链路带崩
       const read = await storage.get(zoomTurntableTipId).catch(() => null);
-      if (cancelled || read) return;
+      if (cancelled) return;
+      // 调试开关打开时忽略已读记录，每次都展示
+      if (read && !FORCE_SHOW_ZOOM_TIP) return;
       const rect = await measureEntryVisible();
       if (cancelled || !rect) return;
       tipCheckedRef.current = true;
+      // ctx.addContent 不按 id 去重，重复添加会在屏幕上留下两份引导，这里先清一次
+      if (hasContent('absolute', zoomTurntableTipId)) {
+        deleteContent('absolute', zoomTurntableTipId);
+      }
       addContent('absolute', {
         id: zoomTurntableTipId,
         content: tipProps => /*#__PURE__*/React.createElement(ZoomTurntableTip, tipProps),
@@ -181,9 +261,10 @@ export const ZoomTurntableEntry = props => {
           anchorRect: rect
         })
       });
-    })();
+    }, TIP_RESHOW_DELAY);
     return () => {
       cancelled = true;
+      clearTimeout(timer);
     };
   }, [disableTip, multiLensReady, playState, screenType, devId]);
 
@@ -254,9 +335,6 @@ export const ZoomTurntableEntry = props => {
         '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),

package/lib/widgets/zoomTurntable/zoomTurntableTip.js

@@ -7,7 +7,7 @@ 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 { FORCE_SHOW_ZOOM_TIP, TIP_LINE_TOTAL, TIP_PANEL_EDGE_GAP, TIP_PANEL_LINE_GAP, TIP_PANEL_WIDTH, TIP_RING_PADDING, zoomTurntableTipId } from './constants';
 import './zoomTurntableTip.less';
 /**
  * 焦距入口圈选引导（一次性）。
@@ -26,51 +26,63 @@ export const ZoomTurntableTip = props => {
   } = useStore({
     playState: props.playState
   });
-  const [ringStyle, setRingStyle] = useState(null);
+  const [layout, setLayout] = useState(null);
 
-  // 把入口的视口坐标换算成播放器容器内坐标
+  // 把入口的视口坐标换算成播放器容器内坐标。
+  // 圈选框按入口实测 rect 自适应：入口是横向倍率胶囊，宽度随镜头数（2 个约 96px、
+  // 3 个约 132px）变化，用固定尺寸框不住。
   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`
+      const ringWidth = anchorRect.width + TIP_RING_PADDING * 2;
+      const ringHeight = anchorRect.height + TIP_RING_PADDING * 2;
+      const ringLeft = anchorRect.left - player.left - TIP_RING_PADDING;
+      const ringBottom = player.bottom - anchorRect.bottom - TIP_RING_PADDING;
+      // 文案面板以圈选中心对齐，但不越出播放器左右边缘
+      const maxLeft = Math.max(player.width - TIP_PANEL_WIDTH - TIP_PANEL_EDGE_GAP, TIP_PANEL_EDGE_GAP);
+      const panelLeft = Math.min(Math.max(ringLeft + ringWidth / 2 - TIP_PANEL_WIDTH / 2, TIP_PANEL_EDGE_GAP), maxLeft);
+      setLayout({
+        ring: {
+          left: `${ringLeft}px`,
+          bottom: `${ringBottom}px`,
+          width: `${ringWidth}px`,
+          height: `${ringHeight}px`
+        },
+        panel: {
+          left: `${panelLeft}px`,
+          bottom: `${ringBottom + ringHeight + TIP_LINE_TOTAL + TIP_PANEL_LINE_GAP}px`,
+          width: `${TIP_PANEL_WIDTH}px`
+        }
       });
     });
     return () => {
       cancelled = true;
     };
   }, [anchorRect]);
-  if (playState !== PlayState.PLAYING || !ringStyle) {
+  if (playState !== PlayState.PLAYING || !layout) {
     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)`
-    }
+    style: layout.ring
+  }), /*#__PURE__*/React.createElement(View, {
+    className: clsx('ipc-player-plugin-zoom-turntable-tip-panel'),
+    style: layout.panel
+  }, /*#__PURE__*/React.createElement(Text, {
+    className: clsx('ipc-player-plugin-zoom-turntable-tip-text')
   }, 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);
+      // 调试开关打开时不落已读标记，免得自测一次就再也看不到
+      if (FORCE_SHOW_ZOOM_TIP) return;
       const storage = new Storage(devId);
       storage.set(zoomTurntableTipId, true);
     }
-  }, Strings.getLang('ipc_player_tip_confirm')));
+  }, Strings.getLang('ipc_player_tip_confirm'))));
 };

package/lib/widgets/zoomTurntable/zoomTurntableTip.less

@@ -10,10 +10,13 @@
   font-size: 14px;
   color: #fff;
 
+  // 圈选框：尺寸与位置按入口实测 rect 由 JS 内联注入。
+  // 入口是横向倍率胶囊，用圆角矩形贴合，不用正圆（正圆框不住宽度、上下还会超出）。
   .ipc-player-plugin-zoom-turntable-tip-ring {
     position: absolute;
+    box-sizing: border-box;
     border: 1px dashed rgba(255, 255, 255, 0.5);
-    border-radius: 50%;
+    border-radius: 12px;
     // 超大扩散阴影把全屏压暗，只露出被圈选的入口
     box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.7);
 
@@ -23,13 +26,13 @@
       position: absolute;
       left: 50%;
       width: 1px;
-      height: 40px;
+      height: 17px;
       box-sizing: border-box;
       border-left: 1px dashed rgba(255, 255, 255, 0.5);
       transform: translateX(-50%) translateY(-100%);
     }
 
-    // 引线末端的小圆点
+    // 引线末端的小圆点：17 虚线 + 4 圆点
     &::before {
       content: '';
       position: absolute;
@@ -38,18 +41,31 @@
       height: 4px;
       border-radius: 50%;
       background-color: rgba(255, 255, 255, 0.5);
-      transform: translateX(-50%) translateY(-44px);
+      transform: translateX(-50%) translateY(-21px);
     }
   }
 
-  .ipc-player-plugin-zoom-turntable-tip-text {
+  // 文案 + 按钮面板：整体定位一次并对齐圈选框中心，内部居中堆叠，
+  // 间距交给布局，不再靠魔法数各自偏移
+  .ipc-player-plugin-zoom-turntable-tip-panel {
     position: absolute;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+  }
+
+  .ipc-player-plugin-zoom-turntable-tip-text {
     max-width: 200px;
+    line-height: 1.4;
+    text-align: center;
   }
 
   .ipc-player-plugin-zoom-turntable-tip-button {
-    position: absolute;
-    padding: 12px 32px;
+    margin-top: 12px;
+    // 比 multiCamera 的 tile-tip（12/32）收紧一圈：引导只是一句短提示，按钮不必那么重
+    padding: 7px 20px;
+    font-size: 12px;
+    line-height: 1.4;
     border: 1px solid rgba(255, 255, 255, 0.5);
     border-radius: 250px;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/ipc-player-integration",
-  "version": "0.0.50-beta.2",
+  "version": "0.0.50-beta.4",
   "description": "IPC 融合播放器",
   "main": "lib/index",
   "files": [