Back to Details

mapbox-navigation-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Mapbox Navigation Patterns

Mapbox 导航实现模式

Expert guidance for implementing navigation and routing features using Mapbox Directions API and Navigation SDKs. Covers turn-by-turn navigation, route optimization, real-time traffic integration, multi-stop routing, and navigation UI components.
本指南提供了使用Mapbox Directions API和Navigation SDKs实现导航及路径规划功能的专业指导，涵盖逐向导航、路线优化、实时路况集成、多站点路径规划以及导航UI组件等内容。

Use This Skill When

适用场景

User says things like:
  • "I need turn-by-turn navigation in my app"
  • "How do I add driving directions?"
  • "I want to show a route on the map"
  • "I need multi-stop routing"
  • "How do I add voice guidance?"
  • "I want real-time traffic updates"
  • "I need to optimize delivery routes"
当用户提出以下需求时使用本技能：
  • "我需要在应用中实现逐向导航"
  • "如何添加驾车导航功能？"
  • "我想在地图上显示路线"
  • "我需要多站点路径规划功能"
  • "如何添加语音导航？"
  • "我想要实时路况更新"
  • "我需要优化配送路线"

Product Overview

产品概述

Directions API (REST)

Directions API（REST）

Best for: Web applications, simple routing, backend route calculation
Features:
  • Route calculation (driving, walking, cycling, traffic)
  • Alternative routes
  • Turn-by-turn instructions
  • Multi-stop routing (up to 25 waypoints)
  • Route optimization
  • Real-time traffic data
  • Avoid specific roads/areas
Pricing: Pay per request
适用场景： 网页应用、简单路径规划、后端路线计算
功能特性：
  • 路线计算（驾车、步行、骑行、路况）
  • 备选路线
  • 逐向导航指令
  • 多站点路径规划（最多25个途经点）
  • 路线优化
  • 实时路况数据
  • 避开特定道路/区域
定价： 按请求次数付费

Navigation SDK for iOS

iOS 导航SDK

Best for: Native iOS apps with turn-by-turn navigation
Defaults: SwiftUI app shell + wrap drop-in 
NavigationViewController
via 
UIViewControllerRepresentable
(official getting-started path). Use a fully custom Core UI (CoreSDKExample) only when the user explicitly wants to build their own nav chrome.
Before coding: SPM (
MapboxNavigationCore
+ 
MapboxNavigationUIKit
), 
.netrc
download token, 
MBXAccessToken
, location permissions, background 
audio
/
location
— see install guide and the iOS reference checklist.
Features:
  • Drop-in turn-by-turn UI (
    NavigationViewController
    ) — default
  • Optional fully custom Core UI (route progress / banner publishers)
  • Voice guidance (30+ languages)
  • Real-time rerouting
  • Traffic-aware routing
  • Offline maps and routing
  • Route progress tracking
  • Speed limit display
Pricing: Monthly Active Users (MAU) based
适用场景： 具备逐向导航功能的原生iOS应用
默认方案： SwiftUI应用框架 + 通过
UIViewControllerRepresentable
封装即插即用的
NavigationViewController
（官方入门路径）。仅当用户明确想要构建自定义导航界面时，才使用完全自定义的Core UI（CoreSDKExample）。
编码前准备： SPM（
MapboxNavigationCore
+ 
MapboxNavigationUIKit
）、
.netrc
下载令牌、
MBXAccessToken
、位置权限、后台
audio
/
location
权限——详见安装指南及iOS参考清单。
功能特性：
  • 即插即用的逐向导航UI（
    NavigationViewController
    ）——默认方案
  • 可选的完全自定义Core UI（路线进度/横幅发布器）
  • 语音导航（支持30+种语言）
  • 实时重新规划路线
  • 路况感知型路线规划
  • 离线地图与导航
  • 路线进度追踪
  • 限速显示
定价： 基于月活跃用户数（MAU）

Navigation SDK for Android

Android 导航SDK

Best for: Native Android apps with turn-by-turn navigation
Features:
  • Complete turn-by-turn navigation UI
  • Voice guidance (30+ languages)
  • Real-time rerouting
  • Traffic-aware routing
  • Offline maps and routing
  • Custom UI components
  • Route progress tracking
  • Speed limit display
Pricing: Monthly Active Users (MAU) based
适用场景： 具备逐向导航功能的原生Android应用
功能特性：
  • 完整的逐向导航UI
  • 语音导航（支持30+种语言）
  • 实时重新规划路线
  • 路况感知型路线规划
  • 离线地图与导航
  • 自定义UI组件
  • 路线进度追踪
  • 限速显示
定价： 基于月活跃用户数（MAU）

Decision Guide

决策指南

Choose Directions API when:

选择Directions API的场景：

  • ✅ Web application
  • ✅ Simple route display (no turn-by-turn)
  • ✅ Backend route calculation
  • ✅ Route planning and optimization
  • ✅ Multi-stop routing
  • ✅ Don't need voice guidance
  • ✅ 网页应用
  • ✅ 仅需简单路线展示（无需逐向导航）
  • ✅ 后端路线计算
  • ✅ 路线规划与优化
  • ✅ 多站点路径规划
  • ✅ 无需语音导航

Choose Navigation SDK when:

选择Navigation SDK的场景：

  • ✅ Native mobile app (iOS/Android)
  • ✅ Need turn-by-turn navigation
  • ✅ Need voice guidance
  • ✅ Need navigation UI components
  • ✅ Need offline navigation
  • ✅ Need real-time rerouting
  • ✅ Building a navigation/delivery app
  • ✅ 原生移动应用（iOS/Android）
  • ✅ 需要逐向导航
  • ✅ 需要语音导航
  • ✅ 需要导航UI组件
  • ✅ 需要离线导航
  • ✅ 需要实时重新规划路线
  • ✅ 构建导航/配送类应用

Implementation Patterns

实现模式

  • references/web-directions-api.md - Directions API patterns for the web: basic route display, turn-by-turn instructions, alternative routes, multi-stop routing, route optimization, and congestion-based route coloring
  • references/ios-navigation-sdk.md - When: iOS turn-by-turn, setup, default SwiftUI + wrapped 
    NavigationViewController
    , Core opt-in, example catalog
  • references/ios-navigation-specialized.md - When: multi-stop, route line, camera, road cameras, route alerts, or 
    NavigationMapView
    customization
  • references/android-navigation-sdk.md - Navigation SDK for Android: basic turn-by-turn navigation, custom navigation UI, route line rendering, maneuver arrows, navigation camera, voice guidance
  • references/android-performance-antipatterns.md - Android Navigation SDK performance and correctness antipatterns: Native Route Object traversal costs, threading, memory/lifecycle leaks, route management correctness, frequent-callback rendering efficiency, and Coordination API lifecycle
  • references/best-practices.md - Route caching, error handling, performance optimization, user experience, and common use cases (delivery routing, ride-sharing ETAs, walking/cycling directions)
  • references/web-directions-api.md - 网页端Directions API实现模式：基础路线展示、逐向导航指令、备选路线、多站点路径规划、路线优化及基于拥堵情况的路线着色
  • references/ios-navigation-sdk.md - 适用场景：iOS逐向导航、环境搭建、默认SwiftUI + 封装
    NavigationViewController
    方案、Core UI自定义选项、示例目录
  • references/ios-navigation-specialized.md - 适用场景：多站点路径规划、路线线条、摄像头、道路摄像头、路线提醒或
    NavigationMapView
    自定义
  • references/android-navigation-sdk.md - Android导航SDK：基础逐向导航、自定义导航UI、路线线条渲染、转向箭头、导航摄像头、语音导航
  • references/android-performance-antipatterns.md - Android导航SDK性能与正确性反模式：原生路线对象遍历成本、线程处理、内存/生命周期泄漏、路线管理正确性、频繁回调渲染效率、Coordination API生命周期
  • references/best-practices.md - 路线缓存、错误处理、性能优化、用户体验及常见用例（配送路线规划、网约车ETA、步行/骑行导航）

Related Skills

相关技能

  • mapbox-search-integration: Address search and geocoding
  • mapbox-web-performance-patterns: Optimizing navigation performance
  • mapbox-ios-patterns: iOS-specific integration patterns
  • mapbox-android-patterns: Android-specific integration patterns
  • mapbox-token-security: Securing your access tokens
  • mapbox-search-integration: 地址搜索与地理编码
  • mapbox-web-performance-patterns: 导航性能优化
  • mapbox-ios-patterns: iOS专属集成模式
  • mapbox-android-patterns: Android专属集成模式
  • mapbox-token-security: 访问令牌安全防护

Resources

资源链接

Quick Decision Guide

快速决策指南

User says: "I need directions"
  • Web app → Use Directions API
  • Mobile app → Use Navigation SDK
User says: "I need turn-by-turn navigation"
  • iOS → Navigation SDK for iOS (SwiftUI + wrapped 
    NavigationViewController
    by default; Core custom UI only if requested)
  • Android → Navigation SDK for Android
  • Web → Use Directions API + custom UI (no voice guidance)
User says: "I need to optimize delivery routes" → Use Optimization API (multi-stop route optimization)
User says: "I need real-time traffic" → Use 
driving-traffic
profile with Directions API or Navigation SDK
User says: "I need voice guidance" → Must use Navigation SDK (iOS/Android only)
User says: "Directions API or Navigation SDK?" → Native turn-by-turn / voice → Navigation SDK (MAU pricing). Web / route display only → Directions API (pay-per-request).
用户需求："我需要导航功能"
  • 网页应用 → 使用Directions API
  • 移动应用 → 使用Navigation SDK
用户需求："我需要逐向导航"
  • iOS → 使用iOS导航SDK（默认采用SwiftUI + 封装
    NavigationViewController
    方案；仅当用户明确要求时才使用Core自定义UI）
  • Android → 使用Android导航SDK
  • 网页 → 使用Directions API + 自定义UI（无语音导航）
用户需求："我需要优化配送路线" → 使用优化API（多站点路线优化）
用户需求："我需要实时路况" → 在Directions API或Navigation SDK中使用
driving-traffic
配置文件
用户需求："我需要语音导航" → 必须使用Navigation SDK（仅支持iOS/Android）
用户需求："选Directions API还是Navigation SDK？" → 原生逐向导航/语音导航 → 使用Navigation SDK（按MAU定价）。网页/仅路线展示 → 使用Directions API（按请求次数付费）。