1. 问题重现：那个“不听话”的include-points属性

最近在做一个基于uniapp的社区配送App，里面有个核心功能是要在地图上展示多个配送点或商家位置。我想，这还不简单？uniapp的map组件不是有个现成的include-points属性嘛，传一个坐标数组进去，地图自动缩放视野，把所有点都囊括进来，多省事。结果，在浏览器调试时一切正常，真机运行到App端（尤其是iOS）直接就“罢工”了，地图纹丝不动，视野压根不会根据我传入的点位进行调整。

我一开始以为是自己的代码写错了，反复检查points数组的格式，确认纬度、经度都没问题。然后去翻官方文档，文档里白纸黑字写着呢，include-points属性用于“缩放视野以包含所有给定的坐标点”。我又去官方示例项目里找，把demo跑起来一看，嘿，在App端同样不好使。这下我明白了，这不是我一个人的问题。

后来在开发者社区里搜了搜，发现不少朋友都踩过这个坑。看起来，在App端，特别是某些原生渲染模式下，include-points属性的表现确实不稳定，或者说存在兼容性问题。官方也没有给出明确的解释和修复时间表。对于我们开发者来说，功能等着上线，不能干等着。既然现成的路走不通，那我们就自己动手，铺一条新路出来。

核心需求其实很明确：我们有一组经纬度坐标点，需要计算出一个合适的地图缩放级别（scale值），让地图在显示时，能够以某个点为中心（通常是第一个点，或者所有点的中心点），并且让所有的点都落在当前地图视野范围内。include-points属性本想帮我们完成这个“自动”计算，但它“旷工”了，所以我们需要自己实现这套计算逻辑。

2. 核心思路：手动计算视野与缩放级别

既然自动的不行，我们就来手动的。思路其实很直观，分三步走：

第一步，确定地图的中心点。 这个中心点可以是你的第一个标记点（markers[0]），也可以是你动态计算的所有点的几何中心。为了简单起见，我们通常直接使用地图初始化时设定的latitude和longitude，或者第一个坐标点作为视觉中心。

第二步，找出离这个中心点最远的那个坐标点。 为什么找最远的？因为只要地图的视野能覆盖到这个最远的点，那么其他离中心更近的点自然也就都在视野里了。这就好比你要用一个圆圈罩住一堆散落的石子，你只需要保证圆圈能罩住离圆心最远的那颗石子就行了。

第三步，根据这个“最远距离”，反推出一个合适的scale值。 这里就是最关键的数学转换环节了。uniapp地图的scale属性值（大致对应缩放级别）和实际的地图显示比例尺（比如1厘米代表多少公里）之间存在一个映射关系。我们需要建立一个经验模型，将计算出的物理距离（公里）映射到一个可用的scale值上。

这个方法的优势在于，它完全绕开了有问题的include-points属性，直接使用scale这个在任何端都表现稳定的属性来控制缩放，实现效果完全自主可控。下面，我们就来一步步拆解，看看具体怎么实现。

2.1 计算两点间的球面距离

首先，我们得会计算地球上两个坐标点之间的实际距离。因为地球是球体，不能直接用平面直角坐标系的距离公式，那样误差会很大，尤其是点距离较远时。这里我们采用经典的“半正矢公式”（Haversine formula），它假设地球是一个完美的球体，计算精度对于大多数应用场景已经足够了。

我们创建一个距离计算工具函数：

// utils/mapDistance.js

const EARTH_RADIUS = 6378137.0; // 地球半径，单位：米
const PI = Math.PI;

// 将角度转换为弧度
function getRad(d) {
    return d * PI / 180.0;
}

/**
 * 使用半正矢公式计算两个经纬度坐标之间的球面距离（米）
 * @param {Array} coord1 - 坐标1，格式 [latitude, longitude]
 * @param {Array} coord2 - 坐标2，格式 [latitude, longitude]
 * @returns {number} 距离，单位：米
 */
export function getGreatCircleDistance(coord1, coord2) {
    const lat1 = coord1[0];
    const lng1 = coord1[1];
    const lat2 = coord2[0];
    const lng2 = coord2[1];

    const radLat1 = getRad(lat1);
    const radLat2 = getRad(lat2);
    const a = radLat1 - radLat2;
    const b = getRad(lng1) - getRad(lng2);

    let s = 2 * Math.asin(
        Math.sqrt(
            Math.pow(Math.sin(a / 2), 2) +
            Math.cos(radLat1) * Math.cos(radLat2) * Math.pow(Math.sin(b / 2), 2)
        )
    );
    s = s * EARTH_RADIUS;
    // 保留两位小数
    s = Math.round(s * 100) / 100;
    return s;
}

