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

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

@@ -0,0 +1,691 @@
+// 手势 / 初始化链路日志开关。定位手势问题期间打开，稳定后置 false。
+const DEBUG_GESTURE = true;
+function dlog() {
+  if (!DEBUG_GESTURE) return;
+  var args = Array.prototype.slice.call(arguments);
+  console.log.apply(console, ['[zoomTurntable/rjs]'].concat(args));
+}
+
+const DEG_TO_RAD = Math.PI / 180;
+const RAD_TO_DEG = 180 / Math.PI;
+// 设计稿椭圆基准尺寸，纵横比固定 516:351；后面所有比例都以这个基准缩放。
+const BASE_RX = 258;     // 516 / 2
+const BASE_RY = 175.5;   // 351 / 2
+const START_ANGLE = 180;
+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;
+// 遮罩本身也保持同一椭圆比例
+const MASK_RX_RATIO = 1;
+const MASK_RY_RATIO = 1;
+// 当前光标圆心实心圆半径固定，不开放外部配置，避免不同挂载层下传参表现不一致。
+const POINTER_DOT_RADIUS = 3;
+// 主刻度之间的次刻度段数（沿弧线均匀分布）
+const MINOR_DIVS = 60;
+// 次刻度靠近主刻度时的跳过阈值（progress 单位）
+const MAJOR_SKIP = 0.004;
+const LABEL_WINDOW = 0.28;
+const TOP_SAFE_AREA = 50;
+// 拖动方向：-1 表示「拖动的是转盘本身」——向左拖，盘面左移，右侧的大刻度转到指针处，倍率变大，
+// 与实体相机的调焦环手感一致；+1 则是「拖动指针」的反向手感。
+const DRAG_DIRECTION = -1;
+
+class ZoomTurntableRenderer {
+  constructor(options) {
+    this.canvas = options.canvas;
+    this.ctx = this.canvas.getContext('2d');
+    this.min = options.min != null ? options.min : 0.6;
+    this.max = options.max != null ? options.max : 20;
+    this.step = options.step != null ? options.step : 0.1;
+    this.marks = options.marks || [];
+    this.ticks = options.ticks || [];
+    this.curve = options.curve || 'log';
+    // 读数小数位按 step 推导（step=0.3 → 1 位，step=0.25 → 2 位，step=1 → 0 位），
+    // 保证显示精度与可调精度一致。不开放外部函数注入（跨线程传函数需 new Function 还原，
+    // 有兼容与安全风险）。
+    var self = this;
+    this.formatLabel = function (v) { return v.toFixed(self._valueDecimals()) + 'X'; };
+    this.activeColor = options.activeColor || '#FFFFFF';
+    this.styleOptions = options.styleOptions || {};
+    this.orientation = this._normalizeOrientation(options.orientation);
+    this.cropRatio = options.cropRatio != null
+      ? options.cropRatio
+      : this._style('cropRatio', 0.2);
+    this.callMethod = options.callMethod;
+
+    this.value = options.defaultValue != null ? options.defaultValue : this.min;
+    // progress(0~1) 是拖动时的唯一真相，保持浮点，避免 step 量化造成的抖动
+    this.progress = this.getProgress(this.value);
+    this.dragging = false;
+    this._rafScheduled = false;
+    this._rafId = null;
+    // 缓存的刻度几何（仅依赖 min/max/curve/marks，不依赖当前值）
+    this._majorTicks = [];
+    this._minorTicks = [];
+    this._markProgress = [];
+
+    // 按目标 scale 派生所有几何尺寸；这里先把“完整遮罩”的尺寸算出来，再按 cropRatio 截掉底部。
+    this._computeGeometry(options.scale != null ? options.scale : 1);
+    this._setupCanvasSize();
+    this._buildTicks();
+    this._render();
+  }
+
+  // 按 scale 整体缩放，先算遮罩，再让轨道按遮罩比例内收。
+  // 轨道和遮罩共用圆心，顶部基准仍由 topSafeArea 控制，角度类（START_ANGLE/POINTER_ANGLE 等）不随尺寸变化。
+  _computeGeometry(scale) {
+    var inputScale = scale != null ? scale : 1; // 外部传入的整体缩放倍数
+    var cropRatio = this.cropRatio != null ? this.cropRatio : this._style('cropRatio', 0.2); // 从上弧顶截到多深
+    if (cropRatio < 0) cropRatio = 0;
+    if (cropRatio > 1) cropRatio = 1;
+    this.cropRatio = cropRatio;
+
+    var bottomSin = 2 * cropRatio - 1; // 对应截面底边的 sin 值，用来反推可见宽度
+    if (bottomSin < -1) bottomSin = -1;
+    if (bottomSin > 1) bottomSin = 1;
+    var cropWidthRatio = 1; // 截面底边相对完整椭圆宽度的比例
+    if (cropRatio < 0.5) {
+      cropWidthRatio = Math.sqrt(1 - bottomSin * bottomSin);
+    }
+    var contentScale = inputScale; // 最终用于整套几何的实际缩放值
+
+    this.inputScale = inputScale;
+    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;
+    // 轨道（含刻度点、指针）与标记文字整体向椭圆内侧收，加大它们与遮罩边缘的距离。
+    // 遮罩半径不变，所以 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;
+    var fullWidth = this.maskRx * 2; // 完整椭圆的理论宽度
+    this.CX = fullWidth / 2; // 椭圆在完整坐标系里水平居中
+    this.topSafeArea = this._style('topSafeArea', TOP_SAFE_AREA) * contentScale;
+    this.CY = this.maskRy + this.topSafeArea; // 顶部预留当前倍率文字空间
+    // cropRatio 表示“从上弧顶往下截取到哪里”，0 是最上弧顶，1 是完整椭圆底部。
+    this.cropBottom = this.topSafeArea + this.maskRy * 2 * cropRatio;
+
+    var cropHalfWidth = this.maskRx; // 当前截面可见半宽，默认等于完整椭圆半径
+    this.maskVisibleStartAngle = START_ANGLE;
+    this.maskVisibleEndAngle = END_ANGLE;
+    if (cropRatio < 0.5) {
+      var bottomAngle = Math.asin(bottomSin) * RAD_TO_DEG; // 截面底边对应的角度
+      this.maskVisibleStartAngle = 180 - bottomAngle;
+      this.maskVisibleEndAngle = 360 + bottomAngle;
+      cropHalfWidth = this.maskRx * Math.cos(bottomAngle * DEG_TO_RAD);
+    }
+
+    // 绘制内容整体纵向偏移（正值下移）。只平移画布坐标系，
+    // 不参与任何角度 / 半径计算，因此刻度与文案的角度分布保持原样。
+    this.contentOffsetY = this._style('contentOffsetY', 0) * contentScale;
+
+    // 触摸响应余量：canvas 是唯一能收 touch 的元素，若尺寸严格等于椭圆截面，
+    // 椭圆上方 / 两侧的空白区域就滑不动（观感上「只有中间能滑」）。
+    // 这里把画布向外扩一圈，绘制坐标同步补偿，视觉不变但整个转盘区域都可拖动。
+    this.hitPaddingX = this._style('hitPaddingX', 0) * contentScale;
+    this.hitPaddingY = this._style('hitPaddingY', 0) * contentScale;
+
+    this.viewportLeft = this.CX - cropHalfWidth;
+    this.viewportTop = this.topSafeArea;
+    this.viewportRight = this.CX + cropHalfWidth;
+    this.viewportBottom = this.cropBottom;
+    // 组件实际占位只取当前截面的真实宽度/高度，避免外层多出空白。
+    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;
+    // 横屏侧边展示时，绘制坐标系先整体旋转 90 度，所以 canvas 宽高也要交换。
+    this.WIDTH = this.orientation === 'right' ? this.baseHeight : this.baseWidth;
+    this.HEIGHT = this.orientation === 'right' ? this.baseWidth : this.baseHeight;
+  }
+
+  _setupCanvasSize() {
+    const systemInfo = getSystemInfo();
+    const dpr = systemInfo.pixelRatio || 1;
+    // 这里设置的是 canvas 物理像素尺寸；style 里保留逻辑像素尺寸，避免模糊。
+    this.canvas.width = this.WIDTH * dpr;
+    this.canvas.height = this.HEIGHT * dpr;
+    this.canvas.style.width = this.WIDTH + 'px';
+    this.canvas.style.height = this.HEIGHT + 'px';
+    if (this.ctx.setTransform) {
+      this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    } else {
+      this.ctx.scale(dpr, dpr);
+    }
+  }
+
+  getProgress(v) {
+    var clamped = Math.max(this.min, Math.min(this.max, v));
+    if (this.curve === 'log') {
+      return Math.log(clamped / this.min) / Math.log(this.max / this.min);
+    }
+    var f = typeof this.curve === 'number' ? this.curve : 1;
+    return Math.pow((clamped - this.min) / (this.max - this.min), 1 / f);
+  }
+
+  // progress(0~1) -> 实际倍率值（未量化）
+  _valueFromProgress(p) {
+    var clamped = Math.max(0, Math.min(1, p));
+    if (this.curve === 'log') {
+      return this.min * Math.pow(this.max / this.min, clamped);
+    }
+    var f = typeof this.curve === 'number' ? this.curve : 1;
+    return this.min + (this.max - this.min) * Math.pow(clamped, f);
+  }
+
+  // 按 step 量化，并夹到 [min, max]
+  _snapValue(raw) {
+    var snapped = Math.round(raw / this.step) * this.step;
+    if (snapped < this.min) return this.min;
+    if (snapped > this.max) return this.max;
+    return snapped;
+  }
+
+  // 刻度盘上的角度（相对于圆心）。
+  // progress = 0 对应左端，progress = 1 对应右端，整段弧线线性映射。
+  getAngle(p) {
+    return START_ANGLE + p * ARC_SPAN;
+  }
+
+  // 预计算刻度几何。主刻度画在 mark 的精确位置，次刻度沿 progress 均匀分布，
+  // 靠近主刻度的次刻度跳过 —— 这样刻度线与数字标签严格对齐。
+  _buildTicks() {
+    var marks = this.marks || [];
+    var markProgress = [];
+    var majorTicks = [];
+    for (var i = 0; i < marks.length; i++) {
+      var p = this.getProgress(marks[i].value);
+      markProgress.push(p);
+      majorTicks.push(this.getAngle(p) * DEG_TO_RAD);
+    }
+    this._markProgress = markProgress;
+    this._majorTicks = majorTicks;
+
+    var minorTicks = [];
+    var isNearMajor = function (pp) {
+      for (var m = 0; m < markProgress.length; m++) {
+        if (Math.abs(markProgress[m] - pp) < MAJOR_SKIP) return true;
+      }
+      return false;
+    };
+
+    if (this.ticks && this.ticks.length) {
+      // 外部给定刻度值：各镜头区间按自己的 step 生成，间距逐段不同
+      for (var t = 0; t < this.ticks.length; t++) {
+        var tp = this.getProgress(this.ticks[t]);
+        if (isNearMajor(tp)) continue;
+        minorTicks.push(this.getAngle(tp) * DEG_TO_RAD);
+      }
+    } else {
+      // 兜底：沿 progress 均匀分布
+      for (var j = 0; j <= MINOR_DIVS; j++) {
+        var pp = j / MINOR_DIVS;
+        if (isNearMajor(pp)) continue;
+        minorTicks.push(this.getAngle(pp) * DEG_TO_RAD);
+      }
+    }
+    this._minorTicks = minorTicks;
+  }
+
+  // 用 rAF 合并多次重绘请求，避免每个 touchmove 事件都全量重绘
+  _scheduleRender() {
+    if (this._rafScheduled) return;
+    this._rafScheduled = true;
+    var self = this;
+    var raf = this._getRaf();
+    this._rafId = raf(function () {
+      self._rafScheduled = false;
+      self._rafId = null;
+      self._render();
+    });
+  }
+
+  _getRaf() {
+    if (this.canvas && typeof this.canvas.requestAnimationFrame === 'function') {
+      return this.canvas.requestAnimationFrame.bind(this.canvas);
+    }
+    if (typeof requestAnimationFrame === 'function') {
+      return requestAnimationFrame;
+    }
+    return function (fn) { return setTimeout(fn, 16); };
+  }
+
+  _render() {
+    var ctx = this.ctx;
+    var s = this.scale;
+    var geo = s * TRACK_TO_MASK_RATIO;
+    ctx.clearRect(0, 0, this.WIDTH, this.HEIGHT);
+    ctx.save();
+    if (this.orientation === 'right') {
+      this._textCounterRotation = Math.PI / 2;
+      ctx.translate(0, this.baseWidth);
+      ctx.rotate(-Math.PI / 2);
+    } else {
+      this._textCounterRotation = 0;
+    }
+    // 画布因触摸余量向外扩过，绘制原点要补偿回来，保证视觉位置不变
+    ctx.translate(
+      -this.viewportLeft + (this.hitPaddingX || 0),
+      -this.viewportTop + (this.hitPaddingY || 0) + (this.contentOffsetY || 0)
+    );
+
+    // 刻度盘角度位移：让当前 progress 对应的刻度转到指针处。
+    // 给每个刻度的参数角度直接加上位移，再用椭圆参数方程算坐标，刻度始终落在椭圆弧上。
+    var rotation = POINTER_ANGLE - this.getAngle(this.progress); // 当前值对应的整体旋转角
+    var rotRad = rotation * DEG_TO_RAD; // rotation 的弧度值
+    var visibleStart = Math.max(START_ANGLE, START_ANGLE + rotation); // 当前可见弧段起点
+    var visibleEnd = Math.min(END_ANGLE, END_ANGLE + rotation); // 当前可见弧段终点
+    if (visibleEnd <= visibleStart) {
+      ctx.restore();
+      return;
+    }
+
+    // 半透明扇形遮罩：固定成完整扇面，不跟随刻度旋转；
+    // 这样“被截掉的底边”始终是组件视觉底部，外部只看到截面。
+    ctx.beginPath();
+    ctx.moveTo(
+      this.CX + this.maskRx * Math.cos(this.maskVisibleStartAngle * DEG_TO_RAD),
+      this.CY + this.maskRy * Math.sin(this.maskVisibleStartAngle * DEG_TO_RAD)
+    );
+    ctx.ellipse(
+      this.CX,
+      this.CY,
+      this.maskRx,
+      this.maskRy,
+      0,
+      this.maskVisibleStartAngle * DEG_TO_RAD,
+      this.maskVisibleEndAngle * DEG_TO_RAD,
+      false
+    );
+    ctx.lineTo(this.viewportRight, this.viewportBottom);
+    ctx.lineTo(this.viewportLeft, this.viewportBottom);
+    ctx.closePath();
+    ctx.fillStyle = 'rgba(0,0,0,' + this._style('overlayOpacity', 0.44) + ')';
+    ctx.fill();
+
+    // 参考图里的轨道是柔和虚线弧，不是密集刻度。
+    ctx.save();
+    ctx.beginPath();
+    ctx.ellipse(this.CX, this.CY, this.rx, this.ry, 0, visibleStart * DEG_TO_RAD, visibleEnd * DEG_TO_RAD, false);
+    ctx.setLineDash([this._style('dashLength', 8) * geo, this._style('dashGap', 8) * geo]);
+    ctx.lineDashOffset = -3 * geo;
+    ctx.strokeStyle = 'rgba(255,255,255,0.42)';
+    ctx.lineWidth = this._style('trackLineWidth', 2.2) * geo;
+    ctx.lineCap = 'round';
+    ctx.stroke();
+    ctx.restore();
+
+    // 主刻度点和附近标签。只展示指针附近的标签，避免默认多焦段标记铺满弧线。
+    var dotRx = this.rx; // 刻度点所在椭圆的横半径
+    var dotRy = this.ry; // 刻度点所在椭圆的纵半径
+    var isRightOrientation = this.orientation === 'right'; // 是否为横屏侧边模式
+    // 横屏侧边模式时，标签朝椭圆内侧收；底部模式则往外侧展开一点，保证和弧线拉开距离。
+    var labelRx = isRightOrientation
+      ? this.rx - this._style('innerLabelOffsetX', 22) * geo
+      : this.rx + 4 * geo;
+    var labelRy = isRightOrientation
+      ? this.ry - this._style('innerLabelOffsetY', 22) * geo
+      : this.ry + 18 * geo;
+    var marks = this.marks || [];
+    if (marks.length > 0) {
+      ctx.textAlign = 'center';
+      ctx.textBaseline = 'middle';
+      for (var k = 0; k < marks.length; k++) {
+        var progressOffset = this._markProgress[k] - this.progress; // 当前 mark 距离指针的相对位置
+        if (Math.abs(progressOffset) > LABEL_WINDOW) continue;
+        if (Math.abs(progressOffset) < 0.012) continue;
+        var mRad = this._majorTicks[k] + rotRad; // 该 mark 旋转后的弧度角
+        var mDeg = mRad / DEG_TO_RAD; // 方便和 visibleStart / visibleEnd 比较
+        if (mDeg < visibleStart || mDeg > visibleEnd) continue;
+        var dx = this.CX + dotRx * Math.cos(mRad);
+        var dy = this.CY + dotRy * Math.sin(mRad);
+        ctx.beginPath();
+        ctx.arc(dx, dy, this._style('markDotRadius', 3) * geo, 0, Math.PI * 2);
+        ctx.fillStyle = 'rgba(255,255,255,0.62)';
+        ctx.fill();
+
+        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';
+        this._fillText(this._normalizeLabel(marks[k].label, marks[k].value), lx, ly - 2 * s);
+      }
+    }
+
+    // 固定中心指示器：白色圆环 + 当前倍率，形成参考图里的视觉锚点。
+    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;
+    // 横屏右侧时当前值文字再往内侧让一点，避免和固定光标圆环重合。
+    var currentLabelRy = isRightOrientation ? labelRy - 10 * geo : labelRy;
+    var currentLabelX = this.CX + currentLabelRx * Math.cos(pointerRad); // 当前值文字 x
+    var currentLabelY = this.CY + currentLabelRy * Math.sin(pointerRad); // 当前值文字 y
+    ctx.beginPath();
+    ctx.arc(px, py, this._style('pointerRadius', 6) * geo, 0, Math.PI * 2);
+    ctx.strokeStyle = this.activeColor;
+    ctx.lineWidth = this._style('pointerStrokeWidth', 1.5) * geo;
+    ctx.stroke();
+    ctx.beginPath();
+    ctx.arc(px, py, POINTER_DOT_RADIUS * geo, 0, Math.PI * 2);
+    ctx.fillStyle = this.activeColor;
+    ctx.fill();
+
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillStyle = this.activeColor;
+    ctx.font = '700 ' + (this._style('currentLabelFontSize', this._style('markLabelFontSize', 14)) * s) + 'px sans-serif';
+    this._fillText(this._formatValue(this.value), currentLabelX, currentLabelY - 2 * s);
+    ctx.restore();
+  }
+
+  _fillText(text, x, y) {
+    if (!this._textCounterRotation) {
+      this.ctx.fillText(text, x, y);
+      return;
+    }
+    this.ctx.save();
+    // 横屏侧边模式下，画布整体旋转过，文字需要反向旋回，才能保持横排可读。
+    this.ctx.translate(x, y);
+    this.ctx.rotate(this._textCounterRotation);
+    this.ctx.fillText(text, 0, 0);
+    this.ctx.restore();
+  }
+
+  _normalizeOrientation(orientation) {
+    return orientation === 'right' ? 'right' : 'bottom';
+  }
+
+  _style(name, fallback) {
+    var value = this.styleOptions && this.styleOptions[name];
+    if (value == null) return fallback;
+    var parsed = Number(value);
+    return isNaN(parsed) ? fallback : parsed;
+  }
+
+  // 当前 step 需要几位小数：0.3 → 1，0.25 → 2，1 → 0
+  _valueDecimals() {
+    var step = this.step != null ? this.step : 0.1;
+    var text = String(step);
+    var dot = text.indexOf('.');
+    if (dot < 0) return 0;
+    return Math.min(2, text.length - dot - 1);
+  }
+
+  _formatValue(v) {
+    if (typeof this.formatLabel === 'function') return this._normalizeLabel(this.formatLabel(v), v);
+    return v.toFixed(this._valueDecimals()) + 'X';
+  }
+
+  _normalizeLabel(label, value) {
+    var decimals = this._valueDecimals();
+    var text = label != null ? String(label) : Number(value).toFixed(decimals);
+    if (!/[xX]$/.test(text)) {
+      var n = Number(text);
+      if (!isNaN(n)) text = n.toFixed(decimals);
+      text += 'X';
+    }
+    return text.replace(/x$/, 'X');
+  }
+
+  setValue(v) {
+    // 拖动中忽略外部回写，防止受控反馈循环导致闪动和方向反转
+    if (this.dragging) return;
+    // 松手后冷却期内忽略所有回写（含 onChange 残余），彻底打断反馈循环
+    if (this._cooldownUntil && Date.now() < this._cooldownUntil) return;
+    // 受控回写也按 step 量化：手势缩放回读来的是连续值（如 3.4666…），
+    // 不量化的话中间读数会出现非 step 倍数的数字，与拖动路径（_snapValue）不一致。
+    var snapped = this._snapValue(Math.max(this.min, Math.min(this.max, v)));
+    // 值无明显变化则跳过，避免浮点抖动触发多余重绘
+    if (Math.abs(snapped - this.value) < this.step * 0.1) return;
+    this.value = snapped;
+    this.progress = this.getProgress(this.value);
+    this._scheduleRender();
+  }
+
+  updateOptions(options) {
+    var prevScale = this.inputScale; // 上一次的整体缩放
+    var prevOrientation = this.orientation; // 上一次方向
+    var prevCropRatio = this.cropRatio; // 上一次截面比例
+    var prevTopSafeArea = this._style('topSafeArea', TOP_SAFE_AREA); // 上一次顶部安全区
+    var prevHitPaddingX = this._style('hitPaddingX', 0); // 上一次横向触摸余量
+    var prevHitPaddingY = this._style('hitPaddingY', 0); // 上一次纵向触摸余量
+    if (options.min != null) this.min = options.min;
+    if (options.max != null) this.max = options.max;
+    if (options.step != null) this.step = options.step;
+    if (options.marks != null) this.marks = options.marks;
+    if (options.ticks != null) this.ticks = options.ticks;
+    if (options.curve != null) this.curve = options.curve;
+    if (options.activeColor != null) this.activeColor = options.activeColor;
+    if (options.styleOptions != null) this.styleOptions = options.styleOptions;
+    if (options.orientation != null) this.orientation = this._normalizeOrientation(options.orientation);
+    if (options.cropRatio != null) this.cropRatio = options.cropRatio;
+    var nextScale = options.scale != null ? options.scale : prevScale; // 更新后的缩放
+    var nextTopSafeArea = this._style('topSafeArea', TOP_SAFE_AREA); // 更新后的顶部安全区
+    var shouldResetCanvas =
+      nextScale !== prevScale ||
+      this.orientation !== prevOrientation ||
+      this.cropRatio !== prevCropRatio ||
+      nextTopSafeArea !== prevTopSafeArea ||
+      this._style('hitPaddingX', 0) !== prevHitPaddingX ||
+      this._style('hitPaddingY', 0) !== prevHitPaddingY;
+    // 只有尺寸相关参数变化才重设 canvas；字号、线宽等普通样式变化只重绘，避免拖动时闪屏。
+    if (shouldResetCanvas) {
+      var nextScale = options.scale != null ? options.scale : this.inputScale;
+      this._computeGeometry(nextScale);
+      this._setupCanvasSize();
+    }
+    // 以下两项不改变 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.value = Math.max(this.min, Math.min(this.max, this.value));
+    this.progress = this.getProgress(this.value);
+    this._buildTicks();
+    this._scheduleRender();
+  }
+
+  _handTouchStart(e) {
+    dlog('touchstart 触发', 'hasPreventDefault=' + !!e.preventDefault, 'touches=' + ((e.touches && e.touches.length) || 0));
+    if (e.preventDefault) e.preventDefault();
+    if (e.stopPropagation) e.stopPropagation();
+    this.dragging = true;
+    // 通知逻辑层禁用原生手势（ty.nativeDisabled），否则播放器的原生缩放/拖动会抢走手势
+    this.callMethod('onTouchStart');
+    var touch = e.touches && e.touches[0];
+    if (!touch) {
+      dlog('touchstart 无 touches，改用 changedTouches');
+      touch = e.changedTouches && e.changedTouches[0];
+    }
+    if (!touch) {
+      dlog('touchstart 拿不到 touch 点，事件对象 keys=', Object.keys(e || {}).join(','));
+      return;
+    }
+    // 缓存 rect，避免每次 move 都调用；右侧模式用 y 轴位移模拟侧向滑动。
+    this._cachedRect = this.canvas.getBoundingClientRect
+      ? this.canvas.getBoundingClientRect()
+      : null;
+    dlog(
+      'touchstart rect=',
+      this._cachedRect
+        ? 'left=' + this._cachedRect.left + ' top=' + this._cachedRect.top +
+          ' w=' + this._cachedRect.width + ' h=' + this._cachedRect.height
+        : 'null(getBoundingClientRect 不可用)',
+      'clientX=' + touch.clientX,
+      'clientY=' + touch.clientY
+    );
+    var rectLeft = this._cachedRect ? this._cachedRect.left : 0;
+    var rectTop = this._cachedRect ? this._cachedRect.top : 0;
+    this.lastTouchPoint = this.orientation === 'right'
+      ? touch.clientY - rectTop
+      : touch.clientX - rectLeft;
+    dlog('touchstart lastTouchPoint=' + this.lastTouchPoint, 'value=' + this.value);
+  }
+
+  _handTouchMove(e) {
+    if (!this.dragging) {
+      dlog('touchmove 被忽略：dragging=false（touchstart 未触发或已被 end/cancel 结束）');
+      return;
+    }
+    if (e.preventDefault) e.preventDefault();
+    if (e.stopPropagation) e.stopPropagation();
+    var touch = (e.touches && e.touches[0]) || (e.changedTouches && e.changedTouches[0]);
+    if (!touch) {
+      dlog('touchmove 拿不到 touch 点');
+      return;
+    }
+    // 使用缓存的 rect，不再重复调用 getBoundingClientRect
+    var rectLeft = this._cachedRect ? this._cachedRect.left : 0;
+    var rectTop = this._cachedRect ? this._cachedRect.top : 0;
+    var currentPoint = this.orientation === 'right'
+      ? touch.clientY - rectTop
+      : touch.clientX - rectLeft;
+
+    // 像素增量直接映射到「值」的等量变化，而非 progress；
+    // 这样无论处于高倍率还是低倍率端，等量滑动产生等量值变化，手感一致（消除 log 曲线导致的两端灵敏度差异）。
+    var deltaX = (currentPoint - this.lastTouchPoint) * DRAG_DIRECTION; // 本次拖动的像素增量（含方向修正）
+    this.lastTouchPoint = currentPoint;
+    var valueSpan = this.max - this.min; // 整个倍率区间跨度
+    var pixelsForFullSpan = 300 * this.scale; // 走完整个区间大约需要多少像素
+    var rawValue = this._valueFromProgress(this.progress) + (deltaX / pixelsForFullSpan) * valueSpan; // 未量化的新值
+    if (rawValue < this.min) rawValue = this.min;
+    else if (rawValue > this.max) rawValue = this.max;
+    // 绘制位置和回调值使用同一个 step 量化结果，避免松手后受控值回写造成回滑。
+    var newValue = this._snapValue(rawValue); // 对齐 step 后的最终值
+    dlog(
+      'touchmove',
+      'currentPoint=' + currentPoint.toFixed(1),
+      'delta=' + deltaX.toFixed(1),
+      'span=' + valueSpan,
+      'pxForSpan=' + pixelsForFullSpan,
+      'raw=' + rawValue.toFixed(3),
+      'new=' + newValue.toFixed(2),
+      'old=' + this.value.toFixed(2),
+      newValue === this.value ? '(值未变化)' : '(值已更新)'
+    );
+    this.progress = this.getProgress(newValue);
+    if (newValue !== this.value) {
+      this.value = newValue;
+      this.callMethod('onChange', newValue);
+    }
+    this._scheduleRender();
+  }
+
+  _handTouchEnd() {
+    dlog('touchend/cancel 触发', 'dragging=' + this.dragging, 'value=' + this.value);
+    if (this.dragging) {
+      this.dragging = false;
+      this._cachedRect = null;
+      // 300ms 冷却期，吸收跨线程残余的 onChange 回写，避免松手后闪动
+      this._cooldownUntil = Date.now() + 300;
+      this.callMethod('onChangeEnd', this.value);
+    }
+    // 无论是否处于拖动，都要恢复原生手势，避免异常路径下 nativeDisabled 卡在 true
+    this.callMethod('onTouchEnd');
+  }
+
+  setupEventListeners() {
+    dlog(
+      'setupEventListeners',
+      'canvas=' + (this.canvas ? 'ok' : 'null'),
+      'addEventListener=' + typeof (this.canvas && this.canvas.addEventListener),
+      'WIDTH=' + this.WIDTH,
+      'HEIGHT=' + this.HEIGHT,
+      'orientation=' + this.orientation
+    );
+    if (!this.canvas || typeof this.canvas.addEventListener !== 'function') {
+      dlog('canvas 不支持 addEventListener，手势无法绑定');
+      return;
+    }
+    this.handTouchStart = this._handTouchStart.bind(this);
+    this.handTouchMove = this._handTouchMove.bind(this);
+    this.handTouchEnd = this._handTouchEnd.bind(this);
+    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);
+  }
+
+  destroy() {
+    if (this._rafId != null) {
+      var cancel = (this.canvas && this.canvas.cancelAnimationFrame)
+        || (typeof cancelAnimationFrame === 'function' ? cancelAnimationFrame : clearTimeout);
+      try { cancel(this._rafId); } catch (e) {}
+      this._rafId = null;
+    }
+    if (this.canvas) {
+      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);
+    }
+  }
+}
+
+export default Render({
+  init(canvasId, options) {
+    this.canvasId = canvasId;
+    this.options = options || {};
+    this._initCanvasAndRenderer(canvasId, options);
+  },
+
+  updateOptions(options) {
+    this.options = options || {};
+    if (this.renderer) {
+      this.renderer.updateOptions(this.options);
+    }
+  },
+
+  setValue(v) {
+    if (this.renderer) {
+      this.renderer.setValue(v);
+    }
+  },
+
+  async _initCanvasAndRenderer(canvasId, options) {
+    dlog('init 开始 canvasId=' + canvasId);
+    var canvas = await getCanvasById(canvasId);
+    dlog('getCanvasById 返回', canvas ? 'ok' : 'null/undefined');
+    if (!canvas) {
+      dlog('拿不到 canvas，渲染与手势都不会生效；检查 canvasId 是否与 tyml 上的 canvas-id 一致');
+      return;
+    }
+    this.canvasDom = canvas;
+
+    this.renderer = new ZoomTurntableRenderer({
+      canvas: canvas,
+      scale: this.options.scale,
+      orientation: this.options.orientation,
+      cropRatio: this.options.cropRatio,
+      min: this.options.min,
+      max: this.options.max,
+      step: this.options.step,
+      defaultValue: this.options.defaultValue,
+      marks: this.options.marks,
+      ticks: this.options.ticks,
+      curve: this.options.curve,
+      activeColor: this.options.activeColor,
+      styleOptions: this.options.styleOptions,
+      callMethod: this.callMethod.bind(this),
+    });
+
+    this.renderer.setupEventListeners();
+  },
+
+  destroy() {
+    if (this.renderer) {
+      this.renderer.destroy();
+      this.renderer = null;
+    }
+  },
+});