# 安装

## 简介

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

## 安装

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

@tab npm
``` sh
npm install vjmap3d
```
@tab yarn
``` sh
yarn add vjmap3d
```
@tab pnpm
``` sh
pnpm add vjmap3d
```
:::

::: tip 提示
`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`。
``` sh
yarn add three        # 或显式 yarn add three@^0.185（npm 版 vjmap3d@2.0.0）
```
:::

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

::: tip 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](../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 传错位置。
:::

## 引入

引入指定模块：

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

或引入全局模块：
```js
 import * as THREE from 'three';
 import * as vjmap3d from 'vjmap3d';
 // 或
 //import vjmap3d from 'vjmap3d';
 // 引入样式
import "vjmap3d/dist/vjmap3d.min.css";
```

## 纯Html开发

对于不使用打包工具的纯 HTML 开发项目，您可以通过 `script` 标签引入库。
```html
<!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>
```

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

::: warning 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
```