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

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

@@ -13,6 +13,16 @@ export declare const zoomTurntableOpen = "zoomTurntableOpen";
 export declare const zoomTurntableLensChange = "zoomTurntableLensChange";
 /** 事件：画面绝对倍率变化，载荷 { curM, d, lensIndex } */
 export declare const zoomTurntableZoomChange = "zoomTurntableZoomChange";
+/**
+ * 事件：物理镜头切换进行中，载荷 { index }（-1 表示结束）。
+ *
+ * 切换从下发到 channelChange 回来有一段真空期（真机上常常走到 10s 超时兜底），
+ * 这期间镜头下标还没动、读数却已经指向目标值。倍率 tab 要据此把高亮提前落到目标镜头，
+ * 否则原镜头的 tab 会显示目标镜头的数值，看起来就是一次跳变。
+ *
+ * 放事件而不是组件内 state：Entry / Dock 是两个 hook 实例，发起方与消费方常常不是同一个。
+ */
+export declare const zoomTurntableSwitching = "zoomTurntableSwitching";
 /** 长按判定时长（ms） */
 export declare const LONG_PRESS_MS = 500;
 /** 长按期间允许的位移容差（px），超出视为横滑并取消长按 */
@@ -24,11 +34,11 @@ export declare const SWITCH_LENS_TIMEOUT = 3000;
  * 超时按下发结果自己收尾，**不回滚** —— 指令已被受理，物理镜头其实已经切了，
  * 回滚读数只会让读数和画面对不上。
  *
- * 与 SWITCH_LENS_TIMEOUT 取同一档（3s）：设备真正切完镜头本身要一会儿，
+ * 取 10s，比 SWITCH_LENS_TIMEOUT 宽得多：设备真正切完镜头本身要一会儿，
  * 给短了会在事件晚到时提前自己收尾，等于白订阅。
  * 真机现状：设备侧暂未推 channelChange，切镜头基本都靠这条超时收尾。
  */
-export declare const CHANNEL_SETTLE_TIMEOUT = 3000;
+export declare const CHANNEL_SETTLE_TIMEOUT = 10000;
 /**
  * 判定「画面是否正好停在镜头光学正倍数」的容差。
  * 回读的 d 是浮点，1.0 附近会有 1.0000001 这种抖动，严格相等判不出来。
@@ -42,8 +52,6 @@ export declare const QUERY_LENS_TIMEOUT = 3000;
  * 待 APP 提供 zoomFree 的「手势是否结束」参数后可改为由该参数触发。
  */
 export declare const GESTURE_SWITCH_DEBOUNCE = 500;
-/** 横屏 dock 距播放器右边的距离，负值时向右探出 */
-export declare const ZOOM_DOCK_RIGHT = -10;
 /** dock 层级，需高于四角容器的 z-index: 100 */
 export declare const ZOOM_DOCK_Z_INDEX = 120;
 /**
@@ -53,22 +61,46 @@ export declare const ZOOM_DOCK_Z_INDEX = 120;
  */
 export declare const CROP_RATIO_BOTTOM = 0.5;
 /**
- * 触摸响应余量：把 canvas 向外扩一圈，让整个转盘区域（含椭圆上方空白）都能拖动，
- * 而不是只有椭圆截面那一条带。绘制位置由 renderer 补偿，视觉不变。
+ * 触摸响应余量：canvas 是唯一能收 touch 的元素，把它向外扩一圈，
+ * **整个转盘范围（椭圆截面 + 上方文案区 + 两侧空白）都能拖动**，而不是只有刻度线那一带。
+ *
+ * 绘制坐标由 renderer 按同样的余量补偿，视觉不变；下面的 ZOOM_DOCK_BOTTOM /
+ * ZOOM_DOCK_RIGHT 也都从「内容边距」反推，改这两个值不会让转盘位置偏移。
  */
