Mapbox GL JS - 无捆绑器

# Mapbox 集成模式技能此技能提供了使用 React、Vue、Svelte、Angular 和 vanilla JavaScript 将 Mapbox GL JS 集成到 Web 应用程序中的官方模式。这些模式基于 Mapbox 的“create-web-app”脚手架工具，代表了生产就绪的最佳实践。 ## 版本要求 ### Mapbox GL JS **推荐：** v3.x（最新） * **最低：** v3.0.0 * **为什么选择 v3.x：** 现代 API、改进的性能、积极的开发 * **v2.x：** 旧版；不再积极开发（请参阅下面的迁移说明） **通过 npm 安装（推荐用于生产）：** npm install mapbox-gl@^3.0.0 # 安装最新的 v3.x **CDN（仅用于原型设计）：** ⚠️ **生产应用程序应该使用 npm，而不是 CDN** \ - 确保一致的版本和离线构建。 ### 框架要求 **反应：** * GL JS 可与 React 16.8+ 配合使用（需要钩子） * 使用 React 19.x 的 `create-web-app` 脚手架 **视觉：** * GL JS 可与 Vue 2.x+ 配合使用（推荐使用 Vue 3 Composition API） * Vue 2.x：使用选项 API 模式（安装/卸载钩子） **苗条：** * GL JS 适用于任何 Svelte 版本 * 使用 Svelte 5.x 的 `create-web-app` 脚手架 **角度：** * GL JS 可与 Angular 2+ 配合使用（任何带有生命周期挂钩的版本） * 使用 Angular 19.x 的 `create-web-app` 脚手架 **下一个.js：** * 最低版本：13.x（应用程序路由器） * 页面路由器：12.x+ ### Mapbox 搜索 JS **搜索集成所需：** npm install @mapbox/search-js-react@^1.0.0 # React npm install @mapbox/search-js-web@^1.0.0 # 其他框架 ### 版本迁移注意事项 **从 v2.x 迁移到 v3.x：** * 现在需要 WebGL 2 * 删除了“optimizeForTerrain”选项 * 改进了 TypeScript 类型 * 更好的摇树支持 * 核心初始化模式没有重大变化 **令牌模式（适用于 v2.x 和 v3.x）：** const token = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; // 在生产中使用环境变量 // 全局令牌（自 v1.x 起有效） mapboxgl.accessToken = 令牌； const map = new mapboxgl.Map({ 容器: '...' }); // 每个地图令牌（多地图设置首选）常量地图=新mapboxgl.Map({ 访问令牌：令牌，容器：'...' }); ## 核心原则 **每个 Mapbox GL JS 集成必须：** 1. 在正确的生命周期钩子中初始化映射 2. 将地图实例存储在组件状态中（不在每次渲染时重新创建） 3. **始终在清理时调用`map.remove()`以防止内存泄漏 4.安全地处理令牌管理（环境变量） 5.导入CSS：`import 'mapbox-gl/dist/mapbox-gl.css'` ## 特定于框架的模式 ### 反应集成 **模式：useRef + useEffect 并进行清理** > **注意：** 这些示例使用 **Vite** （`create-web-app` 中使用的捆绑器）。如果使用 Create React App，请将“import.meta.env.VITE_MAPBOX_ACCESS_TOKEN”替换为“process.env.REACT_APP_MAPBOX_TOKEN”。有关其他捆绑程序，请参阅令牌管理模式部分。从 'react' 导入 { useRef, useEffect }; 从“mapbox-gl”导入mapboxgl；导入'mapbox-gl/dist/mapbox-gl.css'; 函数 MapComponent() { const mapRef = useRef(null); // 存储地图实例 const mapContainerRef = useRef(null); // 存储 DOM 引用使用效果（（）=> { mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; mapRef.current = 新的mapboxgl.Map({ 容器：mapContainerRef.current，中心：[-71.05953，42.3629]，变焦：13 }); // 关键：清理以防止内存泄漏返回（）=> { mapRef.current.remove(); }; }, []); // 空依赖数组 = 在挂载时运行一次返回

