# 介绍 ## 介绍 Movk Mapbox 是一个**声明式 [Mapbox GL JS v3](https://docs.mapbox.com/mapbox-gl-js/){rel=""nofollow""} 封装库**。它把命令式的 `map.addSource` / `map.addLayer` / 标记与控件管理，收敛为一组可组合的 Vue 组件与 composables：用 `MapboxMap` 创建地图，用 `MapboxSource`、`MapboxLayer`、`MapboxMarker`、`MapboxPopup` 与各类控件声明式地组合地图内容，状态即视图。在此之上还内置 3D 建筑、雷达 / 扩散 / 辉光等动态效果，fog / terrain / 天气环境，以及天地图、WMS / WMTS 与多坐标系本土化能力。 它提供**两种使用方式**： - **Nuxt 4** —— 作为 Nuxt 模块，组件与 composables 自动导入，开箱即用。 - **纯 Vue + Vite** —— 经 `@movk/mapbox/vite` + `@movk/mapbox/vue-plugin`，同一套组件与用法在非 Nuxt 项目中通用。 > \[!NOTE] > > 遵循 > > 渐进式采用 > > ：可以只用坐标转换工具，也可以用完整的图层、效果、绘制与本土化底图能力。先看 > > 安装 > > ，再按 > > Nuxt > > 或 > > Vue / Vite > > 接入。 ## 核心特性 **声明式组合** 以组件组合地图、数据源、图层、标记、弹窗与控件，告别命令式 add/remove 样板。 **MapboxContext 注入** 根组件下发上下文，子组件经 useMap() 直接取实例与 isLoaded / whenLoaded() ，无需 id 查表。 **相机双向绑定** v-model\:center / zoom / bearing / pitch 双向同步相机，支持跨路由 persistent 持久化。 **丰富图层与效果** 内置图层类型与聚合 / 建筑 / 栅格 / 视频，叠加雷达、扩散、辉光、迁徙等动态效果与 fog / terrain / 天气环境。 **本土化扩展** 天地图底图、WMS / WMTS 服务、mapbox-gl-draw 绘制与基于 gcoord 的多坐标系转换。 ## 能力分区 > \[!NOTE] > > **文档结构** > > - **核心组件** —— Map、Source、Layer、LayerGroup、CustomLayer、Marker、LottieMarker、Popup、Tooltip > - **图层组件** —— 内置类型（circle/fill/line/symbol/fill-extrusion/heatmap）与数据驱动图层（cluster/building/image/video/raster） > - **控件** —— Navigation / Geolocate / Fullscreen / Scale / Attribution > - **效果组件** —— 雷达、扩散、辉光、波纹、轨迹、迁徙与建筑系效果 > - **环境与天气** —— Fog、Lights、Terrain、Temperature、Rain、Snow > - **扩展能力** —— DrawControl 绘制、天地图、WMS/WMTS 与坐标转换 > - **Composables 与工具函数** —— useMap、useMapboxCamera、useMeasure 等，以及坐标 / 缓冲 / 几何工具 # 安装 ## 环境要求 > \[!NOTE] > > - **Mapbox GL JS** —— v3（`mapbox-gl` 作为 peer 依赖） > - **Vue** —— 3.4+ > - **Node.js** —— `^20.19.0 || >=22.12.0` > - 一个 **Mapbox access token**（[免费申请](https://account.mapbox.com/access-tokens/){rel=""nofollow""}）；如需天地图底图，另需天地图 `tk` ## 安装依赖 ```bash [pnpm] pnpm add @movk/mapbox mapbox-gl ``` ```bash [npm] npm install @movk/mapbox mapbox-gl ``` ```bash [yarn] yarn add @movk/mapbox mapbox-gl ``` 需要绘制能力（`MapboxDrawControl`）时，额外安装： ```bash [pnpm] pnpm add @mapbox/mapbox-gl-draw ``` ```bash [npm] npm install @mapbox/mapbox-gl-draw ``` ```bash [yarn] yarn add @mapbox/mapbox-gl-draw ``` ## 选择接入方式 **Nuxt 4** 作为 Nuxt 模块注册，组件与 composables 自动导入。 **Vue + Vite** 经 Vite 插件 + vue-plugin，在纯 Vue 项目中使用同一套组件。 # Nuxt 4 ## 注册模块 在 `nuxt.config.ts` 中注册模块并配置 token： ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: ['@movk/mapbox'], mapbox: { accessToken: process.env.NUXT_MAPBOX_TOKEN, tiandituToken: process.env.NUXT_TIANDITU_TOKEN } }) ``` > \[!NOTE] > > token 写入 > > runtimeConfig.public.mapbox > > ，组件在客户端创建地图时读取。建议用环境变量注入，不要硬编码。 配套 `.env`： ```bash [.env] NUXT_MAPBOX_TOKEN=pk.your_mapbox_access_token NUXT_TIANDITU_TOKEN=your_tianditu_tk ``` ## 模块选项 | 选项 | 说明 | | --------------- | ---------------------------------------- | | `accessToken` | Mapbox access token | | `tiandituToken` | 天地图服务 `tk`（使用 `MapboxTiandituLayer` 时需要） | | `prefix` | 组件前缀，默认 `Mapbox` | ## 开始使用 组件与 composables 自动导入，开箱即用。地图实例只在客户端 `onMounted` 创建，组件已做 SSR 安全处理，**无需 `` 包裹**： ```vue [app.vue] ``` > \[!WARNING] > > MapboxMap > > 容器为 > > width:100%; height:100% > > ，请确保父级有明确高度，否则地图不可见。 # Vue + Vite ## Vite 插件 在 `vite.config.ts` 中加入插件，负责组件与 composables 的自动导入： ```ts [vite.config.ts] import vue from '@vitejs/plugin-vue' import Mapbox from '@movk/mapbox/vite' export default defineConfig({ plugins: [vue(), Mapbox()] }) ``` `Mapbox()` 内部自动注册组件解析器与自动导入项，独立 Vue + Vite 项目直接使用即可。 ## 复用已有 unplugin 实例 部分库（如 `@nuxt/ui`）的 Vite 插件内置了唯一的 `unplugin-vue-components` / `unplugin-auto-import` 实例。这时无需再加 `Mapbox()`，改用 `@movk/mapbox/unplugin` 导出的 `mapboxComponentResolver` 与 `mapboxAutoImports`，注入宿主插件复用： ```ts [vite.config.ts] import vue from '@vitejs/plugin-vue' import ui from '@nuxt/ui/vite' import { mapboxAutoImports, mapboxComponentResolver } from '@movk/mapbox/unplugin' export default defineConfig({ plugins: [ vue(), ui({ components: { resolvers: [mapboxComponentResolver()] }, autoImport: { imports: [...mapboxAutoImports()] } }) ] }) ``` > \[!NOTE] > > @nuxt/ui > > 检测到第二个 > > unplugin-vue-components > > / > > unplugin-auto-import > > 实例会直接抛错，因此与其同用时务必走注入复用方式，而非再叠加 > > Mapbox() > > 。 `mapboxComponentResolver` 默认以 `Mapbox` 为组件前缀，可通过 `mapboxComponentResolver({ prefix: 'Mb' })` 自定义。 ## 注册 Vue 插件 在入口注册 `vue-plugin`，传入 token 并引入运行时样式： ```ts [main.ts] import { createApp } from 'vue' import MapboxPlugin from '@movk/mapbox/vue-plugin' import '@movk/mapbox/index.css' import App from './App.vue' createApp(App) .use(MapboxPlugin, { accessToken: import.meta.env.VITE_MAPBOX_TOKEN, tiandituToken: import.meta.env.VITE_TIANDITU_TOKEN }) .mount('#app') ``` 配套 `.env`： ```bash [.env] VITE_MAPBOX_TOKEN=pk.your_mapbox_access_token VITE_TIANDITU_TOKEN=your_tianditu_tk ``` ## 用法一致 组件与 composables 由 `@movk/mapbox/vite` 自动导入，用法与 Nuxt 完全一致： ```vue [App.vue] ``` # MCP Server ## 什么是 MCP？ MCP（Model Context Protocol）是一套标准化协议，让 AI 助手访问外部数据源与工具。文档站内置 MCP Server，经 `/mcp` 端点对外开放，Claude Code、Cursor、VS Code 等工具可直接连接，按对话上下文检索本库的组件信息、源码与用法示例。 服务为本组件库提供结构化访问，让 AI 工具更准确地理解并协助 `@movk/mapbox` 开发，访问地址为 `https://mapbox.mhaibaraai.cn/mcp`。 ## 可用资源 MCP Server 提供以下可发现资源： - **`resource://docs/components`**：浏览全部组件及其分类 - **`resource://docs/composables`**：浏览全部 composables 及其分类 - **`resource://docs/examples`**：浏览全部代码示例 - **`resource://docs/documentation-pages`**：浏览全部文档页面 - **`resource://docs/mapbox-conventions`**：本库声明式范式的硬约束（SSR、容器高度、`omitUndefined`、相机 v-model、图层生命周期等） - **`resource://docs/basemap-styles`**：可用底图预设（Mapbox 官方样式与天地图图层类型 vec/img/ter） 在 Claude Code 等工具中可用 `@` 引用这些资源。 ## 可用工具 MCP Server 按类别提供以下工具： ### 搜索工具 - **`search-composables`**：按名称或描述搜索 composables，无参数时列出全部 - **`search-icons`**：在 Iconify 集合中搜索图标（默认 `lucide`），返回 `i-{prefix}-{name}` 格式名称 ### 文档工具 - **`search-documentation`**：按标题、描述或 section 搜索文档页，无参数时列出全部 - **`get-documentation-page`**：按路径取页面内容，支持 `headings` 仅取指定 h2 ### 组件工具 - **`get-component`**：取组件文档，支持 `sections`（`usage` / `examples` / `api` / `theme` / `changelog`）仅取部分 - **`get-component-metadata`**：取组件 props / slots / emits 元数据（轻量，无正文） ### 示例工具 - **`list-examples`**：列出全部示例 - **`get-example`**：取指定示例的实现代码 ### Mapbox 工具 - **`list-mapbox-components`**：按分类（core / layers / controls / effects / environment / extensions / composables / utils）列出全部能力，可按分类或关键词过滤 - **`convert-coordinates`**：在 WGS84 / GCJ02 / BD09 间转换坐标，支持单点或点数组 - **`get-layer-paint-schema`**：按图层 `type`（circle / line / fill / symbol / heatmap / fill-extrusion / raster）返回常用 `paint` / `layout` 键与最小脚手架 ## 可用 Prompts MCP Server 提供以下引导式 Prompt： - **`find_component_for_usecase`**：按使用场景推荐合适的组件 - **`implement_component_with_props`**：基于文档与元数据生成组件实现 - **`build-mapbox-map`**：按任务描述组装一张地图，仅用文档中存在的组件并遵守本库约定 在支持 Prompt 的工具中可用 `/` 调用。 ## 配置 MCP Server 采用 HTTP 传输，可在不同 AI 工具中接入，统一使用名称 `movk-mapbox` 与地址 `https://mapbox.mhaibaraai.cn/mcp`。 ### Claude Code > \[!NOTE] > > 确保已安装 Claude Code，安装说明见 > > Anthropic 文档 > > 。 用 CLI 命令添加服务： ```bash [Terminal] claude mcp add --transport http movk-mapbox https://mapbox.mhaibaraai.cn/mcp ``` ### Claude Desktop 1. 打开 Claude Desktop，进入「Settings」>「Developer」 2. 点击「Edit Config」打开本地配置目录 3. 修改 `claude_desktop_config.json`： ```json [claude_desktop_config.json] { "mcpServers": { "movk-mapbox": { "command": "npx", "args": [ "mcp-remote", "https://mapbox.mhaibaraai.cn/mcp" ] } } } ``` 4. 重启 Claude Desktop ### Cursor :install-button{url="https://mapbox.mhaibaraai.cn/mcp"} 在项目根目录创建或更新 `.cursor/mcp.json`： ```json [.cursor/mcp.json] { "mcpServers": { "movk-mapbox": { "type": "http", "url": "https://mapbox.mhaibaraai.cn/mcp" } } } ``` ### VS Code :install-button{ide="vscode" url="https://mapbox.mhaibaraai.cn/mcp"} > \[!NOTE] > > 确保已安装 > > GitHub Copilot > > 与 > > GitHub Copilot Chat > > 扩展。 在项目 `.vscode` 目录创建或编辑 `mcp.json`： ```json [.vscode/mcp.json] { "servers": { "movk-mapbox": { "type": "http", "url": "https://mapbox.mhaibaraai.cn/mcp" } } } ``` ### Windsurf 1. 打开 Windsurf，进入「Settings」>「Windsurf Settings」>「Cascade」 2. 点击「Manage MCPs」>「View raw config」 3. 添加配置： ```json [mcp_config.json] { "mcpServers": { "movk-mapbox": { "type": "http", "url": "https://mapbox.mhaibaraai.cn/mcp" } } } ``` ### ChatGPT > \[!NOTE] > > 基于 MCP 的自定义连接器在 ChatGPT Pro 与 Plus 账户（Web 端）可用。 1. 启用开发者模式：「Settings」>「Connectors」>「Advanced settings」>「Developer mode」 2. 打开 ChatGPT 设置 3. 在 Connectors 选项卡创建新连接器：名称 `Movk Mapbox`、MCP server URL `https://mapbox.mhaibaraai.cn/mcp`、认证 `None` 4. 点击创建 ### OpenCode 在项目根目录创建 `opencode.json`： ```json [opencode.json] { "$schema": "https://opencode.ai/config.json", "mcp": { "movk-mapbox": { "type": "remote", "url": "https://mapbox.mhaibaraai.cn/mcp", "enabled": true } } } ``` ## 使用示例 接入后可直接向 AI 助手提问，它会自动调用上述工具： - 「按分类列出所有图层组件」 - 「获取 MapboxLayer 的 Props」 - 「把这组 WGS84 坐标转成 GCJ02」 - 「circle 图层有哪些常用 paint 属性」 - 「找出与绘制相关的能力」 - 「按 build-mapbox-map 帮我搭一张叠天地图矢量底图、带导航控件的地图」 > \[!TIP] > > 组件文档可用 > > sections > > 参数（ > > usage > > / > > examples > > / > > api > > / > > theme > > / > > changelog > > ）仅取相关部分；其他页面用 > > headings > > 指定 h2 标题（如 > > \["简介", "API"] > > ），以缩减响应体积。 > \[!TIP] > > 本库 MCP 查封装组件与约定；Mapbox GL 原生 API 与 style spec 请用官方 > > mapbox-docs-mcp > > 。仓库根 > > .mcp.json > > 已同时登记两者，二者互补。 # llms.txt ## 什么是 llms.txt？ llms.txt 是一种面向大语言模型（LLM）的结构化文档格式。文档站经内置 `nuxt-llms` 自动生成 llms.txt 文件，包含本组件库的结构化信息，便于 AI 工具理解并协助 `@movk/mapbox` 开发。 这些文件为 AI 消费而优化，涵盖组件、API、用法模式与最佳实践，默认启用、无需手动维护。 ## 可用路由 文档站提供以下 llms.txt 路由： - [**`/llms.txt`**](https://mapbox.mhaibaraai.cn/llms.txt){rel=""nofollow""}：全部内容的结构化概览与文档链接（约 5K tokens） - [**`/llms-full.txt`**](https://mapbox.mhaibaraai.cn/llms-full.txt){rel=""nofollow""}：完整文档，含实现细节、示例、类型定义与最佳实践（体量大） ## 选择正确的文件 > \[!NOTE] > > 多数场景从 > > /llms.txt > > 开始即可——它包含全部核心信息，适配标准 LLM 上下文窗口。仅当需要完整实现示例且 AI 工具支持大上下文（200K+ tokens）时，再用 > > /llms-full.txt > > 。 ## 重要使用说明 > \[!WARNING] > > 使用 Cursor 或 Windsurf 等工具时， > > @ > > 符号必须在聊天框内手动输入；复制粘贴会破坏工具对上下文引用的识别。 ## 在 AI 工具中使用 ### Cursor 可在 Cursor 中引用 llms.txt 文件以获得更好的 AI 辅助： 1. **直接引用**：提问时提及 llms.txt URL 2. 用 `@docs` 将上述 URL 加入项目上下文 ### Windsurf Windsurf 可直接访问 llms.txt 文件以理解组件用法与最佳实践： - 用 `@docs` 引用具体 llms.txt URL - 在工作区创建引用这些 URL 的持久规则 ### 其他 AI 工具 任何支持 llms.txt 的 AI 工具都可用这些路由更好地理解本库。面向 ChatGPT、Claude 等的提示示例： - 「使用 Movk Mapbox 文档 `https://mapbox.mhaibaraai.cn/llms.txt`」 - 「遵循完整指南 `https://mapbox.mhaibaraai.cn/llms-full.txt`」 > \[!TIP] > > llms.txt > > 告诉 AI「去哪里找信息」， > > Agent Skills > > 告诉 AI「能做什么、怎么做」，两者配合效果最佳。 # Agent Skills ## 什么是 Skills？ Skills 是为 AI 编码代理提供库/框架专属知识的结构化文件。与 [MCP Server](https://mapbox.mhaibaraai.cn/docs/getting-started/ai/mcp) 提供实时工具访问不同，Skill 直接加载进代理上下文，使其在整段对话中都能参考。 文档站提供一个 **usage skill** `movk-mapbox`，教 AI 代理用 `@movk/mapbox` 构建地图：遵循 [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills){rel=""nofollow""} 规范，自动发布到 `/.well-known/skills/` 端点。 ## 用法 `movk-mapbox` skill 涵盖： - 安装与 token 配置（Nuxt 模块 / Vue + Vite 插件） - `MapboxMap` + `MapboxSource` + `MapboxLayer` 声明式核心范式 - SSR 安全、无需 ``，相机 `v-model` 断回环 - 天地图底图、坐标系转换（WGS84/GCJ02/BD09）、绘制与缓冲量算 - 一组必须遵守的约定（容器高度、`omitUndefined`、图层生命周期等） Skill 附带按需加载的 `references/`（components / recipes / conventions），让代理只在需要时拉取细节，保持上下文精简。 > \[!NOTE] > > 查看本站已发布的 Skills： > > /.well-known/skills/index.json > > 。安装后可在代理聊天中输入 > > /movk-mapbox > > 调用。 ### Skills CLI [`skills`](https://skills.sh){rel=""nofollow""} CLI 是安装 Skill 最简单的方式，会自动检测已安装的 Claude Code、Cursor、Windsurf 等代理并一并安装： ```bash [Terminal] npx skills add https://mapbox.mhaibaraai.cn ``` > \[!TIP] > > 访问 > > skills.sh > > 了解 Skills 生态与更多可用技能。 ### Claude Code > \[!NOTE] > > 确保已安装 Claude Code，安装说明见 > > Anthropic 文档 > > 。 用 CLI 添加技能： ```bash [Terminal] claude skill add https://mapbox.mhaibaraai.cn ``` ### Cursor 1. 打开 Cursor，进入「Settings」>「Skills」 2. 点击「Add skill」并填入站点地址： ```text https://mapbox.mhaibaraai.cn ``` ### 其他 AI 工具 Skill 文件公开发布于 `/.well-known/skills/`，任何支持自定义上下文的工具都可直接引用： - 技能索引：[`/.well-known/skills/index.json`](https://mapbox.mhaibaraai.cn/.well-known/skills/index.json){rel=""nofollow""} - 技能入口：[`/.well-known/skills/movk-mapbox/SKILL.md`](https://mapbox.mhaibaraai.cn/.well-known/skills/movk-mapbox/SKILL.md){rel=""nofollow""} # MapboxMap ## 简介 `MapboxMap` 是一切的根组件：它在客户端 `onMounted` 创建 `mapbox-gl` 实例，经 `provide` 下发 [MapboxContext](https://mapbox.mhaibaraai.cn/docs/getting-started/concepts)，子组件经 `useMap()` 取用。容器宽高为 `100%`，请确保父级有明确高度（示例统一用 `h-115`）。 > \[!NOTE] > > 组件已做 SSR 安全处理，无需 > > \ > > 包裹； > > accessToken > > 省略时回退到模块注入的全局 token。 ## 用法 `center` / `zoom` / `bearing` / `pitch` 支持 `v-model`：组件与地图现值比对、有差异才下发，从而断开「模型 → 地图 → 事件 → 模型」回环。拖动或缩放地图，绑定值随之更新。 ```vue [MapBasicExample.vue] ``` ## 示例 ### 相机切换 经 `useMapboxCamera` 的 `flyTo` 在多个预设机位间平滑切换： ```vue [MapCameraExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxMap component */ interface MapboxMapProps { /** * 地图 id；省略时自动生成。提供后可经 useMapbox(id) 外部访问 */ mapId?: string; /** * mapbox-gl Map 初始化选项（container 由组件接管） */ options?: MapboxMapOptions; /** * 覆盖全局 access token */ accessToken?: string; center?: mapboxgl.LngLatLike; zoom?: number; bearing?: number; pitch?: number; /** * 卸载时不销毁实例，配合 keepalive / `` 跨路由复用 * @default "false" */ persistent?: boolean; } ``` ### Emits `update:center` / `update:zoom` / `update:bearing` / `update:pitch` 为相机 `v-model` 同步事件，其余为透传的 mapbox-gl 地图事件。 ```ts /** * Emitted events for the MapboxMap component */ interface MapboxMapEmits { update:center: (payload: [value: mapboxgl.LngLatLike]) => void; update:zoom: (payload: [value: number]) => void; update:bearing: (payload: [value: number]) => void; update:pitch: (payload: [value: number]) => void; load: (payload: [map: mapboxgl.Map]) => void; idle: (payload: [map: mapboxgl.Map]) => void; error: (payload: [event: { type: "error"; target: mapboxgl.Map; } & { error: Error; }]) => void; click: (payload: [event: mapboxgl.MapMouseEvent]) => void; dblclick: (payload: [event: mapboxgl.MapMouseEvent]) => void; contextmenu: (payload: [event: mapboxgl.MapMouseEvent]) => void; mousemove: (payload: [event: mapboxgl.MapMouseEvent]) => void; mousedown: (payload: [event: mapboxgl.MapMouseEvent]) => void; mouseup: (payload: [event: mapboxgl.MapMouseEvent]) => void; movestart: (payload: [event: { type: "movestart"; target: mapboxgl.Map; } & { originalEvent?: MouseEvent | WheelEvent | TouchEvent; }]) => void; moveend: (payload: [event: { type: "moveend"; target: mapboxgl.Map; } & { originalEvent?: MouseEvent | WheelEvent | TouchEvent; }]) => void; zoomstart: (payload: [event: { type: "zoomstart"; target: mapboxgl.Map; }]) => void; zoomend: (payload: [event: { type: "zoomend"; target: mapboxgl.Map; }]) => void; rotateend: (payload: [event: { type: "rotateend"; target: mapboxgl.Map; } & { originalEvent?: MouseEvent | TouchEvent; }]) => void; pitchend: (payload: [event: { type: "pitchend"; target: mapboxgl.Map; }]) => void; dragend: (payload: [event: { type: "dragend"; target: mapboxgl.Map; } & { originalEvent?: MouseEvent | TouchEvent; }]) => void; styledata: (payload: [event: { type: "styledata"; target: mapboxgl.Map; } & mapboxgl.MapStyleDataEvent]) => void; sourcedata: (payload: [event: { type: "sourcedata"; target: mapboxgl.Map; } & mapboxgl.MapSourceDataEvent]) => void; } ``` ### Slots ```ts /** * Slots for the MapboxMap component */ interface MapboxMapSlots { default(): any; } ``` ## Changelog See commit history for [src/runtime/components/MapboxMap.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxMap.vue). # MapboxSource ## 简介 `MapboxSource` 声明式管理一个 mapbox-gl 数据源：地图就绪时 `addSource`，`source` 变更时按类型走增量更新（geojson 调 `setData`、vector 调 `setTiles`）而非整源重建，卸载时安全移除。子图层经 `source=""` 字符串引用该源。 > \[!TIP] > See: /docs/core/layer > > 同一份数据可同时供多个图层消费，这是显式 > > MapboxSource > > 相较 MapboxLayer 内联源的价值。 ## 用法 一份 geojson 同时驱动「光晕」与「实心圆」两个图层： ```vue [SourceGeojsonExample.vue] ``` ## 示例 ### 响应式更新 `source` 为响应式：切换数据集仅触发 `setData`，图层不重建： ```vue [SourceUpdateExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxSource component */ interface MapboxSourceProps { /** * 数据源 id，供图层经 source 字段按字符串引用 */ sourceId: string; /** * 数据源定义 */ source: mapboxgl.SourceSpecification; } ``` ### Slots ```ts /** * Slots for the MapboxSource component */ interface MapboxSourceSlots { default(): any; } ``` ## Changelog See commit history for [src/runtime/components/MapboxSource.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxSource.vue). # MapboxLayer ## 简介 `MapboxLayer` 是通用图层组件：`type` 选渲染方式，`paint` / `layout` / `filter` 控制样式，响应式变更走 `setPaintProperty` / `setLayoutProperty` / `setFilter` 增量下发，不重建图层。`source` 既可传 `sourceId` 引用 [MapboxSource](https://mapbox.mhaibaraai.cn/docs/core/source)，也可传内联 source 对象（自动创建匿名源并随图层卸载）；`beforeId` 控制插入次序。 ## 用法 同一内联多边形源派生 `fill` 与 `line` 两层，`beforeId` 让描边压在填充之上： ```vue [LayerBasicExample.vue] ``` ## 示例 ### 点选交互 监听图层 `@click` 取命中要素，从 `properties` 读取业务字段： ```vue [LayerInteractionExample.vue] ``` ### 过滤渲染 `filter` 传表达式，仅渲染匹配要素，切换即时生效： ```vue [LayerFilterExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLayer component */ interface MapboxLayerProps { /** * 图层 id，全局唯一 */ layerId: string; /** * 图层类型，决定渲染方式与可用的 paint / layout 属性 */ type: "symbol" | "fill" | "line" | "circle" | "heatmap" | "fill-extrusion" | "building" | "raster" | "raster-particle" | "hillshade" | "model" | "background" | "sky" | "slot" | "clip"; /** * source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载） */ source?: string | mapboxgl.SourceSpecification; /** * 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填 */ sourceLayer?: string; /** * 绘制样式属性，响应式变更经 setPaintProperty 增量下发 */ paint?: PropBag; /** * 布局属性，响应式变更经 setLayoutProperty 增量下发 */ layout?: PropBag; /** * 过滤表达式，仅渲染匹配的要素 */ filter?: mapboxgl.FilterSpecification; /** * 最小缩放级别，低于此级别不渲染 */ minzoom?: number; /** * 最大缩放级别，高于此级别不渲染 */ maxzoom?: number; /** * 插入到该 id 图层之前；省略则追加到图层栈顶部 */ beforeId?: string; } ``` ### Emits ```ts /** * Emitted events for the MapboxLayer component */ interface MapboxLayerEmits { click: (payload: [event: mapboxgl.MapMouseEvent]) => void; dblclick: (payload: [event: mapboxgl.MapMouseEvent]) => void; mousedown: (payload: [event: mapboxgl.MapMouseEvent]) => void; mouseup: (payload: [event: mapboxgl.MapMouseEvent]) => void; mousemove: (payload: [event: mapboxgl.MapMouseEvent]) => void; mouseenter: (payload: [event: mapboxgl.MapMouseEvent]) => void; mouseleave: (payload: [event: mapboxgl.MapMouseEvent]) => void; contextmenu: (payload: [event: mapboxgl.MapMouseEvent]) => void; } ``` ### Slots ```ts /** * Slots for the MapboxLayer component */ interface MapboxLayerSlots { default(): any; } ``` ## Changelog See commit history for [src/runtime/components/MapboxLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxLayer.vue). # MapboxLayerGroup ## 简介 `MapboxLayerGroup` 把多个子 [MapboxLayer](https://mapbox.mhaibaraai.cn/docs/core/layer) 归为一组：经 `beforeId` 提供统一的缺省插入锚点，经 `visible` 做组级显隐开关（组开关优先于子图层自身的 `layout.visibility`）。适合「一组相关图层一起显示/隐藏」的场景。 ## 用法 切换 `visible` 即可整组开关，无需逐层设置可见性： ```vue [LayerGroupExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLayerGroup component */ interface MapboxLayerGroupProps { /** * 组内图层缺省插入到该图层之前 */ beforeId?: string; /** * 组级显隐 * @default "true" */ visible?: boolean; } ``` ### Slots ```ts /** * Slots for the MapboxLayerGroup component */ interface MapboxLayerGroupSlots { default(): any; } ``` ## Changelog See commit history for [src/runtime/components/MapboxLayerGroup.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxLayerGroup.vue). # MapboxCustomLayer ## 简介 `MapboxCustomLayer` 是 `CustomLayerInterface` 的逃生舱：把自定义 WebGL 图层（你自己的 `onAdd` / `render`）接入组件生命周期，地图就绪时 `addLayer`、卸载时移除、切换底图后随 `onReady` 重建。适合 Three.js、deck.gl 或裸 WebGL 的深度自定义渲染。 ## 用法 下例用裸 WebGL 在地图坐标系绘制一个半透明三角形： ```vue [CustomLayerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxCustomLayer component */ interface MapboxCustomLayerProps { /** * 自定义图层实现（含 id/type/render） */ layer: mapboxgl.CustomLayerInterface; /** * 插入到该图层之前 */ beforeId?: string; } ``` ### Slots ```ts /** * Slots for the MapboxCustomLayer component */ interface MapboxCustomLayerSlots { default(): any; } ``` ## Changelog See commit history for [src/runtime/components/MapboxCustomLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxCustomLayer.vue). # MapboxMarker ## 简介 `MapboxMarker` 在地图上放置一个标记：默认插槽提供自定义 DOM（省略则用 mapbox 默认水滴图标），位置经 `v-model:lnglat` 双向绑定。`options.draggable` 开启拖拽后，拖拽结束会把新坐标回写到绑定值。 ## 用法 无插槽时使用默认标记，`v-model:lnglat` 控制位置： ```vue [MarkerBasicExample.vue] ``` ## 示例 ### 自定义内容与拖拽 默认插槽渲染自定义 DOM，开启 `draggable` 后拖拽实时回写坐标： ```vue [MarkerDraggableExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxMarker component */ interface MapboxMarkerProps { lnglat: mapboxgl.LngLatLike; /** * 标记选项；element 由默认插槽提供，无需在此传入 */ options?: Omit; } ``` ### Emits ```ts /** * Emitted events for the MapboxMarker component */ interface MapboxMarkerEmits { update:lnglat: (payload: [value: mapboxgl.LngLatLike]) => void; } ``` ### Slots ```ts /** * Slots for the MapboxMarker component */ interface MapboxMarkerSlots { default(): any; } ``` ### Expose 通过 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel=""nofollow""} 访问组件实例。 | Name | Type | | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `marker`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `() => Marker | undefined`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 获取底层 mapbox-gl Marker 实例 | ## Changelog See commit history for [src/runtime/components/MapboxMarker.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxMarker.vue). # MapboxLottieMarker ## 简介 `MapboxLottieMarker` 在标记位置用 lottie-web 渲染矢量动画（基于 [MapboxMarker](https://mapbox.mhaibaraai.cn/docs/core/marker) 的 DOM，而非 icon 帧驱动）。动画来源 `animationData`（内联 JSON）或 `path`（远程 URL）二选一，位置经 `v-model:lnglat` 绑定。 ## 用法 传入内联 `animationData`，`width` / `height` 控制尺寸： ```vue [LottieMarkerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLottieMarker component */ interface MapboxLottieMarkerProps { lnglat: mapboxgl.LngLatLike; /** * lottie 动画数据（JSON 对象）；与 path 二选一 */ animationData?: object; /** * lottie 动画 URL；与 animationData 二选一 */ path?: string; /** * 播放速度倍率 * @default "1" */ speed?: number; /** * 容器宽（像素） * @default "64" */ width?: number; /** * 容器高（像素） * @default "64" */ height?: number; /** * 是否循环 * @default "true" */ loop?: boolean; /** * 是否自动播放 * @default "true" */ autoplay?: boolean; } ``` ### Emits ```ts /** * Emitted events for the MapboxLottieMarker component */ interface MapboxLottieMarkerEmits { update:lnglat: (payload: [value: mapboxgl.LngLatLike]) => void; } ``` ## Changelog See commit history for [src/runtime/components/MapboxLottieMarker.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxLottieMarker.vue). # MapboxPopup ## 简介 `MapboxPopup` 在指定 `lnglat` 锚定一个弹窗，默认插槽渲染任意内容；`lnglat` 变更时响应式更新位置，关闭时触发 `close` 事件。 ## 用法 默认插槽渲染弹窗内容，`options.closeOnClick` 等选项透传给 mapbox： ```vue [PopupBasicExample.vue] ``` ## 示例 ### 点击设置位置 点击地图取坐标并赋给 `lnglat`，弹窗随之定位： ```vue [PopupClickExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxPopup component */ interface MapboxPopupProps { /** * 弹窗锚定的经纬度 */ lnglat: mapboxgl.LngLatLike; /** * Popup 选项 */ options?: mapboxgl.PopupOptions; } ``` ### Emits ```ts /** * Emitted events for the MapboxPopup component */ interface MapboxPopupEmits { close: (payload: []) => void; } ``` ### Slots ```ts /** * Slots for the MapboxPopup component */ interface MapboxPopupSlots { default(): any; } ``` ### Expose 通过 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel=""nofollow""} 访问组件实例。 | Name | Type | | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `popup`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `() => Popup | undefined`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 获取底层 mapbox-gl Popup 实例 | ## Changelog See commit history for [src/runtime/components/MapboxPopup.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxPopup.vue). # MapboxTooltip ## 简介 `MapboxTooltip` 是 Popup 的 hover 模式：鼠标悬浮到 `layerId` 指定图层的要素上时跟随显示、移出即消失。默认插槽暴露命中要素（`feature`），可渲染其属性；按 `layerId` 委托到地图级监听，因此目标图层晚于本组件挂载也能命中。 ## 用法 悬浮圆点图层显示要素信息，slot 取 `feature.properties`： ```vue [TooltipExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxTooltip component */ interface MapboxTooltipProps { /** * 目标图层 id */ layerId: string; /** * Popup 选项（closeButton/closeOnClick 由组件接管） */ options?: mapboxgl.PopupOptions; /** * 悬浮时鼠标指针样式 * @default "\"pointer\"" */ cursor?: string; } ``` ### Slots ```ts /** * Slots for the MapboxTooltip component */ interface MapboxTooltipSlots { default(): any; } ``` ### Expose 通过 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel=""nofollow""} 访问组件实例。 | Name | Type | | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hovered`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `() => GeoJSONFeature | undefined`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 当前悬浮命中的要素 | ## Changelog See commit history for [src/runtime/components/MapboxTooltip.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/MapboxTooltip.vue). # circle ## 简介 `MapboxLayer` 设 `type="circle"` 即渲染圆点图层。下例用内联 `source` 传入 geojson，经 `paint` 控制半径、颜色与描边；调整控件时 `paint` 响应式变更仅触发 `setPaintProperty` 增量更新。 > \[!NOTE] > See: /docs/core/layer > > circle 由通用组件 MapboxLayer 承载，完整 Props 与事件见其文档。 ## 用法 ```vue [LayerCircleExample.vue] ``` ## 示例 ### 数据驱动样式 paint 用表达式按要素属性分级映射，实现数据驱动的半径与颜色： ```vue [LayerCircleDataExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLayer component */ interface MapboxLayerProps { /** * 图层 id，全局唯一 */ layerId: string; /** * 图层类型，决定渲染方式与可用的 paint / layout 属性 */ type: "symbol" | "fill" | "line" | "circle" | "heatmap" | "fill-extrusion" | "building" | "raster" | "raster-particle" | "hillshade" | "model" | "background" | "sky" | "slot" | "clip"; /** * source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载） */ source?: string | mapboxgl.SourceSpecification; /** * 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填 */ sourceLayer?: string; /** * 绘制样式属性，响应式变更经 setPaintProperty 增量下发 */ paint?: PropBag; /** * 布局属性，响应式变更经 setLayoutProperty 增量下发 */ layout?: PropBag; /** * 过滤表达式，仅渲染匹配的要素 */ filter?: mapboxgl.FilterSpecification; /** * 最小缩放级别，低于此级别不渲染 */ minzoom?: number; /** * 最大缩放级别，高于此级别不渲染 */ maxzoom?: number; /** * 插入到该 id 图层之前；省略则追加到图层栈顶部 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/Layer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/Layer.vue). # MapboxVideoLayer ## 简介 `MapboxVideoLayer` 把视频按四角经纬度贴合到地图（多格式 `urls` 回退），内部以 `video` 源 + `raster` 图层实现，并经 `defineExpose` 暴露 `play` / `pause` / `video` 供编程控制。 ## 用法 叠加无人机航拍视频，按钮控制播放： ```vue [VideoLayerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxVideoLayer component */ interface MapboxVideoLayerProps { /** * 视频地址列表（多格式回退） */ urls: string[]; /** * 四角经纬度：左上/右上/右下/左下 */ coordinates: [[number, number], [number, number], [number, number], [number, number]]; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 不透明度 * @default "1" */ opacity?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ### Expose 通过 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel=""nofollow""} 访问组件实例。 | Name | Type | | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `play`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `() => void`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 播放视频 | | `pause`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `() => void`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 暂停视频 | | `video`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `() => HTMLVideoElement | undefined`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 底层 video 元素 | ## Changelog See commit history for [src/runtime/components/layers/VideoLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/layers/VideoLayer.vue). # MapboxRasterLayer ## 简介 `MapboxRasterLayer` 叠加外部栅格瓦片服务（`{z}/{x}/{y}` 模板 URL），支持 `tileSize` / `scheme` / `minzoom` / `maxzoom` / `attribution` / `opacity`。天地图等国内底图见 [扩展能力](https://mapbox.mhaibaraai.cn/docs/extensions/tianditu)。 ## 用法 在空样式底图上叠加 OpenStreetMap 瓦片： ```vue [RasterLayerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxRasterLayer component */ interface MapboxRasterLayerProps { /** * URL 模板瓦片地址（{z}/{x}/{y} 占位） */ tiles: string[]; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 瓦片尺寸 * @default "256" */ tileSize?: number; /** * 瓦片坐标方案 */ scheme?: "xyz" | "tms"; /** * 数据源最小缩放级别 */ minzoom?: number; /** * 数据源最大缩放级别 */ maxzoom?: number; /** * 版权信息 */ attribution?: string; /** * 不透明度 * @default "1" */ opacity?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/layers/RasterLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/layers/RasterLayer.vue). # MapboxBufferCircle ## 简介 `MapboxBufferCircle` 以圆心与米半径生成 turf 测地圆，渲染为填充 + 描边两层。`color` 提供快捷配色，`fillPaint` / `linePaint` 可整体覆盖样式。 ## 用法 拖动滑块调整半径（米）： ```vue [BufferCircleExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxBufferCircle component */ interface MapboxBufferCircleProps { /** * 圆心经纬度 */ center: [number, number]; /** * 半径（米） */ radius: number; /** * 圆周采样段数 * @default "64" */ steps?: number; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色（快捷样式） */ color?: string; /** * 整体覆盖填充 paint */ fillPaint?: Record; /** * 整体覆盖描边 paint */ linePaint?: Record; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/buffers/BufferCircle.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/buffers/BufferCircle.vue). # MapboxBufferEllipse ## 简介 `MapboxBufferEllipse` 以中心、x/y 半轴（米）与长轴方位角 `angle` 生成椭圆，渲染为填充 + 描边两层。 ## 用法 长轴 3000m、短轴 1500m、旋转 30°： ```vue [BufferEllipseExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxBufferEllipse component */ interface MapboxBufferEllipseProps { /** * 中心经纬度 */ center: [number, number]; /** * x 半轴（米） */ xSemiAxis: number; /** * y 半轴（米） */ ySemiAxis: number; /** * 旋转角（度，正北顺时针） * @default "0" */ angle?: number; /** * 周长采样段数 * @default "64" */ steps?: number; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色（快捷样式） */ color?: string; /** * 整体覆盖填充 paint */ fillPaint?: Record; /** * 整体覆盖描边 paint */ linePaint?: Record; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/buffers/BufferEllipse.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/buffers/BufferEllipse.vue). # MapboxBufferLine ## 简介 `MapboxBufferLine` 沿线两侧扩展 `width` 米生成走廊面，`line` 接受线要素、几何或坐标数组。常用于道路红线、管线保护范围等。 ## 用法 沿折线生成 600m 宽走廊： ```vue [BufferLineExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxBufferLine component */ interface MapboxBufferLineProps { /** * 线要素、几何或坐标数组 */ line: GeoJSON.LineString | GeoJSON.Feature | [number, number][]; /** * 缓冲宽度（米） */ width: number; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色（快捷样式） */ color?: string; /** * 整体覆盖填充 paint */ fillPaint?: Record; /** * 整体覆盖描边 paint */ linePaint?: Record; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/buffers/BufferLine.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/buffers/BufferLine.vue). # MapboxBufferPolygon ## 简介 `MapboxBufferPolygon` 把面要素向外扩展 `width` 米（负值向内收缩），`polygon` 接受面要素、几何或外环坐标数组。 ## 用法 拖动滑块在扩展与收缩间切换： ```vue [BufferPolygonExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxBufferPolygon component */ interface MapboxBufferPolygonProps { /** * 面要素、几何或外环坐标数组 */ polygon: GeoJSON.Polygon | GeoJSON.Feature | [number, number][]; /** * 缓冲宽度（米），负值向内收缩 */ width: number; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色（快捷样式） */ color?: string; /** * 整体覆盖填充 paint */ fillPaint?: Record; /** * 整体覆盖描边 paint */ linePaint?: Record; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/buffers/BufferPolygon.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/buffers/BufferPolygon.vue). # MapboxBufferSector ## 简介 `MapboxBufferSector` 以圆心、米半径与起止方位角（`bearing1` → `bearing2`，正北顺时针）生成扇面，渲染为填充 + 描边两层。常用于视域、信号覆盖扇区等。 ## 用法 30° → 120° 的扇形，半径 3000m： ```vue [BufferSectorExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxBufferSector component */ interface MapboxBufferSectorProps { /** * 圆心经纬度 */ center: [number, number]; /** * 半径（米） */ radius: number; /** * 起始方位角（度） */ bearing1: number; /** * 结束方位角（度） */ bearing2: number; /** * 弧线采样段数 * @default "64" */ steps?: number; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色（快捷样式） */ color?: string; /** * 整体覆盖填充 paint */ fillPaint?: Record; /** * 整体覆盖描边 paint */ linePaint?: Record; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/buffers/BufferSector.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/buffers/BufferSector.vue). # fill ## 简介 `MapboxLayer` 设 `type="fill"` 渲染面图层，`fill-color` / `fill-opacity` 控制样式，配合 `['get', ...]` 表达式可逐要素着色。 > \[!NOTE] > See: /docs/core/layer > > fill 由通用组件 MapboxLayer 承载，完整 Props 与事件见其文档。 ## 用法 两个多边形按属性 `c` 取色： ```vue [LayerFillExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLayer component */ interface MapboxLayerProps { /** * 图层 id，全局唯一 */ layerId: string; /** * 图层类型，决定渲染方式与可用的 paint / layout 属性 */ type: "symbol" | "fill" | "line" | "circle" | "heatmap" | "fill-extrusion" | "building" | "raster" | "raster-particle" | "hillshade" | "model" | "background" | "sky" | "slot" | "clip"; /** * source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载） */ source?: string | mapboxgl.SourceSpecification; /** * 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填 */ sourceLayer?: string; /** * 绘制样式属性，响应式变更经 setPaintProperty 增量下发 */ paint?: PropBag; /** * 布局属性，响应式变更经 setLayoutProperty 增量下发 */ layout?: PropBag; /** * 过滤表达式，仅渲染匹配的要素 */ filter?: mapboxgl.FilterSpecification; /** * 最小缩放级别，低于此级别不渲染 */ minzoom?: number; /** * 最大缩放级别，高于此级别不渲染 */ maxzoom?: number; /** * 插入到该 id 图层之前；省略则追加到图层栈顶部 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/Layer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/Layer.vue). # line ## 简介 `MapboxLayer` 设 `type="line"` 渲染线图层，`line-width` / `line-color` 控制描边，`line-cap` / `line-join` 控制端点与拐角样式。 > \[!NOTE] > See: /docs/core/layer > > line 由通用组件 MapboxLayer 承载，完整 Props 与事件见其文档。 ## 用法 一条折线，圆角端点： ```vue [LayerLineExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLayer component */ interface MapboxLayerProps { /** * 图层 id，全局唯一 */ layerId: string; /** * 图层类型，决定渲染方式与可用的 paint / layout 属性 */ type: "symbol" | "fill" | "line" | "circle" | "heatmap" | "fill-extrusion" | "building" | "raster" | "raster-particle" | "hillshade" | "model" | "background" | "sky" | "slot" | "clip"; /** * source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载） */ source?: string | mapboxgl.SourceSpecification; /** * 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填 */ sourceLayer?: string; /** * 绘制样式属性，响应式变更经 setPaintProperty 增量下发 */ paint?: PropBag; /** * 布局属性，响应式变更经 setLayoutProperty 增量下发 */ layout?: PropBag; /** * 过滤表达式，仅渲染匹配的要素 */ filter?: mapboxgl.FilterSpecification; /** * 最小缩放级别，低于此级别不渲染 */ minzoom?: number; /** * 最大缩放级别，高于此级别不渲染 */ maxzoom?: number; /** * 插入到该 id 图层之前；省略则追加到图层栈顶部 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/Layer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/Layer.vue). # symbol ## 简介 `MapboxLayer` 设 `type="symbol"` 渲染文字/图标标注：`text-field` 经 `['get', ...]` 读取属性，`text-size` / `text-offset` 等 layout 控制排布（图标需先经 [useMapboxImage](https://mapbox.mhaibaraai.cn/docs/composables/use-mapbox-image) 注册）。 > \[!NOTE] > See: /docs/core/layer > > symbol 由通用组件 MapboxLayer 承载，完整 Props 与事件见其文档。 ## 用法 按属性渲染文字标注，带描边便于深浅底图阅读： ```vue [LayerSymbolExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLayer component */ interface MapboxLayerProps { /** * 图层 id，全局唯一 */ layerId: string; /** * 图层类型，决定渲染方式与可用的 paint / layout 属性 */ type: "symbol" | "fill" | "line" | "circle" | "heatmap" | "fill-extrusion" | "building" | "raster" | "raster-particle" | "hillshade" | "model" | "background" | "sky" | "slot" | "clip"; /** * source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载） */ source?: string | mapboxgl.SourceSpecification; /** * 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填 */ sourceLayer?: string; /** * 绘制样式属性，响应式变更经 setPaintProperty 增量下发 */ paint?: PropBag; /** * 布局属性，响应式变更经 setLayoutProperty 增量下发 */ layout?: PropBag; /** * 过滤表达式，仅渲染匹配的要素 */ filter?: mapboxgl.FilterSpecification; /** * 最小缩放级别，低于此级别不渲染 */ minzoom?: number; /** * 最大缩放级别，高于此级别不渲染 */ maxzoom?: number; /** * 插入到该 id 图层之前；省略则追加到图层栈顶部 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/Layer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/Layer.vue). # fill-extrusion ## 简介 `MapboxLayer` 设 `type="fill-extrusion"` 把面挤出为 3D 体块，`fill-extrusion-height` 经 `['get', ...]` 读取属性逐要素设高；需给地图设 `pitch` 才能看出立体效果。3D 城市建筑见 [building](https://mapbox.mhaibaraai.cn/docs/layers/building)。 > \[!NOTE] > See: /docs/core/layer > > fill-extrusion 由通用组件 MapboxLayer 承载，完整 Props 与事件见其文档。 ## 用法 两个体块按属性 `height` 挤出，地图俯仰 55°： ```vue [LayerFillExtrusionExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLayer component */ interface MapboxLayerProps { /** * 图层 id，全局唯一 */ layerId: string; /** * 图层类型，决定渲染方式与可用的 paint / layout 属性 */ type: "symbol" | "fill" | "line" | "circle" | "heatmap" | "fill-extrusion" | "building" | "raster" | "raster-particle" | "hillshade" | "model" | "background" | "sky" | "slot" | "clip"; /** * source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载） */ source?: string | mapboxgl.SourceSpecification; /** * 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填 */ sourceLayer?: string; /** * 绘制样式属性，响应式变更经 setPaintProperty 增量下发 */ paint?: PropBag; /** * 布局属性，响应式变更经 setLayoutProperty 增量下发 */ layout?: PropBag; /** * 过滤表达式，仅渲染匹配的要素 */ filter?: mapboxgl.FilterSpecification; /** * 最小缩放级别，低于此级别不渲染 */ minzoom?: number; /** * 最大缩放级别，高于此级别不渲染 */ maxzoom?: number; /** * 插入到该 id 图层之前；省略则追加到图层栈顶部 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/Layer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/Layer.vue). # heatmap ## 简介 `MapboxLayer` 设 `type="heatmap"` 把点密度渲染为热力图，`heatmap-radius` / `heatmap-intensity` / `heatmap-opacity` 调节观感。按属性加权的温度热力见 [MapboxTemperature](https://mapbox.mhaibaraai.cn/docs/environment/temperature)。 > \[!NOTE] > See: /docs/core/layer > > heatmap 由通用组件 MapboxLayer 承载，完整 Props 与事件见其文档。 ## 用法 200 个随机点的密度热力（暗色底图对比更清晰）： ```vue [LayerHeatmapExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLayer component */ interface MapboxLayerProps { /** * 图层 id，全局唯一 */ layerId: string; /** * 图层类型，决定渲染方式与可用的 paint / layout 属性 */ type: "symbol" | "fill" | "line" | "circle" | "heatmap" | "fill-extrusion" | "building" | "raster" | "raster-particle" | "hillshade" | "model" | "background" | "sky" | "slot" | "clip"; /** * source id 字符串引用，或内联 source 对象（自动创建匿名源并随图层卸载） */ source?: string | mapboxgl.SourceSpecification; /** * 矢量瓦片源内的子图层名（source-layer），消费矢量源时必填 */ sourceLayer?: string; /** * 绘制样式属性，响应式变更经 setPaintProperty 增量下发 */ paint?: PropBag; /** * 布局属性，响应式变更经 setLayoutProperty 增量下发 */ layout?: PropBag; /** * 过滤表达式，仅渲染匹配的要素 */ filter?: mapboxgl.FilterSpecification; /** * 最小缩放级别，低于此级别不渲染 */ minzoom?: number; /** * 最大缩放级别，高于此级别不渲染 */ maxzoom?: number; /** * 插入到该 id 图层之前；省略则追加到图层栈顶部 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/Layer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/Layer.vue). # MapboxClusterLayer ## 简介 `MapboxClusterLayer` 把大量点数据自动聚合：内部用开启 `cluster` 的 geojson 源渲染「聚合圆 + 计数文字 + 散点」三层。点击聚合圆默认放大到展开级别（`autoExpand`），并派发 `clusterClick` / `pointClick` 事件。 ## 用法 传入点数据即自动聚合，点击聚合圆展开： ```vue [ClusterLayerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxClusterLayer component */ interface MapboxClusterLayerProps { /** * 点要素数据（GeoJSON 或其 URL） */ data: string | GeoJSON.GeoJSON; /** * source 与图层 id 前缀；省略时自动生成 */ sourceId?: string; /** * 聚合半径（像素） * @default "50" */ clusterRadius?: number; /** * 超过该缩放级别不再聚合 * @default "14" */ clusterMaxZoom?: number; /** * 覆盖聚合圆 paint */ clusterPaint?: PropBag; /** * 覆盖计数文字 layout */ countLayout?: PropBag; /** * 覆盖计数文字 paint */ countPaint?: PropBag; /** * 覆盖散点 paint */ pointPaint?: PropBag; /** * 插入到该图层之前 */ beforeId?: string; /** * 点击聚合圆自动放大到展开级别 * @default "true" */ autoExpand?: boolean; } ``` ### Emits ```ts /** * Emitted events for the MapboxClusterLayer component */ interface MapboxClusterLayerEmits { clusterClick: (payload: [payload: { clusterId: number; coordinates: [number, number]; expansionZoom: number; }]) => void; pointClick: (payload: [feature: mapboxgl.GeoJSONFeature]) => void; } ``` ## Changelog See commit history for [src/runtime/components/layers/ClusterLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/layers/ClusterLayer.vue). # MapboxBuildingLayer ## 简介 `MapboxBuildingLayer` 把 Mapbox 官方样式自带的 `composite` / `building` 矢量源挤出为 3D 建筑，封装好高度表达式，开放 `color` / `opacity` / `minzoom` 快捷设置。 > \[!NOTE] > > 依赖官方样式的 > > composite/building > > 源，天地图等空样式下无效；需地图 > > pitch > > 与较高 > > zoom > > （默认 minzoom 15）才能看到建筑。 ## 用法 俯仰视角下渲染城市 3D 建筑： ```vue [BuildingLayerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxBuildingLayer component */ interface MapboxBuildingLayerProps { /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 矢量数据源 id */ source?: string; /** * 数据源图层名 */ sourceLayer?: string; /** * 建筑颜色 */ color?: string; /** * 整体透明度 */ opacity?: number; /** * 显示建筑的最小缩放级别 */ minzoom?: number; /** * 整体覆盖 paint（提供时忽略 color/opacity 预设） */ paint?: Record; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/layers/BuildingLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/layers/BuildingLayer.vue). # MapboxImageLayer ## 简介 `MapboxImageLayer` 把一张图片按四角经纬度（左上 / 右上 / 右下 / 左下）贴合到地图，常用于雷达图、扫描影像、历史地图等叠加。内部以 `image` 源 + `raster` 图层实现。 ## 用法 把一张雷达图叠加到指定区域： ```vue [ImageLayerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxImageLayer component */ interface MapboxImageLayerProps { /** * 图片地址 */ url: string; /** * 四角经纬度：左上/右上/右下/左下 */ coordinates: [[number, number], [number, number], [number, number], [number, number]]; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 不透明度 * @default "1" */ opacity?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/layers/ImageLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/layers/ImageLayer.vue). # MapboxNavigationControl ## 简介 `MapboxNavigationControl` 在地图上挂载缩放按钮与指北罗盘。`position` 指定停靠角（省略用地图默认位置），`options` 直通 mapbox-gl 的 `NavigationControl` 构造选项（`showZoom` / `showCompass` / `visualizePitch`）。控件在地图就绪后挂载，组件卸载时自动移除。 ## 用法 调整 `position` 切换停靠角： ```vue [NavigationControlExample.vue] ``` ## 示例 ### 可视化俯仰角 倾斜底图后开启 `visualizePitch`，罗盘随俯仰角倾斜以指示视角： ```vue [NavigationControlPitchExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxNavigationControl component */ interface MapboxNavigationControlProps { /** * 控件停靠位置；省略用地图默认位置 */ position?: mapboxgl.ControlPosition; /** * NavigationControl 构造选项 */ options?: mapboxgl.NavigationControlOptions; } ``` ## Changelog See commit history for [src/runtime/components/controls/NavigationControl.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/controls/NavigationControl.vue). # MapboxGeolocateControl ## 简介 `MapboxGeolocateControl` 提供定位按钮：点击后请求浏览器地理定位并将视图移至用户位置。`options` 直通 mapbox-gl 的 `GeolocateControl` 构造选项，`trackUserLocation` 持续跟踪、`showUserHeading` 显示方向锥、`positionOptions.enableHighAccuracy` 提升精度。 > \[!NOTE] > > 浏览器定位需在 HTTPS（或 localhost）下运行，并由用户在弹窗中授权；未授权或不支持时按钮不会移动视图。 ## 用法 点击控件触发定位授权，授权后持续跟踪并显示方向： ```vue [GeolocateControlExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxGeolocateControl component */ interface MapboxGeolocateControlProps { /** * 控件停靠位置；省略用地图默认位置 */ position?: mapboxgl.ControlPosition; /** * GeolocateControl 构造选项 */ options?: mapboxgl.GeolocateControlOptions; } ``` ## Changelog See commit history for [src/runtime/components/controls/GeolocateControl.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/controls/GeolocateControl.vue). # MapboxFullscreenControl ## 简介 `MapboxFullscreenControl` 提供全屏按钮，点击在全屏与常态间切换地图容器。`position` 指定停靠角，`options.container` 可指定进入全屏的目标元素（省略则用地图容器）。 ## 用法 点击右上角按钮切换全屏： ```vue [FullscreenControlExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxFullscreenControl component */ interface MapboxFullscreenControlProps { /** * 控件停靠位置；省略用地图默认位置 */ position?: mapboxgl.ControlPosition; /** * FullscreenControl 构造选项 */ options?: mapboxgl.FullscreenControlOptions; } ``` ## Changelog See commit history for [src/runtime/components/controls/FullscreenControl.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/controls/FullscreenControl.vue). # MapboxScaleControl ## 简介 `MapboxScaleControl` 显示当前地图比例尺并随缩放更新。`options.unit` 选择单位（`metric` / `imperial` / `nautical`），`options.maxWidth` 限制比例尺最大像素宽度。 ## 用法 切换 `unit` 查看不同单位下的比例尺： ```vue [ScaleControlExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxScaleControl component */ interface MapboxScaleControlProps { /** * 控件停靠位置；省略用地图默认位置 */ position?: mapboxgl.ControlPosition; /** * ScaleControl 构造选项 */ options?: mapboxgl.ScaleControlOptions; } ``` ## Changelog See commit history for [src/runtime/components/controls/ScaleControl.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/controls/ScaleControl.vue). # MapboxAttributionControl ## 简介 `MapboxAttributionControl` 在地图角落展示数据来源署名。`options.compact` 折叠为可展开的图标按钮，`options.customAttribution` 追加自定义版权文本（字符串或字符串数组）。 > \[!TIP] > > 样式或数据源自带的署名通常已自动显示；本控件用于自定义展示形态或补充版权。 ## 用法 折叠模式并追加自定义版权： ```vue [AttributionControlExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxAttributionControl component */ interface MapboxAttributionControlProps { /** * 控件停靠位置；省略用地图默认位置 */ position?: mapboxgl.ControlPosition; /** * AttributionControl 构造选项 */ options?: mapboxgl.AttributionControlOptions; } ``` ## Changelog See commit history for [src/runtime/components/controls/AttributionControl.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/controls/AttributionControl.vue). # MapboxRadar ## 简介 `MapboxRadar` 在点要素上渲染雷达扫描：canvas 生成扇形扫描贴图，symbol 图层按帧旋转；`color` / `radius` / `speed` 控制颜色、扫描半径与转速。 ## 用法 调整 `speed`（度/秒）观察扫描转速： ```vue [RadarExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxRadar component */ interface MapboxRadarProps { /** * 点要素数据（GeoJSON 或其 URL） */ data: string | GeoJSON.GeoJSON; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色 * @default "\"#22c55e\"" */ color?: string; /** * 扫描半径（像素） * @default "60" */ radius?: number; /** * 旋转速度（度/秒） * @default "120" */ speed?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/Radar.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/Radar.vue). # MapboxWindowBuilding ## 简介 `MapboxWindowBuilding` 基于官方样式的 `composite/building` 渲染 3D 建筑，并用程序生成的窗户点阵贴图作 `fill-extrusion-pattern`；`rows` / `cols` / `litColor` / `darkColor` / `litRatio` / `seed` 控制窗格外观。需倾斜视角且缩放 ≥ `minzoom`（默认 15）。 ## 用法 夜色样式下点亮随机窗格： ```vue [WindowBuildingExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxWindowBuilding component */ interface MapboxWindowBuildingProps { /** * 最小缩放级别 * @default "15" */ minzoom?: number; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 窗户行数 */ rows?: number; /** * 窗户列数 */ cols?: number; /** * 亮窗颜色 */ litColor?: string; /** * 暗窗/墙体颜色 */ darkColor?: string; /** * 亮窗比例 */ litRatio?: number; /** * 随机种子 */ seed?: number; /** * 整体透明度 */ opacity?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/WindowBuilding.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/WindowBuilding.vue). # MapboxSpriteImage ## 简介 `MapboxSpriteImage` 把一张雪碧图（行优先排布的多帧）切帧后注册为帧驱动图标，symbol 图层逐帧循环播放，零解码依赖；`frames` / `columns` / `rows` / `frameWidth` / `frameHeight` / `fps` / `size` 控制切帧与播放。 ## 用法 加载一张 18 帧雪碧图并循环播放： ```vue [SpriteImageExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxSpriteImage component */ interface MapboxSpriteImageProps { /** * 点要素数据（GeoJSON 或其 URL） */ data: string | GeoJSON.GeoJSON; /** * 雪碧图 URL（所有帧拼一张图，行优先排布） */ image: string; /** * 总帧数 */ frames: number; /** * 列数；省略时等于 frames（单行） */ columns?: number; /** * 行数 */ rows?: number; /** * 单帧宽（像素）；省略由图宽/列数推算 */ frameWidth?: number; /** * 单帧高（像素）；省略由图高/行数推算 */ frameHeight?: number; /** * 播放帧率（帧/秒） * @default "12" */ fps?: number; /** * 上图图标边长（像素） * @default "64" */ size?: number; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/SpriteImage.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/SpriteImage.vue). # MapboxAnimatedImage ## 简介 `MapboxAnimatedImage` 用 `ImageDecoder` 把 GIF / APNG / WebP / AVIF 动图解码为帧，按各帧时长驱动 symbol 逐帧循环播放，零解码依赖；`size` 统一帧尺寸，`fps` 为无原生帧时长时的回退帧率。 ## 用法 加载 Mapbox 示例雷达动图并循环播放： ```vue [AnimatedImageExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxAnimatedImage component */ interface MapboxAnimatedImageProps { /** * 点要素数据（GeoJSON 或其 URL） */ data: string | GeoJSON.GeoJSON; /** * 动图 URL（GIF/APNG/WebP/AVIF） */ image: string; /** * 图标边长（像素），帧统一缩放到 size×size * @default "64" */ size?: number; /** * 解码无原生帧时长时的回退帧率 * @default "12" */ fps?: number; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/AnimatedImage.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/AnimatedImage.vue). # MapboxDiffusionCircle ## 简介 `MapboxDiffusionCircle` 在点要素上渲染扩散圆：多圈同心圆周期性向外扩张并渐隐；`color` / `maxRadius` / `duration` / `rings` / `opacity` 控制外观与节奏。 ## 用法 切换主色查看扩散动画： ```vue [DiffusionExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxDiffusionCircle component */ interface MapboxDiffusionCircleProps { /** * 点要素数据（GeoJSON 或其 URL） */ data: string | GeoJSON.GeoJSON; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色 * @default "\"#3b82f6\"" */ color?: string; /** * 最大扩散半径（像素） * @default "40" */ maxRadius?: number; /** * 单圈扩散周期（毫秒） * @default "2400" */ duration?: number; /** * 同时扩散的圈数 * @default "3" */ rings?: number; /** * 峰值不透明度 * @default "0.6" */ opacity?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/DiffusionCircle.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/DiffusionCircle.vue). # MapboxGlowCircle ## 简介 `MapboxGlowCircle` 在点要素上渲染炫光圆：实心内核 + 模糊光晕，`pulse` 开启呼吸脉冲；`color` / `radius` / `glowScale` / `duration` 控制外观与节奏。 ## 用法 切换主色查看带呼吸脉冲的炫光： ```vue [GlowExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxGlowCircle component */ interface MapboxGlowCircleProps { /** * 点要素数据（GeoJSON 或其 URL） */ data: string | GeoJSON.GeoJSON; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色 * @default "\"#f59e0b\"" */ color?: string; /** * 内核半径（像素） * @default "6" */ radius?: number; /** * 光晕半径倍数 * @default "3" */ glowScale?: number; /** * 脉冲周期（毫秒） * @default "2000" */ duration?: number; /** * 插入到该图层之前 */ beforeId?: string; /** * 呼吸脉冲（光晕半径 ±25% 正弦摆动） * @default "false" */ pulse?: boolean; } ``` ## Changelog See commit history for [src/runtime/components/effects/GlowCircle.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/GlowCircle.vue). # MapboxWaveCircle ## 简介 `MapboxWaveCircle` 在点要素上渲染波浪圆：常驻实心底圆 + 周期向外扩张的描边波纹；`color` / `baseRadius` / `maxRadius` / `duration` / `rings` 控制外观与节奏。 ## 用法 切换主色查看波纹扩散： ```vue [WaveExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxWaveCircle component */ interface MapboxWaveCircleProps { /** * 点要素数据（GeoJSON 或其 URL） */ data: string | GeoJSON.GeoJSON; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色 * @default "\"#10b981\"" */ color?: string; /** * 底圆半径（像素） * @default "6" */ baseRadius?: number; /** * 波纹最大半径（像素） * @default "36" */ maxRadius?: number; /** * 波纹周期（毫秒） * @default "2000" */ duration?: number; /** * 波纹圈数 * @default "2" */ rings?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/WaveCircle.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/WaveCircle.vue). # MapboxTrail ## 简介 `MapboxTrail` 在线要素上渲染动态轨迹：`line-gradient` 彗尾窗口沿线循环平移（source 自动开启 `lineMetrics`）；`color` / `lineWidth` / `trailLength` / `duration` / `baseLine` 控制外观与节奏。 ## 用法 切换主色查看彗尾沿线流动： ```vue [TrailExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxTrail component */ interface MapboxTrailProps { /** * 线要素数据（GeoJSON 或其 URL） */ data: string | GeoJSON.GeoJSON; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色 * @default "\"#8b5cf6\"" */ color?: string; /** * 线宽（像素） * @default "4" */ lineWidth?: number; /** * 彗尾长度（line-progress 占比 0-1） * @default "0.25" */ trailLength?: number; /** * 跑完全程的周期（毫秒） * @default "3000" */ duration?: number; /** * 插入到该图层之前 */ beforeId?: string; /** * 是否同时绘制半透明底线 * @default "true" */ baseLine?: boolean; } ``` ## Changelog See commit history for [src/runtime/components/effects/Trail.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/Trail.vue). # MapboxMigration ## 简介 `MapboxMigration` 由起讫点对（`data` 为 `{ from, to }` 列表）生成贝塞尔弧线，粒子沿线循环飞行并带渐变尾迹；`color` / `curvature` / `duration` / `lineWidth` / `particleRadius` 控制外观与节奏。 ## 用法 切换主色查看自北京出发的迁徙航线： ```vue [MigrationExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxMigration component */ interface MapboxMigrationProps { /** * 起讫点对列表 */ data: MigrationRoute[]; /** * 图层 id 前缀；省略时自动生成 */ layerId?: string; /** * 主色 * @default "\"#f43f5e\"" */ color?: string; /** * 弧线弯曲程度 * @default "0.3" */ curvature?: number; /** * 单程飞行周期（毫秒） * @default "3000" */ duration?: number; /** * 线宽（像素） * @default "2" */ lineWidth?: number; /** * 粒子半径（像素） * @default "4" */ particleRadius?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/Migration.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/Migration.vue). # MapboxFlowBuilding ## 简介 `MapboxFlowBuilding` 基于官方样式的 `composite/building` 渲染 3D 建筑：渐变着色 + 高亮带沿建筑高度循环流动；`color` / `flowColor` / `duration` / `bandHeight` / `maxHeight` 控制外观与节奏。需倾斜视角且缩放 ≥ `minzoom`（默认 15）。 ## 用法 倾斜视角下查看高亮带在楼体上流动： ```vue [FlowBuildingExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxFlowBuilding component */ interface MapboxFlowBuildingProps { /** * 基色 * @default "\"#1e3a8a\"" */ color?: string; /** * 流动高亮色 * @default "\"#67e8f9\"" */ flowColor?: string; /** * 流动周期（毫秒） * @default "3000" */ duration?: number; /** * 高亮带覆盖的高度范围（米） * @default "60" */ bandHeight?: number; /** * 建筑最大参考高度（米） * @default "300" */ maxHeight?: number; /** * 最小缩放级别 * @default "15" */ minzoom?: number; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 整体透明度 */ opacity?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/FlowBuilding.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/FlowBuilding.vue). # MapboxGradientBuilding ## 简介 `MapboxGradientBuilding` 基于官方样式的 `composite/building` 渲染 3D 建筑，并按高度在 `stops` 断点间插值着色；`opacity` / `minzoom` 控制透明度与起始缩放。需倾斜视角且缩放 ≥ `minzoom`（默认 15）。 ## 用法 倾斜视角下按高度对楼体分级着色： ```vue [GradientBuildingExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxGradientBuilding component */ interface MapboxGradientBuildingProps { /** * 最小缩放级别 * @default "15" */ minzoom?: number; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 高度-颜色断点 */ stops?: [number, string][]; /** * 整体透明度 */ opacity?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/GradientBuilding.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/GradientBuilding.vue). # MapboxTextureBuilding ## 简介 `MapboxTextureBuilding` 基于官方样式的 `composite/building` 渲染 3D 建筑，并以 `url` 贴图作 `fill-extrusion-pattern`；`opacity` / `minzoom` 控制透明度与起始缩放。需倾斜视角且缩放 ≥ `minzoom`（默认 15）。 ## 用法 以可平铺砖墙贴图覆盖楼体表面： ```vue [TextureBuildingExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxTextureBuilding component */ interface MapboxTextureBuildingProps { /** * 贴图地址 */ url: string; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 整体透明度 */ opacity?: number; /** * 最小缩放级别 * @default "15" */ minzoom?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/effects/TextureBuilding.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/effects/TextureBuilding.vue). # MapboxFog ## 简介 `MapboxFog` 调用 `setFog` 为地图添加雾 / 大气效果，`options` 透传 mapbox fog 规格（`color`/`high-color`/`horizon-blend`/`space-color`/`range` 等），省略则用样式默认大气。倾斜或地球投影下最明显。 ## 用法 倾斜视角下叠加带色大气与星空： ```vue [FogExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxFog component */ interface MapboxFogProps { /** * 大气/雾效果选项；缺省 {} 使用样式默认大气 */ options?: mapboxgl.FogSpecification; } ``` ## Changelog See commit history for [src/runtime/components/environment/Fog.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/environment/Fog.vue). # MapboxLights ## 简介 `MapboxLights` 调用 `setLights` 设置地图的 3D 光照列表（`ambient` 环境光 / `directional` 平行光 / `flat` 平面光），作用于 3D 建筑与地形。需配合含 3D 内容的样式（如 `standard`）与倾斜视角。 ## 用法 环境光叠加带投影的平行光，照亮 standard 样式的 3D 建筑： ```vue [LightsExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxLights component */ interface MapboxLightsProps { /** * 3D 光照列表（ambient/directional/flat） */ lights: mapboxgl.LightsSpecification[]; } ``` ## Changelog See commit history for [src/runtime/components/environment/Lights.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/environment/Lights.vue). # MapboxTerrain ## 简介 `MapboxTerrain` 调用 `setTerrain` 启用三维地形：`source` 缺省用 Mapbox 官方 `terrain-dem-v1`，`exaggeration` 控制夸张程度。倾斜视角下起伏最明显。 ## 用法 调整 `exaggeration` 查看珠峰一带的地形起伏： ```vue [TerrainExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxTerrain component */ interface MapboxTerrainProps { /** * 地形夸张系数 * @default "1" */ exaggeration?: number; /** * DEM source id * @default "\"movk-terrain-dem\"" */ sourceId?: string; /** * DEM 数据源，缺省用 Mapbox 官方 terrain-dem-v1 */ source?: mapboxgl.RasterDEMSourceSpecification; } ``` ## Changelog See commit history for [src/runtime/components/environment/Terrain.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/environment/Terrain.vue). # MapboxTemperature ## 简介 `MapboxTemperature` 把 GeoJSON 点按温度属性渲染为 mapbox 原生 heatmap：`weightProperty` 取权重字段、`weightRange` 线性映射到热力权重，`radius`/`intensity`/`opacity` 与 `colorStops` 控制呈现。 ## 用法 各城市温度采样点的热力分布，调整 `radius` 观察扩散： ```vue [TemperatureExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxTemperature component */ interface MapboxTemperatureProps { /** * 点要素数据（GeoJSON 或其 URL） */ data: string | GeoJSON.GeoJSON; /** * 图层 id；省略时自动生成 */ layerId?: string; /** * 权重取值的要素属性 * @default "\"temperature\"" */ weightProperty?: string; /** * 温度取值范围 [min, max]，线性映射到热力权重 */ weightRange?: [number, number]; /** * 密度-颜色断点；缺省为蓝→红五档 */ colorStops?: [number, string][]; /** * 热力半径（像素） * @default "30" */ radius?: number; /** * 热力强度 * @default "1" */ intensity?: number; /** * 不透明度 * @default "1" */ opacity?: number; /** * 超过该缩放级别隐藏热力（通常切到点图）；省略不限制 */ maxzoom?: number; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/environment/Temperature.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/environment/Temperature.vue). # MapboxRain ## 简介 `MapboxRain` 调用 `setRain` 为地图添加降雨效果，`options` 透传 mapbox rain 规格（`density`/`intensity`/`color` 等），省略用默认雨效。 > \[!NOTE] > > setRain > > 为 mapbox 实验性 API，需 v3 样式（如 > > standard > > ），未来版本可能变更。 ## 用法 倾斜视角下叠加降雨： ```vue [RainExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxRain component */ interface MapboxRainProps { /** * 降雨效果选项；缺省 {} 使用默认雨效 */ options?: mapboxgl.RainSpecification; } ``` ## Changelog See commit history for [src/runtime/components/environment/Rain.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/environment/Rain.vue). # MapboxSnow ## 简介 `MapboxSnow` 调用 `setSnow` 为地图添加降雪效果，`options` 透传 mapbox snow 规格（`density`/`intensity`/`color` 等），省略用默认雪效。 > \[!NOTE] > > setSnow > > 为 mapbox 实验性 API，需 v3 样式（如 > > standard > > ），未来版本可能变更。 ## 用法 倾斜视角下叠加降雪： ```vue [SnowExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxSnow component */ interface MapboxSnowProps { /** * 降雪效果选项；缺省 {} 使用默认雪效 */ options?: mapboxgl.SnowSpecification; } ``` ## Changelog See commit history for [src/runtime/components/environment/Snow.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/environment/Snow.vue). # MapboxDrawControl ## 简介 `MapboxDrawControl` 基于 [mapbox-gl-draw](https://github.com/mapbox/mapbox-gl-draw){rel=""nofollow""} 提供声明式绘制：`v-model:features` 受控要素集合（赋值即导入、绘制即回写）、`v-model:mode` 当前模式；触发 create / update / delete / selectionchange / modechange 事件；并经 `defineExpose` 暴露命令式方法。子组件可用 [useMapboxDraw](https://mapbox.mhaibaraai.cn/docs/composables/use-mapbox-draw) 注入实例。 ## 用法 用内置工具栏绘制点 / 线 / 面，`v-model:features` 实时回写要素数： ```vue [DrawControlExample.vue] ``` ## 示例 ### 命令式操作 经 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel=""nofollow""} 取实例，调用 `changeMode` / `deleteAll`（已关闭默认工具栏）： ```vue [DrawControlActionsExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxDrawControl component */ interface MapboxDrawControlProps { /** * 控件停靠位置；省略用地图默认位置 */ position?: mapboxgl.ControlPosition; /** * MapboxDraw 构造选项 */ options?: any; features?: GeoJSON.Feature[]; mode?: string; } ``` ### Emits ```ts /** * Emitted events for the MapboxDrawControl component */ interface MapboxDrawControlEmits { update:features: (payload: [value: GeoJSON.Feature[]]) => void; update:mode: (payload: [value: string]) => void; create: (payload: [features: GeoJSON.Feature[]]) => void; update: (payload: [features: GeoJSON.Feature[]]) => void; delete: (payload: [features: GeoJSON.Feature[]]) => void; selectionchange: (payload: [features: GeoJSON.Feature[]]) => void; modechange: (payload: [mode: string]) => void; } ``` ### Slots ```ts /** * Slots for the MapboxDrawControl component */ interface MapboxDrawControlSlots { default(): any; } ``` ### Expose 通过 [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel=""nofollow""} 访问组件实例。 | Name | Type | | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `draw`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `() => MapboxDraw | undefined`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 获取底层 MapboxDraw 实例 | | `getAll`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `() => FeatureCollection | undefined`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 当前全部要素集合 | | `add`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `(geojson: Feature | FeatureCollection | Geometry) => string[] | undefined`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 添加要素，返回要素 id 列表 | | `deleteAll`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `() => void`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 清空全部要素并同步模型 | | `changeMode`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `(next: string) => void`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 切换绘制模式并同步模型 | | `setFeatureProperty`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `(featureId: string, property: string, value: unknown) => void`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br 设置要素 user\_\* 属性（驱动主题样式）并同步模型 | ## Changelog See commit history for [src/runtime/components/extensions/DrawControl.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/extensions/DrawControl.vue). # movkDrawModes ## 简介 `movkDrawModes` 是 movk 提供的自定义绘制模式集合（圆 / 椭圆 / 矩形 / 扇形），与 `MapboxDraw.modes` 合并后注入 [MapboxDrawControl](https://mapbox.mhaibaraai.cn/docs/extensions/draw) 的 `options.modes`，再经 `changeMode` 切换。 从 `@movk/mapbox` 自动导入，无需手写 import。 ## 用法 合并自定义模式后，用按钮切换绘制圆 / 椭圆 / 矩形 / 扇形： ```vue [DrawModesExample.vue] ``` ## API ### `movkDrawModes`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 模式集合对象，键为模式名（传给 `changeMode`），值为 mapbox-gl-draw 模式对象。各模式也可单独具名导入（`drawRectangleMode` / `drawCircleMode` / `drawEllipseMode` / `drawSectorMode`）。 **draw\_rectangle** (`DrawCustomMode`): 矩形绘制模式。 **draw\_circle** (`DrawCustomMode`): 圆绘制模式。 **draw\_ellipse** (`DrawCustomMode`): 椭圆绘制模式。 **draw\_sector** (`DrawCustomMode`): 扇形绘制模式。 ## Changelog See commit history for [src/runtime/draw-modes/index.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/draw-modes/index.ts). # drawThemeStyles ## 简介 `drawThemeStyles` 依据主题选项生成完整的 mapbox-gl-draw `styles` 数组，配合 `userProperties: true` 使用；颜色取 `coalesce(user_color, 主题色)`，要素级 `user_color` 可覆盖主题色。 从 `@movk/mapbox` 自动导入，无需手写 import。 ## 用法 切换主色生成主题样式（预置多边形即时呈现）： ```vue [DrawThemeExample.vue] ``` ## API ### `drawThemeStyles()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 入参 `options: DrawThemeOptions`（省略用默认值），返回 `StyleSpec[]`，可直接传给 [MapboxDrawControl](https://mapbox.mhaibaraai.cn/docs/extensions/draw) 的 `options.styles`。 **color** (`string`): 非激活态主色，默认 #3b82f6。 **activeColor** (`string`): 激活态（绘制 / 选中）主色，默认 #f59e0b。 **fillOpacity** (`number`): 多边形填充不透明度，默认 0.1。 **lineWidth** (`number`): 线宽，默认 2。 **vertexRadius** (`number`): 顶点圆半径，默认 5。 ## Changelog See commit history for [src/runtime/utils/drawTheme.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/utils/drawTheme.ts). # MapboxTiandituLayer ## 简介 `MapboxTiandituLayer` 以天地图 WMTS 瓦片作底图：`layer` 选类型（`vec` 矢量 / `img` 影像 / `ter` 地形，及注记 `cva`/`cia`/`cta`），`annotation` 叠加对应注记层，`tk` 缺省时回退运行时配置的 `tiandituToken`。 > \[!NOTE] > > 天地图为 GCJ02 坐标系，叠加自有 WGS84 数据时先经 > > 坐标转换 > > 对齐。 ## 用法 切换 `layer` 查看矢量/影像/地形底图（均叠加注记）： ```vue [TiandituLayerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxTiandituLayer component */ interface MapboxTiandituLayerProps { /** * 天地图图层类型（vec 矢量底图） * @default "\"vec\"" */ layer?: TiandituLayerType; /** * 天地图 token；缺省时回退运行时配置 */ tk?: string; /** * 插入到该图层之前 */ beforeId?: string; /** * 叠加对应注记图层（vec→cva / img→cia / ter→cta） * @default "false" */ annotation?: boolean; } ``` ## Changelog See commit history for [src/runtime/components/extensions/TiandituLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/extensions/TiandituLayer.vue). # MapboxWmsLayer ## 简介 `MapboxWmsLayer` 把标准 WMS（GetMap）服务接入为栅格图层：`url` 与 `layers` 必填，`version` / `format` / `crs` / `transparent` 等透传，`params` 追加自定义查询参数。瓦片按 `{bbox-epsg-3857}` 逐块请求。 ## 用法 接入 terrestris 公开 OSM-WMS： ```vue [WmsLayerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxWmsLayer component */ interface MapboxWmsLayerProps { /** * WMS 服务基础地址 */ url: string; /** * 图层 LAYERS（逗号分隔多层） */ layers: string; /** * source/layer id */ layerId?: string; /** * WMS 版本 */ version?: string; /** * 图片格式 */ format?: string; /** * 样式 */ styles?: string; /** * 坐标参考系 */ crs?: string; /** * 瓦片尺寸 */ tileSize?: number; /** * 版权信息 */ attribution?: string; /** * 透传查询参数 */ params?: Record; /** * 插入到该图层之前 */ beforeId?: string; /** * 是否透明 */ transparent?: boolean; } ``` ## Changelog See commit history for [src/runtime/components/extensions/WmsLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/extensions/WmsLayer.vue). # MapboxWmtsLayer ## 简介 `MapboxWmtsLayer` 把标准 WMTS（KVP GetTile）服务接入为栅格图层：`url` 与 `layer` 必填，`tileMatrixSet` / `style` / `format` 透传，`url` 含 `{s}` 时配合 `subdomains` 展开多 host，`params` 追加鉴权参数（如 `tk`）。[MapboxTiandituLayer](https://mapbox.mhaibaraai.cn/docs/extensions/tianditu) 即基于它封装。 ## 用法 以天地图影像为例演示 WMTS 接入（`tk` 取自运行时配置）： ```vue [WmtsLayerExample.vue] ``` ## API ### Props ```ts /** * Props for the MapboxWmtsLayer component */ interface MapboxWmtsLayerProps { /** * WMTS 服务基础地址；含 {s} 时配合 subdomains 展开 */ url: string; /** * 图层标识 LAYER */ layer: string; /** * source/layer id */ layerId?: string; /** * 瓦片矩阵集 */ tileMatrixSet?: string; /** * 瓦片格式 */ format?: string; /** * 子域名列表，替换 url 中的 {s} */ subdomains?: string[]; /** * 瓦片尺寸 */ tileSize?: number; /** * 版权信息 */ attribution?: string; /** * 透传查询参数（如 { tk }） */ params?: Record; /** * 插入到该图层之前 */ beforeId?: string; } ``` ## Changelog See commit history for [src/runtime/components/extensions/WmtsLayer.vue](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/components/extensions/WmtsLayer.vue). # 坐标转换 ## 简介 `transformPoint` / `transformGeoJSON` 基于 [gcoord](https://github.com/hujiulong/gcoord){rel=""nofollow""} 在 WGS84 / GCJ02 / BD09 / EPSG3857 间转换坐标：前者转单个经纬度点，后者转任意 GeoJSON 并返回新对象（不修改入参）。常用于把来自高德 / 腾讯（GCJ02）、百度（BD09）的数据纠偏到 WGS84，对齐天地图与 Mapbox 底图。 > \[!NOTE] > > 不同底图的坐标系不同，叠加数据前需统一： > > - **天地图**：CGCS2000，与 WGS84 厘米级相容。`MapboxTiandituLayer` 走 `w`（EPSG:3857 球面墨卡托）瓦片，WGS84 数据**直接对齐，无需转换**。 > - **高德 / 腾讯**：GCJ02（火星坐标，加密偏移），其数据叠到天地图 / Mapbox 前需 `GCJ02 → WGS84`。 > - **百度**：BD09，需 `BD09 → WGS84`。 两者均从 `@movk/mapbox/utils/coordinate` 导入（非自动导入）。 ## 用法 WGS84 坐标在天地图底图上直接对齐；把它转成 GCJ02（高德 / 腾讯坐标系）后叠在天地图上，反而会偏移： ```vue [CoordinateExample.vue] ``` ## 示例 ### 纠偏 GeoJSON 把高德导出的 GCJ02 折线经 `transformGeoJSON` 转回 WGS84，对齐天地图底图。红线为原始 GCJ02（偏移），绿线为转换后 WGS84（对齐）： ```vue [CoordinateGeoJsonExample.vue] ``` ### 控制坐标精度 `precision` 指定输出坐标保留的小数位数，用于去抖与减小传输体积；省略则保留完整精度： ```ts import { transformGeoJSON } from '@movk/mapbox/utils/coordinate' const compact = transformGeoJSON(raw, 'GCJ02', 'WGS84', { precision: 6 }) ``` ## API ### `transformPoint()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 转换单个经纬度点，返回新坐标。 **point** (`[number, number]`) *required*: 经纬度点 \[lng, lat]。 **from** (`CRS`) *required*: 源坐标系。 **to** (`CRS`) *required*: 目标坐标系。 **options.precision** (`number`): 输出坐标保留的小数位数，省略则保留完整精度。 返回 `[number, number]`：转换后的 `[lng, lat]`。 ### `transformGeoJSON()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 转换任意 GeoJSON（点 / 线 / 面 / 集合），返回与入参同类型的新对象，不修改入参。 **geojson** (`T`) *required*: 任意 GeoJSON 对象（Feature / Geometry / FeatureCollection 等）。 **from** (`CRS`) *required*: 源坐标系。 **to** (`CRS`) *required*: 目标坐标系。 **options.precision** (`number`): 输出坐标保留的小数位数，省略则保留完整精度。 返回 `T`：与入参同类型的新 GeoJSON 对象。 ### `CRS`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 坐标系标识：`'WGS84'` | `'GCJ02'` | `'BD09'` | `'EPSG3857'`。 ## Changelog See commit history for [src/runtime/utils/坐标转换.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/utils/坐标转换.ts). # useMap ## 简介 `useMap` 注入由最近的 `` 下发的上下文，返回地图实例引用、样式就绪状态与就绪回调。它是所有声明式子组件读取地图的统一入口，无需经 id 查表。 > \[!NOTE] > > 必须在 > > \ > > 子树内调用，否则抛错。需要在地图组件树之外访问，请改用 > > useMapbox > > 。 `onReady` 在样式首次加载与每次 `setStyle` 后都会重跑，是建 source / layer、绑定事件的推荐入口；`map` 在 SSR 与挂载前为 `undefined`，组件已做 SSR 安全处理。 ## 用法 子组件经 `useMap()` 读取实时相机状态（中心、缩放、就绪状态）： ```vue [UseMapExample.vue] ``` ## API ### `useMap()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 注入当前地图上下文，返回 `MapboxContext`。无参数。 返回 `MapboxContext`： **id** (`string`): 地图 id，未显式指定时为内部生成的唯一值。 **map** (`ShallowRef`): 地图实例引用；SSR 与挂载前为 undefined。 **isLoaded** (`Ref`): 样式是否已加载完成。 **whenLoaded** (`() => Promise`): 样式首次加载完成时 resolve，返回地图实例。 **onReady** (`(cb: (map: Map) => void) => () => void`): 样式就绪即执行回调，且每次 setStyle 重新加载后重跑（用于重建 source / layer）；返回取消订阅函数。 ## Changelog See commit history for [src/runtime/composables/useMap.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMap.ts). # useMeasure ## 简介 `useMeasure` 提供测距 / 测面交互：单击加点、移动预览、双击结束当前段、Esc 取消。它自管展示用的 geojson 源与图层，用 turf 实时计算并格式化读数。返回 `start` / `stop` / `clear` 控制方法与 `mode` / `active` / `result` 响应式状态。 > \[!NOTE] > > 在 > > \ > > 子树外使用时经 > > options.mapId > > 指定目标地图。读数格式化复用 > > formatDistance / formatArea > > 。 ## 用法 工具栏切换测距 / 测面，`result` 实时显示当前段读数： ```vue [UseMeasureExample.vue] ``` ## API ### `useMeasure()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 创建测量工具。 **options.mapId** (`string`): 目标地图 id；在 \ 子树外使用时必填。 **options.color** (`string`): 主色，默认 '#f59e0b'。 返回 `UseMeasureReturn`： **start** (`(mode: MeasureMode) => void`): 进入测量：click 加点、mousemove 预览、dblclick 结束当前段。 **stop** (`() => void`): 退出测量交互（保留已绘结果）。 **clear** (`() => void`): 清空全部测量结果。 **mode** (`Ref`): 当前测量模式。 **active** (`Ref`): 测量是否激活。 **result** (`Ref`): 当前段（含光标预览）的格式化读数。 ### `MeasureMode`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 测量模式：`'distance'` | `'area'`。 ## Changelog See commit history for [src/runtime/composables/useMeasure.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMeasure.ts). # defineMapboxControl ## 简介 `defineMapboxControl` 用回调式 `onAdd` / `onRemove` 快速定义一个符合 `IControl` 接口的自定义控件，省去手写控件类的样板。`onAdd` 返回控件的 DOM 元素，`onRemove` 负责清理。返回的对象可直接传给 `map.addControl`。 > \[!NOTE] > > 本助手只产出控件对象，不负责挂载。结合 > > useMap > > / > > useMapbox > > 取得地图后调用 > > addControl > > 即可。 ## 用法 定义一个「回到原点」按钮控件并添加到地图： ```vue [DefineMapboxControlExample.vue] ``` ## API ### `defineMapboxControl()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 创建自定义控件对象。 **onAdd** (`(map: Map) => HTMLElement`) *required*: 控件添加到地图时调用，返回控件的 DOM 元素。 **onRemove** (`(map: Map) => void`) *required*: 控件从地图移除时调用，负责清理。 返回 `IControl`：可直接传给 `map.addControl` 的控件对象。 ## Changelog See commit history for [src/runtime/composables/defineMapboxControl.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/defineMapboxControl.ts). # useMapbox ## 简介 `useMapbox` 是 [useMap](https://mapbox.mhaibaraai.cn/docs/composables/use-map) 的「逃生口」：按 id 从注册表获取已挂载地图的上下文，可在 `` 组件树之外、甚至跨路由访问地图。未找到对应 id 时返回 `undefined`。 > \[!NOTE] > > 仅对显式设置了 > > map-id > > 的 > > \ > > 生效（未指定 id 的地图不进注册表）。注册发生在地图挂载阶段，故调用时机需在地图挂载之后；常见做法是在事件回调或 > > whenLoaded() > > 中使用。 ## 用法 工具栏位于 `` 子树之外，经 `useMapbox(id)` 跨树访问地图并飞行到目标城市： ```vue [UseMapboxExample.vue] ``` ## API ### `useMapbox()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 按 id 从注册表获取地图上下文。 **id** (`string`) *required*: 目标地图的 map-id。 返回 `MapboxContext | undefined`：对应 id 的地图上下文（结构见 [useMap](https://mapbox.mhaibaraai.cn/docs/composables/use-map#api)），未找到时为 `undefined`。 ## Changelog See commit history for [src/runtime/composables/useMapbox.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMapbox.ts). # useMapboxCamera ## 简介 `useMapboxCamera` 封装常用相机操作：平滑飞行、缓动、立即跳转与缩放到范围。所有方法均返回 `Promise`，内部等待地图加载完成后执行，无需手动判断就绪状态。`fitBounds` 额外接受任意 GeoJSON，自动求其包围盒。 > \[!NOTE] > > 在 > > \ > > 子树外使用时，经 > > options.mapId > > 指定目标地图。 ## 用法 工具栏触发飞行与缩放到路线（`fitBounds` 直接传入 GeoJSON）： ```vue [UseMapboxCameraExample.vue] ``` ## API ### `useMapboxCamera()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 创建相机操作助手。 **options.mapId** (`string`): 目标地图 id；在 \ 子树外使用时必填。 返回 `UseMapboxCameraReturn`： **flyTo** (`(options: EasingOptions) => Promise`): 平滑飞行到目标视角。 **easeTo** (`(options: EasingOptions) => Promise`): 缓动到目标视角。 **jumpTo** (`(options: CameraOptions) => Promise`): 立即跳转到目标视角。 **fitBounds** (`(target: LngLatBoundsLike | GeoJSON, options?: FitBoundsOptions) => Promise`): 缩放到目标范围；target 支持包围盒或任意 GeoJSON（自动求包围盒）。 ## Changelog See commit history for [src/runtime/composables/useMapboxCamera.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMapboxCamera.ts). # useMapboxDraw ## 简介 `useMapboxDraw` 注入最近 `` 提供的 [MapboxDraw](https://github.com/mapbox/mapbox-gl-draw){rel=""nofollow""} 实例（`ShallowRef` 包装），用于在子组件中程序化切换绘制模式、增删要素等。 > \[!NOTE] > > 必须在 > > \ > > 子树内调用，否则抛错。实例在控件挂载后才赋值，使用前判空。 ## 用法 子组件经 `useMapboxDraw()` 注入实例并切换绘制模式；要素数量由控件的 `v-model:features` 回写： ```vue [UseMapboxDrawExample.vue] ``` ## API ### `useMapboxDraw()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 注入当前绘制实例，无参数。 返回 `ShallowRef`：当前 `MapboxDrawControl` 的绘制实例；控件挂载前为 `undefined`。 ## Changelog See commit history for [src/runtime/composables/useMapboxDraw.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMapboxDraw.ts). # useMapboxImage ## 简介 `useMapboxImage` 加载远程图片并注册为样式图片，供 symbol 图层经 `icon-image` 引用。`setStyle` 清空样式图片后会经 `onReady` 自动补回，组件卸载时移除。返回 `loaded` 状态便于在加载完成前给出占位反馈。 > \[!NOTE] > > 设 > > sdf: true > > 注册为 SDF 图标后，可经 > > icon-color > > 着色。在 > > \ > > 子树外使用时经 > > options.mapId > > 指定目标地图。 ## 用法 注册一张远程图片，symbol 图层经 `icon-image` 引用： ```vue [UseMapboxImageExample.vue] ``` ## API ### `useMapboxImage()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 注册命名图片。 **name** (`string`) *required*: 图片注册名称，供 icon-image 引用。 **url** (`string`) *required*: 图片 URL 地址。 **options.mapId** (`string`): 目标地图 id；在 \ 子树外使用时必填。 **options.sdf** (`boolean`): 作为 SDF 图标（可经 icon-color 着色）。 **options.pixelRatio** (`number`): 像素密度，默认 1。 返回 `{ loaded: Ref }`：图片是否已加载完成。 ## Changelog See commit history for [src/runtime/composables/useMapboxImage.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMapboxImage.ts). # useFeatureState ## 简介 `useFeatureState` 在目标图层上自动维护 `feature-state` 的 hover / selected 状态：消费侧 paint 用 `['feature-state', 'hover' | 'selected']` 表达式驱动样式，无需重设 source 数据即可高亮悬浮与选中要素。返回当前悬浮 / 选中要素与清除选中方法。 > \[!NOTE] > > 要素必须带 > > id > > ：在 source 上配置 > > generateId: true > > 或 > > promoteId > > ，否则 > > feature-state > > 无法定位要素。 ## 用法 悬浮高亮、点击选中，`fill-opacity` 经 `feature-state` 表达式分级驱动： ```vue [UseFeatureStateExample.vue] ``` ## API ### `useFeatureState()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 在目标图层上维护交互状态。 **layerId** (`string`) *required*: 目标图层 id。 **options.mapId** (`string`): 目标地图 id；在 \ 子树外使用时必填。 **options.hover** (`boolean`): 维护 hover 状态，默认 true。 **options.select** (`boolean`): 维护 click 选中状态，默认 true。 **options.cursor** (`boolean`): 悬浮时设置 pointer 指针，默认 true。 返回 `UseFeatureStateReturn`： **hovered** (`ShallowRef`): 当前悬浮要素。 **selected** (`ShallowRef`): 当前选中要素。 **clearSelection** (`() => void`): 清除选中。 ## Changelog See commit history for [src/runtime/composables/useFeatureState.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useFeatureState.ts). # useFrameIcon ## 简介 `useFrameIcon` 是帧动画图标的底层原语：把一组逐帧 `ImageData` 注册为 `StyleImageInterface`，按 `fps` 或每帧 `durations` 循环播放，并自动处理样式重载补回、`styleimagemissing` 兜底与卸载清理。[MapboxSpriteImage](https://mapbox.mhaibaraai.cn/docs/effects/sprite-image) 与 [MapboxAnimatedImage](https://mapbox.mhaibaraai.cn/docs/effects/animated-image) 即基于它实现。 > \[!NOTE] > > 在 > > \ > > 子树内调用（内部依赖 > > useMap > > ）。 > > frames > > / > > durations > > 为取值函数，返回值变化即生效，便于异步解码后再填充。多数场景直接用 SpriteImage / AnimatedImage 组件即可，仅在自定义帧来源时才需此原语。 ## 用法 子组件用 canvas 逐帧绘制扩散圆环，经 `useFrameIcon` 注册为 symbol 图标： ```vue [UseFrameIconExample.vue] ``` 子组件实现（位于 `` 子树内）： ```vue ``` ## API ### `useFrameIcon()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 注册帧动画图标，无返回值（副作用型）。 **options.imageName** (`string`) *required*: 注册到样式的图片名（symbol 图层 icon-image 引用）。 **options.size** (`number`) *required*: 纹理边长（像素）。 **options.frames** (`() => ImageData[]`) *required*: 当前帧序列（响应式取值）。 **options.fps** (`number`): 固定帧率，durations 缺省时生效。 **options.durations** (`() => number[] | undefined`): 每帧时长 ms（响应式取值），优先于 fps。 ## Changelog See commit history for [src/runtime/composables/useFrameIcon.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useFrameIcon.ts). # useMapAnimation ## 简介 `useMapAnimation` 是地图帧动画原语：基于 `useRafFn`（组件卸载自动停止），仅在地图存在且样式就绪时调用 `frame` 回调，回调第二参为自启动起的累计毫秒数。动效组件与帧驱动图片均复用它。返回 `pause` / `resume` / `isActive` 控制运行状态。 > \[!NOTE] > > 在 > > \ > > 子树外使用时经 > > options.mapId > > 指定目标地图。回调内每帧执行，避免在其中创建新对象或做重计算。 ## 用法 每帧驱动 `circle-radius` 周期脉动： ```vue [UseMapAnimationExample.vue] ``` ## API ### `useMapAnimation()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 创建帧动画循环。 **frame** (`(map: Map, elapsedMs: number) => void`) *required*: 每帧回调；elapsedMs 为自启动起的累计毫秒数。 **options.mapId** (`string`): 目标地图 id；在 \ 子树外使用时必填。 **options.immediate** (`boolean`): 创建后立即启动，默认 true。 返回 `UseMapAnimationReturn`： **pause** (`() => void`): 暂停动画。 **resume** (`() => void`): 恢复动画。 **isActive** (`Readonly>`): 是否正在运行。 ## Changelog See commit history for [src/runtime/composables/useMapAnimation.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMapAnimation.ts). # useMapExport ## 简介 `useMapExport` 把当前地图导出为图片：`exportImage` 返回 dataURL，`download` 直接触发浏览器下载。它在 `render` 回调内同步读取画布，无需为地图开启 `preserveDrawingBuffer`（WebGL 缓冲区在帧渲染后即被清空，故必须在该时机取 `toDataURL`）。 > \[!NOTE] > > 在 > > \ > > 子树外使用时经 > > options.mapId > > 指定目标地图。导出含外部瓦片的地图可能受跨域画布污染限制。 ## 用法 截图预览与下载 PNG： ```vue [UseMapExportExample.vue] ``` ## API ### `useMapExport()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 创建导出助手。 **options.mapId** (`string`): 目标地图 id；在 \ 子树外使用时必填。 返回 `UseMapExportReturn`： **exportImage** (`(options?: ExportImageOptions) => Promise`): 导出当前地图为 dataURL。 **download** (`(options?: DownloadOptions) => Promise`): 导出并触发浏览器下载。 ### `ExportImageOptions`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} **format** (`'image/png' | 'image/jpeg' | 'image/webp'`): 图像格式，默认 'image/png'。 **quality** (`number`): 有损格式质量 0-1，默认 0.92。 ### `DownloadOptions`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 继承 `ExportImageOptions`，额外： **fileName** (`string`): 下载文件名，默认 'map.png'。 ## Changelog See commit history for [src/runtime/composables/useMapExport.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMapExport.ts). # transformPoint / transformGeoJSON ## 简介 `transformPoint` / `transformGeoJSON` 基于 [gcoord](https://github.com/hujiulong/gcoord){rel=""nofollow""} 在 WGS84 / GCJ02 / BD09 / EPSG3857 间转换坐标：前者转单个经纬度点，后者转任意 GeoJSON 并返回新对象（不修改入参）。常用于把高德 / 腾讯（GCJ02）、百度（BD09）数据纠偏到 WGS84，对齐天地图与 Mapbox 底图。 两者均从 `@movk/mapbox/utils/coordinate` 导入（非自动导入）： ```ts import { transformGeoJSON, transformPoint } from '@movk/mapbox/utils/coordinate' const gcj02 = transformPoint([121.4737, 31.2304], 'WGS84', 'GCJ02') const wgs84 = transformGeoJSON(raw, 'GCJ02', 'WGS84', { precision: 6 }) ``` > \[!NOTE] > See: /docs/extensions/coordinate > > 完整的可视化示例（点纠偏、GeoJSON 纠偏、精度控制）见 > > 坐标转换 > > 扩展页。 ## API ### `transformPoint()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 转换单个经纬度点，返回新坐标。 **point** (`[number, number]`) *required*: 经纬度点 \[lng, lat]。 **from** (`CRS`) *required*: 源坐标系。 **to** (`CRS`) *required*: 目标坐标系。 **options.precision** (`number`): 输出坐标保留的小数位数，省略则保留完整精度。 返回 `[number, number]`：转换后的 `[lng, lat]`。 ### `transformGeoJSON()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 转换任意 GeoJSON（点 / 线 / 面 / 集合），返回与入参同类型的新对象，不修改入参。 **geojson** (`T`) *required*: 任意 GeoJSON 对象（Feature / Geometry / FeatureCollection 等）。 **from** (`CRS`) *required*: 源坐标系。 **to** (`CRS`) *required*: 目标坐标系。 **options.precision** (`number`): 输出坐标保留的小数位数，省略则保留完整精度。 返回 `T`：与入参同类型的新 GeoJSON 对象。 ### `CRS`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 坐标系标识：`'WGS84'` | `'GCJ02'` | `'BD09'` | `'EPSG3857'`。 ## Changelog See commit history for [src/runtime/utils/transformPoint transformGeoJSON.ts](). # bufferPaints ## 简介 `bufferPaints` 按主色、填充不透明度与描边宽度生成一对 `fill` / `line` paint 对象，供缓冲区的填充层与描边层复用。`MapboxBufferCircle` 等[缓冲区组件](https://mapbox.mhaibaraai.cn/docs/layers/buffer-circle)的默认样式即来自它，也可单独用于自绘的缓冲区图层。 从 `@movk/mapbox/utils/buffer` 导入（非自动导入）。 ## 用法 把 `bufferPaints` 的输出分别绑定到 fill / line 图层： ```vue [BufferPaintsExample.vue] ``` ## API ### `bufferPaints()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 生成缓冲区默认 paint。 **options.color** (`string`): 主色（同时用于 fill 与 line），默认 '#3b82f6'。 **options.fillOpacity** (`number`): 填充不透明度，默认 0.25。 **options.lineWidth** (`number`): 描边宽度，默认 2。 返回 `{ fill, line }`：分别为填充层与描边层的 paint 对象，可直接绑定到 `` 的 `paint`。 ## Changelog See commit history for [src/runtime/utils/bufferPaints.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/utils/bufferPaints.ts). # boundsOfGeoJSON ## 简介 `boundsOfGeoJSON` 扫描任意 GeoJSON（要素 / 几何 / 集合 / 几何集合）的全部坐标，求西南、东北角包围盒，返回可直接传给 `map.fitBounds` 的元组；无坐标时返回 `undefined`。常用于把视野缩放到一组数据的范围。[useMapboxCamera](https://mapbox.mhaibaraai.cn/docs/composables/use-mapbox-camera) 的 `fitBounds` 接受 GeoJSON 时即内部调用它。 从 `@movk/mapbox/utils/geometry` 导入（非自动导入）。 ## 用法 求折线包围盒并缩放到该范围，同时用矩形可视化包围盒： ```vue [GeometryBoundsExample.vue] ``` ## API ### `boundsOfGeoJSON()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 求 GeoJSON 包围盒。 **input** (`GeoJSON`) *required*: 任意 GeoJSON 对象。 返回 `LngLatBoundsTuple | undefined`：`[[west, south], [east, north]]` 元组；无坐标时为 `undefined`。 ### `LngLatBoundsTuple`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 西南 / 东北角包围盒：`[[number, number], [number, number]]`，可直接传给 `map.fitBounds`。 ## Changelog See commit history for [src/runtime/utils/boundsOfGeoJSON.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/utils/boundsOfGeoJSON.ts). # formatDistance / formatArea ## 简介 `formatDistance` / `formatArea` 把原始的米 / 平方米数值格式化为带单位的可读字符串：距离千米以下取整米、以上保留两位 km；面积平方千米以下取整平方米、以上保留两位 km²。[useMeasure](https://mapbox.mhaibaraai.cn/docs/composables/use-measure) 的实时读数即由它们格式化。 从 `@movk/mapbox/utils/measure` 导入（非自动导入）。 ## 用法 不同量级的输入对应的格式化结果： ```vue ``` ## API ### `formatDistance()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 格式化距离。 **meters** (`number`) *required*: 距离值（米）。 返回 `string`：千米以下取整米（如 `850 m`），以上保留两位 km（如 `1.23 km`）。 ### `formatArea()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 格式化面积。 **squareMeters** (`number`) *required*: 面积值（平方米）。 返回 `string`：平方千米以下取整平方米（如 `5000 m²`），以上保留两位 km²（如 `1.20 km²`）。 ## Changelog See commit history for [src/runtime/utils/formatDistance formatArea.ts](). # heatmapPaint ## 简介 `heatmapPaint` 一步生成 heatmap 图层的完整 paint：把指定要素属性按 `weightRange` 线性映射为 0..1 热力权重，并按 `heatmap-density` 经颜色断点着色（density 0 处自动透明，避免全图铺底色）。免去手写冗长的 `interpolate` 表达式。 从 `@movk/mapbox/utils/heatmap` 导入（非自动导入）。 ## 用法 把带 `temperature` 属性的点数据渲染为热力图： ```vue [HeatmapPaintExample.vue] ``` ## API ### `heatmapPaint()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} 生成 heatmap 图层 paint。 **options.weightProperty** (`string`): 权重取值的要素属性，默认 'temperature'。 **options.weightRange** (`[number, number]`): 权重属性取值范围 \[min, max]，线性映射到 0..1，默认 \[0, 40]。 **options.colorStops** (`[number, string][]`): 密度-颜色断点 \[密度比 0..1, 颜色]\[]；缺省为蓝→红五档，density 0 处自动透明。 **options.radius** (`number`): 热力半径（像素），默认 30。 **options.intensity** (`number`): 热力强度，默认 1。 **options.opacity** (`number`): 整体不透明度，默认 1。 返回热力图层 paint 对象，可直接绑定到 `` 的 `paint`。 ## Changelog See commit history for [src/runtime/utils/heatmapPaint.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/utils/heatmapPaint.ts). # Movk Mapbox — 声明式 Mapbox GL v3 封装库 ::u-page-hero --- class: dark:bg-gradient-to-b from-neutral-900 to-neutral-950 orientation: horizontal --- :::motion --- transition: duration: 0.6 delay: 0.1 class: mx-auto w-full --- :home-hero-demo ::: #top :hero-background #title :::motion 声明式 [Mapbox GL]{.text-primary} 组件库 ::: #description :::motion --- transition: duration: 0.6 delay: 0.3 --- 声明式组合地图、图层、标记与控件，相机参数 `v-model` 双向绑定。一套组件通用于 Nuxt 4 与纯 Vue + Vite，内置 3D 建筑、动态效果、天气环境与本土化底图。 ::: #links :::motion --- transition: duration: 0.6 delay: 0.5 class: flex flex-wrap gap-x-6 gap-y-3 --- [](https://mapbox.mhaibaraai.cn/docs/getting-started) [](https://github.com/mhaibaraai/movk-mapbox) ::: :: ::u-page-section --- class: dark:bg-neutral-950 --- #title 核心特性 #description 声明式组合、上下文注入与双模式运行，从一张底图到复杂的三维效果与本土化底图服务，按需采用。 #features :::u-page-feature --- icon: i-lucide-blocks --- #title 声明式组合 #description 以组件组合地图、数据源、图层、标记、弹窗与控件，状态即视图，告别命令式的 add/remove 样板。 ::: :::u-page-feature --- icon: i-lucide-share-2 --- #title MapboxContext 注入 #description 根组件下发上下文，子组件经 useMap() 直接取实例与 isLoaded / whenLoaded()，无需 id 查表。 ::: :::u-page-feature --- icon: i-lucide-move --- #title 相机双向绑定 #description v-model\:center / zoom / bearing / pitch 双向同步相机参数，并支持跨路由 persistent 持久化。 ::: :::u-page-feature --- icon: i-lucide-layers --- #title 丰富图层与效果 #description 内置 circle / fill / line / symbol / fill-extrusion / heatmap 与聚合、建筑、栅格、视频图层，叠加雷达、扩散、辉光、波纹、迁徙、轨迹等动态效果。 ::: :::u-page-feature --- icon: i-lucide-cloud-sun --- #title 环境与天气 #description fog 大气、3D lights、terrain 地形与 temperature / rain / snow 天气，配合相机倾斜还原沉浸式三维场景。 ::: :::u-page-feature --- icon: i-lucide-map --- #title 本土化扩展 #description 天地图底图、WMS / WMTS 服务、mapbox-gl-draw 绘制，以及基于 gcoord 的 WGS84 / GCJ02 / BD09 坐标转换，开箱即用。 ::: :::u-page-feature --- icon: i-lucide-package --- #title Nuxt / Vue 双模式 #description 既是 Nuxt 4 模块，也提供 @movk/mapbox/vite + vue-plugin，让同一套组件在纯 Vue + Vite 项目中通用。 ::: :::u-page-feature --- icon: i-lucide-toy-brick --- #title Composables 与工具 #description useMap、useMapboxCamera、useMeasure、useMapExport 等 composables，搭配坐标、缓冲、几何与量算工具，按需渐进式采用。 ::: :: ::u-page-c-t-a --- links: - label: Star on GitHub to: https://github.com/mhaibaraai/movk-mapbox target: _blank icon: i-lucide-star color: neutral - label: 快速入门 to: /docs/getting-started color: neutral variant: outline trailingIcon: i-lucide-arrow-right class: dark:bg-neutral-950 --- #title 开始构建你的下一张地图 #description 从一张底图到三维建筑、动态效果与本土化底图服务，Movk Mapbox 用声明式组件把 Mapbox GL 的复杂度收敛为可组合的能力。 ::