唯杰地图 logo唯杰地图
VJMAP
EN

安装

vjmap3d/references/guide/quickstart.md 5.1 KB120 行
原文

简介

本指南介绍如何使用基于 vjmap3d 进行二次开发。通过阅读本指南，您将了解如何安装、引入并在不同的开发环境中使用该库。

安装

首先，确保您已安装 Node.js 和 npm、yarn 或 pnpm。然后在您的项目目录中运行以下命令来安装库： ::: tabs

@tab npm

npm install vjmap3d

@tab yarn

yarn add vjmap3d

@tab pnpm

pnpm add vjmap3d

:::

提示

vjmap3d依赖threejs库，当安装vjmap时，如果没有自动安装peerDependencies中的依赖时，需要手动安装three.js。版本以所装 vjmap3d 包声明的 peer 为准：npm 上 vjmap3d@2.0.0 声明 three@>=0.185.0（v2 起 WebGPU 渲染引擎依赖该版本的 three/webgpu 与 three/tsl 入口）；npm i vjmap3d three 时 npm/pnpm 会按 peer 自动选对版本。旧版 vjmap3d@1.0.23（webgl-only）对应 three@^0.165。

yarn add three        # 或显式 yarn add three@^0.185（npm 版 vjmap3d@2.0.0）

如开发中需要threejs的类型提示，还需要安装threejs的类型库 @types/three（版本与 three 主版本对齐）

npm install @types/three -D

TypeScript 工程配置

vjmap3d v2 的类型声明引用了 three/webgpu 子路径导出，TypeScript 工程建议 tsconfig.json 的 moduleResolution 设为 bundler（或 node16/nodenext）；若使用旧的 node 解析方式，请开启 skipLibCheck: true。

适用环境：vjmap3d@2.0.0 + typescript@7 + @types/three@0.185

  • skipLibCheck: true 是必需项：vjmap3d.d.ts 在 declare namespace 内部写了 import {...} from 'three'（TS1147），不开 skipLibCheck 会刷出一屏声明文件错误。
  • 即便开了 skipLibCheck，继承 three 材质的参数接口会断链——如 new MapProvider(layers, { transparent: true }) 运行时合法（MapProviderParameters extends MeshBasicMaterialParameters），但 tsc 报 TS2353 'transparent' does not exist（命名空间内 import 失败导致 extends 未解析）。transparent/opacity/color 等全部继承自 MeshBasicMaterialParameters 的键都报 excess-property（只有自有键 rootTile/backColor/texture/colorFilter 可用）。绕过：把 options 赋给变量再传入、或 as any；setValue/onChange 回调的 strict-TS 写法见 ../ui/uiconfig.md。
  • d.ts 欠声明（已修复）：GeoBounds.toArray()/toPointArray()/width()/height()/scale() 在 v2.0.0 的 vjmap3d.d.ts 中均已声明，无需 (as any) 绕过；若个别旧版包缺声明才需要自行补充。
  • toDist 签名是 (dist, isMap2dHeightMeter?, app?, mapView?)——app 是第三参数，toDist(x, app) 会把 App 当 boolean 传错位置。

引入

引入指定模块：

import { App } from 'vjmap3d';
// 引入样式
import "vjmap3d/dist/vjmap3d.min.css";

或引入全局模块：

 import * as THREE from 'three';
 import * as vjmap3d from 'vjmap3d';
 // 或
 //import vjmap3d from 'vjmap3d';
 // 引入样式
import "vjmap3d/dist/vjmap3d.min.css";

纯Html开发

对于不使用打包工具的纯 HTML 开发项目，您可以通过 script 标签引入库。

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>map3d</title>
	<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
	<link type="text/css" rel="stylesheet" href="./lib/vjmap3d/dist/vjmap3d.min.css">
</head>
<body>
	<script type="importmap">
        {
            "imports": {
                "three": "./lib/three/build/three.module.js",
                "three/webgpu": "./lib/three/build/three.webgpu.js",
                "three/tsl": "./lib/three/build/three.tsl.js",
                "three/examples/jsm/": "./lib/three/examples/jsm/",
                "vjmap3d": "./lib/vjmap3d/dist/vjmap3d.min.js"
            }
        }
	</script>
    <script type="module">
        import * as THREE from 'three';
        import * as vjmap3d from 'vjmap3d';
    </script>
</body>
</html>

提示

three/webgpu 与 three/tsl 两条映射用于 WebGPU 渲染引擎（render: { engine: "webgpu" }，SDK 内部按需动态加载，webgl 用户零开销）。若只使用默认的 webgl 引擎，可以省略这两条。

three 版本必须与 vjmap3d 的 peer 对齐

npm 上 vjmap3d@2.0.0 声明 three@>=0.185.0，其 dist 在 WebGPU 引擎下动态 import three/webgpu、three/tsl（three@0.165 的包甚至没有 three.webgpu.js/three.tsl.js 构建文件）。不要把 vjmap3d@2.0.0 与 three@0.165 混用——npm 模板/文档里写 ^0.185 就用 0.185.x。旧版 vjmap3d@1.0.23（webgl-only，peer three@^0.165）不 import 这两个子路径，也无需这两条 importmap。templates/cdn/index.html 已按 v2 对齐。

目录格式如下：

- index.html
- lib/
  - three/
  - vjmap3d/
    - dist/
        - vjmap3d.min.js
        - vjmap3d.min.css