; } **要点：** * 对地图实例和容器使用`useRef` * 在 `useEffect` 中使用空 deps `[]` 进行初始化 * **始终返回调用 `map.remove()` 的清理函数** * 切勿在渲染中初始化地图（导致无限循环） **反应+搜索JS：** 从 'react' 导入 { useRef, useEffect, useState }; 从“mapbox-gl”导入mapboxgl；从'@mapbox/search-js-react'导入{SearchBox}；导入'mapbox-gl/dist/mapbox-gl.css'; const accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; 常量中心 = [-71.05953, 42.3629]; 函数 MapWithSearch() { const mapRef = useRef(null); const mapContainerRef = useRef(null); const [inputValue, setInputValue] = useState(''); 使用效果（（）=> { mapboxgl.accessToken = accessToken; mapRef.current = 新的mapboxgl.Map({ 容器：mapContainerRef.current，中心：中心，变焦：13 }); 返回（）=> { mapRef.current.remove(); }; }, []); 返回（ <>

<搜索框访问令牌={访问令牌} 地图={mapRef.当前} 地图框={地图框} 值={输入值} 接近度={中心} onChange={(d) => setInputValue(d)} 标记 />

）； } ** ** ### Vue 集成 **模式：已安装 + 未安装的生命周期挂钩** <模板>

