视口、工具与主题

示例以已有Editor为参数，SkyNoteEditor和CanvasThemeSeed从@skynote/editor导入。

坐标系统

属性 / 方法	单位与含义
viewport	只读{x,y,zoom}，本地会话状态
viewportSize	当前宿主容器的像素宽高
viewportCenter	视口中心对应的世界坐标
screenToWorld(point)	容器内屏幕坐标转世界坐标
worldToScreen(point)	世界坐标转容器内屏幕坐标

两个转换方法的屏幕点相对于画布容器左上角，不是浏览器clientX/clientY。宿主先减去容器的位置；滚动、全屏或布局变化后不要长期复用旧的DOM矩形。

export function placeAtPointer(
  editor: SkyNoteEditor<HTMLElement>,
  localPoint: { x: number; y: number }
): string | null {
  const world = editor.screenToWorld(localPoint);
  return editor.insertNodeAt({ nodeType: 'sticky', options: { text: '从这里开始' } }, world);
}

缩放与定位

接口	默认与边界
zoomAt(factor, center?)	倍数缩放，缺省锚点为视口中心；center是容器内屏幕点
fitContent()	容纳全部内容；内容较少时不放大到超过原始尺寸，空画布回原点
fitEntities(refs)	只适配指定实体；全部不存在时不改变视口
applyInitialView(mode?, viewport?)	mode缺省沿用构造配置
revealEntities(refs, options?)	保持缩放，平移以揭示目标；可指定居中、padding和面板insets
previewEntities(refs)	临时预览目标，返回结束预览的清理函数

打开策略：actual-size按100%缩放居中（受zoomRange限制）；fit-content适配内容；preserve只在提供视口时写入，不自动居中。直接传initialViewport却保留默认actual-size会在挂载时应用打开策略，恢复旧位置应配套使用preserve。

全屏或容器尺寸改变时，渲染器更新像素尺寸，不代表会自动重新居中。希望内容跟随适配的宿主，应等尺寸更新后调用fitContent()；不要在每次用户平移时调用，否则会把用户拉回原位。

工具与只读

tool读取当前工具，默认选择工具。startConnectorTool(type?)进入连线工具，type缺省沿用当前线型；stopTool()退出当前工具。线型取straight / orthogonal / curved。

setReadOnly(value)切换只读，isReadOnly查询状态，onReadOnlyChange(listener)返回解绑函数。只读仍允许会话导航；只读不是宿主鉴权，文档的访问权限、账号与插件开放范围由宿主负责。

主题与光标

export function useCanvasTheme(editor: SkyNoteEditor<HTMLElement>, seed: CanvasThemeSeed): void {
  editor.setTheme({ seed });
}

CanvasThemeSeed提供背景、前景与强调色等种子配置；setTheme({seed, overrides?})改变画布会话主题，theme读取推导结果。resolveColor(colorOrToken)解析当前主题颜色，例如$teal调色板引用。

宿主CSS明暗切换不会自动调用setTheme。宿主应从同一组主题配置同时更新CSS和画布，避免界面变暗、画布仍保持浅色。

registerCursor(definition)注册或覆盖光标并返回恢复函数；setCursorStyle(style)改变整套光标的配色。DOM悬停区域应通过宿主桥接统一光标，不另外叠加一套与画布不一致的鼠标样式。