MapCadLayer API

大约 4 分钟

MapCadLayer API

MapCadLayer 是 vjmapext 的核心门面类，实现 vjmap 的 IControl 接口，通过 map.addControl() 挂载到地图上。

构造函数

new MapCadLayer(options?: Partial<MapCadLayerOptions>)

MapCadLayerOptions

属性	类型	默认值	说明
`locale`	`'zh' \| 'en'`	`'zh'`	界面语言
`defaultColor`	`number`	`0x00ff00`	新建实体的默认颜色（24 位 RGB 整数）
`nudgePixels`	`number`	`1`	方向键微移像素数
`nudgeRotateDeg`	`number`	`1`	微旋转角度（度）
`nudgeScaleFactor`	`number`	`1.02`	微缩放因子
`mode`	`'edit' \| 'browse'`	`'edit'`	初始模式
`modeToggleShortcut`	`string`	`'ctrl+shift+e'`	模式切换快捷键
`shortcuts`	`ShortcutMap`	—	自定义快捷键映射
`drawingDefaults`	`Partial<DrawingDefaultsData>`	—	绘图默认值覆盖

示例：

import { MapCadLayer } from 'vjmapext';

const cadLayer = new MapCadLayer({
  locale: 'zh',
  defaultColor: 0xff0000,
  mode: 'edit',
});
map.addControl(cadLayer);

只读成员

通过这些属性访问各子系统实例。

属性	类型	说明
`coordMapper`	`CoordMapper`	坐标映射器（地理 ↔ CAD）
`eventBus`	`EventBus`	全局事件总线
`store`	`EntityStore`	实体数据存储
`renderCache`	`RenderCache`	渲染缓存
`renderPipeline`	`RenderPipeline`	渲染管线
`previewManager`	`PreviewManager`	预览管理器
`inputManager`	`InputManager`	输入管理器
`commandRegistry`	`CommandRegistry`	命令注册表
`entityRegistry`	`EntityRegistry`	实体类型注册表
`gripManager`	`GripManager`	夹点管理器
`undoManager`	`UndoManager`	撤销管理器
`pluginManager`	`PluginManager`	插件管理器
`snapManager`	`SnapManager`	捕捉管理器
`linetypeManager`	`LinetypeManager`	线型管理器
`drawingDefaults`	`DrawingDefaults`	绘图默认值
`animationManager`	`AnimationManager`	动画管理器
`blocks`	`Blocks`	块定义集合
`dimReactorManager`	`DimReactorManager`	标注反应器管理器

生命周期

onAdd

onAdd(map: vjmap.Map): HTMLElement

当控件被添加到地图时自动调用，完成坐标绑定、图层创建与事件监听。通常不需要手动调用，由 map.addControl() 触发。

参数	类型	说明
`map`	`vjmap.Map`	地图实例

返回： HTMLElement — 控件容器元素。

onRemove

onRemove(): void

控件从地图上移除时自动调用，释放所有资源。

字体加载

loadFont

loadFont(url: string, name?: string): Promise<void>

加载 OpenType 字体文件（.ttf / .otf），用于文字实体渲染。

参数	类型	说明
`url`	`string`	字体文件 URL
`name`	`string`	可选，字体注册名称。省略时从文件名推断

示例：

await cadLayer.loadFont('/fonts/simhei.ttf', '黑体');

模式管理

getMode

getMode(): 'edit' | 'browse'

返回： 当前模式字符串。

setMode

setMode(mode: 'edit' | 'browse'): void

切换编辑 / 浏览模式。

参数	类型	说明
`mode`	`'edit' \| 'browse'`	目标模式

toggleMode

toggleMode(): void

在编辑与浏览模式之间切换。

setModeToggleShortcut

setModeToggleShortcut(shortcut: string): void

设置模式切换快捷键。

参数	类型	说明
`shortcut`	`string`	快捷键字符串，如 `'ctrl+shift+e'`

快捷键

setShortcuts

setShortcuts(map: ShortcutMap): void

