Add SEO metadata and security headers

2026-05-23 11:17:29 +08:00
parent cc65395b59
commit 582a4214b6
40 changed files with 15323 additions and 5 deletions
@@ -0,0 +1,247 @@
+# 地图加载与初始化 (Map Initialization)
+
+本指南介绍如何使用 `@amap/amap-jsapi-loader` 异步加载高德地图 JSAPI v2.0，并初始化地图实例。
+
+## 前置条件
+
+在加载地图前，**必须**先完成安全配置。请参考 [安全配置文档](./security.md)。
+
+```javascript
+// 必须在加载前执行
+window._AMapSecurityConfig = {
+  securityJsCode: '您的安全密钥',
+};
+```
+
+## 1. 引入加载器
+使用 script 标签加载 loader.js：
+```bash
+<script src="https://webapi.amap.com/loader.js"></script>
+```
+
+## 2. 异步加载 JSAPI
+
+使用 `AMapLoader.load` 方法加载 API。
+
+```javascript
+import AMapLoader from '@amap/amap-jsapi-loader';
+
+AMapLoader.load({
+    key: '您的Key',              // 必填，申请的 Web 端开发者 Key
+    version: '2.0',             // 必填，指定版本号
+    plugins: ['AMap.Scale'],    // 预加载插件列表
+}).then((AMap) => {
+    // JSAPI 加载完成，可以开始初始化地图
+    initMap(AMap);
+}).catch((e) => {
+    console.error('地图加载失败', e);
+});
+```
+
+## 3. 进阶配置 (Advanced Configuration)
+
+### 加载 Loca 数据可视化库
+Loca 是高德地图基于 WebGL 的高性能数据可视化库。需要在加载器中显式声明 `Loca` 配置。
+
+```javascript
+AMapLoader.load({
+    key: '您的Key',
+    version: '2.0',
+    Loca: {
+        version: '2.0.0' // 指定 Loca 版本
+    }
+}).then((AMap) => {
+    const map = new AMap.Map('container');
+    
+    // 初始化 Loca 容器
+    const loca = new Loca.Container({
+        map: map,
+    });
+});
+```
+
+
+```
+
+### 加载器参数详解
+
+| 参数 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `key` | String | 是 | 申请好的 Web 端开发者 Key |
+| `version` | String | 是 | 指定要加载的 JSAPI 版本，如 "2.0" |
+| `plugins` | Array | 否 | 需要预加载的插件列表，如 `['AMap.Scale', 'AMap.ToolBar']` |
+| `Loca` | Object | 否 | Loca 库配置，包含 `{ version: '2.0.0' }` |
+| `AMapUI` | Object | 否 | AMapUI 库配置，包含 `{ version: '1.1', plugins: [] }` |
+| `serviceHost` | String | 否 | 代理服务器地址（通常在安全配置中全局设置，此处也可覆盖） |
+
+## 3. 初始化地图实例
+
+创建 `AMap.Map` 实例，建议开启 3D 视图模式以获得最佳性能。
+
+```javascript
+function initMap(AMap) {
+    const map = new AMap.Map('container', {
+        viewMode: '3D',    // 开启 3D 模式 (推荐)
+        zoom: 11,          // 初始化缩放级别 [2, 20]
+        center: [116.397428, 39.90923], // 初始化中心点坐标 [lng, lat]
+        pitch: 45,         // 俯仰角度，有效范围 [0, 83]
+        rotation: 0,       // 旋转角度
+        mapStyle: 'amap://styles/normal', // 地图样式
+    });
+
+    // 添加控件
+    map.addControl(new AMap.Scale());
+}
+```
+### 常用配置项
+
+| 参数 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| viewMode | String | '2D' | 渲染模式：'2D' 或 '3D' |
+| zoom | Number | - | 初始缩放级别 |
+| center | Array | - | 初始中心点 [lng, lat] |
+| pitch | Number | 0 | 俯仰角度 (3D 模式有效) |
+| rotation | Number | 0 | 旋转角度 |
+| mapStyle | String | - | 地图样式 URL |
+| zooms | Array | [2, 20] | 缩放级别范围 |
+
+## 4. 地图生命周期管理
+### 地图加载完成
+
+```javascript
+map.on('complete', function() {
+  console.log('地图加载完成');
+});
+```
+
+### 销毁地图
+在组件卸载或不再需要地图时，务必调用 `destroy` 方法以释放 WebGL 上下文和内存资源。
+
+```javascript
+// 销毁地图实例
+if (map) {
+    map.destroy();
+    map = null;
+}
+```
+## 5. 地图样式
+
+### 官方主题样式
+
+```javascript
+const map = new AMap.Map('container', {
+  mapStyle: 'amap://styles/normal', // 标准
+  // mapStyle: 'amap://styles/dark',      // 幻影黑
+  // mapStyle: 'amap://styles/light',     // 月光银
+  // mapStyle: 'amap://styles/whitesmoke',// 远山黛
+  // mapStyle: 'amap://styles/fresh',     // 草色青
+  // mapStyle: 'amap://styles/grey',      // 雅士灰
+  // mapStyle: 'amap://styles/graffiti',  // 涂鸦
+  // mapStyle: 'amap://styles/macaron',   // 马卡龙
+  // mapStyle: 'amap://styles/blue',      // 靛青蓝
+  // mapStyle: 'amap://styles/darkblue',  // 极夜蓝
+  // mapStyle: 'amap://styles/wine',      // 酱籽
+});
+
+// 动态切换样式
+map.setMapStyle('amap://styles/dark');
+```
+
+## 完整示例 (Vue 3)
+
+```vue
+<template>
+  <div id="map-container" style="width: 100%; height: 500px;"></div>
+</template>
+
+<script setup>
+import { onMounted, onUnmounted, shallowRef } from 'vue';
+import AMapLoader from '@amap/amap-jsapi-loader';
+
+const map = shallowRef(null); // 使用 shallowRef 避免深层响应式带来的性能损耗
+
+onMounted(() => {
+  window._AMapSecurityConfig = { securityJsCode: '您的安全密钥' };
+
+  AMapLoader.load({
+    key: '您的Key',
+    version: '2.0',
+    plugins: ['AMap.Scale'], // 按需加载插件
+  }).then((AMap) => {
+    map.value = new AMap.Map('map-container', {
+      viewMode: '3D',
+      zoom: 12,
+      center: [120.15, 30.28],
+    });
+    // 添加插件
+    map.value.addControl(new AMap.Scale());
+  }).catch(e => console.error(e));
+});
+
+onUnmounted(() => {
+  map.value?.destroy();
+});
+</script>
+```
+## 5. 地图控件
+
+```javascript
+// 比例尺
+map.addControl(new AMap.Scale());
+
+// 工具条（缩放、定位）
+map.addControl(new AMap.ToolBar({
+  position: 'RT' // 右上角
+}));
+
+// 3D 控制（旋转、俯仰）
+map.addControl(new AMap.ControlBar({
+  position: { right: '10px', top: '10px' }
+}));
+
+// 鹰眼（缩略图）
+map.addControl(new AMap.HawkEye());
+
+// 图层切换
+map.addControl(new AMap.MapType());
+```
+
+## 完整示例 (React Hooks)
+
+```jsx
+import React, { useEffect, useRef } from 'react';
+import AMapLoader from '@amap/amap-jsapi-loader';
+
+export default function MapComponent() {
+  const mapRef = useRef(null);
+
+  useEffect(() => {
+    // 安全密钥配置
+    window._AMapSecurityConfig = { securityJsCode: '您的安全密钥' };
+
+    AMapLoader.load({
+      key: '您的Key',
+      version: '2.0',
+      plugins: ['AMap.Scale'], // 预加载插件
+    }).then((AMap) => {
+      mapRef.current = new AMap.Map('map-container', {
+        viewMode: '3D',
+        zoom: 11,
+        center: [116.397428, 39.90923],
+      });
+
+      // 添加控件
+      mapRef.current.addControl(new AMap.Scale());
+    }).catch((e) => {
+      console.error('地图加载失败', e);
+    });
+
+    // 销毁地图
+    return () => {
+      mapRef.current?.destroy();
+    };
+  }, []);
+
+  return <div id="map-container" style={{ width: '100%', height: '500px' }} />;
+}
+```