pathkit-ts

TypeScript 1:1 移植版 pathkit（Skia Path API）——纯 TS 实现，无 WASM、无原生依赖，可在 Node / 浏览器任意环境直接运行。

src/index.ts 作为库入口，导出完整的 Skia 路径 API：路径构建、描边、测量、路径布尔运算、Dash/圆角特效及全部基础几何类型。

特性

• 1:1 移植：逐行对照 Skia C++ 源码（SkPath、SkStroke、SkPathMeasure、pathops 引擎等）移植，行为与 Skia 一致
• Tree-Shaking：sideEffects: false + 按模块编译，打包时自动剔除未用代码
• 零依赖：纯 TypeScript，无 WASM / 无原生绑定，node --test 即可跑 88 个回归测试
• 双入口：单文件 bundle（ES / UMD）+ 逐模块 ESM 产物（支持子路径导入）
• 类型完备：随包发布完整 .d.ts 声明

安装

npm install pathkit-ts

快速上手

ESM 子路径导入（推荐，模块级 Tree-Shaking）

只打包用到的模块及其依赖，体积最小：

import { SkPath } from "pathkit-ts/core/SkPath";
import { SkRect } from "pathkit-ts/core/SkRect";
import { SkPoint } from "pathkit-ts/core/SkPoint";
import { SkStroke } from "pathkit-ts/core/SkStroke";
import { SkPaint } from "pathkit-ts/core/SkPaint";

// 构建路径
const path = new SkPath();
path.moveTo(0, 0);
path.lineTo(100, 0);
path.lineTo(100, 100);
path.close();

path.contains(50, 50);                     // true
path.getBounds();                          // {fLeft:0, fTop:0, fRight:100, fBottom:100}

// 描边（Skia stroker 输出闭合轮廓）
const stroker = new SkStroke();
stroker.setWidth(4);
stroker.setCap(SkPaint.kRound_Cap);
stroker.setJoin(SkPaint.kRound_Join);
const stroked = new SkPath();
stroker.strokePath(path, stroked);

根入口（单文件 bundle）

import { SkPath, SkRect, SkPathOp, Op } from "pathkit-ts";

const a = new SkPath();
a.addRect(SkRect.MakeLTRB(0, 0, 60, 60));
const b = new SkPath();
b.addRect(SkRect.MakeLTRB(40, 40, 100, 100));

const union = new SkPath();
Op(a, b, SkPathOp.kUnion_SkPathOp, union); // true

UMD（<script> 全局或 CommonJS）

<script src="./node_modules/pathkit-ts/dist/pathkit-ts.umd.cjs"></script>
<script>
  const p = new pathkit.SkPath();
  p.addRect({ fLeft: 0, fTop: 0, fRight: 100, fBottom: 100 });
  p.contains(50, 50); // true
</script>

// CommonJS
const { SkPath } = require("pathkit-ts");

构建

npm run build          # 完整构建：单文件 bundle（ES+UMD）+ 逐模块 ESM + 类型声明
npm run build:lib      # 仅单文件 bundle：dist/pathkit-ts.js（ES）+ dist/pathkit-ts.umd.cjs（UMD）
npm run build:es       # 仅逐模块 ESM：dist/es/**（src 目录结构逐一编译）
npm run build:types    # 仅类型声明：dist/types/**
npm run dev            # 启动示例 dev server（Vite）
npm run build:examples # 构建静态示例（dist-examples/）
npm test               # 运行 88 个回归测试（node --test）

产物结构

dist/
├── pathkit-ts.js        # ES bundle（根入口 "import"）
├── pathkit-ts.umd.cjs   # UMD bundle（根入口 "require" / 浏览器全局 pathkit）
├── es/                  # 逐模块 ESM（支持子路径导入 + 模块级 Tree-Shaking）
│   ├── index.js
│   ├── core/  effects/  pathops/  private/  utils/
└── types/               # 与 es/ 对应的 .d.ts 声明

package.json 的 exports 已配置子路径映射：

import { SkPath } from "pathkit-ts/core/SkPath";          // → dist/es/core/SkPath.js
import { Op } from "pathkit-ts/pathops/SkPathOpsOp";      // → dist/es/pathops/SkPathOpsOp.js
import { SkDashPathEffect } from "pathkit-ts/effects/SkDashPathEffect";

API 总览

| 分类 | 导出 | | --- | --- | | 路径 | SkPath（moveTo/lineTo/quadTo/conicTo/cubicTo/arcTo、addRect/addOval/addCircle/addRoundRect/addPoly、contains/getBounds/setFillType…）、SkPathBuilder（链式 API、offset、detach/snapshot） | | 描边 | SkStroke（setWidth/setCap/setJoin/setMiterLimit、strokePath）、SkStrokeRec、SkPaint（cap/join 常量） | | 测量 | SkPathMeasure（getLength/getPosTan）、SkContourMeasure | | 特效 | SkDashPathEffect.Make(intervals, count, phase)、SkCornerPathEffect.Make(radius)、SkPathEffect | | 路径运算 | SkOpBuilder（add/resolve）、Op(one, two, op, result)、Simplify、AsWinding | | 几何 | SkRect、SkRRect、SkPoint、SkPoint3、SkMatrix | | 枚举/常量 | SkPathFillType（kWinding/kEvenOdd）、SkPathDirection（kCW/kCCW）、SkPathOp（kUnion/kIntersect/kDifference/kXOR/kReverseDifference）、SkPathVerb、SkPathSegmentMask、kMove_Verb 等 |

示例

examples/ 目录下有可直接运行的 Vite 演示：

| 示例 | 说明 | | --- | --- | | path | SkPath 底层 verb、addRect/addOval、contains、迭代 | | path-builder | 链式 SkPathBuilder、offset、detach | | path-stroke | 描边宽度、cap、join、miter limit | | path-dash | 虚线间隔、phase、cap/join | | pathops | Union / Intersect / Difference / XOR | | path2d-cmp | 与原生 canvas Path2D 逐项对比，lil-gui 调参 |

移植保真度

• SkPath.contains() 与高精度扁平化绕数计算对照验证
• 虚线渲染与原生 Chrome canvas 逐像素对比（144 组配置全部一致）
• 描边、conic 弧线在 path2d-cmp 示例中与原生 Path2D 并排目视对比
• 88 个回归测试覆盖 path / builder / stroke / ops 全部模块

致谢

Google Skia 的 pathkit 项目——本库是它的 TypeScript 移植。