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

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

@@ -1,5 +1,5 @@
 // 手势 / 初始化链路日志开关。定位手势问题期间打开，稳定后置 false。
-const DEBUG_GESTURE = true;
+const DEBUG_GESTURE = false;
 function dlog() {
   if (!DEBUG_GESTURE) return;
   var args = Array.prototype.slice.call(arguments);
@@ -16,8 +16,12 @@ const END_ANGLE = 360;
 const ARC_SPAN = END_ANGLE - START_ANGLE;
 // 指针固定在弧线中点（顶部）
 const POINTER_ANGLE = START_ANGLE + ARC_SPAN / 2;
-// 轨道半径是遮罩半径的 5/6，整体比遮罩稍收一点
-const TRACK_TO_MASK_RATIO = 5/6;
+// 线宽 / 虚线 / 圆点 / 标签偏移这类几何元素的缩放系数。
+// 数值沿用旧的轨道比例 5/6，保证轨道改成等距内收后这些细节尺寸不变。
+const GEO_SCALE = 5 / 6;
+// 轨道相对遮罩的默认内收距离（scale=1 时的 px），可由 styleOptions.trackEdgeInset 覆盖。
+// 两条弧线按「同一个绝对间距」内收，而不是按同一个比例 —— 原因见 _computeGeometry。
+const DEFAULT_TRACK_EDGE_INSET = 30;
 // 遮罩本身也保持同一椭圆比例
 const MASK_RX_RATIO = 1;
 const MASK_RY_RATIO = 1;
@@ -29,9 +33,32 @@ 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;
+/**
+ * 横屏的位移轴向修正。
+ *
+ * 横屏画布整体 `translate(0, baseWidth) + rotate(-90°)`，绘制 x 轴因此映射到屏幕的**向上**方向 ——
+ * progress 越大（倍率越大）的刻度落在屏幕越上方。而手势取的是 clientY（向下为正），
+ * 与绘制 x 轴正好反向，不补这一下 DRAG_DIRECTION 在横屏就被翻转成「拖动指针」的手感：
+ * 向上拖倍率变大，跟实体相机的调焦环相反。
+ *
+ * 补上之后横竖屏统一为「拖动盘面」：竖屏向左拖 = 把右侧的大刻度拖到指针处 = 变大；
+ * 横屏向下拖 = 把上方的大刻度拖到指针处 = 变大。
+ */
+const RIGHT_AXIS_SIGN = -1;
+// 遮罩平底边向外多铺的像素，抵消亚像素舍入造成的 1px 缝
+const EDGE_OVERFILL = 1.5;
 
 class ZoomTurntableRenderer {
   constructor(options) {
@@ -56,7 +83,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;
@@ -96,13 +127,31 @@ class ZoomTurntableRenderer {
     this.scale = contentScale;
     this.scaleX = contentScale;
     this.scaleY = contentScale;
-    this.maskRx = BASE_RX * contentScale * MASK_RX_RATIO;
-    this.maskRy = BASE_RY * contentScale * MASK_RY_RATIO;
-    // 轨道（含刻度点、指针）与标记文字整体向椭圆内侧收，加大它们与遮罩边缘的距离。
+    // 横半径同样允许被 styleOptions.ellipseRx 覆盖。竖屏必须跟着窗口宽度缩放：
+    // 弧顶到屏幕两侧的落差取决于「屏幕半宽 / 横半径」这个比值，横半径写死 258 的话，
+    // 屏幕越宽落差越大（430 宽机型上两侧只剩 15px），各机型弧形就不一致了。
+    this.maskRx = this._style('ellipseRx', BASE_RX) * contentScale * MASK_RX_RATIO;
+    // 纵半径允许被 styleOptions.ellipseRy 覆盖：竖屏要求整条背景带只有 ~70px 高，
+    // 按设计稿比例（516:351）的椭圆装不下。这里只压扁纵向、不动横向 ——
+    // 整体缩小会让背景撑不满播放器宽度，两侧会露出直角缺口。
+    this.maskRy = this._style('ellipseRy', BASE_RY) * contentScale * MASK_RY_RATIO;
+    // 轨道（含刻度点、指针）与标记文字向椭圆内侧「等距」收一圈：rx、ry 各减同一个绝对值，
+    // 而不是各乘同一个比例。按比例收的话弧顶间距 = maskRy × k、两侧间距 = maskRx × k，
+    // 椭圆越扁两者差得越多（旧的 5/6 + inset 方案在竖屏是弧顶 39px / 两侧 65px），
+    // 外圈背景看起来就比内部描边更扁；等距内收才是一对弧度一致的平行弧。
     // 遮罩半径不变，所以 canvas 尺寸与截面都不受影响。
-    this.trackEdgeInset = this._style('trackEdgeInset', 0) * contentScale;
-    this.rx = this.maskRx * TRACK_TO_MASK_RATIO - this.trackEdgeInset;
-    this.ry = this.maskRy * TRACK_TO_MASK_RATIO - this.trackEdgeInset;
+    this.trackEdgeInset = this._style('trackEdgeInset', DEFAULT_TRACK_EDGE_INSET) * contentScale;
+    this.ry = this.maskRy - this.trackEdgeInset;
+    /**
+     * 轨道横半径可以单独指定（styleOptions.trackRx），不指定就跟纵向一样等距内收。
+     *
+     * 竖屏要的是「虚线弧两端扎出播放器底边」：轨道椭圆比播放器窄一些，弧才会在到达
+     * 屏幕左右边缘之前先降到底边以下、被 canvas 底边切断。若沿用等距内收（横半径只比
+     * 遮罩小一个 inset），轨道就跟着遮罩一起铺得很宽、两端贴着播放器左右下角擦出去，
+     * 看着就是「顶到最左最右」。反推见 constants 的 getTrackRxBottom。
+     */
+    var trackRxOverride = this._style('trackRx', 0) * contentScale;
+    this.rx = trackRxOverride > 0 ? trackRxOverride : this.maskRx - this.trackEdgeInset;
     var fullWidth = this.maskRx * 2; // 完整椭圆的理论宽度
     this.CX = fullWidth / 2; // 椭圆在完整坐标系里水平居中
     this.topSafeArea = this._style('topSafeArea', TOP_SAFE_AREA) * contentScale;
@@ -129,6 +178,13 @@ class ZoomTurntableRenderer {
     // 这里把画布向外扩一圈，绘制坐标同步补偿，视觉不变但整个转盘区域都可拖动。
     this.hitPaddingX = this._style('hitPaddingX', 0) * contentScale;
     this.hitPaddingY = this._style('hitPaddingY', 0) * contentScale;
+    // 上下余量可分别覆盖，默认都取 hitPaddingY。
+    // 竖屏底部必须传 0：转盘贴着播放器底边，底边以下的余量既摸不到（原生层已裁），
+    // 又会把 canvas 底边推到播放器之外 —— 而 CoverView 里负 margin 并不可靠，
+    // 一旦不生效，canvas 底边就停在播放器底边，绘制内容整体被顶高一截、下面还留一条缝。
+    this.hitPaddingTop = this._style('hitPaddingTop', this._style('hitPaddingY', 0)) * contentScale;
+    this.hitPaddingBottom =
+      this._style('hitPaddingBottom', this._style('hitPaddingY', 0)) * contentScale;
 
     this.viewportLeft = this.CX - cropHalfWidth;
     this.viewportTop = this.topSafeArea;
@@ -138,8 +194,11 @@ class ZoomTurntableRenderer {
     this.drawWidth = this.viewportRight - this.viewportLeft;
     this.drawHeight = this.viewportBottom - this.viewportTop;
     // 画布尺寸 = 椭圆截面 + 触摸响应余量（两侧 / 上下各扩一份）
-    this.baseWidth = this.drawWidth + this.hitPaddingX * 2;
-    this.baseHeight = this.drawHeight + this.hitPaddingY * 2;
+    // 向上取整：截面宽高是浮点，原生层按整数像素布局，取整不足会把最外侧那一行像素裁掉，
+    // 表现就是「有些机型边缘露 1px 空白」。取整后 canvas 略大于内容，边缘那点空隙由
+    // 遮罩的 EDGE_OVERFILL 铺满。**必须与 index.js 的 computeCanvasViewport 用同一套公式**。
+    this.baseWidth = Math.ceil(this.drawWidth + this.hitPaddingX * 2);
+    this.baseHeight = Math.ceil(this.drawHeight + this.hitPaddingTop + this.hitPaddingBottom);
     // 横屏侧边展示时，绘制坐标系先整体旋转 90 度，所以 canvas 宽高也要交换。
     this.WIDTH = this.orientation === 'right' ? this.baseHeight : this.baseWidth;
     this.HEIGHT = this.orientation === 'right' ? this.baseWidth : this.baseHeight;
@@ -259,7 +318,7 @@ class ZoomTurntableRenderer {
   _render() {
     var ctx = this.ctx;
     var s = this.scale;
-    var geo = s * TRACK_TO_MASK_RATIO;
+    var geo = s * GEO_SCALE;
     ctx.clearRect(0, 0, this.WIDTH, this.HEIGHT);
     ctx.save();
     if (this.orientation === 'right') {
@@ -272,7 +331,7 @@ class ZoomTurntableRenderer {
     // 画布因触摸余量向外扩过，绘制原点要补偿回来，保证视觉位置不变
     ctx.translate(
       -this.viewportLeft + (this.hitPaddingX || 0),
-      -this.viewportTop + (this.hitPaddingY || 0) + (this.contentOffsetY || 0)
+      -this.viewportTop + (this.hitPaddingTop || 0) + (this.contentOffsetY || 0)
     );
 
     // 刻度盘角度位移：让当前 progress 对应的刻度转到指针处。
@@ -303,8 +362,10 @@ class ZoomTurntableRenderer {
       this.maskVisibleEndAngle * DEG_TO_RAD,
       false
     );
-    ctx.lineTo(this.viewportRight, this.viewportBottom);
-    ctx.lineTo(this.viewportLeft, this.viewportBottom);
+    // 平底边多铺 EDGE_OVERFILL：这条边在竖屏落在播放器底边、横屏落在屏幕右缘，
+    // 亚像素舍入下差一点就露出一条 1px 的画面缝，多铺一点由画布边界裁掉，观感无差别。
+    ctx.lineTo(this.viewportRight, this.viewportBottom + EDGE_OVERFILL);
+    ctx.lineTo(this.viewportLeft, this.viewportBottom + EDGE_OVERFILL);
     ctx.closePath();
     ctx.fillStyle = 'rgba(0,0,0,' + this._style('overlayOpacity', 0.44) + ')';
     ctx.fill();
@@ -325,13 +386,33 @@ class ZoomTurntableRenderer {
     var dotRx = this.rx; // 刻度点所在椭圆的横半径
     var dotRy = this.ry; // 刻度点所在椭圆的纵半径
     var isRightOrientation = this.orientation === 'right'; // 是否为横屏侧边模式
+    var markFontSize = this._style('markLabelFontSize', 14) * s; // 刻度字号
+    var currentFontSize =
+      this._style('currentLabelFontSize', this._style('markLabelFontSize', 14)) * s; // 当前值字号
+    /**
+     * 文案「顶边到遮罩弧」的固定留白（scale=1 时的 px），传了才启用。
+     *
+     * 竖屏背景带很矮，文案位置必须以遮罩弧为基准 —— 原来按轨道弧往外推 18px，
+     * 一旦调整轨道间距（trackEdgeInset）文案就跟着上下窜，还会两种字号各错开一点。
+     * 这里改成让文案椭圆与遮罩椭圆**等距内收**：内收量 = 留白 + 半个字高 + 绘制时的 2px 上移补偿，
+     * 于是不同字号的文案顶边落在同一条线上、且沿整条弧都与背景边缘保持同样的留白。
+     */
+    var labelTopGap = this._style('labelTopGap', -1);
+    var markLabelInset =
+      labelTopGap >= 0 ? labelTopGap * s + markFontSize / 2 + 2 * s : null;
+    var currentLabelInset =
+      labelTopGap >= 0 ? labelTopGap * s + currentFontSize / 2 + 2 * s : null;
     // 横屏侧边模式时，标签朝椭圆内侧收；底部模式则往外侧展开一点，保证和弧线拉开距离。
     var labelRx = isRightOrientation
       ? this.rx - this._style('innerLabelOffsetX', 22) * geo
-      : this.rx + 4 * geo;
+      : markLabelInset != null
+        ? this.maskRx - markLabelInset
+        : this.rx + 4 * geo;
     var labelRy = isRightOrientation
       ? this.ry - this._style('innerLabelOffsetY', 22) * geo
-      : this.ry + 18 * geo;
+      : markLabelInset != null
+        ? this.maskRy - markLabelInset
+        : this.ry + 18 * geo;
     var marks = this.marks || [];
     if (marks.length > 0) {
       ctx.textAlign = 'center';
@@ -353,7 +434,7 @@ class ZoomTurntableRenderer {
         var lx = this.CX + labelRx * Math.cos(mRad); // 刻度文字 x 坐标
         var ly = this.CY + labelRy * Math.sin(mRad); // 刻度文字 y 坐标
         ctx.fillStyle = 'rgba(255,255,255,' + (0.76 - Math.abs(progressOffset) * 1.5) + ')';
-        ctx.font = '500 ' + (this._style('markLabelFontSize', 14) * s) + 'px sans-serif';
+        ctx.font = '500 ' + markFontSize + 'px sans-serif';
         this._fillText(this._normalizeLabel(marks[k].label, marks[k].value), lx, ly - 2 * s);
       }
     }
@@ -362,10 +443,18 @@ class ZoomTurntableRenderer {
     var pointerRad = POINTER_ANGLE * DEG_TO_RAD; // 指针在椭圆上的固定角度
     var px = this.CX + this.rx * Math.cos(pointerRad); // 指针圆环中心 x
     var py = this.CY + this.ry * Math.sin(pointerRad); // 指针圆环中心 y
-    // 当前值文字和普通刻度标签共用同一套 labelRx/labelRy，保证位置、字号和节奏一致。
-    var currentLabelRx = labelRx;
+    // 当前值文字与普通刻度共用同一套基准：启用 labelTopGap 时各按自己的字号算内收量，
+    // 两种字号的顶边因此对齐同一条线；没启用时沿用旧的 labelRx/labelRy。
+    var currentLabelRx =
+      !isRightOrientation && currentLabelInset != null
+        ? this.maskRx - currentLabelInset
+        : labelRx;
     // 横屏右侧时当前值文字再往内侧让一点，避免和固定光标圆环重合。
-    var currentLabelRy = isRightOrientation ? labelRy - 10 * geo : labelRy;
+    var currentLabelRy = isRightOrientation
+      ? labelRy - 10 * geo
+      : currentLabelInset != null
+        ? this.maskRy - currentLabelInset
+        : labelRy;
     var currentLabelX = this.CX + currentLabelRx * Math.cos(pointerRad); // 当前值文字 x
     var currentLabelY = this.CY + currentLabelRy * Math.sin(pointerRad); // 当前值文字 y
     ctx.beginPath();
@@ -381,7 +470,7 @@ class ZoomTurntableRenderer {
     ctx.textAlign = 'center';
     ctx.textBaseline = 'middle';
     ctx.fillStyle = this.activeColor;
-    ctx.font = '700 ' + (this._style('currentLabelFontSize', this._style('markLabelFontSize', 14)) * s) + 'px sans-serif';
+    ctx.font = '700 ' + currentFontSize + 'px sans-serif';
     this._fillText(this._formatValue(this.value), currentLabelX, currentLabelY - 2 * s);
     ctx.restore();
   }
@@ -457,6 +546,10 @@ class ZoomTurntableRenderer {
     var prevTopSafeArea = this._style('topSafeArea', TOP_SAFE_AREA); // 上一次顶部安全区
     var prevHitPaddingX = this._style('hitPaddingX', 0); // 上一次横向触摸余量
     var prevHitPaddingY = this._style('hitPaddingY', 0); // 上一次纵向触摸余量
+    var prevHitPaddingTop = this._style('hitPaddingTop', prevHitPaddingY); // 上一次上余量
+    var prevHitPaddingBottom = this._style('hitPaddingBottom', prevHitPaddingY); // 上一次下余量
+    var prevEllipseRx = this._style('ellipseRx', BASE_RX); // 上一次椭圆横半径
+    var prevEllipseRy = this._style('ellipseRy', BASE_RY); // 上一次椭圆纵半径
     if (options.min != null) this.min = options.min;
     if (options.max != null) this.max = options.max;
     if (options.step != null) this.step = options.step;
@@ -475,7 +568,11 @@ class ZoomTurntableRenderer {
       this.cropRatio !== prevCropRatio ||
       nextTopSafeArea !== prevTopSafeArea ||
       this._style('hitPaddingX', 0) !== prevHitPaddingX ||
-      this._style('hitPaddingY', 0) !== prevHitPaddingY;
+      this._style('hitPaddingY', 0) !== prevHitPaddingY ||
+      this._style('hitPaddingTop', this._style('hitPaddingY', 0)) !== prevHitPaddingTop ||
+      this._style('hitPaddingBottom', this._style('hitPaddingY', 0)) !== prevHitPaddingBottom ||
+      this._style('ellipseRx', BASE_RX) !== prevEllipseRx ||
+      this._style('ellipseRy', BASE_RY) !== prevEllipseRy;
     // 只有尺寸相关参数变化才重设 canvas；字号、线宽等普通样式变化只重绘，避免拖动时闪屏。
     if (shouldResetCanvas) {
       var nextScale = options.scale != null ? options.scale : this.inputScale;
@@ -484,9 +581,10 @@ class ZoomTurntableRenderer {
     }
     // 以下两项不改变 canvas 尺寸，走不到上面的重算分支，这里单独同步后重绘即可
     this.contentOffsetY = this._style('contentOffsetY', 0) * this.scale;
-    this.trackEdgeInset = this._style('trackEdgeInset', 0) * this.scale;
-    this.rx = this.maskRx * TRACK_TO_MASK_RATIO - this.trackEdgeInset;
-    this.ry = this.maskRy * TRACK_TO_MASK_RATIO - this.trackEdgeInset;
+    this.trackEdgeInset = this._style('trackEdgeInset', DEFAULT_TRACK_EDGE_INSET) * this.scale;
+    this.ry = this.maskRy - this.trackEdgeInset;
+    var nextTrackRx = this._style('trackRx', 0) * this.scale;
+    this.rx = nextTrackRx > 0 ? nextTrackRx : this.maskRx - this.trackEdgeInset;
     this.value = Math.max(this.min, Math.min(this.max, this.value));
     this.progress = this.getProgress(this.value);
     this._buildTicks();
@@ -527,6 +625,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,9 +649,20 @@ 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; // 本次拖动的像素增量（含方向修正）
+    // 本次拖动的像素增量（含方向修正 + 横屏的轴向翻转）
+    var axisSign = this.orientation === 'right' ? RIGHT_AXIS_SIGN : 1;
+    var deltaX = (currentPoint - this.lastTouchPoint) * DRAG_DIRECTION * axisSign;
     this.lastTouchPoint = currentPoint;
     var valueSpan = this.max - this.min; // 整个倍率区间跨度
     var pixelsForFullSpan = 300 * this.scale; // 走完整个区间大约需要多少像素
@@ -579,19 +690,131 @@ 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;
+    var isTap = !!(wasDragging && this._tapStart && !this._tapStart.moved &&
+        Date.now() - this._tapStart.t <= TAP_MAX_MS);
+    if (isTap) {
+      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);
+      if (isTap && !tapped) {
+        /**
+         * 点在转盘的空白处（没命中刻度带）—— 用户的意图就是「点画面」。
+         *
+         * canvas 覆盖了播放器下部很大一片，touchstart/end 又是 preventDefault + stopPropagation，
+         * 播放器根本收不到这一下 tap，于是「点画面收起转盘」在转盘范围内整个失效，
+         * 表现就是「第一次点没反应、第二次点（落到画面上部）才收起」。
+         * 这里补一条回调，让逻辑层把它当作点画面处理。
+         *
+         * 同时不发 onChangeEnd：值没变，再下发一次纯属多余。
+         */
+        this.callMethod('onBlankTap');
+      } else if (!tapped) {
+        // tap 命中时由动画结束统一发 onChange / onChangeEnd，这里不能再按旧值发一次；
+        // 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.hitPaddingTop || 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 +831,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 +856,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/turntable/type.d.ts

@@ -45,11 +45,44 @@ export interface ZoomTurntableStyleOptions {
     hitPaddingX?: number;
     hitPaddingY?: number;
     /**
-     * 轨道（含刻度点、指针）与标记文字整体向椭圆内侧收的距离，
-     * scale=1 时的 px 值，默认 0。用于加大它们与遮罩边缘的间距；
+     * 纵向触摸余量的上 / 下单独覆盖，scale=1 时的 px 值，默认都取 hitPaddingY。
+     * 竖屏底部传 0：canvas 底边即播放器底边，底边以下的余量收不到 touch（原生层已裁），
+     * 留着只会把 canvas 推出播放器，从而依赖 CoverView 里并不可靠的负 margin。
+     */
+    hitPaddingTop?: number;
+    hitPaddingBottom?: number;
+    /**
+     * 轨道（含刻度点、指针）与标记文字向椭圆内侧等距收的距离，
+     * scale=1 时的 px 值，默认 30。横半径与纵半径各减同一个绝对值，
+     * 这样内部虚线弧与外圈遮罩弧的间距处处相等、弧度看起来一致
+     * （按比例内收会让弧顶间距明显小于两侧，外圈显得更扁）。
      * 遮罩半径不变，故不影响组件占位尺寸。
      */
     trackEdgeInset?: number;
+    /**
+     * 轨道椭圆的横半径，scale=1 时的 px 值。不传则与纵向一样按 trackEdgeInset 等距内收。
+     * 传一个更小的值可让虚线弧比遮罩弧更弯 —— 两端在到达播放器左右边缘之前就降到
+     * 底边以下、被画布底边切断，也就是设计稿里「刻度线扎进播放器底部」的样子。
+     */
+    trackRx?: number;
+    /**
+     * 刻度文案「顶边到遮罩弧」的留白，scale=1 时的 px 值。不传则沿用旧算法
+     * （按轨道弧往外推 18px）。传了之后文案椭圆与遮罩椭圆等距内收，
+     * 不同字号的顶边对齐同一条线，且沿整条弧留白一致 —— 仅 `bottom` 模式生效。
+     */
+    labelTopGap?: number;
+    /**
+     * 遮罩椭圆的横半径，scale=1 时的 px 值，默认 258（设计稿 516×351）。
+     * 弧顶到屏幕两侧的落差取决于「屏幕半宽 / 横半径」，所以竖屏要跟着窗口宽度缩放，
+     * 否则宽屏机型上弧会明显更弯。
+     */
+    ellipseRx?: number;
+    /**
+     * 遮罩椭圆的纵半径，scale=1 时的 px 值，默认 175.5（设计稿 516×351）。
+     * 只压扁纵向、不动横向：竖屏背景带高度受限（约 70px）时按比例缩小整只椭圆
+     * 会让宽度撑不满播放器，两侧露出直角缺口。
+     */
+    ellipseRy?: number;
 }
 export interface ZoomTurntableProps {
     /** 整体缩放倍数，默认 1。1.0 = 完整椭圆 351×516，可见画布约 351×149；椭圆比例固定 351:516 */
@@ -76,6 +109,12 @@ export interface ZoomTurntableProps {
     onTouchStart?: () => void;
     /** 手指离开转盘，含 touchcancel（用于恢复原生手势） */
     onTouchEnd?: () => void;
+    /**
+     * 点在转盘空白处（未命中刻度带）。
+     * canvas 会吃掉落在自己范围内的 tap，播放器收不到，「点画面收起」在转盘上就失效了；
+     * 挂载方拿这个回调当作「点画面」处理即可。
+     */
+    onBlankTap?: () => void;
     /** 主刻度标记数组 */
     marks?: ZoomMark[];
     /**

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

@@ -16,6 +16,8 @@ export declare const useLensZoom: (options: Options) => {
     /** 镜头列表（按 value 升序），用于渲染倍率 tab */
     lenses: import("./lensSkill").Lens[];
     lensIndex: number;
+    /** 正在切往的目标镜头下标；-1 表示没有切换进行中 */
+    switchingIndex: number;
     /** 画面绝对倍率 */
     curM: number;
     min: number;
@@ -29,6 +31,7 @@ export declare const useLensZoom: (options: Options) => {
     ticks: number[];
     beginDrag: (this: unknown, value: number) => void;
     applyZoom: (this: unknown, targetM: number) => Promise<void>;
+    endDrag: (this: unknown) => void;
     switchToLens: (this: unknown, index: number) => Promise<void>;
 };
 export {};