MapLibre Logo

MapLibre Native

MapLibre Native 是一个免费且开源的库，用于在各种平台的应用程序和桌面应用程序中发布地图。得益于 GPU 加速的矢量瓦片渲染，可以实现地图的快速显示。

该项目最初是 Mapbox GL Native 的一个分支，源于其在 2020 年 12 月转向非开源许可证之前。更多信息，请参阅：FORK.md.

Android device with MapLibre iOS device with MapLibre

入门指南

Android

将 MapLibre Native Android 的最新版本作为依赖项添加到您的项目中。

    dependencies {
        ...
        implementation 'org.maplibre.gl:android-sdk:11.11.0'
        ...
    }

在您的布局 XML 文件中添加一个 MapView：

<org.maplibre.android.maps.MapView
    android:id="@+id/mapView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    />

[!TIP] 有外部项目，例如 Ramani Maps 和 MapLibre Compose Playground，可用于将 MapLibre Native Android 集成到基于 Compose 的项目中。

接下来，在活动（activity）中初始化地图：

Show code

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.LayoutInflater
import org.maplibre.android.MapLibre
import org.maplibre.android.camera.CameraPosition
import org.maplibre.android.geometry.LatLng
import org.maplibre.android.maps.MapView
import org.maplibre.android.testapp.R

class MainActivity : AppCompatActivity() {

    // Declare a variable for MapView
    private lateinit var mapView: MapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Init MapLibre
        MapLibre.getInstance(this)

        // Init layout view
        val inflater = LayoutInflater.from(this)
        val rootView = inflater.inflate(R.layout.activity_main, null)
        setContentView(rootView)

        // Init the MapView
        mapView = rootView.findViewById(R.id.mapView)
        mapView.getMapAsync { map ->
            map.setStyle("https://demotiles.maplibre.org/style.json")
            map.cameraPosition = CameraPosition.Builder().target(LatLng(0.0,0.0)).zoom(1.0).build()
        }
    }

    override fun onStart() {
        super.onStart()
        mapView.onStart()
    }

    override fun onResume() {
        super.onResume()
        mapView.onResume()
    }

    override fun onPause() {
        super.onPause()
        mapView.onPause()
    }

    override fun onStop() {
        super.onStop()
        mapView.onStop()
    }

    override fun onLowMemory() {
        super.onLowMemory()
        mapView.onLowMemory()
    }

    override fun onDestroy() {
        super.onDestroy()
        mapView.onDestroy()
    }

    override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        mapView.onSaveInstanceState(outState)
    }
}

有关更多信息，请参阅 Android API 文档或 Android 示例文档。

iOS

您可以在 Cocoapods 和 Swift Package Index 上找到 MapLibre Native iOS。您也可以将 MapLibre Native iOS 直接作为依赖项添加到 Xcode。

MapLibre Native iOS 使用 UIKit。要将其与 UIKit 项目集成，您可以使用

class SimpleMap: UIViewController, MLNMapViewDelegate {
    var mapView: MLNMapView!

    override func viewDidLoad() {
        super.viewDidLoad()
        mapView = MLNMapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)
        mapView.delegate = self
    }

    func mapView(_: MLNMapView, didFinishLoading _: MLNStyle) {
    }
}

使用 SwiftUI 时，您需要创建一个包装器。

import MapLibre

struct SimpleMap: UIViewRepresentable {
    func makeUIView(context _: Context) -> MLNMapView {
        let mapView = MLNMapView()
        return mapView
    }

    func updateUIView(_: MLNMapView, context _: Context) {}
}

[!TIP] 你还可以使用 MapLibreSwiftUI，这是一个围绕 MapLibre Native iOS 的封装，提供类似 SwiftUI 的声明式 API。

iOS 文档包含许多示例以及该库的完整 API。

Node.js

有一个 npm 包用于在 Node.js 项目中使用 MapLibre Native。该项目的源代码可以在此仓库中找到。

Qt

请查看 maplibre/maplibre-native-qt 仓库以了解如何将 MapLibre Native 集成到 Qt 项目中。

Compose Multiplatform

MapLibre Compose 为 Compose Multiplatform 支持的各种平台封装了 MapLibre Native。截至 2025 年 8 月，已支持 iOS 和 Android，Web 和桌面端部分支持。

其他平台

MapLibre Native 也可以在 Linux、Windows 和 macOS 上构建。

贡献

[!NOTE] 本节仅适用于希望为 MapLibre Native 做出贡献的人员。

MapLibre Native 的核心是一个 C++ 库。目前大部分开发工作都在此进行。

要开始接触代码库，你需要克隆包含所有子模块的仓库。

所有贡献者都使用来自私有 fork 的 pull request。Fork 该项目。然后运行：

git clone --recurse-submodules git@github.com:<YOUR NAME>/maplibre-native.git
git remote add origin https://github.com/maplibre/maplibre-native.git

首选参考资料是 MapLibre Native 开发者文档。

[!TIP] 查看标记为 good first issue 的问题。

Core

CONTRIBUTING.md
GitHub Wiki：与社区分享信息的低摩擦方式
Core C++ API 文档（不稳定）

Android

使用 Android Studio 打开 platform/android。

更多信息：MapLibre Android 开发者指南。

iOS

您需要使用 Bazel 来生成 Xcode 项目。安装 bazelisk（一个安装所需 Bazel 版本的包装器）。接下来，使用：

bazel run //platform/ios:xcodeproj --@rules_xcodeproj//xcodeproj:extra_common_flags="--//:renderer=metal"
xed platform/ios/MapLibre.xcodeproj

生成并打开 Xcode 项目。

更多信息：MapLibre iOS 开发者指南。

其他平台

请参阅 /platform 并导航至您感兴趣的平台以获取更多信息。

参与贡献

加入 OSMUS 的 #maplibre-native Slack 频道。在 https://slack.openstreetmap.us/ 获取邀请。

成为赞助商 💰

我们感谢过去在财务上支持我们的所有人，并特别感谢以定期捐款支持我们的人们和组织！

在 https://maplibre.org/sponsors/ 阅读有关 MapLibre 赞助计划的更多信息。

金牌：

Silver:

支持者与赞助者：

许可证

MapLibre Native 采用 BSD 2-Clause License 授权。