-export declare const HIT_PADDING_X = 16;
-export declare const HIT_PADDING_Y = 24;
+export declare const HIT_PADDING_X = 48;
+export declare const HIT_PADDING_Y = 56;
 /**
  * 竖屏 dock 高度：必须 >= canvas 实际高度（椭圆截面 + 上下触摸余量），
  * 否则承载它的 CoverView 会把转盘裁掉一截。随 CROP_RATIO_BOTTOM / HIT_PADDING_Y 自动跟随，留 8px 余量。
  */
 export declare const ZOOM_DOCK_HEIGHT: number;
 /**
- * 竖屏 dock 距播放器底边的距离。
- * 负值 = 椭圆下半探出播放器底边，由 .ipc-player-content 的 overflow: hidden 裁掉，
- * 保证背景铺满到底边、下方不留空隙。
+ * 竖屏 dock 距播放器底边的距离，固定 0（贴底，不再探出）。
+ *
+ * 这里曾用负值让浮层整体下沉、把椭圆下半探出播放器底边。副作用是 CoverView 顶边
+ * 跟着被压低，canvas 顶部（含刻度线那一带）露在 CoverView 之外被裁掉 —— 原生层裁掉的
+ * 部分收不到 touch，表现就是「只有刻度尺下方能滑，上半部分直接拖到播放器」。
+ * 实测：dock 可命中高度只有 155，而 canvas 高 287.5，顶部溢出 132.5。
+ *
+ * 现在改由 canvas 自己用负 margin 向下探出（见 ZOOM_CANVAS_OVERSHOOT_BOTTOM），
+ * 浮层顶边因此上移，canvas 完整落在可命中区内，而内容视觉位置不变。
+ */
+export declare const ZOOM_DOCK_BOTTOM = 0;
+/**
+ * 竖屏 canvas 底边探出播放器底边的距离。
+ * canvas 在 dock 内底部对齐，靠这个负 margin 下移，使绘制内容仍然铺到播放器底边：
+ *   内容底探出 = ZOOM_CANVAS_OVERSHOOT_BOTTOM - HIT_PADDING_Y
+ * 探出去的部分由 .ipc-player-content 的 overflow: hidden 裁掉，与改动前的观感一致。
  */
-export declare const ZOOM_DOCK_BOTTOM: number;
+export declare const ZOOM_CANVAS_OVERSHOOT_BOTTOM: number;
+/**
+ * 拖动转盘时连续下发缩放的节流间隔（ms）。
+ * 转盘每跨一个 step 就回调一次，不节流会把 setScaleMultiple 打爆；
+ * 松手时 applyZoom 还会按最终值精确下发一次，所以这里丢掉尾值也没关系。
+ */
+export declare const ZOOM_PREVIEW_THROTTLE = 80;
+/** 横屏 dock 距播放器右边的距离，负值时向右探出 */
+export declare const ZOOM_DOCK_RIGHT: number;
 /** 横屏截取比例（右侧展示空间较窄，截得更深） */
 export declare const CROP_RATIO_RIGHT = 0.45;
 /** 布局沉降兜底：onShow / onResize 后的重挂载延时 */

package/lib/widgets/zoomTurntable/constants.js

@@ -19,6 +19,17 @@ export const zoomTurntableLensChange = 'zoomTurntableLensChange';
 /** 事件：画面绝对倍率变化，载荷 { curM, d, lensIndex } */
 export const zoomTurntableZoomChange = 'zoomTurntableZoomChange';
 
+/**
+ * 事件：物理镜头切换进行中，载荷 { index }（-1 表示结束）。
+ *
+ * 切换从下发到 channelChange 回来有一段真空期（真机上常常走到 10s 超时兜底），
+ * 这期间镜头下标还没动、读数却已经指向目标值。倍率 tab 要据此把高亮提前落到目标镜头，
+ * 否则原镜头的 tab 会显示目标镜头的数值，看起来就是一次跳变。
+ *
+ * 放事件而不是组件内 state：Entry / Dock 是两个 hook 实例，发起方与消费方常常不是同一个。
+ */
+export const zoomTurntableSwitching = 'zoomTurntableSwitching';
+
 /** 长按判定时长（ms） */
 export const LONG_PRESS_MS = 500;
 
@@ -33,11 +44,11 @@ export const SWITCH_LENS_TIMEOUT = 3000;
  * 超时按下发结果自己收尾，**不回滚** —— 指令已被受理，物理镜头其实已经切了，
  * 回滚读数只会让读数和画面对不上。
  *
- * 与 SWITCH_LENS_TIMEOUT 取同一档（3s）：设备真正切完镜头本身要一会儿，
+ * 取 10s，比 SWITCH_LENS_TIMEOUT 宽得多：设备真正切完镜头本身要一会儿，
  * 给短了会在事件晚到时提前自己收尾，等于白订阅。
  * 真机现状：设备侧暂未推 channelChange，切镜头基本都靠这条超时收尾。
  */