这个getGreatCircleDistance函数就是我们的“尺子”。给它两个带纬度和经度的数组，它就能告诉我们这两点之间大概隔了多少米。你可以把它单独放在一个工具文件里，方便其他地方调用。

2.2 寻找距离中心最远的点

有了“尺子”，下一步就是在所有目标点中，找到离我们选定中心点最远的那个。这个过程就是一个简单的循环比较。

假设我们的数据是这样的：

// 在Vue组件的data或props中
data() {
    return {
        centerPoint: [39.90923, 116.397428], // 中心点，可以是北京天安门坐标
        targetPoints: [
            { latitude: 39.913, longitude: 116.402 },
            { latitude: 39.905, longitude: 116.392 },
            { latitude: 39.917, longitude: 116.410 },
            // ... 更多点
        ],
        mapScale: 16 // 初始缩放级别
    };
}

我们写一个方法来找出最远点及其距离：

// 在Vue组件的methods中
methods: {
    findFarthestPoint(center, points) {
        let farthestDistance = 0;
        let farthestPoint = null;

        points.forEach(point => {
            // 将点对象转换为[lat, lng]数组
            const targetCoord = [point.latitude, point.longitude];
            const distance = getGreatCircleDistance(center, targetCoord);

            if (distance > farthestDistance) {
                farthestDistance = distance;
                farthestPoint = point;
            }
        });

        return {
            point: farthestPoint,
            distance: farthestDistance // 单位：米
        };
    }
}

这个方法遍历所有点，用上一节的“尺子”量出它们到中心的距离，并始终记录下最大值。最后返回的farthestDistance，就是能覆盖所有点所需的最小视野半径（从中心到最远点的距离）。

3. 实战：从距离到地图scale的映射

好了，现在我们知道了最远距离是5000米（举个例子）。那么，地图的scale应该设置成多少，才能保证屏幕能显示出半径5公里的范围呢？这是整个方案中最需要“调参”和根据实际情况摸索的部分。

uniapp的map组件，其scale属性值范围通常是3-20（不同平台可能有细微差异）。值越小，地图显示的范围越大（ zoom out ）；值越大，地图显示得越详细，范围越小（ zoom in ）。但这个数值和实际公里数没有直接的、标准的数学公式对应，它受到手机屏幕尺寸、地图控件显示区域大小、地图比例尺等多种因素影响。

因此，我们需要建立一个经验映射表。这个表是基于多次试验得出的：在某个特定的屏幕和地图显示高度下，不同的scale值大致对应能显示多少公里的视野半径。

根据我多个项目的实测经验，下面给出一个比较通用的映射关系参考表。你可以基于这个表开始调试，并根据自己App的实际UI布局进行微调。

地图可视半径 (公里)	推荐 scale 值	说明
> 500 km	3-4	显示省级或国家级范围
200 - 500 km	5	显示多个城市
100 - 200 km	6	显示一个城市群
50 - 100 km	7	显示大城市及周边
20 - 50 km	8	显示主城区及近郊
10 - 20 km	9	显示主要城区
5 - 10 km	10-11	显示城区局部
2 - 5 km	12-13	显示街道、片区
1 - 2 km	14-15	显示详细街道
0.5 - 1 km	16	显示街区、大型建筑
< 0.5 km	17-20	显示建筑物细节

注意，这个表是在地图组件高度约为屏幕高度30% (30vh) 的情况下测试的。如果你的地图显示区域更大或更小，这个映射关系会变化！ 区域越大，同一scale值显示的地理范围就越大。

基于上表，我们可以编写一个函数，根据计算出的最远距离（单位转为公里），来动态选择合适的scale值：

// 在Vue组件的methods中
methods: {
    // ... 其他方法

    calculateScaleByDistance(distanceInMeters) {
        // 将米转换为公里
        const distanceInKm = distanceInMeters / 1000;

        // 定义距离阈值和对应的scale值
        // 这是一个可调整的配置数组，格式为 [距离阈值(km), 推荐的scale值]
        // 阈值按从大到小排列
        const scaleConfig = [
            [500, 4],
            [200, 5],
            [100, 6],
            [50, 7],
            [20, 8],
            [10, 9],
            [5, 11],
            [2, 13],
            [1, 15],
            [0.5, 16],
            [0, 18] // 默认值，距离非常近时使用
        ];

        for (let i = 0; i < scaleConfig.length; i++) {
            if (distanceInKm >= scaleConfig[i][0]) {
                return scaleConfig[i][1];
            }
        }
        // 如果距离小于最后一个阈值（0），返回最大的scale值（最详细）
        return 20;
    }
}

