expo-gaode-map 2.2.32 → 2.2.33

package/ios/ExpoGaodeMapModule.swift

@@ -48,12 +48,19 @@ public class ExpoGaodeMapModule: Module {
             _ = self.trySetupApiKeyFromPlist()
         }
         
-        Function("setPrivacyShow") { (hasShow: Bool, hasContainsPrivacy: Bool) in
-            GaodeMapPrivacyManager.setPrivacyShow(hasShow, hasContainsPrivacy: hasContainsPrivacy)
-        }
+        Function("setPrivacyConfig") { (config: [String: Any]) in
+            let hasShow = config["hasShow"] as? Bool ?? false
+            let hasContainsPrivacy = config["hasContainsPrivacy"] as? Bool ?? hasShow
+            let hasAgree = config["hasAgree"] as? Bool ?? false
+            let privacyVersion = config["privacyVersion"] as? String
 
-        Function("setPrivacyAgree") { (hasAgree: Bool) in
-            GaodeMapPrivacyManager.setPrivacyAgree(hasAgree)
+            GaodeMapPrivacyManager.setPrivacyConfig(
+                hasShow: hasShow,
+                hasContainsPrivacy: hasContainsPrivacy,
+                hasAgree: hasAgree,
+                privacyVersion: privacyVersion,
+                updatesPrivacyVersion: config.keys.contains("privacyVersion")
+            )
         }
 
         Function("setPrivacyVersion") { (version: String) in
@@ -76,7 +83,7 @@ public class ExpoGaodeMapModule: Module {
          */
         Function("initSDK") { (config: [String: String]) in
             guard GaodeMapPrivacyManager.isReady else {
-                throw Exception(name: "PRIVACY_NOT_AGREED", description: "隐私协议未完成确认，请先调用 setPrivacyShow/setPrivacyAgree")
+                throw Exception(name: "PRIVACY_NOT_AGREED", description: "隐私协议未完成确认，请先调用 setPrivacyConfig")
             }
             GaodeMapPrivacyManager.applyPrivacyState()
 
@@ -273,6 +280,31 @@ public class ExpoGaodeMapModule: Module {
             }
             return ClusterNative.calculateDistance(lat1: coord1.latitude, lon1: coord1.longitude, lat2: coord2.latitude, lon2: coord2.longitude)
         }
+
+        /**
+         * 根据多个坐标点计算可同时可见的推荐缩放级别
+         */
+        Function("calculateFitZoom") {
+            (points: [Any]?, viewportWidthPx: Double?, viewportHeightPx: Double?, paddingPx: Double?, minZoom: Int?, maxZoom: Int?) -> Double in
+            let coords = LatLngParser.parseLatLngList(points)
+            let safeMinZoom = minZoom ?? 3
+            let safeMaxZoom = maxZoom ?? 20
+            if coords.isEmpty {
+                return Double(safeMinZoom)
+            }
+
+            let lats = coords.map { NSNumber(value: $0.latitude) }
+            let lons = coords.map { NSNumber(value: $0.longitude) }
+            return ClusterNative.calculateFitZoom(
+                latitudes: lats,
+                longitudes: lons,
+                viewportWidthPx: viewportWidthPx ?? 390.0,
+                viewportHeightPx: viewportHeightPx ?? 844.0,
+                paddingPx: paddingPx ?? 48.0,
+                minZoom: Int32(safeMinZoom),
+                maxZoom: Int32(safeMaxZoom)
+            )
+        }
         
         /**
          * 计算多边形面积

package/ios/ExpoGaodeMapView.swift

@@ -1349,17 +1349,24 @@ extension ExpoGaodeMapView {
         isHandlingAnnotationSelect = true
         
         // 🔑 统一从 overlayViews 查找 MarkerView（新旧架构统一）
-        for view in overlayViews {
-            if let markerView = view as? MarkerView {
+        for overlayView in overlayViews {
+            if let markerView = overlayView as? MarkerView {
                 if markerView.annotation === annotation {
                     let eventData: [String: Any] = [
                         "latitude": annotation.coordinate.latitude,
                         "longitude": annotation.coordinate.longitude
                     ]
                     markerView.onMarkerPress(eventData)
+                    // iOS 对“已选中 annotation”再次点击通常不会重复触发 didSelect。
+                    // 对自定义 children marker（无系统 callout）这里主动取消选中，
+                    // 以保证同一 marker 可以连续触发点击（例如关闭 sheet 后再次点击）。
+                    if !markerView.subviews.isEmpty {
+                        mapView.deselectAnnotation(annotation, animated: false)
+                        isHandlingAnnotationSelect = false
+                    }
                     return
                 }
-            } else if let clusterView = view as? ClusterView {
+            } else if let clusterView = overlayView as? ClusterView {
                 if clusterView.containsAnnotation(annotation) {
                     clusterView.handleAnnotationTap(annotation)
                     return

package/ios/GaodeMapPrivacyManager.swift

@@ -46,24 +46,6 @@ enum GaodeMapPrivacyManager {
         applyPrivacyState()
     }
 
-    static func setPrivacyShow(_ show: Bool, hasContainsPrivacy: Bool) {
-        let previousStatus = status()
-        hasShow = show
-        self.hasContainsPrivacy = hasContainsPrivacy
-        persistState()
-        applyPrivacyState()
-        notifyIfNeeded(previousStatus: previousStatus)
-    }
-
-    static func setPrivacyAgree(_ agree: Bool) {
-        let previousStatus = status()
-        hasAgree = agree
-        agreedPrivacyVersion = agree ? privacyVersion : nil
-        persistState()
-        applyPrivacyState()
-        notifyIfNeeded(previousStatus: previousStatus)
-    }
-
     static func setPrivacyVersion(_ version: String) {
         let previousStatus = status()
         privacyVersion = version.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -83,6 +65,32 @@ enum GaodeMapPrivacyManager {
         notifyIfNeeded(previousStatus: previousStatus)
     }
 
+    static func setPrivacyConfig(
+        hasShow: Bool,
+        hasContainsPrivacy: Bool,
+        hasAgree: Bool,
+        privacyVersion newPrivacyVersion: String?,
+        updatesPrivacyVersion: Bool
+    ) {
+        let previousStatus = status()
+
+        if updatesPrivacyVersion {
+            privacyVersion = newPrivacyVersion?.trimmingCharacters(in: .whitespacesAndNewlines)
+            if privacyVersion?.isEmpty == true {
+                privacyVersion = nil
+            }
+        }
+
+        self.hasShow = hasShow
+        self.hasContainsPrivacy = hasContainsPrivacy
+        self.hasAgree = hasAgree
+        agreedPrivacyVersion = hasAgree ? privacyVersion : nil
+
+        persistState()
+        applyPrivacyState()
+        notifyIfNeeded(previousStatus: previousStatus)
+    }
+
     static func resetPrivacyConsent() {
         let previousStatus = status()
         clearConsentPersistedState(keepCurrentVersion: false)

package/ios/modules/LocationManager.swift

@@ -238,7 +238,7 @@ class LocationManager: NSObject, AMapLocationManagerDelegate {
      */
     func coordinateConvert(_ coordinate: [String: Double], type: Int, promise: Promise) {
         guard GaodeMapPrivacyManager.isReady else {
-            promise.reject("PRIVACY_NOT_AGREED", "隐私协议未完成确认，请先调用 setPrivacyShow/setPrivacyAgree")
+            promise.reject("PRIVACY_NOT_AGREED", "隐私协议未完成确认，请先调用 setPrivacyConfig")
             return
         }
 

package/ios/overlays/MarkerView.swift

@@ -36,10 +36,10 @@ class MarkerView: ExpoView {
     var iconWidth: Double = 40
     /// 图标高度（用于自定义图标 icon 属性）
     var iconHeight: Double = 40
-    /// 自定义视图宽度（用于 children 属性）
-    var customViewWidth: Double = 0
-    /// 自定义视图高度（用于 children 属性）
-    var customViewHeight: Double = 0
+    /// 内容宽度（用于 children 属性）
+    var contentWidth: Double = 0
+    /// 内容高度（用于 children 属性）
+    var contentHeight: Double = 0
     /// 中心偏移
     var centerOffset: [String: Double]?
     /// 是否显示动画
@@ -230,7 +230,7 @@ class MarkerView: ExpoView {
         
         // 1. 如果有 children，使用自定义视图
         if self.subviews.count > 0 {
-            let size = resolvedCustomSubviewSize(defaultSize: CGSize(width: 200, height: 60))
+            let size = resolvedContentSubviewSize(defaultSize: CGSize(width: 200, height: 60))
             let key = childrenCacheKey(for: size)
             if let cached = IconBitmapCache.shared.image(forKey: key) {
                 annotationView?.image = cached
@@ -243,6 +243,7 @@ class MarkerView: ExpoView {
             // 异步渲染并设置
             DispatchQueue.main.async { [weak self, weak annotationView] in
                 guard let self = self, let annotationView = annotationView else { return }
+                guard self.isAnnotationView(annotationView, boundTo: annotation) else { return }
                 if let generated = self.createImageFromSubviews() {
                     annotationView.image = generated
                     self.applyCenterOffset(to: annotationView, defaultOffset: .zero)
@@ -265,6 +266,7 @@ class MarkerView: ExpoView {
             // 异步加载图标
             loadIcon(iconUri: iconUri) { [weak self, weak annotationView] image in
                 guard let self = self, let image = image, let annotationView = annotationView else { return }
+                guard self.isAnnotationView(annotationView, boundTo: annotation) else { return }
                 let size = CGSize(width: self.iconWidth, height: self.iconHeight)
                 UIGraphicsBeginImageContextWithOptions(size, false, 0.0)
                 image.draw(in: CGRect(origin: .zero, size: size))
@@ -305,8 +307,9 @@ class MarkerView: ExpoView {
         
         // 🔑 如果有 children，使用自定义视图
         if self.subviews.count > 0 {
-            // 使用 class-level reuseId，便于系统复用 view，减少内存
-            let reuseId = "custom_marker_children" + (growAnimation ? "_grow" : "")
+            let reuseToken = cacheKey?.replacingOccurrences(of: "|", with: "_")
+                ?? String(ObjectIdentifier(self).hashValue)
+            let reuseId = "custom_marker_children_\(reuseToken)" + (growAnimation ? "_grow" : "")
             var annotationView = mapView.dequeueReusableAnnotationView(withIdentifier: reuseId)
             if annotationView == nil {
                 if growAnimation {
@@ -326,7 +329,7 @@ class MarkerView: ExpoView {
             self.annotationView = annotationView
 
             // 生成 cacheKey 或 fallback 到 identifier
-            let size = resolvedCustomSubviewSize(defaultSize: CGSize(width: 200, height: 40))
+            let size = resolvedContentSubviewSize(defaultSize: CGSize(width: 200, height: 40))
             let key = childrenCacheKey(for: size)
 
             // 1) 如果缓存命中，直接同步返回图像（fast path）
@@ -347,6 +350,7 @@ class MarkerView: ExpoView {
             // 🔑 修复:延长延迟时间,给 React Native Image 更多加载时间
             DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self, weak annotationView] in
                 guard let self = self, let annotationView = annotationView else { return }
+                guard self.isAnnotationView(annotationView, boundTo: annotation) else { return }
                 // 再次检查缓存（避免重复渲染）
                 if let cached = IconBitmapCache.shared.image(forKey: key) {
                     annotationView.image = cached
@@ -410,12 +414,12 @@ class MarkerView: ExpoView {
                 UIGraphicsEndImageContext()
 
                 DispatchQueue.main.async {
+                    guard let annotationView else { return }
+                    guard self.isAnnotationView(annotationView, boundTo: annotation) else { return }
                     if let img = resizedImage {
                         IconBitmapCache.shared.setImage(img, forKey: key)
-                        annotationView?.image = img
-                        if let annotationView = annotationView {
-                            self.applyCenterOffset(to: annotationView, defaultOffset: CGPoint(x: 0, y: -img.size.height / 2))
-                        }
+                        annotationView.image = img
+                        self.applyCenterOffset(to: annotationView, defaultOffset: CGPoint(x: 0, y: -img.size.height / 2))
                     }
                 }
             }
@@ -496,7 +500,7 @@ class MarkerView: ExpoView {
      * 将子视图转换为图片
      */
     private func createImageFromSubviews() -> UIImage? {
-        let size = resolvedCustomSubviewSize(defaultSize: CGSize(width: 200, height: 60))
+        let size = resolvedContentSubviewSize(defaultSize: CGSize(width: 200, height: 60))
         let key = childrenCacheKey(for: size)
 
         if let cachedImage = IconBitmapCache.shared.image(forKey: key) {
@@ -580,14 +584,21 @@ class MarkerView: ExpoView {
         return .zero
     }
 
-    private func resolvedCustomSubviewSize(defaultSize: CGSize) -> CGSize {
+    private func isAnnotationView(_ annotationView: MAAnnotationView, boundTo annotation: MAAnnotation) -> Bool {
+        guard let current = annotationView.annotation else {
+            return false
+        }
+        return (current as AnyObject) === (annotation as AnyObject)
+    }
+
+    private func resolvedContentSubviewSize(defaultSize: CGSize) -> CGSize {
         guard let firstSubview = subviews.first else {
             return defaultSize
         }
 
-        if customViewWidth > 0 || customViewHeight > 0 {
-            let width = customViewWidth > 0 ? CGFloat(customViewWidth) : defaultSize.width
-            let height = customViewHeight > 0 ? CGFloat(customViewHeight) : defaultSize.height
+        if contentWidth > 0 || contentHeight > 0 {
+            let width = contentWidth > 0 ? CGFloat(contentWidth) : defaultSize.width
+            let height = contentHeight > 0 ? CGFloat(contentHeight) : defaultSize.height
             return CGSize(width: width, height: height)
         }
 
@@ -842,8 +853,8 @@ class MarkerView: ExpoView {
 
     private func invalidateCurrentChildrenCache() {
         let sizes = [
-            resolvedCustomSubviewSize(defaultSize: CGSize(width: 200, height: 40)),
-            resolvedCustomSubviewSize(defaultSize: CGSize(width: 200, height: 60))
+            resolvedContentSubviewSize(defaultSize: CGSize(width: 200, height: 40)),
+            resolvedContentSubviewSize(defaultSize: CGSize(width: 200, height: 60))
         ]
 
         for size in sizes {
@@ -1000,17 +1011,17 @@ class MarkerView: ExpoView {
         }
     }
 
-    func setCustomViewWidth(_ width: Double) {
-        guard customViewWidth != width else { return }
-        customViewWidth = width
+    func setContentWidth(_ width: Double) {
+        guard contentWidth != width else { return }
+        contentWidth = width
         if !subviews.isEmpty {
             refreshAnnotationAppearance(invalidateChildrenCache: true)
         }
     }
 
-    func setCustomViewHeight(_ height: Double) {
-        guard customViewHeight != height else { return }
-        customViewHeight = height
+    func setContentHeight(_ height: Double) {
+        guard contentHeight != height else { return }
+        contentHeight = height
         if !subviews.isEmpty {
             refreshAnnotationAppearance(invalidateChildrenCache: true)
         }

package/ios/overlays/MarkerViewModule.swift

@@ -41,12 +41,12 @@ public class MarkerViewModule: Module {
                 view.setIconHeight(height)
             }
             
-            Prop("customViewWidth") { (view: MarkerView, width: Double) in
-                view.setCustomViewWidth(width)
+            Prop("contentWidth") { (view: MarkerView, width: Double) in
+                view.setContentWidth(width)
             }
             
-            Prop("customViewHeight") { (view: MarkerView, height: Double) in
-                view.setCustomViewHeight(height)
+            Prop("contentHeight") { (view: MarkerView, height: Double) in
+                view.setContentHeight(height)
             }
             
             Prop("centerOffset") { (view: MarkerView, offset: [String: Double]) in

package/ios/utils/ClusterNative.h

@@ -55,6 +55,14 @@ NS_ASSUME_NONNULL_BEGIN
 + (NSDictionary * _Nullable)calculatePathBoundsWithLatitudes:(NSArray<NSNumber *> *)latitudes
                                                 longitudes:(NSArray<NSNumber *> *)longitudes NS_SWIFT_NAME(calculatePathBounds(latitudes:longitudes:));
 
++ (double)calculateFitZoomWithLatitudes:(NSArray<NSNumber *> *)latitudes
+                             longitudes:(NSArray<NSNumber *> *)longitudes
+                        viewportWidthPx:(double)viewportWidthPx
+                       viewportHeightPx:(double)viewportHeightPx
+                               paddingPx:(double)paddingPx
+                                 minZoom:(int)minZoom
+                                 maxZoom:(int)maxZoom NS_SWIFT_NAME(calculateFitZoom(latitudes:longitudes:viewportWidthPx:viewportHeightPx:paddingPx:minZoom:maxZoom:));
+
 + (NSString *)encodeGeoHashWithLat:(double)lat
                                lon:(double)lon
                          precision:(int)precision NS_SWIFT_NAME(encodeGeoHash(lat:lon:precision:));

package/ios/utils/ClusterNative.mm

@@ -242,6 +242,33 @@
     };
 }
 
++ (double)calculateFitZoomWithLatitudes:(NSArray<NSNumber *> *)latitudes
+                              longitudes:(NSArray<NSNumber *> *)longitudes
+                         viewportWidthPx:(double)viewportWidthPx
+                        viewportHeightPx:(double)viewportHeightPx
+                                paddingPx:(double)paddingPx
+                                  minZoom:(int)minZoom
+                                  maxZoom:(int)maxZoom {
+    if (latitudes.count == 0 || latitudes.count != longitudes.count) {
+        return (double)minZoom;
+    }
+
+    std::vector<gaodemap::GeoPoint> points;
+    points.reserve(latitudes.count);
+    for (NSUInteger i = 0; i < latitudes.count; i++) {
+        points.push_back({[latitudes[i] doubleValue], [longitudes[i] doubleValue]});
+    }
+
+    return gaodemap::calculateFitZoomForPoints(
+        points,
+        viewportWidthPx,
+        viewportHeightPx,
+        paddingPx,
+        minZoom,
+        maxZoom
+    );
+}
+
 + (NSString *)encodeGeoHashWithLat:(double)lat
                                lon:(double)lon
                          precision:(int)precision {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-gaode-map",
-  "version": "2.2.32",
+  "version": "2.2.33",
   "description": "A full-featured React Native AMap (Gaode Map) library for Expo, including map display, location, overlays, offline maps, and geometry utilities.",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -9,6 +9,7 @@
     "android",
     "ios",
     "shared",
+    "scripts",
     "app.plugin.js",
     "expo-module.config.json",
     "plugin/build"
@@ -20,6 +21,7 @@
     "lint": "expo-module lint",
     "test": "expo-module test",
     "prepare": "expo-module prepare && yarn build:plugin",
+    "postinstall": "node scripts/check-expo-modules.js",
     "prepublishOnly": "echo 'Skipping proofread check' && exit 0",
     "expo-module": "expo-module",
     "open:ios": "xed example/ios",

package/scripts/check-expo-modules.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function resolveProjectRoot() {
+  return process.env.INIT_CWD || process.env.npm_config_local_prefix || process.cwd();
+}
+
+function hasPackage(pkgName, projectRoot) {
+  try {
+    require.resolve(`${pkgName}/package.json`, { paths: [projectRoot] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function printWarning(lines) {
+  const prefix = '[expo-gaode-map]';
+  console.warn(`${prefix} WARNING: Expo Modules infrastructure was not detected in this React Native project.`);
+  for (const line of lines) {
+    console.warn(`${prefix} ${line}`);
+  }
+}
+
+function main() {
+  const projectRoot = resolveProjectRoot();
+
+  // Skip non-React Native consumers.
+  if (!hasPackage('react-native', projectRoot)) {
+    return;
+  }
+
+  const hasExpo = hasPackage('expo', projectRoot);
+  const hasExpoModulesCore = hasPackage('expo-modules-core', projectRoot);
+  const podfilePath = path.join(projectRoot, 'ios', 'Podfile');
+  const hasPodfile = fs.existsSync(podfilePath);
+  const hasUseExpoModules = hasPodfile
+    ? /\buse_expo_modules!\b/m.test(fs.readFileSync(podfilePath, 'utf8'))
+    : true;
+
+  if (hasExpo && hasExpoModulesCore && hasUseExpoModules) {
+    return;
+  }
+
+  const details = [];
+  if (!hasExpo) {
+    details.push('Missing dependency: expo');
+  }
+  if (!hasExpoModulesCore) {
+    details.push('Missing dependency: expo-modules-core');
+  }
+  if (!hasUseExpoModules) {
+    details.push('iOS Podfile does not contain use_expo_modules!');
+  }
+
+  printWarning([
+    ...details,
+    'This package requires Expo Modules infrastructure even in bare React Native apps.',
+    'Suggested fix:',
+    '  npx install-expo-modules@latest',
+    hasPodfile ? '  (then) cd ios && pod install' : null,
+    'Docs: https://docs.expo.dev/bare/installing-expo-modules/',
+  ].filter(Boolean));
+}
+
+main();

package/shared/cpp/GeometryEngine.cpp

@@ -3,6 +3,7 @@
 #include <cmath>
 #include <map>
 #include <algorithm>
+#include <limits>
 
 namespace gaodemap {
 
@@ -19,6 +20,54 @@ static inline double geo_toDegrees(double radians) {
     return radians * kRadiansToDegrees;
 }
 
+static inline double clampMercatorLatitude(double lat) {
+    static constexpr double kMaxMercatorLatitude = 85.05112878;
+    if (lat > kMaxMercatorLatitude) return kMaxMercatorLatitude;
+    if (lat < -kMaxMercatorLatitude) return -kMaxMercatorLatitude;
+    return lat;
+}
+
+static inline double mercatorX01(double lon) {
+    double wrapped = std::fmod(lon + 180.0, 360.0);
+    if (wrapped < 0.0) {
+        wrapped += 360.0;
+    }
+    return wrapped / 360.0;
+}
+
+static inline double mercatorY01(double lat) {
+    const double clampedLat = clampMercatorLatitude(lat);
+    const double latRad = geo_toRadians(clampedLat);
+    const double y = (1.0 - std::asinh(std::tan(latRad)) / kPi) * 0.5;
+    if (y < 0.0) return 0.0;
+    if (y > 1.0) return 1.0;
+    return y;
+}
+
+static double wrappedSpan01(std::vector<double> xs) {
+    if (xs.size() <= 1) {
+        return 0.0;
+    }
+
+    std::sort(xs.begin(), xs.end());
+    double maxGap = 0.0;
+
+    for (size_t i = 0; i + 1 < xs.size(); ++i) {
+        const double gap = xs[i + 1] - xs[i];
+        if (gap > maxGap) {
+            maxGap = gap;
+        }
+    }
+
+    const double endGap = xs.front() + 1.0 - xs.back();
+    if (endGap > maxGap) {
+        maxGap = endGap;
+    }
+
+    const double span = 1.0 - maxGap;
+    return span < 0.0 ? 0.0 : span;
+}
+
 double calculateDistance(double lat1, double lon1, double lat2, double lon2) {
     const double radLat1 = geo_toRadians(lat1);
     const double radLat2 = geo_toRadians(lat2);
@@ -512,6 +561,69 @@ GeoPoint pixelToLatLng(double x, double y, int zoom) {
     return {lat, lon};
 }
 
+double calculateFitZoomForPoints(
+    const std::vector<GeoPoint>& points,
+    double viewportWidthPx,
+    double viewportHeightPx,
+    double paddingPx,
+    int minZoom,
+    int maxZoom
+) {
+    if (minZoom > maxZoom) {
+        std::swap(minZoom, maxZoom);
+    }
+    if (points.empty()) {
+        return static_cast<double>(minZoom);
+    }
+    if (points.size() == 1) {
+        return static_cast<double>(maxZoom);
+    }
+
+    const double safeViewportWidth = viewportWidthPx > 1.0 ? viewportWidthPx : 390.0;
+    const double safeViewportHeight = viewportHeightPx > 1.0 ? viewportHeightPx : 844.0;
+    const double safePadding = std::max(0.0, paddingPx);
+    const double availableWidth = std::max(1.0, safeViewportWidth - safePadding * 2.0);
+    const double availableHeight = std::max(1.0, safeViewportHeight - safePadding * 2.0);
+
+    std::vector<double> projectedXs;
+    projectedXs.reserve(points.size());
+
+    double minY = std::numeric_limits<double>::max();
+    double maxY = -std::numeric_limits<double>::max();
+
+    for (const auto& p : points) {
+        projectedXs.push_back(mercatorX01(p.lon));
+        const double y = mercatorY01(p.lat);
+        if (y < minY) minY = y;
+        if (y > maxY) maxY = y;
+    }
+
+    const double spanX = wrappedSpan01(projectedXs);
+    const double spanY = std::max(0.0, maxY - minY);
+    static constexpr double kTileSize = 256.0;
+    static constexpr double kSpanEpsilon = 1e-12;
+
+    const double zoomX = spanX <= kSpanEpsilon
+        ? static_cast<double>(maxZoom)
+        : std::log2(availableWidth / (kTileSize * spanX));
+    const double zoomY = spanY <= kSpanEpsilon
+        ? static_cast<double>(maxZoom)
+        : std::log2(availableHeight / (kTileSize * spanY));
+
+    double fitZoom = std::min(zoomX, zoomY);
+    if (!std::isfinite(fitZoom)) {
+        fitZoom = static_cast<double>(minZoom);
+    }
+
+    if (fitZoom < static_cast<double>(minZoom)) {
+        fitZoom = static_cast<double>(minZoom);
+    } else if (fitZoom > static_cast<double>(maxZoom)) {
+        fitZoom = static_cast<double>(maxZoom);
+    }
+
+    return fitZoom;
+}
+
 // --- 批量地理围栏与热力图 ---
 
 int findPointInPolygons(double pointLat, double pointLon, const std::vector<std::vector<GeoPoint>>& polygons) {

package/shared/cpp/GeometryEngine.hpp

@@ -125,6 +125,27 @@ PixelResult latLngToPixel(double lat, double lon, int zoom);
  */
 GeoPoint pixelToLatLng(double x, double y, int zoom);
 
+/**
+ * 根据一组坐标点和视口尺寸计算“可同时看到所有点”的推荐缩放级别。
+ * 使用 Web Mercator 投影，在跨经线场景下会自动取更小经度跨度。
+ *
+ * @param points 坐标点集合，至少 1 个
+ * @param viewportWidthPx 视口宽度（像素）
+ * @param viewportHeightPx 视口高度（像素）
+ * @param paddingPx 四周预留的内边距（像素）
+ * @param minZoom 最小缩放级别
+ * @param maxZoom 最大缩放级别
+ * @return 推荐 zoom（已在 [minZoom, maxZoom] 范围内）
+ */
+double calculateFitZoomForPoints(
+    const std::vector<GeoPoint>& points,
+    double viewportWidthPx,
+    double viewportHeightPx,
+    double paddingPx,
+    int minZoom,
+    int maxZoom
+);
+
 // --- 批量地理围栏与热力图 ---
 
 /**

package/shared/cpp/tests/test_main.cpp

@@ -167,6 +167,21 @@ void testGeometryEngineExtended() {
     // Test trailing semicolon
     assert(parsePolyline("116.4074,39.9042;").size() == 1);
 
+    // 10. calculateFitZoomForPoints
+    std::vector<GeoPoint> nearby = {
+        {39.9042, 116.4074}, // Beijing
+        {39.9142, 116.4174}
+    };
+    std::vector<GeoPoint> farAway = {
+        {39.9042, 116.4074}, // Beijing
+        {31.2304, 121.4737}  // Shanghai
+    };
+    const double nearZoom = calculateFitZoomForPoints(nearby, 390, 844, 48, 3, 20);
+    const double farZoom = calculateFitZoomForPoints(farAway, 390, 844, 48, 3, 20);
+    assert(nearZoom > farZoom);
+    assert(nearZoom <= 20.0 && nearZoom >= 3.0);
+    assert(farZoom <= 20.0 && farZoom >= 3.0);
+
     std::cout << "PASSED" << std::endl;
 }