小地图

基础能力 · Beta

从全局到局部，点击定位、拖动平移，让大画布始终有方向。

大画布里的方向感

免费体验，点击后加载；修改只保留在当前页面。

小地图收集未隐藏的节点与连线路由，提供视口映射、点击定位和拖动平移。显示的是几何示意，不加载文字和媒体像素。

完整方法签名、类型、坐标约定和释放方式见小地图API。

按需安装

import { SkyNoteEditor } from '@skynote/editor';
import { LeaferAdapter } from '@skynote/renderer-leafer';
import { MinimapPlugin, type MinimapSnapshot } from '@skynote/plugins-basic';

export function mountMinimapExample(
  container: HTMLElement,
  draw: (snapshot: MinimapSnapshot | null) => void
): { editor: SkyNoteEditor<HTMLElement>; minimap: MinimapPlugin; destroy: () => void } {
  const minimap = new MinimapPlugin();
  const editor = new SkyNoteEditor<HTMLElement>({ renderer: new LeaferAdapter(), plugins: [minimap] });
  let frame: number | undefined;
  const unsubscribe = minimap.subscribe(() => {
    if (frame !== undefined) return;
    frame = requestAnimationFrame(() => {
      frame = undefined;
      draw(minimap.getSnapshot({ width: 224, height: 144 }));
    });
  });
  function destroy(): void {
    unsubscribe();
    if (frame !== undefined) cancelAnimationFrame(frame);
    editor.destroy();
  }
  try {
    editor.mount(container);
    editor.createNode({ nodeType: 'sticky', x: 0, y: 0, options: { text: '从这里开始' } });
    editor.fitContent();
    minimap.setEnabled(true);
    return { editor, minimap, destroy };
  } catch (error) {
    destroy();
    throw error;
  }
}

在客户端容器就绪后调用mountMinimapExample(container, draw)；draw由宿主实现，将几何快照绘制到自己的小地图区域。退出时调用返回对象的destroy()，释放订阅、待执行动画帧及Editor。此示例完成安装和快照订阅，不是包含全部指针交互的小地图UI组件。

读取快照前需要完成插件安装。宿主通过 subscribe 接收失效通知并合并绘制，使用同一投影绘制内容和视口框，避免两者比例不一致。

宿主职责

指针捕获、Canvas或DOM绘制、焦点与界面属于宿主。获焦/失焦通过 setFocused() 同步，按键按下和抬起经InputScope成对分发，失焦与卸载清理按住状态。

视口框最小宽度为50 CSS像素，高度保持画布视口比例；触及最小映射比例时显示局部概览，远处内容可能被裁切。导航只更新会话，不修改文档或历史。关闭后停止收集场景。

当前版本的大场景浏览器帧率验收仍待补，不承诺所有内容规模下的固定帧率。

快照字段

getSnapshot({width, height})读取当前几何投影。未安装、未启用或尺寸不为正时返回null；宿主收到null应清空或收起展示，不继续使用上一次内容。

字段	坐标 / 含义
`content.nodes`	节点ID、世界外框和是否为容器
`content.connectors`	连线ID、世界路由点和外框
`content.bounds`	内容整体世界范围，可为空
`projection`	`scale/x/y`，将同一世界坐标映射到小地图像素
`viewport`	当前画布可视区域的世界矩形
`theme`	绘制时使用的画布主题
`selectedNodes/selectedConnectors`	只读选区ID集合
`navigating`	是否正在进行小地图导航手势
`disabled`	当前维护冻结等状态不允许导航

内容与视口必须使用同一projection绘制。不能给视口框单独设最小宽高后仍沿用旧内容缩放，否则框与实际范围会错位。拖动过程中投影可保持稳定，不由宿主反复自行重算另一套比例。

导航方法

方法	参数 / 返回
`setEnabled(enabled)`	启闭收集；关闭时清理内容及导航状态
`setFocused(focused)`	同步当前小地图表面的键盘焦点
`subscribe(listener)`	失效通知；返回解绑函数
`beginNavigation(pointerId, point, size)`	point为小地图内像素点；成功认领本次导航返回true
`moveNavigation(pointerId, point)`	更新同一指针的导航
`endNavigation(pointerId)`	结束对应指针会话
`cancelNavigation()`	取消当前会话并通知重绘
`zoomAt(point, size, factor)`	输入小地图位置、尺寸和正倍率
`panBy(x, y)`	按输入增量平移；冻结或导航冲突时不执行

宿主只在beginNavigation返回true后捕获指针，PointerUp释放，PointerCancel或失焦时取消。导航只改变视口，即使文档只读也可以浏览；维护冻结则应尊重disabled。

常见问题

现象	排查
快照一直为null	安装插件后启用，并提供实际正尺寸
小地图没有文字和图片细节	当前是几何示意，不是第二套完整渲染器
远处内容被裁切	最小视口映射采用局部概览，不能假定任何距离都同时缩进一张图
方向键移动了主画布选中对象	同步小地图获焦状态，避免宿主焦点落在其他表面
关闭后还在收集或绘制	关闭setEnabled并释放宿主订阅、动画帧和指针会话

小地图 ​

大画布里的方向感 ​

按需安装 ​

宿主职责 ​

快照字段 ​

导航方法 ​

常见问题 ​