-export const CHANNEL_SETTLE_TIMEOUT = 3000;
+export const CHANNEL_SETTLE_TIMEOUT = 10000;
 
 /**
  * 判定「画面是否正好停在镜头光学正倍数」的容差。
@@ -55,9 +66,6 @@ export const QUERY_LENS_TIMEOUT = 3000;
  */
 export const GESTURE_SWITCH_DEBOUNCE = 500;
 
-/** 横屏 dock 距播放器右边的距离，负值时向右探出 */
-export const ZOOM_DOCK_RIGHT = -10;
-
 /** dock 层级，需高于四角容器的 z-index: 100 */
 export const ZOOM_DOCK_Z_INDEX = 120;
 
@@ -72,11 +80,14 @@ export const CROP_RATIO_BOTTOM = 0.5;
 const BASE_ELLIPSE_HEIGHT = 351;
 
 /**
- * 触摸响应余量：把 canvas 向外扩一圈，让整个转盘区域（含椭圆上方空白）都能拖动，
- * 而不是只有椭圆截面那一条带。绘制位置由 renderer 补偿，视觉不变。
+ * 触摸响应余量：canvas 是唯一能收 touch 的元素，把它向外扩一圈，
+ * **整个转盘范围（椭圆截面 + 上方文案区 + 两侧空白）都能拖动**，而不是只有刻度线那一带。
+ *
+ * 绘制坐标由 renderer 按同样的余量补偿，视觉不变；下面的 ZOOM_DOCK_BOTTOM /
+ * ZOOM_DOCK_RIGHT 也都从「内容边距」反推，改这两个值不会让转盘位置偏移。
  */
-export const HIT_PADDING_X = 16;
-export const HIT_PADDING_Y = 24;
+export const HIT_PADDING_X = 48;
+export const HIT_PADDING_Y = 56;
 
 /**
  * 竖屏 dock 高度：必须 >= canvas 实际高度（椭圆截面 + 上下触摸余量），
@@ -85,18 +96,51 @@ export const HIT_PADDING_Y = 24;
 export const ZOOM_DOCK_HEIGHT = Math.ceil(BASE_ELLIPSE_HEIGHT * CROP_RATIO_BOTTOM) + HIT_PADDING_Y * 2 + 8;
 
 /**
- * 内容顶部到播放器底边的距离（视觉基准）。
- * dock 是 bottom 定位、内容从顶部往下画，所以顶部位置 = 该值，与截取比例无关 ——
- * 改 CROP_RATIO_BOTTOM 只影响背景往下探多深，不会动到当前倍率文案与刻度的位置。
+ * 绘制内容（椭圆截面）顶边到播放器底边的距离 —— 真正的视觉基准。
+ *
+ * canvas 在 dock 内是底部对齐的，内容在 canvas 里又偏移了一份 HIT_PADDING_Y，
+ * 所以位置要从内容边界反推、而不是从 dock 边界反推，否则一改触摸余量转盘就整体挪位。
+ *   内容顶距播放器底 = 截面高 + HIT_PADDING_Y + ZOOM_DOCK_BOTTOM
+ */
+const ZOOM_CONTENT_TOP_GAP = 137;
+
+/**
+ * 竖屏 dock 距播放器底边的距离，固定 0（贴底，不再探出）。
+ *
+ * 这里曾用负值让浮层整体下沉、把椭圆下半探出播放器底边。副作用是 CoverView 顶边
+ * 跟着被压低，canvas 顶部（含刻度线那一带）露在 CoverView 之外被裁掉 —— 原生层裁掉的
+ * 部分收不到 touch，表现就是「只有刻度尺下方能滑，上半部分直接拖到播放器」。
+ * 实测：dock 可命中高度只有 155，而 canvas 高 287.5，顶部溢出 132.5。
+ *
+ * 现在改由 canvas 自己用负 margin 向下探出（见 ZOOM_CANVAS_OVERSHOOT_BOTTOM），
+ * 浮层顶边因此上移，canvas 完整落在可命中区内，而内容视觉位置不变。
+ */
+export const ZOOM_DOCK_BOTTOM = 0;
+
+/**
+ * 竖屏 canvas 底边探出播放器底边的距离。
+ * canvas 在 dock 内底部对齐，靠这个负 margin 下移，使绘制内容仍然铺到播放器底边：
+ *   内容底探出 = ZOOM_CANVAS_OVERSHOOT_BOTTOM - HIT_PADDING_Y
+ * 探出去的部分由 .ipc-player-content 的 overflow: hidden 裁掉，与改动前的观感一致。
  */