<脚本> 从“mapbox-gl”导入mapboxgl；导入'mapbox-gl/dist/mapbox-gl.css'; mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; 导出默认值{ 安装（）{ 常量地图=新mapboxgl.Map({ 容器：this.$refs.mapContainer，样式：'mapbox://styles/mapbox/standard', 中心：[-71.05953，42.3629]，变焦：13 }); // 将地图实例分配给组件属性 this.map = 地图; }, // 关键：组件卸载时清理卸载（）{ this.map.remove(); this.map = null; } }; <风格> .map-container { 宽度：100%；高度：100%； } **要点：** * 在`mounted()`钩子中初始化 * 通过 `this.$refs.mapContainer` 访问容器 * 将地图存储为`this.map` * **始终实现`unmounted()`钩子**来调用`map.remove()` ** ** ### 精简集成 **模式：onMount + onDestroy** <脚本> 从“mapbox-gl”导入mapboxgl 导入 'mapbox-gl/dist/mapbox-gl.css' 从 'svelte' 导入 { onMount, onDestroy } 让地图让mapContainer 挂载（（）=> { 地图 = 新的 mapboxgl.Map({ 容器：mapContainer， accessToken: import.meta.env.VITE_MAPBOX_ACCESS_TOKEN, 中心：[-71.05953，42.36290]，变焦：13 }) }) // 关键：在组件销毁时进行清理 onDestroy(() => { 地图.删除() })

<风格> .地图{ 位置：绝对；宽度：100%；高度：100%； } **要点：** * 使用`onMount`进行初始化 * 使用`bind:this={mapContainer}`绑定容器 * **始终实现`onDestroy`**来调用`map.remove()` * 可以将 `accessToken` 直接传递给 Svelte 中的 Map 构造函数 ** ** ### 角度整合 **模式：带有 SSR 处理的 ngOnInit + ngOnDestroy** 从 '@angular/core' 导入 { Component, ElementRef, OnDestroy, OnInit, ViewChild, 注入 }; 从 '@angular/common' 导入 { isPlatformBrowser, CommonModule }; 从“@angular/core”导入{PLATFORM_ID}；从'../../environments/environment'导入{环境}； @组件（{ 选择器：'应用程序地图'，独立：真实，导入：[CommonModule]， templateUrl: './map.component.html', styleUrls: ['./map.component.scss'] }) 导出类 MapComponent 实现 OnInit、OnDestroy { @ViewChild('mapContainer', { static: false }) mapContainer!: ElementRef; 私人地图：任何；私有只读platformId =注入(PLATFORM_ID); 异步 ngOnInit(): Promise { // 重要提示：检查是否在浏览器中运行（不是 SSR） if (!isPlatformBrowser(this.platformId)) { 返回； } 尝试{ 等待 this.initializeMap(); } 捕获（错误）{ console.error('初始化地图失败：', error); } } 私有异步initializeMap(): Promise { // 动态导入以避免SSR问题 const mapboxgl = (await import('mapbox-gl')).default; this.map = 新的mapboxgl.Map({ accessToken：环境.mapboxAccessToken，容器：this.mapContainer.nativeElement，中心：[-71.05953，42.3629]，变焦：13 }); // 处理地图错误 this.map.on('error', (e: any) => console.error('地图错误：', e.error)); } // 关键：在组件销毁时进行清理 ngOnDestroy(): 无效 { if (this.map) { this.map.remove(); } } } **模板（map.component.html）：**

**要点：** * 使用`@ViewChild`来引用地图容器 * **初始化前检查`isPlatformBrowser`**（SSR支持） * **动态导入`mapbox-gl`**以避免SSR问题 * 在`ngOnInit()`生命周期钩子中初始化 * **始终实现`ngOnDestroy()`**来调用`map.remove()` * 使用`map.on('error', ...)`处理错误 ** ** ### Vanilla JavaScript（带有 Vite） **模式：带有初始化函数的模块导入** 从“mapbox-gl”导入mapboxgl；导入'mapbox-gl/dist/mapbox-gl.css'; 导入'./main.css'; // 设置访问令牌 mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; 让地图； /** * 初始化地图 */ 函数 initMap() { 地图 = 新的 mapboxgl.Map({ 容器：'地图容器'，中心：[-71.05953，42.3629]，变焦：13 }); map.on('加载', () => { console.log('地图已加载'); }); } // 脚本运行时初始化初始化映射(); **HTML：**

**要点：** * 将映射存储在模块范围的变量中 * 立即初始化或在 DOMContentLoaded 上初始化 * 监听初始化后操作的“加载”事件 ** ** ### Vanilla JavaScript（无捆绑程序 - CDN） **模式：具有内联初始化的脚本标记** ⚠️ **注意：** 此模式仅用于原型设计。生产应用程序应使用 npm/bundler 进行版本控制和离线构建。 <头> <元字符集=“UTF-8”/> Mapbox GL JS - 无捆绑器 <风格> 身体{ 位置：绝对；顶部：0；右：0；底部：0；左：0；保证金：0；填充：0； } #map-container { 高度：100%；宽度：100%； } <正文>

<脚本> // 设置访问令牌 mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN_HERE'; 让地图；函数 initMap() { 地图 = 新的 mapboxgl.Map({ 容器：'地图容器'，中心：[-71.05953，42.3629]，变焦：13 }); map.on('加载', () => { console.log('地图已加载'); }); } // 页面加载时初始化初始化映射(); **要点：** * ⚠️ **仅限原型制作** \- 不建议用于生产 * 将 `3.x.x` 替换为 [Mapbox 文档]() 中的特定版本（例如，`3.7.0`） * **不要使用`/latest/`** \- 始终固定到特定版本以保持一致性 * 脚本加载后初始化（主体底部） * 对于生产：使用 npm + bundler 代替 **为什么不使用 CDN 进行生产？** * ❌ 网络依赖（断线） * ❌ 无版本锁定（CDN 可能会更改） * ❌ 较慢（无捆绑器优化） * ❌ 没有摇树 * ✅ 使用 npm 进行生产：`npm install mapbox-gl@^3.0.0` ** ** ## 高级模式 ### Web 组件（与框架无关） Web 组件是一种 W3C 标准，用于创建可在任何框架或根本没有框架中工作的可重用自定义元素。 **何时使用 Web 组件：** * ✅ **普通 JavaScript 应用程序** \- 没有框架？ Web 组件是一个不错的选择 * ✅ **设计系统** \- 构建跨多个框架使用的组件库 * ✅ **微前端** \- 应用程序在不同部分使用不同的框架 * ✅ **多框架组织** \- 使用 React、Vue、Svelte 等的团队需要共享组件 * ✅ **框架迁移** \- 逐步从一个框架过渡到另一个框架 * ✅ **长期稳定性** \- W3C 标准，无框架锁定 **真实世界的示例：** 一家拥有 React（主应用程序）、Vue（管理面板）和 Svelte（营销网站）的公司可以构建一个可在任何地方使用的“”组件。 **何时使用特定于框架的模式：** * 🔧 **已经使用框架** \- 如果您在 React 中构建，请使用 React 模式（更简单，集成更好） * 🔧 **需要框架功能** \- 与 React hooks、Vue Composition API、状态管理、路由深度集成 * 🔧 **团队熟悉度** \- 团队精通框架模式 > **💡提示：** 如果您使用 React、Vue、Svelte 或 Angular，请从上面特定于框架的模式开始。它们更简单并且集成得更好。当您需要跨框架兼容性或正在构建普通 JavaScript 应用程序时，请使用 Web 组件。 ** ** **模式：具有生命周期回调的标准自定义元素** Web 组件提供了一种与框架无关的方法，使用 W3C Web 组件标准封装 Mapbox 地图。 **基本网络组件：** 从“mapbox-gl”导入mapboxgl；导入'mapbox-gl/dist/mapbox-gl.css'; 类 MapboxMap 扩展 HTMLElement { 构造函数（）{ 超级（）； this.map = null; } 连接回调() { // 从属性中获取配置 const token = this.getAttribute('access-token') || import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; const mapStyle = this.getAttribute('地图样式') || 'mapbox://styles/mapbox/standard'; const center = this.getAttribute('center')?.split(',').map(Number) || [-71.05953, 42.3629]; const Zoom = parseFloat(this.getAttribute('zoom')) || 13； // 初始化地图 mapboxgl.accessToken = 令牌； this.map = 新的mapboxgl.Map({ 容器：这个，样式：地图样式，中心：中心，变焦：变焦 }); // 地图加载时调度自定义事件 this.map.on('加载', () => { this.dispatchEvent( 新的 CustomEvent('地图加载', { 详细信息：{ 地图：this.map } }) ）； }); } // 关键：删除元素时进行清理断开连接回调() { if (this.map) { this.map.remove(); this.map = null; } } // 将地图实例公开给 JavaScript 获取地图（）{ 返回这个.map； } } // 注册自定义元素 customElements.define('mapbox-map', MapboxMap); **在 HTML 中的用法：** <风格> 地图框地图 { 显示：块；高度：100vh；宽度：100%； } **在反应中的用法：** 导入'./mapbox-地图组件'; // 导入到注册元素函数应用程序（）{ const mapRef = useRef(null); 使用效果（（）=> { const handleMapLoad = (e) => { const map = e.detail.map; // 添加标记、图层等。新的mapboxgl.Marker().setLngLat([-122.4194, 37.7749]).addTo(map); }; mapRef.current?.addEventListener('mapload',handleMapLoad); 返回（）=> { mapRef.current?.removeEventListener('mapload',handleMapLoad); }; }, []); 返回（）； } **在 Vue 中的用法：** <模板> <脚本> 导入'./mapbox-地图组件'; 导出默认值{ 数据（）{ 返回{ 令牌：import.meta.env.VITE_MAPBOX_ACCESS_TOKEN }; }, 方法：{ 处理MapLoad（事件）{ const map = event.detail.map; // 与地图交互 } } }; **在 Svelte 中的用法：** <脚本> 导入'./mapbox-地图组件'; 让地图元素；函数handleMapLoad（事件）{ const map = event.detail.map; // 与地图交互 }

**高级：反应式属性模式：** 类 MapboxMapReactive 扩展 HTMLElement { 静态获取观察属性（）{ return ['center', 'zoom', 'map-style']; } 构造函数（）{ 超级（）； this.map = null; } 连接回调() { mapboxgl.accessToken = this.getAttribute('访问令牌'); this.map = 新的mapboxgl.Map({ 容器：这个，样式： this.getAttribute('地图样式') || 'mapbox://styles/mapbox/standard', center: this.getAttribute('center')?.split(',').map(Number) || [0, 0], 缩放：parseFloat(this.getAttribute('zoom')) || 9 }); } 断开连接回调() { if (this.map) { this.map.remove(); this.map = null; } } // 对属性变化做出反应 attributeChangedCallback(名称, oldValue, newValue) { if (!this.map || oldValue === newValue) return; 开关（名称）{ 案例“中心”： const center = newValue.split(',').map(Number); this.map.setCenter(center); 休息; 案例“缩放”： this.map.setZoom(parseFloat(newValue)); 休息; 案例“地图样式”： this.map.setStyle(newValue); 休息; } } } customElements.define('mapbox-map-reactive', MapboxMapReactive); **实施要点：** * 使用`connectedCallback()`进行初始化（相当于mount/ngOnInit） * **始终实现`disconnectedCallback()`**来调用`map.remove()`（防止内存泄漏） * 从 HTML 属性中读取配置 * 调度地图交互的自定义事件（`mapload`等） * 使用 `observedAttributes` \+ `attributeChangedCallback` 进行反应式更新 * 无需修改即可在任何框架中工作 ** ** ## 代币管理模式 ### 环境变量（推荐）不同的框架对客户端环境变量使用不同的前缀：框架/捆绑器 |环境变量|访问模式 ---|---|--- **投票** | `VITE_MAPBOX_ACCESS_TOKEN` | `import.meta.env.VITE_MAPBOX_ACCESS_TOKEN` **Next.js** | `NEXT_PUBLIC_MAPBOX_TOKEN` | `process.env.NEXT_PUBLIC_MAPBOX_TOKEN` **创建 React 应用程序** | `REACT_APP_MAPBOX_TOKEN` | `process.env.REACT_APP_MAPBOX_TOKEN` **角度** | `environment.mapboxAccessToken` |环境文件（`environment.ts`） **Vite .env 文件：** VITE_MAPBOX_ACCESS_TOKEN=pk.YOUR_MAPBOX_TOKEN_HERE **Next.js .env.local 文件：** NEXT_PUBLIC_MAPBOX_TOKEN=pk.YOUR_MAPBOX_TOKEN_HERE **重要：** * ✅ 始终使用令牌的环境变量 * ✅ 切勿将 `.env` 文件提交到版本控制 * ✅ 对客户端应用程序使用公共令牌 (pk.*) * ✅ 将 `.env` 添加到 `.gitignore` * ✅ 为团队提供 `.env.example` 模板 **.gitignore:** .env .env.local .env.*.local **.env.示例：** VITE_MAPBOX_ACCESS_TOKEN=your_token_here ** ** ## Mapbox 搜索 JS 集成 ### 搜索框组件模式 **安装依赖项：** npm install @mapbox/search-js-react # React npm install @mapbox/search-js-web # Vanilla/Vue/Svelte **注意：** 这两个包都包含 `@mapbox/search-js-core` 作为依赖项。如果构建自定义搜索 UI，您只需要直接安装 `-core`。 **反应搜索模式：** 从'@mapbox/search-js-react'导入{SearchBox}； // 内部组件： <搜索框访问令牌={访问令牌} map={mapRef.current} // 传递地图实例 mapboxgl={mapboxgl} // 传递mapboxgl库值={输入值} onChange={(值) => setInputValue(值)} proximity={centerCooperatives} // 偏向中心附近的结果标记 // 显示所选结果的标记 />; **关键配置选项：** * `accessToken`：您的 Mapbox 公共令牌 * `map`: 地图实例（必须先初始化） * `mapboxgl`：mapboxgl 库参考 * `proximity`: `[lng, lat]` 使结果在地理上产生偏差 * `marker`: 显示/隐藏结果标记的布尔值 * `placeholder`: 搜索框占位符文本 ### 定位搜索框 **绝对定位（叠加）：**

**常见职位：** * 右上角：`顶部：10px，右侧：10px` * 左上：`顶部：10px，左侧：10px` * 左下：`底部：10px，左侧：10px` ** ** ## 要避免的常见错误 ### ❌错误1：忘记调用map.remove() // 不好 - 内存泄漏！使用效果（（）=> { const map = new mapboxgl.Map({ ... }) // 没有清理函数 }, []) // 好 - 适当的清理使用效果（（）=> { const map = new mapboxgl.Map({ ... }) return () => map.remove() // ✅ 清理 }, []) **原因：** 每个 Map 实例都会创建 WebGL 上下文、事件侦听器和 DOM 节点。如果不进行清理，它们就会累积并导致内存泄漏。 ** ** ### ❌错误2：在渲染中初始化地图 // 不好 - React 中的无限循环！函数 MapComponent() { const map = new mapboxgl.Map({ ... }) // 在每次渲染时运行返回

} // 好 - 初始化生效函数 MapComponent() { 使用效果（（）=> { const map = new mapboxgl.Map({ ... }) }, []) 返回

} **为什么：** React 组件频繁重新渲染。在每次渲染上创建新地图会导致无限循环和崩溃。 ** ** ### ❌错误3：没有正确存储地图实例 // 不好 - 渲染之间映射变量丢失函数 MapComponent() { 使用效果（（）=> { 让地图 = 新的mapboxgl.Map({ ... }) // 稍后无法访问映射变量 }, []) } // 好 - 存储在 useRef 中函数 MapComponent() { const mapRef = useRef() 使用效果（（）=> { mapRef.current = new mapboxgl.Map({ ... }) // mapRef.current 可在整个组件中访问 }, []) } **为什么：** 您需要访问地图实例来执行添加图层、标记或调用“remove()”等操作。 ** ** ### ❌错误4：useEffect中的依赖数组错误 // 不好 - 在每次渲染时重新创建地图使用效果（（）=> { const map = new mapboxgl.Map({ ... }) return () => map.remove() }) // 无依赖数组 // 不好 - 当 props 改变时重新创建地图使用效果（（）=> { const map = new mapboxgl.Map({ center: props.center, ... }) return () => map.remove() }, [props.center]) // 好 - 初始化一次使用效果（（）=> { const map = new mapboxgl.Map({ ... }) return () => map.remove() }, []) // 空数组 = 运行一次 // 好 - 更新地图属性使用效果（（）=> { if (mapRef.current) { mapRef.current.setCenter(props.center) } }, [props.center]) **为什么：** 地图初始化的成本很高。初始化一次，然后使用映射方法更新属性。 ** ** ### ❌错误 5：在源代码中硬编码令牌 // BAD - 令牌在源代码中公开 mapboxgl.accessToken = 'pk.YOUR_MAPBOX_TOKEN_HERE'; // 好 - 使用环境变量 mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; **为什么：** 源代码中的令牌被提交给版本控制并公开公开。始终使用环境变量。 ** ** ### ❌错误 6：未处理 Angular SSR // 不好 - 在服务器端渲染期间崩溃 ngOnInit() { 导入（'mapbox-gl'）。然后（mapboxgl => { this.map = new mapboxgl.Map({ ... }) }) } // 好 - 首先检查平台 ngOnInit() { if (!isPlatformBrowser(this.platformId)) { return // 在SSR期间跳过map init } 导入（'mapbox-gl'）。然后（mapboxgl => { this.map = new mapboxgl.Map({ ... }) }) } **原因：** Mapbox GL JS 需要浏览器 API（WebGL、Canvas）。如果没有平台检查，Angular Universal (SSR) 将崩溃。 ** ** ### ❌错误 7：缺少 CSS 导入 // 不好 - 地图渲染但看起来已损坏从“mapbox-gl”导入mapboxgl； // 缺少 CSS 导入 // 好 - 导入 CSS 以获得正确的样式从“mapbox-gl”导入mapboxgl；导入'mapbox-gl/dist/mapbox-gl.css'; **原因：** CSS 文件包含地图控件、弹出窗口和标记的关键样式。没有它，地图就会显得破碎。 ** ** ## Next.js 特定模式 ### 应用程序路由器（推荐） 'use client' // 标记为客户端组件从 'react' 导入 { useRef, useEffect } 从“mapbox-gl”导入mapboxgl 导入 'mapbox-gl/dist/mapbox-gl.css' 导出默认函数 Map() { const mapRef = useRef() const mapContainerRef = useRef(null) 使用效果（（）=> { if (!mapContainerRef.current) 返回 mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_TOKEN！ mapRef.current = 新的mapboxgl.Map({ 容器：mapContainerRef.current，中心：[-71.05953，42.36290]，变焦：13 }) return () => mapRef.current?.remove() }, []) 返回

} **要点：** * **必须使用`'use client'`指令**（地图需要浏览器API） * 使用“process.env.NEXT_PUBLIC_*”作为环境变量 * 使用 TypeScript 正确输入 `mapRef` ### 页面路由器（旧版）从“下一个/动态”导入动态 // 动态导入以禁用地图组件的SSR const Map = 动态(() => import('../components/Map'), { SSR：假，加载中：() =>

