Two.js Two.Arc 弧形路径全面解析：构造参数、属性与源码实现

图形学前端【免费下载链接】two.jsA renderer agnostic two-dimensional drawing api for the web项目地址https://gitcode.com/gh_mirrors/tw/two.js点击查看免费下载Two.Arc是 two.js一个与渲染器无关的 Web 二维绘图 API在extras模块中提供的一种基于弧线的图形原语它继承自 Two.Path用于绘制任意起止角度、任意横纵直径的开放弧形而非封闭的圆环或扇形。本文以 arc 官方文档 为核心结合仓库中 arc 的 ESM 源码、UMD 版本、类型声明 与全局常量定义系统讲解 Two.Arc 的构造参数、四大属性、克隆方法、顶点计算原理以及与 Two.Circle、Two.ArcSegment 的差异帮助你直接在生产代码中绘制饼图缺口、仪表盘刻度、折线弧度等场景所需的弧形。Two.Arc 是什么Two.Arc 是一个通过width横向直径、height纵向直径以及弧度制起止角startAngle/endAngle来描述的弧形路径。它属于 two.js 的extras扩展包模块并不打包在核心two.js的默认发行版中——在构建时它由 utils/source-files.js 明确列入extras/jsm/arc.js作为可选的扩展源码。从类定义看extras/jsm/arc.js#L22export class Arc extends Path { ... }它直接继承自核心类Two.Path因此天然拥有Two.Path的全部能力如stroke、fill、linewidth、opacity、visible、变换矩阵、事件绑定等并在其之上新增了四个专属属性width、height、startAngle、endAngle对应Arc.Properties数组见 extras/jsm/arc.js#L98。在构造时代码还设置了this.curved trueextras/jsm/arc.js#L50这意味着路径会自动为每个锚点计算贝塞尔控制点从而渲染出平滑的曲线而非折线。构造函数与参数说明构造函数签名new Two.Arc(x, y, width, height, startAngle, endAngle, resolution)官方文档给出的参数含义如下与 arc README 一致参数类型默认值说明xNumber0弧所在位置的 x 坐标yNumber0弧所在位置的 y 坐标widthNumber0弧的宽度即横向直径水平方向直径heightNumber0弧的高度即纵向直径垂直方向直径startAngleNumber0弧的起始角度单位为弧度endAngleNumber2π (≈ 6.283)弧的结束角度单位为弧度resolutionNumber12用于构建弧形的顶点数量其中“默认值”一栏并非文档表格中原有内容而是从源码注释extras/jsm/arc.js#L10-L20与实现中归纳确认的构造器在typeof x number等判断通过后才会赋值未传时保持0endAngle的实例私有字段初值为TWO_PIextras/jsm/arc.js#L31即Math.PI * 2resolution未传入时回退到全局常量Constants.Resolutionif (typeof resolution ! number) { resolution Constants.Resolution; }而 src/constants.js#L42-L45 中定义了该全局默认值/** * name Two.Resolution * property {Number} - Default amount of vertices to be used for interpreting Arcs and ArcSegments. */ Resolution: 12,也就是说默认会用 12 个顶点来逼近一段弧线。resolution 越大曲线越平滑但顶点与渲染开销也越高反之越小弧线越趋近于多边形折线。resolution的最小可用值为 2否则无法在顶点间进行插值见下文_update的计算公式。一个完整示例结合 README.md 中 two.js 的基本用法可以写出如下可运行的弧形示例import Two from two.js; import { Arc } from two.js/extras/jsm/arc; const two new Two({ fullscreen: true, autostart: true }).appendTo(document.body); // 一个水平直径 200、垂直直径 120、从 0 到 π半圆的弧形 const arc new Arc(0, 0, 200, 120, 0, Math.PI); arc.stroke #ff6b6b; arc.linewidth 4; arc.noFill(); two.add(arc); two.update();如果使用传统script引入方式UMD 构建见 extras/js/arc.js则等价写法为var arc new Two.Arc(0, 0, 200, 120, 0, Math.PI); two.add(arc);类型层面extras/jsm/arc.d.ts 声明了Arc类及其构造器签名、四个属性与clone方法配合 tests/typescript/index.ts 中的类型测试new Arc(0, 0, 20, 10, 0, Math.PI)与arc.clone().endAngle Math.PI * 2可以确认该扩展在 TypeScript 项目中可直接import { Arc } from two.js/extras/jsm/arc使用。四大属性详解Two.Arc的实例拥有Arc.Properties [width, height, startAngle, endAngle]这四个专属属性extras/jsm/arc.js#L98。它们在构造时通过Object.defineProperty绑定到实例上并配对了访问器getter / setter与脏标记dirty flag机制见 extras/jsm/arc.js#L198-L247。width / heightwidth弧的水平尺寸横向直径即弧在 x 方向上的跨度。源码中它以_width存储setter 在值变化时置位_flagWidth trueextras/jsm/arc.js#L200-L205。height弧的垂直尺寸纵向直径即弧在 y 方向上的跨度同理对应_flagHeightextras/jsm/arc.js#L212-L217。在_update()中二者被除以 2 得到椭圆弧的横、纵半轴半径const rx width / 2; const ry height / 2;因此当width height时弧形落在正圆上当二者不等时弧形落在椭圆上。这与 Two.Ellipse 中半径的语义一致——这里的width/height是“直径”而非“半径”构造时传200实际得到的是半轴为100的弧线。startAngle / endAnglestartAngle弧的起始角度单位为弧度弧度制0表示 3 点钟方向正方向为顺时针——注意这与数学坐标系中的逆时针约定不同two.js 使用屏幕坐标系。endAngle弧的结束角度单位同为弧度。两者默认分别为0和TWO_PI即一整圈2π因此在不传角度参数时Two.Arc 渲染出的其实是一个完整的椭圆/圆形路径。这一点从 extras/jsm/arc.js#L27-L31 的字段初值可以看出。属性变更与脏标记机制每个属性的 setter 都只在“新值 ! 旧值”时置位对应的_flagXxx标记见 extras/jsm/arc.js#L194-L247。这些标记会被_update()检查从而保证只有真正发生变化的属性才会触发顶点重算这是 two.js 渲染性能优化的核心机制。渲染完成后flagReset()会把_flagWidth、_flagHeight、_flagStartAngle、_flagEndAngle全部复位为falseextras/jsm/arc.js#L142-L152。clone 方法克隆一个弧形clone(parent)用于创建与当前弧形属性完全相同的新实例extras/jsm/arc.js#L161-L195。参数类型说明parentTwo.Group可选要将克隆体加入的父组或场景返回值Two.Arc新的弧形实例。其复制内容覆盖了四个弧专属属性width、height、startAngle、endAngle与当前顶点数量resolution以this.vertices.length为准变换信息position、rotation、scale、skewX、skewY若当前矩阵是手动矩阵this.matrix.manual还会拷贝matrix继承自Two.Path的全部属性通过遍历Path.Properties逐个赋值若传入了parent克隆体会被parent.add(clone)自动加入该组。典型用法const arc new Two.Arc(0, 0, 200, 120, 0, Math.PI); const twin arc.clone(); // 独立副本不加入任何组 const twin2 arc.clone(two.group); // 克隆并加入指定组 twin.endAngle Math.PI * 2; // 修改副本不影响原弧由于clone是按值复制而非共享引用修改克隆体的角度或尺寸不会影响原弧适合用于快速生成仪表盘的多个刻度弧。内部实现顶点如何被计算Two.Arc 并不在渲染时实时绘制圆弧而是把弧离散化为一系列锚点Anchor顶点交由底层渲染器Canvas / SVG / WebGL渲染。顶点计算发生在_update()方法中extras/jsm/arc.js#L108-L134_update() { if (this._flagVertices || this._flagRadius || this._flagWidth || this._flagHeight || this._flagStartAngle || this._flagEndAngle) { const { width, height, startAngle, endAngle, vertices } this; const rx width / 2; const ry height / 2; for (let i 0; i vertices.length; i) { const v vertices[i]; const pct i / (vertices.length - 1); const theta pct * (endAngle - startAngle) startAngle; v.x rx * cos(theta); v.y ry * sin(theta); } } super._update.call(this); return this; }这段代码揭示了三个关键实现细节参数方程第i个顶点对应角度theta (i / (n-1)) * (endAngle - startAngle) startAngle坐标由椭圆参数方程x rx·cos(theta)、y ry·sin(theta)计算。width / height作为直径参与运算所以弧的纵向坐标 y 随角度正弦变化屏幕坐标系下表现为顺时针方向展开。首尾插值pct的分母是vertices.length - 1因此第一个顶点落在startAngle处最后一个顶点精确落在endAngle处中间顶点均匀插值。这也解释了为什么resolution至少应为 2。叠加父类子类算完顶点后调用super._update()由Two.Path完成贝塞尔曲线化因为curved true、边界盒计算等后续工作。文档建议_update()每帧最多调用一次见源码注释 extras/jsm/arc.js#L100-L107正常使用时无需手动调用渲染器会在合适的时机自动触发。与 Two.Circle、Two.ArcSegment 的区别在 two.js 的图形体系里弧形相关的原语有三个容易混淆Two.Circle核心模块 src/shapes/circle.js由圆心与半径描述永远是一个完整、封闭的圆不支持起止角裁剪。Two.Arc扩展模块由横纵直径与起止角描述可以画出开放的一段圆弧curved true且默认不闭合典型用途是描边弧线、扇形外缘。Two.ArcSegment核心模块 src/shapes/arc-segment.js拥有innerRadius/outerRadius/startAngle/endAngle绘制的是“环形扇区”带内外半径的封闭填充区域构造时传入super(points, true, false, true)默认闭合src/shapes/arc-segment.js#L78。简言之需要一条有描边、可开口的弧线时选 Two.Arc需要一块填充的圆环/扇形时选 Two.ArcSegment只需要完整圆形时用 Two.Circle。另外Two.Arc 默认resolution来自全局Two.Resolution12而 Two.ArcSegment 的默认顶点数为Constants.Resolution * 3src/shapes/arc-segment.js#L72这也反映了两者在平滑度需求上的差异。常见使用建议角度一律用弧度startAngle/endAngle均为弧度制绘制“半圆”请使用Math.PI整圆使用Math.PI * 2避免与角度制的直觉混淆。用 width / height 控制椭圆想要椭圆弧时只需让width ! height想要圆弧时令二者相等。若后续需要动态改变弧的粗细直接修改width/height属性即可脏标记机制会自动触发重绘。调整平滑度对平滑度敏感的图形如大半径仪表盘可适当调高resolution如 32、64对性能敏感的移动端场景可调低到 8 左右并结合resolution与圆弧跨度权衡。结合 Group 变换使用由于 Two.Arc 继承 Two.Path可以通过arc.rotation、arc.scale、arc.position甚至加入 Two.Group 后再整体变换实现复杂图表布局且clone(parent)支持直接复制到目标组。参考资源官方文档Two.Arc 文档核心实现extras/jsm/arc.jsESM、extras/js/arc.jsUMD、类型声明相关依赖src/path.js基类、src/constants.jsResolution全局常量、src/shapes/arc-segment.js环形扇区对照类型与构建证据tests/typescript/index.ts、utils/source-files.js赞分享图形学前端【免费下载链接】two.jsA renderer agnostic two-dimensional drawing api for the web项目地址https://gitcode.com/gh_mirrors/tw/two.js点击查看免费下载相关推荐WPF vs WinForms 20255个关键指标决定桌面开发技术选型WPF vs WinForms 20255个关键指标决定桌面开发技术选型 在.NET桌面开发领域技术决策者面临的核心挑战是如何在WPF与WinForms之间图形学前端Two.js WebGLRenderer 技术指南构造参数、渲染管线与源码实现详解Two.js WebGLRenderer 技术指南构造参数、渲染管线与源码实现详解 Two.js 的 WebGLRenderer 是一个与渲染后端解耦的二维绘图形学前端微信聊天记录导出完全指南用免费本地工具永久保存对话并生成年度聊天报告微信聊天记录导出完全指南用免费本地工具永久保存对话并生成年度聊天报告 换手机时别只“迁移”微信数据再留一份副本才是正解。WeChatMsg留痕是一款免图形学前端上一篇CodeIgniter RestServer 项目教程构建专业级REST API的终极指南下一篇fast-copy在大型前端项目中的架构设计与应用策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考