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

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

@@ -2,6 +2,13 @@
    -- 小程序原生组件层（rjs Component 壳），运行在 render 线程的 ES5 环境，
       沿用内嵌来源 ray-zoom-turntable 的写法，不套用主工程的 ES6+ 规则 */
 import Render from './index.rjs';
+
+/**
+ * 注意：下面的 computeCanvasViewport 是 canvas **DOM 尺寸**的唯一来源（index.tyml 内联 style 用它），
+ * 与 index.rjs 的 _computeGeometry 是两份独立实现，**必须逐项对齐**。
+ * 任何影响画布尺寸的 styleOptions（ellipseRx/ellipseRy/hitPadding*）两边都要读，
+ * 否则绘制坐标系与 DOM 尺寸不一致：画面被拉伸，且溢出承载 CoverView 的部分收不到 touch。
+ */
 var BASE_RX = 258;
 var BASE_RY = 175.5;
 
@@ -67,7 +74,9 @@ function computeCanvasViewport(props) {
   if (cropRatio > 1) cropRatio = 1;
   // 与 renderer 的 hitPadding 保持一致，否则 canvas 的 DOM 尺寸与绘制尺寸会打架
   var hitPaddingX = styleNumber(props.styleOptions, 'hitPaddingX', 0) * inputScale;
-  var hitPaddingY = styleNumber(props.styleOptions, 'hitPaddingY', 0) * inputScale;
+  var hitPaddingY = styleNumber(props.styleOptions, 'hitPaddingY', 0);
+  var hitPaddingTop = styleNumber(props.styleOptions, 'hitPaddingTop', hitPaddingY) * inputScale;
+  var hitPaddingBottom = styleNumber(props.styleOptions, 'hitPaddingBottom', hitPaddingY) * inputScale;
   var bottomSin = 2 * cropRatio - 1;
   if (bottomSin < -1) bottomSin = -1;
   if (bottomSin > 1) bottomSin = 1;
@@ -76,9 +85,19 @@ function computeCanvasViewport(props) {
     cropWidthRatio = Math.sqrt(1 - bottomSin * bottomSin);
   }
   var contentScale = inputScale;
-  var cropHalfWidth = BASE_RX * contentScale * cropWidthRatio;
-  var canvasWidth = cropHalfWidth * 2 + hitPaddingX * 2;
-  var canvasHeight = BASE_RY * contentScale * 2 * cropRatio + hitPaddingY * 2;
+  // 椭圆半径同样要读 styleOptions —— 竖屏会按容器 16:9 传入压扁后的 ellipseRx/ellipseRy。
+  // 这里漏读过一次：canvas 的 DOM 尺寸仍按设计稿 258×175.5 算（208 高），
+  // 而 renderer 按传入值算（186 高），结果画面被拉伸、canvas 顶部溢出承载它的
+  // CoverView 被裁掉 —— 裁掉的部分收不到 touch，表现就是「手势整体不生效」。
+  var maskRx = styleNumber(props.styleOptions, 'ellipseRx', BASE_RX) * contentScale;
+  var maskRy = styleNumber(props.styleOptions, 'ellipseRy', BASE_RY) * contentScale;
+  var cropHalfWidth = maskRx * cropWidthRatio;
+
+  // 向上取整，与 index.rjs 的 baseWidth / baseHeight 保持一致：
+  // 尺寸取整不足会被原生层裁掉最外侧那一行像素（部分机型边缘露 1px 空白），
+  // 两边算法只要有一处不取整，DOM 尺寸与绘制坐标系就又会打架。
+  var canvasWidth = Math.ceil(cropHalfWidth * 2 + hitPaddingX * 2);
+  var canvasHeight = Math.ceil(maskRy * 2 * cropRatio + hitPaddingTop + hitPaddingBottom);
   return orientation === 'right' ? {
     canvasWidth: canvasHeight,
     canvasHeight: canvasWidth
@@ -231,6 +250,10 @@ Component({
     onChangeEnd(value) {
       this.triggerEvent('changeEnd', value);
     },
+    // 点在转盘空白处（未命中刻度带）：等同于点画面，逻辑层据此收起转盘
+    onBlankTap() {
+      this.triggerEvent('blankTap');
+    },
     // 转盘触摸开始 / 结束（含 touchcancel），逻辑层据此切换 ty.nativeDisabled
     onTouchStart() {
       this.triggerEvent('turntableTouchStart');

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;
@@ -41,6 +45,20 @@ 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) {
@@ -109,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;
@@ -142,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;
@@ -151,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;
@@ -272,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') {
@@ -285,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 对应的刻度转到指针处。
@@ -316,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();
@@ -338,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';
@@ -366,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);
       }
     }
@@ -375,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();
@@ -394,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();
   }
@@ -470,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;
@@ -488,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;
@@ -497,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();
@@ -575,7 +660,9 @@ class ZoomTurntableRenderer {
 
     // 像素增量直接映射到「值」的等量变化，而非 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; // 走完整个区间大约需要多少像素
@@ -610,8 +697,9 @@ class ZoomTurntableRenderer {
 
     // 没怎么移动、按得也短 —— 当作「点击某个刻度」，直接滚过去并下发
     var tapped = false;
-    if (wasDragging && this._tapStart && !this._tapStart.moved &&
-        Date.now() - this._tapStart.t <= TAP_MAX_MS) {
+    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);
@@ -621,8 +709,20 @@ class ZoomTurntableRenderer {
 
     if (wasDragging) {
       this._cachedRect = null;
-      // tap 命中时由动画结束统一发 onChange / onChangeEnd，这里不能再按旧值发一次
-      if (!tapped) {
+      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);
@@ -638,7 +738,7 @@ class ZoomTurntableRenderer {
    */
   _drawPointFromCanvas(cx, cy) {
     var offX = -this.viewportLeft + (this.hitPaddingX || 0);
-    var offY = -this.viewportTop + (this.hitPaddingY || 0) + (this.contentOffsetY || 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 };

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

@@ -31,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 {};