vjmapext

vjmapext

语言 / Languages： 中文（默认） · English

在 vjmap 上叠加 CAD 级矢量绘图、标注与高性能特效图层（fx） 的前端扩展库。核心类 MapCadLayer 实现 vjmap 的 IControl，可作为地图控件挂载，提供实体、命令、捕捉、夹点、撤销、标注、动画、GPU 着色器特效与可选内置 UI（工具栏 / 属性 / 命令行）。

中文

特性摘要

• 实体：直线、多段线、圆、弧、椭圆、样条、填充、文字、多行文字、块引用及多种标注等。
• 命令：绘图与编辑命令体系，可注册自定义命令。
• 地图数据：可与底图要素联动查询与转换（视业务与 vjmap 服务配置而定）。
• 动画：内置 AnimationManager，支持补间、路径等效果。
• 高性能特效图层（fx）：GPU 着色器驱动，支持点/线预设、Shadertoy、Symbol 图标与 CAD 实体绑定，适合万级实例的实时视觉效果。
• 国际化：内置中英文文案，可通过 API 切换语言（与宿主应用语言策略配合）。
• TypeScript：提供类型定义（dist 内 .d.ts，具体以发布包为准）。

依赖与环境（必读）

• vjmapext 不能脱离 vjmap 单独使用。 必须先具备 vjmap 运行环境（地图 SDK、底图样式、服务与 vjmap.Map 等），再使用本库。
• npm 工程：请同时安装 vjmap 与 vjmapext（或已安装满足版本要求的 vjmap）。仅安装 vjmapext、未安装/未加载 vjmap 时无法正常工作。
• 本包发布内容：以 package.json 的 files 为准，一般为 dist 下的 vjmapext.min.js（UMD） 与类型声明；不包含 .map 源映射文件。

npm 安装

npm install vjmap vjmapext

若已单独安装 vjmap，请保证其版本满足当前 vjmapext 版本的兼容范围（见发布说明或 peer 依赖约束）。

Vite / Webpack 等打包引用

发布 dist 仅含 UMD 的 vjmapext.min.js（无 ESM 分包）。在打包工具中请使用 命名空间导入，例如：

import * as vjmapext from 'vjmapext';

const { MapCadLayer, setLocale } = vjmapext;

并配置好 vjmap 的解析（与 node_modules 中 vjmap 入口一致）。

在 HTML 中通过 <script> 引用

在纯 HTML 或不经打包工具的场景下，请严格按顺序加载：先 vjmap，再 vjmapext（本库依赖 vjmap 提供的全局对象与地图实例）。

<link rel="stylesheet" href="./vjmap.min.css" />
<script src="./vjmap.min.js"></script>
<script src="./vjmapext.min.js"></script>
<script>
  // 此时应已存在全局 vjmap；vjmapext 的导出挂在全局 vjmapext（与 dist UMD 一致）
  // 先按 vjmap 文档创建 map、打开服务，再：
  // const mapcadLayer = new vjmapext.MapCadLayer();
  // map.addControl(mapcadLayer);
</script>

路径请按实际部署修改；切勿在 vjmap 未加载完成前执行依赖 vjmap 或 MapCadLayer 的代码。

最小用法

import 'vjmap/dist/vjmap.min.css';
import vjmap from 'vjmap';
import { MapCadLayer, setLocale } from 'vjmapext';

// …创建 map、打开图纸或服务，await map.onLoad() 之后：

setLocale('zh'); // 或 'en'

const mapcad = new MapCadLayer();
map.addControl(mapcad);
mapcad.createUI({ theme: 'dark' }); // 可选：内置工具栏 / 属性面板 / 命令行

// 示例：添加实体（具体 API 以类型定义与文档为准）
// mapcad.store / mapcad.commandRegistry 等

文档与示例

• 产品介绍与架构说明见 vjmap 官方文档站点中的 vjmapext / MapCadLayer 章节。

• 高性能特效图层文档见 fx 专题（总览、快速开始、点/线预设、Shadertoy、CAD 绑定、性能调优等）。

• 文档地址：https://vjmap.com/app/docsext

• 示例地址：https://vjmap.com/app/demoext

许可证

本包以 LGPL-3.0 发布（见仓库内 LICENSE 或 npm 元数据）。

English

Back to 中文 (top)

Overview

vjmapext is a front-end extension for vjmap that adds CAD-style vector drawing, annotation, and a high-performance FX layer on top of the map. The core class MapCadLayer implements vjmap’s IControl interface, attaches as a map control, and provides entities, commands, object snaps, grips, undo/redo, dimensions, animation, GPU shader effects, and an optional built-in UI (toolbar / property panel / command line).

Highlights

• Entities: lines, polylines, circles, arcs, ellipses, splines, hatches, text, MText, block references, and multiple dimension types, etc.
• Commands: drawing and editing command system; custom commands can be registered.
• Map data: can interoperate with base-map features (depending on your vjmap service setup).
• Animation: built-in AnimationManager (tweens, paths, etc.).
• High-performance FX layer: GPU shader driven visual effects with point/line presets, Shadertoy integration, symbol icons, and CAD entity binding for large-scale real-time rendering.
• i18n: built-in Chinese / English strings; switch via API to match your app.
• TypeScript: typings shipped under dist (subject to the published package layout).

Requirements (read this)

• vjmapext cannot be used without vjmap. You must have the vjmap runtime (SDK, styles, services, and a vjmap.Map instance) before using this library.
• npm projects: install both vjmap and vjmapext (or ensure a compatible vjmap is already installed). Installing only vjmapext is not sufficient.

Install (npm)

npm install vjmap vjmapext

Ensure your vjmap version satisfies the compatibility range required by your vjmapext release.

Vite / Webpack (UMD package)

The published dist contains vjmapext.min.js (UMD) only (no ESM split). Prefer a namespace import:

import * as vjmapext from 'vjmapext';

const { MapCadLayer, setLocale } = vjmapext;

Ensure vjmap resolves like your other node_modules dependencies.

Browser: <script> tags (UMD)

Load scripts in order: vjmap first, then vjmapext. The library expects the global vjmap environment to exist first.

<link rel="stylesheet" href="./vjmap.min.css" />
<script src="./vjmap.min.js"></script>
<script src="./vjmapext.min.js"></script>
<script>
  // Globals: vjmap, vjmapext (UMD bundle names as shipped in dist)
  // Create the map per vjmap docs, then e.g. new vjmapext.MapCadLayer()
</script>

Adjust paths to your deployment. Do not load vjmapext before vjmap.

Minimal example

import 'vjmap/dist/vjmap.min.css';
import vjmap from 'vjmap';
import { MapCadLayer, setLocale } from 'vjmapext';

// …create the map, open your map service, after await map.onLoad():

setLocale('en'); // or 'zh'

const mapcad = new MapCadLayer();
map.addControl(mapcad);
mapcad.createUI({ theme: 'dark' }); // optional built-in UI

// Add entities / run commands via mapcad.store, mapcad.commandRegistry, etc.

Docs & demos

• See the official vjmap documentation for vjmapext / MapCadLayer.

• See the FX documentation for the new GPU effect layer (overview, quick start, presets, Shadertoy, CAD binding, and performance tuning).

• Docs : https://vjmap.com/app/docsext/en

• Playground : https://vjmap.com/app/demoext/#/gallery/map?lang=en

License

Published under LGPL-3.0 (see LICENSE in the repository or npm metadata).