加载地图...

}) 导出默认函数 HomePage() { 返回<地图/> } **要点：** * 使用带有“ssr: false”的“动态”导入 * 提供加载状态 * Map组件本身遵循标准React模式 ** ** ## 样式配置 ### 默认中心和缩放准则 **默认示例（在 create-web-app 演示中使用）：** * **中心** ：`[-71.05953, 42.36290]`（马萨诸塞州波士顿） * **缩放** : `13` 用于城市级视图 > **注意：** 如果未指定，GL JS 默认为 `center: [0, 0]` 和 `zoom: 0`。始终明确设置这些。 **缩放级别指南：** * `0-2`: 世界观 * `3-5`: 大陆/国家 * `6-9`: 地区/州 * `10-12`: 城市景观 * `13-15`: 邻里 * `16-18`：街道层 * `19-22`: 建筑层数 **针对用户位置进行定制：** // 使用浏览器地理位置 if (navigator.geolocation) { navigator.geolocation.getCurrentPosition((位置) => { map.setCenter([position.coords.longitude,position.coords.latitude]); 地图.setZoom(13); }); } ** ** ## 测试模式 ### 单元测试图 **模拟mapbox-gl：** // vitest.config.js 或 jest.config.js 导出默认值{ setupFiles: ['./test/setup.js'] }; // 测试/setup.js vi.mock('mapbox-gl', () => ({ 默认值：{ 映射： vi.fn(() => ({ 上： vi.fn(), 删除：vi.fn(), 设置中心：vi.fn(), 设置缩放：vi.fn() }）），访问令牌：'' } })); **原因：** Mapbox GL JS 需要测试环境中不存在的 WebGL 和浏览器 API。模拟库以测试组件逻辑。 ** ** ## 何时使用此技能在以下情况下调用该技能： * 在新项目中设置 Mapbox GL JS * 将 Mapbox 集成到特定框架（React、Vue、Svelte、Angular、Next.js） * 构建与框架无关的 Web 组件 * 为组件库创建可重用的地图组件 * 调试地图初始化问题 * 添加Mapbox搜索功能 * 实施适当的清理和生命周期管理 * 框架之间的转换（例如，React 到 Vue） * 审查 Mapbox 集成最佳实践的代码 ## 相关技能 * **mapbox-cartography** ：地图设计原则和样式 * **mapbox-token-security** ：令牌管理和安全 * **mapbox-style-patterns** : 常见的地图样式模式 ## 资源 * [Mapbox GL JS 文档]() * [Mapbox 搜索 JS 文档]() * [create-web-app GitHub]()

Mapbox Web 集成模式

包含技能