-const ZOOM_DOCK_TOP_GAP = 169;
+export const ZOOM_CANVAS_OVERSHOOT_BOTTOM = Math.ceil(BASE_ELLIPSE_HEIGHT * CROP_RATIO_BOTTOM) + HIT_PADDING_Y - ZOOM_CONTENT_TOP_GAP;
 
 /**
- * 竖屏 dock 距播放器底边的距离。
- * 负值 = 椭圆下半探出播放器底边，由 .ipc-player-content 的 overflow: hidden 裁掉，
- * 保证背景铺满到底边、下方不留空隙。
+ * 横屏内容右边相对播放器右边的内缩距离（视觉基准）。
+ * canvas 在 dock 内右对齐，内容右边又内缩一份 HIT_PADDING_Y（横屏画布旋转 90°）：
+ *   内容右边内缩 = ZOOM_DOCK_RIGHT + HIT_PADDING_Y
  */
-export const ZOOM_DOCK_BOTTOM = ZOOM_DOCK_TOP_GAP - ZOOM_DOCK_HEIGHT;
+const ZOOM_CONTENT_RIGHT_INSET = 14;
+
+/**
+ * 拖动转盘时连续下发缩放的节流间隔（ms）。
+ * 转盘每跨一个 step 就回调一次，不节流会把 setScaleMultiple 打爆；
+ * 松手时 applyZoom 还会按最终值精确下发一次，所以这里丢掉尾值也没关系。
+ */
+export const ZOOM_PREVIEW_THROTTLE = 80;
+
+/** 横屏 dock 距播放器右边的距离，负值时向右探出 */
+export const ZOOM_DOCK_RIGHT = ZOOM_CONTENT_RIGHT_INSET - HIT_PADDING_Y;
 
 /** 横屏截取比例（右侧展示空间较窄，截得更深） */
 export const CROP_RATIO_RIGHT = 0.45;

package/lib/widgets/zoomTurntable/lensModel.test.js

@@ -97,7 +97,7 @@ describe('ipc_multi_zoom 上报值解析', () => {
     });
     expect(zoomBounds(skill)).toEqual([1, 6]);
   });