这个函数逻辑很清晰：如果最远距离大于等于500公里，就用scale=4；如果在200到500公里之间，用scale=5，以此类推。你可以把scaleConfig数组抽到配置文件中，方便不同页面或不同地图尺寸时快速调整。

4. 完整方案集成与组件封装

现在，我们把所有零件组装起来，形成一个完整的、可复用的解决方案。我建议将核心逻辑封装成一个独立的工具函数或一个Vue Composable（组合式函数），这样在任何需要的地图页面都能轻松引入。

4.1 创建工具函数

新建一个文件 useMapViewport.js：

// composables/useMapViewport.js
import { getGreatCircleDistance } from '@/utils/mapDistance.js';

export function useMapViewport() {
    // 配置：距离(km)到scale的映射，可根据实际地图容器尺寸调整
    const defaultScaleConfig = [
        [500, 4],
        [200, 5],
        [100, 6],
        [50, 7],
        [20, 8],
        [10, 9],
        [5, 11],
        [2, 13],
        [1, 15],
        [0.5, 16],
        [0, 18]
    ];

    /**
     * 计算最佳地图缩放级别
     * @param {Array} center - 中心点坐标 [lat, lng]
     * @param {Array} points - 点位数组，每个元素需包含 latitude, longitude
     * @param {Array} scaleConfig - 可选的自定义缩放配置
     * @returns {number} 推荐的 scale 值
     */
    const calculateOptimalScale = (center, points, scaleConfig = defaultScaleConfig) => {
        if (!points || points.length === 0) {
            // 如果没有点，返回一个默认的缩放级别，比如显示城市级别
            return 12;
        }

        // 1. 找出离中心点最远的距离
        let maxDistance = 0; // 单位：米
        points.forEach(point => {
            const targetCoord = [point.latitude, point.longitude];
            const distance = getGreatCircleDistance(center, targetCoord);
            if (distance > maxDistance) {
                maxDistance = distance;
            }
        });

        // 2. 将距离转换为公里
        const maxDistanceKm = maxDistance / 1000;
        console.log(`最远点距离中心约 ${maxDistanceKm.toFixed(2)} 公里`);

        // 3. 根据配置映射到 scale 值
        for (let i = 0; i < scaleConfig.length; i++) {
            if (maxDistanceKm >= scaleConfig[i][0]) {
                const recommendedScale = scaleConfig[i][1];
                console.log(`推荐使用 scale: ${recommendedScale}`);
                return recommendedScale;
            }
        }

        // 如果所有阈值都比距离大（即距离非常小），返回最大的scale
        return 20;
    };

    return {
        calculateOptimalScale
    };
}

4.2 在Vue页面中应用

在你的地图页面组件中，可以这样使用：

<template>
    <view class="container">
        <!-- 地图组件，使用动态计算的 scale -->
        <map
            id="myMap"
            style="width: 100%; height: 300px;"
            :latitude="center.latitude"
            :longitude="center.longitude"
            :scale="dynamicScale"
            :markers="markers"
            show-location
        ></map>
        <!-- 其他UI内容 -->
    </view>
</template>

<script>
import { useMapViewport } from '@/composables/useMapViewport.js';

export default {
    data() {
        return {
            center: {
                latitude: 39.90923,
                longitude: 116.397428
            },
            markers: [
                { id: 1, latitude: 39.913, longitude: 116.402, title: '点A' },
                { id: 2, latitude: 39.905, longitude: 116.392, title: '点B' },
                { id: 3, latitude: 39.917, longitude: 116.410, title: '点C' },
            ],
            dynamicScale: 16 // 初始值，会被计算覆盖
        };
    },
    mounted() {
        // 组件挂载后计算最佳缩放级别
        this.calculateAndSetScale();
    },
    methods: {
        calculateAndSetScale() {
            const { calculateOptimalScale } = useMapViewport();
            const centerArray = [this.center.latitude, this.center.longitude];

            // 计算并更新 scale
            this.dynamicScale = calculateOptimalScale(centerArray, this.markers);

            // 如果需要，也可以在这里重新设置地图中心点
            // 例如，如果你想将中心点设置为所有点的几何中心，可以在此计算并更新 this.center
        }
    },
    // 如果 points 是动态获取的，可以在watch中监听
    watch: {
        markers: {
            deep: true,
            handler(newVal) {
                if (newVal && newVal.length > 0) {
                    // 稍微延迟一下，确保DOM更新完毕
                    setTimeout(() => {
                        this.calculateAndSetScale();
                    }, 100);
                }
            }
        }
    }
};
</script>

