---
title: "介绍"
description: "了解 Movk Mapbox 的声明式设计、上下文注入架构与 Nuxt / Vue 双模式，从安装到组合地图、数据源、图层与控件。"
seo_title: "Introduction"
seo_description: "Movk Mapbox is a declarative Mapbox GL v3 wrapper that provides MapboxMap / MapboxSource / MapboxLayer components and composables, with native Nuxt 4 support and a Vite plugin for plain Vue + Vite projects."
canonical_url: "https://mapbox.mhaibaraai.cn/docs/getting-started"
---
# 介绍

> 了解 Movk Mapbox 的声明式设计、上下文注入架构与 Nuxt / Vue 双模式，从安装到组合地图、数据源、图层与控件。

## 介绍

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 等，以及坐标 / 缓冲 / 几何工具


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.