-  it('对象值直接透传（调试注入 mockZoomSkill）', () => {
+  it('对象值直接透传（内部 mock 常量）', () => {
     expect(parseZoomSkill(DOUBLE)).toBe(DOUBLE);
   });
   it('空值 / 畸形 JSON 返回 null，不抛错', () => {

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

@@ -53,7 +53,7 @@ export declare const lensCount: (skill?: ZoomSkill | null) => number;
 export declare const isZoomSkillValid: (skill?: ZoomSkill | null) => boolean;
 /**
  * 解析 ipc_multi_zoom DP 上报的 string 值为镜头能力。
- * @param value DP 值；调试注入的对象（mockZoomSkill）直接透传，两条来源共用同一校验链路
+ * @param value DP 值；内部 mock 常量是对象、DP 上报是 string，两条来源共用同一校验链路
  */
 export declare const parseZoomSkill: (value?: unknown) => ZoomSkill | null;
 /**

package/lib/widgets/zoomTurntable/lensSkill.js

@@ -90,7 +90,7 @@ export const isZoomSkillValid = skill => {
 
 /**
  * 解析 ipc_multi_zoom DP 上报的 string 值为镜头能力。
- * @param value DP 值；调试注入的对象（mockZoomSkill）直接透传，两条来源共用同一校验链路
+ * @param value DP 值；内部 mock 常量是对象、DP 上报是 string，两条来源共用同一校验链路
  */
 export const parseZoomSkill = value => {
   if (value == null || value === '') return null;

package/lib/widgets/zoomTurntable/turntable/index.js

@@ -30,6 +30,9 @@ const ZoomTurntable = props => {
     styleOptions = {}
   } = props;
   const canvasId = useRef(`ipc-zoom-turntable-${++canvasIdCounter}`).current;
+
+  // 起始值兜底：非受控用法下没有后续回写纠正，非法初值会让指针停在 0.0X
+  const safeDefaultValue = Number(defaultValue) > 0 ? Math.min(max, Math.max(min, Number(defaultValue))) : min;
   console.log('[zoomTurntable/logic] render', JSON.stringify({
     canvasId,
     min,
@@ -45,7 +48,7 @@ const ZoomTurntable = props => {
     min: min,
     max: max,
     step: step,
-    defaultValue: defaultValue,
+    defaultValue: safeDefaultValue,
     value: controlledValue,
     scale: scale,
     orientation: orientation,

package/lib/widgets/zoomTurntable/turntable/rjs/index.rjs

@@ -29,6 +29,15 @@ const MINOR_DIVS = 60;
 const MAJOR_SKIP = 0.004;
 const LABEL_WINDOW = 0.28;
 const TOP_SAFE_AREA = 50;
+// 点击（非拖动）判定：手指位移与按压时长都在阈值内才算 tap
+const TAP_MOVE_TOLERANCE = 10;
+const TAP_MAX_MS = 350;
+// tap 命中弧带的归一化半径范围（1 = 刻度轨道所在的椭圆）。
+// 太靠圆心或太靠外都不算点刻度，直接忽略，避免误触把倍率甩飞。
+const TAP_HIT_MIN_R = 0.55;
+const TAP_HIT_MAX_R = 1.4;
+// 点击后滚到目标刻度的动画时长（ms）
+const TAP_ANIM_MS = 220;
 // 拖动方向：-1 表示「拖动的是转盘本身」——向左拖，盘面左移，右侧的大刻度转到指针处，倍率变大，
 // 与实体相机的调焦环手感一致；+1 则是「拖动指针」的反向手感。
 const DRAG_DIRECTION = -1;
@@ -56,7 +65,11 @@ class ZoomTurntableRenderer {
       : this._style('cropRatio', 0.2);
     this.callMethod = options.callMethod;
 
-    this.value = options.defaultValue != null ? options.defaultValue : this.min;
+    // 起始值必须落在 [min, max] 内：外部传进来的初值可能是尚未就绪的占位值（0 / NaN），
+    // 非受控模式下没有后续回写来纠正，直接夹住
+    var initial = Number(options.defaultValue);
+    if (!(initial > 0)) initial = this.min;
+    this.value = Math.max(this.min, Math.min(this.max, initial));
     // progress(0~1) 是拖动时的唯一真相，保持浮点，避免 step 量化造成的抖动
     this.progress = this.getProgress(this.value);
     this.dragging = false;
@@ -527,6 +540,8 @@ class ZoomTurntableRenderer {
     this.lastTouchPoint = this.orientation === 'right'
       ? touch.clientY - rectTop
       : touch.clientX - rectLeft;
+    // tap 判定的起点：位移 / 时长都在阈值内，touchend 时按「点击刻度」处理
+    this._tapStart = { x: touch.clientX, y: touch.clientY, t: Date.now(), moved: false };
     dlog('touchstart lastTouchPoint=' + this.lastTouchPoint, 'value=' + this.value);
   }
 
@@ -549,6 +564,15 @@ class ZoomTurntableRenderer {
       ? touch.clientY - rectTop
       : touch.clientX - rectLeft;
 
+    if (this._tapStart && !this._tapStart.moved) {
+      if (
+        Math.abs(touch.clientX - this._tapStart.x) > TAP_MOVE_TOLERANCE ||
+        Math.abs(touch.clientY - this._tapStart.y) > TAP_MOVE_TOLERANCE
+      ) {
+        this._tapStart.moved = true;
+      }
+    }
+
     // 像素增量直接映射到「值」的等量变化，而非 progress；
     // 这样无论处于高倍率还是低倍率端，等量滑动产生等量值变化，手感一致（消除 log 曲线导致的两端灵敏度差异）。
     var deltaX = (currentPoint - this.lastTouchPoint) * DRAG_DIRECTION; // 本次拖动的像素增量（含方向修正）
@@ -579,19 +603,118 @@ class ZoomTurntableRenderer {
     this._scheduleRender();
   }
 
-  _handTouchEnd() {
+  _handTouchEnd(e) {
     dlog('touchend/cancel 触发', 'dragging=' + this.dragging, 'value=' + this.value);
-    if (this.dragging) {
-      this.dragging = false;
+    var wasDragging = this.dragging;
+    this.dragging = false;
+
+    // 没怎么移动、按得也短 —— 当作「点击某个刻度」，直接滚过去并下发
+    var tapped = false;
+    if (wasDragging && this._tapStart && !this._tapStart.moved &&
+        Date.now() - this._tapStart.t <= TAP_MAX_MS) {
+      var touch = e && ((e.changedTouches && e.changedTouches[0]) || (e.touches && e.touches[0]));
+      if (touch) {
+        tapped = this._handleTapAt(touch.clientX, touch.clientY);
+      }
+    }
+    this._tapStart = null;
+
+    if (wasDragging) {
       this._cachedRect = null;
-      // 300ms 冷却期，吸收跨线程残余的 onChange 回写，避免松手后闪动
-      this._cooldownUntil = Date.now() + 300;
-      this.callMethod('onChangeEnd', this.value);
+      // tap 命中时由动画结束统一发 onChange / onChangeEnd，这里不能再按旧值发一次
+      if (!tapped) {
+        // 300ms 冷却期，吸收跨线程残余的 onChange 回写，避免松手后闪动
+        this._cooldownUntil = Date.now() + 300;
+        this.callMethod('onChangeEnd', this.value);
+      }
     }
     // 无论是否处于拖动，都要恢复原生手势，避免异常路径下 nativeDisabled 卡在 true
     this.callMethod('onTouchEnd');
   }
 
+  /**
+   * canvas 内坐标 → 绘制坐标系（逆掉 _render 里的 translate / rotate）。
+   * 竖屏只有一次平移；横屏画布整体旋转过 -90°，要连旋转一起逆算。
+   */
+  _drawPointFromCanvas(cx, cy) {
+    var offX = -this.viewportLeft + (this.hitPaddingX || 0);
+    var offY = -this.viewportTop + (this.hitPaddingY || 0) + (this.contentOffsetY || 0);
+    if (this.orientation === 'right') {
+      // 正变换：canvas = ( py + offY, baseWidth - (px + offX) )
+      return { x: this.baseWidth - cy - offX, y: cx - offY };
+    }
+    return { x: cx - offX, y: cy - offY };
+  }
+
+  /**
+   * 点击刻度：由触点反推该处对应的倍率。
+   *
+   * 刻度盘整体旋转 rotation = POINTER_ANGLE - getAngle(progress)，所以某个 p 的绘制角
+   *   angle(p) = POINTER_ANGLE + (p - progress) * ARC_SPAN
+   * 反过来由触点的椭圆参数角 θ 就能解出 p：
+   *   p = progress + (θ - POINTER_ANGLE) / ARC_SPAN
+   *
+   * @returns {boolean} 是否命中刻度带（未命中则按普通 touchend 走）
+   */
+  _handleTapAt(clientX, clientY) {
+    var rect = this._cachedRect;
+    if (!rect) return false;
+    var pt = this._drawPointFromCanvas(clientX - rect.left, clientY - rect.top);
+    // 归一化到单位圆：半径 1 即刻度轨道所在的椭圆
+    var nx = (pt.x - this.CX) / this.rx;
+    var ny = (pt.y - this.CY) / this.ry;
+    var r = Math.sqrt(nx * nx + ny * ny);
+    if (r < TAP_HIT_MIN_R || r > TAP_HIT_MAX_R) {
+      dlog('tap 未命中刻度带，忽略', 'r=' + r.toFixed(2));
+      return false;
+    }
+    var theta = Math.atan2(ny, nx) * RAD_TO_DEG;
+    if (theta < 0) theta += 360; // 上半椭圆对应 [180, 360]
+    if (theta < START_ANGLE || theta > END_ANGLE) {
+      dlog('tap 角度超出弧段，忽略', 'theta=' + theta.toFixed(1));
+      return false;
+    }
+    var p = this.progress + (theta - POINTER_ANGLE) / ARC_SPAN;
+    if (p < 0) p = 0;
+    else if (p > 1) p = 1;
+    var target = this._snapValue(this._valueFromProgress(p));
+    dlog('tap 命中', 'theta=' + theta.toFixed(1), 'r=' + r.toFixed(2), 'target=' + target);
+    // 点的就是当前值：算命中（不再按旧值重复下发），但不用动
+    if (Math.abs(target - this.value) < this.step * 0.5) return true;
+    this._animateTo(target);
+    return true;
+  }
+
+  /** 点击后滚到目标刻度：动画期间只重绘，落位后才发一次 onChange + onChangeEnd */
+  _animateTo(target) {
+    var self = this;
+    var from = this.value;
+    var startAt = Date.now();
+    var raf = this._getRaf();
+    // 动画期间屏蔽外部受控回写，否则会被 value 回写打断
+    this._cooldownUntil = startAt + TAP_ANIM_MS + 300;
+    var tick = function () {
+      var t = (Date.now() - startAt) / TAP_ANIM_MS;
+      if (t > 1) t = 1;
+      var eased = 1 - Math.pow(1 - t, 3); // ease-out cubic
+      var v = from + (target - from) * eased;
+      self.value = self._snapValue(v);
+      self.progress = self.getProgress(self.value);
+      self._scheduleRender();
+      if (t < 1) {
+        raf(tick);
+        return;
+      }
+      self.value = target;
+      self.progress = self.getProgress(target);
+      self._scheduleRender();
+      self._cooldownUntil = Date.now() + 300;
+      self.callMethod('onChange', target);
+      self.callMethod('onChangeEnd', target);
+    };
+    raf(tick);
+  }
+
   setupEventListeners() {
     dlog(
       'setupEventListeners',
@@ -608,12 +731,18 @@ class ZoomTurntableRenderer {
     this.handTouchStart = this._handTouchStart.bind(this);
     this.handTouchMove = this._handTouchMove.bind(this);
     this.handTouchEnd = this._handTouchEnd.bind(this);
+    // 手势被系统打断走的是 cancel，不能当作「点击刻度」，先把 tap 起点清掉再收尾
+    var self = this;
+    this.handTouchCancel = function (e) {
+      self._tapStart = null;
+      self._handTouchEnd(e);
+    };
     this.canvas.addEventListener('touchstart', this.handTouchStart, false);
     this.canvas.addEventListener('touchmove', this.handTouchMove, false);
     this.canvas.addEventListener('touchend', this.handTouchEnd, false);
     // 手势被系统打断时 touchend 不会派发，必须补 touchcancel，
     // 否则 ty.nativeDisabled 会卡在 true，之后播放器所有原生手势都失效
-    this.canvas.addEventListener('touchcancel', this.handTouchEnd, false);
+    this.canvas.addEventListener('touchcancel', this.handTouchCancel, false);
   }
 
   destroy() {
@@ -627,7 +756,7 @@ class ZoomTurntableRenderer {
       this.canvas.removeEventListener('touchstart', this.handTouchStart, false);
       this.canvas.removeEventListener('touchmove', this.handTouchMove, false);
       this.canvas.removeEventListener('touchend', this.handTouchEnd, false);
-      this.canvas.removeEventListener('touchcancel', this.handTouchEnd, false);
+      this.canvas.removeEventListener('touchcancel', this.handTouchCancel, false);
     }
   }
 }

package/lib/widgets/zoomTurntable/turntable/rjs/index.tyml

@@ -3,5 +3,6 @@
      而该伴生文件不在 lib 产物里，会报 Cannot find module './ray-styles.tyss' -->
 <canvas
   canvas-id="{{canvasId}}"
+  class="ipc-zoom-turntable-canvas"
   style="display: block; width: {{canvasWidth}}px; height: {{canvasHeight}}px;"
 ></canvas>

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

@@ -1,10 +1,7 @@
 import { ComponentConfigProps } from '../../interface';
-import { ZoomSkill } from './lensSkill';
 type Options = ComponentConfigProps & {
     /** 业务侧的功能开关；实际是否渲染仍由 ipc_multi_zoom 解析出的 cnt 决定 */
     showZoomTurntable?: boolean;
-    /** 调试用：直接注入镜头能力，跳过 ipc_multi_zoom DP 解析 */
-    mockZoomSkill?: ZoomSkill | boolean;
     /** 跳过能力加载：Entry 常驻负责加载，Dock 作为消费方传 true 避免重复解析 */
     skipLoad?: boolean;
 };
@@ -15,10 +12,12 @@ type Options = ComponentConfigProps & {
 export declare const useLensZoom: (options: Options) => {
     /** 是否具备多镜头变焦能力（不具备则整个 widget 不出现） */
     multiLensReady: boolean;
-    zoomSkill: ZoomSkill | null;
+    zoomSkill: import("./lensSkill").ZoomSkill | null;
     /** 镜头列表（按 value 升序），用于渲染倍率 tab */
     lenses: import("./lensSkill").Lens[];
     lensIndex: number;
+    /** 正在切往的目标镜头下标；-1 表示没有切换进行中 */
+    switchingIndex: number;
     /** 画面绝对倍率 */
     curM: number;
     min: number;