4.3 处理动态数据与性能优化

在实际项目中，你的坐标点数据很可能是从网络API异步获取的。这时候，你需要在数据获取成功后，再调用我们的计算方法。同时，为了避免频繁计算（比如点数据微调时），可以添加简单的防抖逻辑。

// 在组件 methods 中
async fetchPointsAndUpdateMap() {
    try {
        const pointsData = await this.$api.getDeliveryPoints(); // 假设的API调用
        this.markers = pointsData.map(item => ({
            id: item.id,
            latitude: item.lat,
            longitude: item.lng,
            title: item.name
        }));

        // 数据更新后，计算新的缩放级别
        this.calculateAndSetScale();
    } catch (error) {
        console.error('获取点位数据失败:', error);
    }
}

如果地图上的点会实时更新（比如跟踪配送员位置），频繁计算距离可能会带来性能压力。对于这种场景，有两点优化建议：

1. 设置计算阈值：只有当新增点或移动的点超出当前视野范围一定比例时，才重新计算scale。
2. 使用防抖函数：对于连续的位置更新，可以设置一个300-500毫秒的防抖，避免毫秒级的频繁计算。

import { debounce } from 'lodash-es'; // 或自己实现一个简单的防抖

export default {
    methods: {
        // 创建防抖版本的计算函数
        calculateAndSetScaleDebounced: debounce(function() {
            const { calculateOptimalScale } = useMapViewport();
            const centerArray = [this.center.latitude, this.center.longitude];
            this.dynamicScale = calculateOptimalScale(centerArray, this.markers);
        }, 500), // 500ms内只执行一次

        // 在频繁更新的地方调用防抖函数
        onPositionUpdate(newPosition) {
            // ... 更新 markers 逻辑
            this.calculateAndSetScaleDebounced();
        }
    }
}

5. 避坑指南与进阶技巧

自己动手实现的过程中，我踩过几个坑，这里分享给你，希望能帮你节省时间。

坑1：坐标格式不一致。 有时候从不同来源获取的坐标数据，格式可能是{lat: xxx, lng: xxx}，也可能是[longitude, latitude]（注意顺序！），或者是字符串类型。我们的计算函数期望的是数字类型的[latitude, longitude]数组。务必在计算前做好数据清洗和格式统一，否则会算出莫名其妙的结果甚至报错。一个健壮的函数开头应该加上类型判断和转换。

坑2：地图容器尺寸的影响极大。 我前面提供的scaleConfig映射表，是在height: 300px（约30vh）下调试的。如果你的地图是全屏的，那么scale=10显示的范围会比小地图大得多。因此，强烈建议你在自己的项目里，用几个已知距离的点做一次校准。 方法很简单：固定两个点，手动调整scale值，直到两点刚好在地图左右（或上下）边缘，记录下此时的scale和实际距离，多测几组数据，就能拟合出你自己项目的映射关系。

坑3：跨平台差异。 虽然scale属性在各端基本可用，但iOS和Android上同一scale值下的视觉范围可能仍有细微差别。如果对一致性要求极高，可以考虑针对不同平台微调scaleConfig配置。

进阶技巧：计算几何中心点。 上面的例子一直用第一个点或手动指定的点作为中心。更优雅的方式是计算所有点的几何中心（质心），让地图视野真正“居中”于所有点集。计算很简单，就是所有纬度值的平均值，和所有经度值的平均值。

function calculateCenterPoint(points) {
    if (!points || points.length === 0) return null;
    let totalLat = 0;
    let totalLng = 0;
    const count = points.length;

    points.forEach(point => {
        totalLat += Number(point.latitude);
        totalLng += Number(point.longitude);
    });

    return [totalLat / count, totalLng / count];
}

然后在你的calculateAndSetScale方法中，先调用这个函数计算中心点，再用这个中心点去计算最远距离和缩放级别。这样，当地图展示时，所有点就会均匀地分布在地图中央区域了。

最后一点经验： 这个方案虽然解决了include-points失效的问题，但它本质上是一个“估算”方案。由于scale与实际距离没有绝对精确的数学关系，它无法像原生include-points那样做到像素级的完美适配边缘。但在绝大多数业务场景下，这个方案带来的视觉效果已经完全可接受，用户根本察觉不到区别。开发就是这样，有时候没有完美的银弹，但总有切实可行的土办法。