设置自定义快捷键映射，替换现有映射。

参数	类型	说明
`map`	`ShortcutMap`	快捷键到命令的映射对象

getShortcuts

getShortcuts(): ShortcutMap

返回： 当前快捷键映射副本。

命令执行

executeCommand

executeCommand(name: string, opts?: Record<string, any>): Promise<void>

按名称执行已注册的命令。

参数	类型	说明
`name`	`string`	命令名称
`opts`	`Record<string, any>`	可选参数传递给命令

示例：

await cadLayer.executeCommand('line');
await cadLayer.executeCommand('circle', { radius: 50 });

repeatLastCommand

repeatLastCommand(): Promise<void>

重复执行上一条命令。

getLastCommandName

getLastCommandName(): string | undefined

返回： 上一条执行的命令名称，未执行过则返回 undefined。

实体操作

addEntity

addEntity(entity: EntityBase): void

将实体添加到存储。

参数	类型	说明
`entity`	`EntityBase`	实体实例

deleteEntity

deleteEntity(id: string): void

按 ID 删除实体。

getEntities

getEntities(): EntityBase[]

返回： 所有实体数组。

getSelectedEntities

getSelectedEntities(): EntityBase[]

返回： 当前选中的实体数组。

clearSelection

clearSelection(): void

清除所有选择。

绘图顺序

moveToFront

moveToFront(ids?: string[]): void

将指定实体移至最前。省略 ids 时操作选中实体。

moveToBack

moveToBack(ids?: string[]): void

将指定实体移至最后。

moveUp

moveUp(ids?: string[]): void

将指定实体上移一层。

moveDown

moveDown(ids?: string[]): void

将指定实体下移一层。

撤销 / 重做

undo

undo(): void

撤销上一步操作。

redo

redo(): void

重做上一步被撤销的操作。

插件

loadPlugin

loadPlugin(plugin: Plugin): Promise<void>

加载并激活插件。

参数	类型	说明
`plugin`	`Plugin`	插件对象

序列化

toJSON

toJSON(): SerializedDocument

将当前绘图序列化为 JSON 文档。

返回： SerializedDocument 对象。

fromJSON

fromJSON(doc: SerializedDocument): void

从 JSON 文档恢复绘图。

参数	类型	说明
`doc`	`SerializedDocument`	序列化文档对象

示例：

const doc = cadLayer.toJSON();
localStorage.setItem('drawing', JSON.stringify(doc));

// 恢复
const saved = JSON.parse(localStorage.getItem('drawing')!);
cadLayer.fromJSON(saved);

对象捕捉

setSnapEnabled

setSnapEnabled(enabled: boolean): void

启用或禁用对象捕捉。

setSnapMode

setSnapMode(mode: number): void

设置捕捉模式（位掩码组合）。详见 SnapManager API。

绘图默认值

getDrawingDefaults

getDrawingDefaults(): DrawingDefaultsData

返回： 当前绘图默认值副本。

setDrawingDefaults

setDrawingDefaults(opts: Partial<DrawingDefaultsData>): void

更新绘图默认值（合并模式）。

视图

zoomExtents

zoomExtents(padding?: number): void

缩放到全部实体范围。

参数	类型	说明
`padding`	`number`	可选，边距像素数

getMap

getMap(): vjmap.Map

返回： 关联的 vjmap 地图实例。

getMapContainer

getMapContainer(): HTMLElement

返回： 地图容器 DOM 元素。

refreshDisplayLevel

refreshDisplayLevel(): void

根据当前缩放级别刷新实体的显示层级过滤。

国际化

setLocale

setLocale(locale: Locale): void

切换界面语言。

参数	类型	说明
`locale`	`Locale`	`'zh'` 或 `'en'`

UI 创建

createUI

createUI(options?: object): void

创建默认 UI 组件（工具栏、属性面板、命令输入框等）。

参数	类型	说明
`options`	`object`	可选，UI 配置项

示例：

cadLayer.createUI();