@edv4h/usketch-plugin-edge-pan

中文文档
0.2.13发布于 2026/11/15MITTypeScriptES Module构建来源已验证近 30 天下载 1967
原始使用文档
文档目录6 节
  1. 仕組み
  2. 使い方
  3. オプション(すべてホストが設定可能)
  4. HUD(end-user 向け)
  5. Snap プラグインとの併用
  6. 補足

@edv4h/usketch-plugin-edge-pan

Shape をドラッグ中、ポインタを画角の端に寄せると、その方向へ**画角が自動でスライド(スクロール)**するプラグイン。tldraw の "edge scrolling" 相当。掴んでいる Shape はカーソル下に留まったまま、世界がその下をスクロールします。

仕組み

  • ポインタが画角端の「帯(margin)」に入ると、BoardStore.panBy で毎フレーム画角をパンします。速度は帯の奥ほど速く(境界で 0・端で最大)。
  • パンで画角が動くと、カーソルが止まっていてもドラッグ中のツールは位置を再計算しません(掴んだ Shape がワールドに取り残される)。そこで本プラグインは、パンした分だけドラッグ中の Shape をワールド空間で直接移動させ、画面上はカーソル下に留めます(移動量 = 実パン量 ÷ zoom)。
  • ドラッグ中に動いた Shape の id(select ツールが動かした親+子孫)を蓄積し、それらを追従対象にします。移動は transient(コマンド化しない)ので Undo を汚さず、drop 時に select ツールが最終位置を 1 コマンドとして確定します(commit() は現在の store 位置を採るため追従分も含まれる)。

使い方

import { createEdgePanPlugin } from "@edv4h/usketch-plugin-edge-pan";

// 既定のまま
createEdgePanPlugin();

// ホスト側で挙動を設定
createEdgePanPlugin({
  edgeSize: 64,      // 反応する端の帯の幅(px)
  maxSpeed: 24,      // 帯の最奥での 1 フレームあたりのパン量(px)
  axes: "both",      // "both" | "horizontal" | "vertical"
  curve: (d) => d * d, // 端に近づくほど急加速(既定は線形)
});

オプション(すべてホストが設定可能)

interface EdgePanOptions {
  enabled?:  boolean      | (() => boolean);       // 既定 true
  edgeSize?: number       | (() => number);        // 既定 48 (px)
  maxSpeed?: number       | (() => number);        // 既定 16 (px/frame)
  axes?:     EdgePanAxes   | (() => EdgePanAxes);   // 既定 "both"
  curve?:    (depth: number) => number;            // 0..1 → 0..1、既定は線形
}
type EdgePanAxes = "both" | "horizontal" | "vertical";
  • すべて getter(() => value)でも渡せます — 設定 UI のスライダー等からライブに反映されます(値は毎フレーム評価)。
  • 数値は堅牢化のためクランプ・不正値は既定へフォールバック(edgeSize >= 1、maxSpeed >= 0)。

HUD(end-user 向け)

プロジェクト規約どおり独自 UI は持たず、共有 HUD に設定グループ「端で画角スライド」を登録します(有効 / 端の帯(px) / 最大速度 / 対象軸)。HUD の上書きはホスト options より優先され、options を土台に end-user がその場で微調整できます。

Snap プラグインとの併用

@edv4h/usketch-plugin-snap は store.updateShape をモンキーパッチして、ドラッグ中の位置更新をガイドへスナップします。自動パンの追従移動は「画角補正」であってユーザー操作ではないため、追従はスナップさせずカーソル下へ留めたい(スナップさせると、ワールド固定のガイドに貼り付いてスクロールしても図形が動かなくなる)。

edge-pan は setup 時に掴んだパッチ前の生 updateShape で追従を行うことでこれを回避します。そのため edge-pan を snap より先に登録してください(先に登録されていれば生の updateShape を掴めます)。スクロール中は追従(非スナップ)、ポインタを実際に動かせば snap は通常どおり再作動します。

補足

  • パンは BoardStore の viewport constraint を通るので、setViewportConstraint(例: dashboard のスクロール制限)が効いている盤面では、その範囲内でのみスライドします。
  • ドラッグ検知は shape:updated+pointer-down、終了は shapes:move-end / canvas:pointerup。

版本与发布记录

@edv4h/usketch-plugin-edge-pan 共发布 13 个版本,首次发布于 2026/09/09;过去 12 个月发布了 13 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.2.13latest2026/11/15今天
0.2.122026/11/151 天前
0.2.102026/11/105 天前
0.2.92026/11/106 天前
0.2.82026/11/069 天前
0.2.72026/11/069 天前

关于 @edv4h/usketch-plugin-edge-pan 的常见问题

如何安装 @edv4h/usketch-plugin-edge-pan?

在项目目录运行 npm install @edv4h/usketch-plugin-edge-pan,或使用 pnpm add / yarn add / bun add。

@edv4h/usketch-plugin-edge-pan 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@edv4h/usketch-plugin-edge-pan 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@edv4h/usketch-plugin-edge-pan 可以商用吗?

@edv4h/usketch-plugin-edge-pan 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@edv4h/usketch-plugin-edge-pan 的下载量有多少?

根据 npm 官方下载统计,@edv4h/usketch-plugin-edge-pan 在 2026/10/13 – 2026/11/11 这 30 天内被下载 1,967 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@edv4h/usketch-plugin-edge-pan 还在维护吗?

最新版本 0.2.13 发布于 2026/11/15(今天);至今共发布 13 个版本,其中过去 12 个月发布了 13 个;首次发布于 2026/09/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。