第2章 快速开始：Hello World路线规划

本章带你在5分钟内跑通一个完整的路线规划示例。从零开始引入导航SDK、初始化地图容器、设置起终点坐标、发起路线请求并在地图上绘制路径，最终在浏览器中看到一条从A到B的导航路线。先理解整体流程，再动手编码。

2.1 原理概述

路线规划的核心流程可概括为“环境就绪 → 地图就绪 → 起终点就绪 → 请求路线 → 渲染路线”五个阶段。地图服务商提供的SDK封装了底图加载、坐标转换、路径计算和图层绘制等复杂逻辑，开发者只需按照固定顺序调用对应API即可完成路线展示。下图展示了该流程的完整链路：

2.2 环境准备与SDK引入

在HTML页面中通过 <script> 标签加载导航SDK的核心文件。注意：需要先前往地图服务平台申请有效的，否则后续请求会被拒绝。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Hello World 路线规划</title>
    <!-- 引入导航SDK核心库 -->
    <script src="https://sdk.navicloud.com/v2/navi-sdk.min.js"></script>
    <link rel="stylesheet" href="https://sdk.navicloud.com/v2/navi-sdk.css">
    <style>
        #map-container { width: 100%; height: 500px; }
    </style>
</head>
<body>
    <div id="map-container"></div>
    <script>
        // 后续所有代码均在此 script 内编写
    </script>
</body>
</html>

2.3 初始化地图

调用 NaviSDK.init() 方法创建地图实例，传入容器ID和。初始化必须等待页面DOM渲染完成，建议将代码放在 window.onload 或 DOMContentLoaded 事件中执行。

window.onload = function() {
    // 初始化地图
    var map = NaviSDK.init({
        container: 'map-container',
        : 'YOUR__HERE',
        center: [116.397, 39.908],   // 默认中心：北京天安门
        zoom: 13
    });
    console.log('地图初始化完成');
};

2.4 设置起点与终点

使用 NaviSDK.LngLat 创建坐标对象，分别赋值给起点和终点变量。坐标格式为 [经度, 纬度]，注意不要颠倒。

    // 在 map 初始化之后继续编写
    var origin = new NaviSDK.LngLat(116.397, 39.908);     // 天安门
    var destination = new NaviSDK.LngLat(116.497, 39.918); // 朝阳大望路

    // 添加起点标记（红色）
    var originMarker = new NaviSDK.Marker({ color: '#e74c3c' })
        .setLngLat(origin)
        .addTo(map);

    // 添加终点标记（蓝色）
    var destMarker = new NaviSDK.Marker({ color: '#3498db' })
        .setLngLat(destination)
        .addTo(map);

2.5 发起路线规划请求

调用导航服务的 nav.getRoute() 方法，传入起终点坐标和出行方式（driving / walking / cycling）。请求为异步操作，使用 .then() 或 async/await 处理返回结果。

    // 创建导航客户端实例
    var nav = new NaviSDK.Navigation({ : 'YOUR__HERE' });

    // 请求驾车路线
    nav.getRoute({
        origin: origin,
        destination: destination,
        mode: 'driving'    // 可选: driving | walking | cycling
    }).then(function(routeData) {
        console.log('路线规划成功', routeData);
        // routeData 包含路径坐标点串、距离、耗时等信息
    }).catch(function(err) {
        console.error('路线规划失败', err);
    });

2.6 显示路线

将返回的路径坐标点串添加到地图的路线图层中。使用 map.addRouteLayer() 方法绘制折线，并自动适配地图视野以完整展示整条路线。

    // 在 getRoute 的 then 回调中继续
    .then(function(routeData) {
        // 绘制路线
        map.addRouteLayer({
            id: 'my-route',
            coordinates: routeData.path,  // 坐标点串 [[lng,lat], ...]
            color: '#2ecc71',
            width: 5,
            opacity: 0.85
        });

        // 自动调整视野包含起终点
        map.fitBounds([
            [origin.lng, origin.lat],
            [destination.lng, destination.lat]
        ], { padding: 80 });
    })

2.7 完整示例代码

将上述所有片段合并为一个完整的HTML文件，复制后替换 YOUR__HERE 即可直接运行。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Hello World 路线规划</title>
    <script src="https://sdk.navicloud.com/v2/navi-sdk.min.js"></script>
    <link rel="stylesheet" href="https://sdk.navicloud.com/v2/navi-sdk.css">
    <style>
        body { margin: 0; padding: 20px; font-family: sans-serif; }
        #map-container { width: 100%; height: 560px; border-radius: 12px; box-shadow: 0 4px 20px rgba(0,0,0,0.1); }
    </style>
</head>
<body>
    <h3>我的第一条导航路线</h3>
    <div id="map-container"></div>
    <script>
        window.onload = function() {
            // 1. 初始化地图
            var map = NaviSDK.init({
                container: 'map-container',
                : 'YOUR__HERE',
                center: [116.397, 39.908],
                zoom: 13
            });

            // 2. 设置起终点
            var origin = new NaviSDK.LngLat(116.397, 39.908);
            var destination = new NaviSDK.LngLat(116.497, 39.918);

            new NaviSDK.Marker({ color: '#e74c3c' }).setLngLat(origin).addTo(map);
            new NaviSDK.Marker({ color: '#3498db' }).setLngLat(destination).addTo(map);

            // 3. 请求并显示路线
            var nav = new NaviSDK.Navigation({ : 'YOUR__HERE' });
            nav.getRoute({
                origin: origin,
                destination: destination,
                mode: 'driving'
            }).then(function(routeData) {
                map.addRouteLayer({
                    id: 'my-route',
                    coordinates: routeData.path,
                    color: '#2ecc71',
                    width: 5,
                    opacity: 0.85
                });
                map.fitBounds([
                    [origin.lng, origin.lat],
                    [destination.lng, destination.lat]
                ], { padding: 80 });
                console.log('路线已显示，距离：' + routeData.distance + ' 米，耗时：' + routeData.duration + ' 秒');
            }).catch(function(err) {
                console.error('路线规划失败：', err);
                alert('路线规划失败，请检查和网络连接。');
            });
        };
    </script>
</body>
</html>

2.8 关键API参数说明

下表列出快速开始中使用到的核心API及其必填参数，方便对照查阅：

2.9 调试与验证

验证路线是否显示正确，可以手动在地图上拖拽缩放，检查起点标记（红色）、终点标记（蓝色）以及中间的绿色路线折线是否连贯。如果路线未显示，优先检查 routeData.path 是否为空数组。

2.10 部署到静态服务器

将完整示例HTML文件保存为 index.html，然后使用任意静态服务器托管。本地测试可用Python快速启动：

# 在 index.html 所在目录执行
python3 -m http.server 8080

浏览器访问 http://localhost:8080 即可看到路线效果。生产环境建议将HTML、CSS、JS分离，并使用HTTPS协议加载SDK。

2.11 常见错误与避坑

• 无效或未设置：请求返回 401 或 403 状态码。检查 参数是否正确，并确认该Key已开启路线规划服务权限。
• 坐标顺序颠倒：标准格式为 [经度, 纬度]，误写为 [纬度, 经度] 会导致起点/终点定位到错误大陆。
• 地图容器未设置高度：容器div缺少固定高度时，地图渲染为0像素，页面看不到地图。务必给 #map-container 设置明确的height值。
• 异步请求未处理错误：getRoute() 的 .catch() 缺失时，网络错误或服务端异常会静默失败，路线不显示且无提示。始终添加错误处理。
• SDK版本不一致：引入的JS和CSS文件版本号必须相同，否则可能引起样式错乱或API不兼容。

2.12 性能与稳定性建议