@baidumap/vue-bmap 1.0.0

package/dist/drivers/types.d.ts

@@ -0,0 +1,359 @@
+import { BMapVersion, Capability, LayerKind, LoadKeyComponents, UnsupportedBehavior, Bounds, ControlHandle, LayerHandle, MapHandle, OverlayHandle, Pixel, Point, ServiceHandle, Size } from '../types';
+
+/**
+ * BMapDriver 接口 — 完整覆盖 bmap-jsapi-dts 中 Map 类的全部公共方法。
+ *
+ * 分类（按 dts src/core/Map.d.ts 顺序）：
+ * 1. Map 工厂 / 销毁
+ * 2. 交互开关（enable/disable 系列）
+ * 3. 视角控制（heading / tilt / rotate）
+ * 4. 缩放级别（zoom / minZoom / maxZoom）
+ * 5. 自动 resize
+ * 6. 显示配置（displayOptions / setOptions）
+ * 7. 容器信息（size / container）
+ * 8. 坐标转换（point/pixel/mercator）
+ * 9. 地图状态查询
+ * 10. 地图标注 / Spots / 区域
+ * 11. 视野控制（center / zoom / pan / flyTo / viewport）
+ * 12. 地图类型
+ * 13. 控件 / 右键菜单
+ * 14. 覆盖物
+ * 15. 图层（addLayer / addNormalLayer / addGeoJSONLayer / addDistrictLayer / traffic / tileLayer）
+ * 16. 信息窗口
+ * 17. 样式 / 主题
+ * 18. 视角动画
+ * 19. 截图 / 版权
+ * 20. 地球模式 / 室内 / 街景 / 语言 / 私有 / 焦点遮罩 / 自定义 HTML 图层 / 停车场等
+ * 21. 3.0-only（setPanorama / addHotspot / setCurrentCity / highResolution 等）
+ * 22. Overlay/Control/Layer/Service/ContextMenu/Panorama 工厂与操作
+ * 23. 事件
+ *
+ * 关键约定（DESIGN.md §12）：
+ * - 工厂方法：不支持时返回 null 或 isNull: true 的 ServiceHandle。
+ * - 命令方法：签名 void，不支持时按 unsupportedBehavior（throw / warn+noop / ignore+noop）。
+ * - Getter：签名与 dts 一致；不支持时按 behavior：throw / warn+NaN或合理兜底 / ignore。
+ * - **绝不污染原返回类型为 T | undefined**。
+ */
+export interface BMapDriver {
+    readonly version: BMapVersion;
+    readonly rawSDK: unknown;
+    readonly capabilities: ReadonlySet<Capability>;
+    readonly unsupportedBehavior: UnsupportedBehavior;
+    createMap(container: HTMLElement, options: unknown): MapHandle;
+    destroyMap(handle: MapHandle): void;
+    enableDragging(map: MapHandle): void;
+    disableDragging(map: MapHandle): void;
+    enableInertialDragging(map: MapHandle): void;
+    disableInertialDragging(map: MapHandle): void;
+    enableScrollWheelZoom(map: MapHandle): void;
+    disableScrollWheelZoom(map: MapHandle): void;
+    enableContinuousZoom(map: MapHandle): void;
+    disableContinuousZoom(map: MapHandle): void;
+    enableResizeOnCenter(map: MapHandle): void;
+    disableResizeOnCenter(map: MapHandle): void;
+    enableDoubleClickZoom(map: MapHandle): void;
+    disableDoubleClickZoom(map: MapHandle): void;
+    enableKeyboard(map: MapHandle): void;
+    disableKeyboard(map: MapHandle): void;
+    enablePinchToZoom(map: MapHandle): void;
+    disablePinchToZoom(map: MapHandle): void;
+    enableRotate(map: MapHandle): void;
+    disableRotate(map: MapHandle): void;
+    enableRotateGestures(map: MapHandle): void;
+    disableRotateGestures(map: MapHandle): void;
+    enableTilt(map: MapHandle): void;
+    disableTilt(map: MapHandle): void;
+    enableTiltGestures(map: MapHandle): void;
+    disableTiltGestures(map: MapHandle): void;
+    enableAutoResize(map: MapHandle): void;
+    disableAutoResize(map: MapHandle): void;
+    /** 开启点击底图标注后自动展示信息窗口，同时会开启底图标注点击（4.0+） */
+    enableIconInfoWindow(map: MapHandle): void;
+    disableIconInfoWindow(map: MapHandle): void;
+    /** 启用首选语言，language 使用 BMAP_LANGUAGE_* 常量（4.0+） */
+    enablePreferredLanguage(map: MapHandle, language?: string): void;
+    disablePreferredLanguage(map: MapHandle): void;
+    setHeading(map: MapHandle, heading: number, options?: unknown): void;
+    getHeading(map: MapHandle): number;
+    setTilt(map: MapHandle, tilt: number, options?: unknown): void;
+    getTilt(map: MapHandle): number;
+    getCurrentMaxTilt(map: MapHandle): number;
+    setMinZoom(map: MapHandle, zoom: number): void;
+    setMaxZoom(map: MapHandle, zoom: number): void;
+    getMinZoom(map: MapHandle): number;
+    getMaxZoom(map: MapHandle): number;
+    checkResize(map: MapHandle): void;
+    resize(map: MapHandle): void;
+    setSize(map: MapHandle, size: {
+        width: number;
+        height: number;
+    }): void;
+    zoomTo(map: MapHandle, level: number, point?: unknown): void;
+    setDisplayOptions(map: MapHandle, options: unknown): void;
+    setOptions(map: MapHandle, options: unknown): void;
+    getSize(map: MapHandle): Size;
+    getContainerSize(map: MapHandle): Size;
+    getZoomUnits(map: MapHandle): number;
+    getContainer(map: MapHandle): HTMLElement;
+    pixelToPoint(map: MapHandle, pixel: Pixel, options?: unknown): Point;
+    pointToPixel(map: MapHandle, point: Point, options?: unknown): Pixel;
+    lnglatToMercator(map: MapHandle, lng: number, lat: number): [number, number];
+    mercatorToLnglat(map: MapHandle, mcLng: number, mcLat: number): [number, number];
+    pointToOverlayPixel(map: MapHandle, point: Point, options?: unknown): Pixel;
+    overlayPixelToPoint(map: MapHandle, pixel: Pixel, options?: unknown): Point;
+    getDistance(map: MapHandle, start: Point, end: Point): number;
+    isLoaded(map: MapHandle): boolean;
+    getCoordType(map: MapHandle): string;
+    getMapTypeId(map: MapHandle): string;
+    getMapCoordType(map: MapHandle): string;
+    getMapStyleId(map: MapHandle): string;
+    getAreaStyleId(map: MapHandle): string;
+    getRenderType(map: MapHandle): string;
+    isCanvasMap(map: MapHandle): boolean;
+    getProjection(map: MapHandle): unknown;
+    getSolarInfo(map: MapHandle, date: Date): unknown;
+    getTileId(map: MapHandle, point: Point, level: number): string;
+    getPoiByUid(map: MapHandle, uid: string, callback: (poi: unknown) => void): void;
+    getPanes(map: MapHandle): unknown;
+    getInfoWindow(map: MapHandle): OverlayHandle | null;
+    addSpots(map: MapHandle, spots: unknown[], options?: unknown): string;
+    getSpots(map: MapHandle, id: string): unknown[];
+    removeSpots(map: MapHandle, id: string): void;
+    clearSpots(map: MapHandle): void;
+    resetSpotStatus(map: MapHandle): void;
+    hightlightSpotByUid(map: MapHandle, uid: string, tilePosStr: string): void;
+    addAreaSpot(map: MapHandle, areaSpot: number[], options?: unknown): string;
+    getAreaSpot(map: MapHandle, id: string): number[];
+    removeAreaSpot(map: MapHandle, id: string): void;
+    clearAreaSpots(map: MapHandle): void;
+    clearLabels(map: MapHandle): void;
+    addMapLabels(map: MapHandle, labels: unknown[]): string[];
+    removeMapLabels(map: MapHandle, labelUids: string[]): void;
+    getIconByClickPosition(map: MapHandle, clickPosition: Pixel): unknown | null;
+    setBounds(map: MapHandle, bounds: Bounds): void;
+    centerAndZoom(map: MapHandle, center: Point | string, zoom?: number, options?: unknown): void;
+    panTo(map: MapHandle, center: Point, options?: unknown): void;
+    panBy(map: MapHandle, x: number, y: number, options?: unknown): void;
+    flyTo(map: MapHandle, center: Point, zoom: number, options?: unknown): void;
+    reset(map: MapHandle): void;
+    setCenter(map: MapHandle, center: Point | string, options?: unknown): void;
+    getCenter(map: MapHandle): Point;
+    setViewport(map: MapHandle, view: Point[] | Bounds, viewportOptions?: unknown): void;
+    getViewport(map: MapHandle, view: Point[] | Bounds, viewportOptions?: unknown): unknown;
+    setZoom(map: MapHandle, zoom: number, options?: unknown): void;
+    getZoom(map: MapHandle): number;
+    zoomIn(map: MapHandle, zoomCenter?: Point): void;
+    zoomOut(map: MapHandle, zoomCenter?: Point): void;
+    getBounds(map: MapHandle): Bounds;
+    restrictBounds(map: MapHandle, bounds: Bounds | null): void;
+    setMapType(map: MapHandle, mapTypeId: string | number): void;
+    getMapType(map: MapHandle): string;
+    addControl(map: MapHandle, control: ControlHandle): void;
+    removeControl(map: MapHandle, control: ControlHandle): void;
+    setControlOptions(control: ControlHandle, options: unknown): void;
+    showControl(control: ControlHandle): void;
+    hideControl(control: ControlHandle): void;
+    addContextMenu(map: MapHandle | OverlayHandle, menu: OverlayHandle): void;
+    removeContextMenu(map: MapHandle | OverlayHandle, menu: OverlayHandle): void;
+    addOverlay(map: MapHandle, overlay: OverlayHandle): void;
+    removeOverlay(map: MapHandle, overlay: OverlayHandle): void;
+    clearOverlays(map: MapHandle): void;
+    getOverlays(map: MapHandle): OverlayHandle[];
+    /** 把 Label 挂到 Marker 上（marker.setLabel），随 marker 定位/拖拽跟随（4.0/GL 与 3.0 均支持） */
+    setMarkerLabel(marker: OverlayHandle, label: OverlayHandle): void;
+    /** 解除 Marker 上的 Label（SDK 无官方清除 API，兜底隐藏并清引用） */
+    removeMarkerLabel(marker: OverlayHandle, label: OverlayHandle): void;
+    addLayer(map: MapHandle, layer: LayerHandle): void;
+    removeLayer(map: MapHandle, layer: LayerHandle): void;
+    addTileLayer(map: MapHandle, layer: LayerHandle): void;
+    removeTileLayer(map: MapHandle, layer: LayerHandle): void;
+    getTileLayer(map: MapHandle, mapType: string): LayerHandle | null;
+    addGeoJSONLayer(map: MapHandle, layer: LayerHandle): void;
+    removeGeoJSONLayer(map: MapHandle, layer: LayerHandle): void;
+    addDistrictLayer(map: MapHandle, layer: LayerHandle): void;
+    removeDistrictLayer(map: MapHandle, layer: LayerHandle): void;
+    addNormalLayer(map: MapHandle, layer: LayerHandle): void;
+    removeNormalLayer(map: MapHandle, layer: LayerHandle): void;
+    setTrafficOn(map: MapHandle): void;
+    setTrafficOff(map: MapHandle): void;
+    showOverlayContainer(map: MapHandle): void;
+    hideOverlayContainer(map: MapHandle): void;
+    openInfoWindow(map: MapHandle | OverlayHandle, iw: OverlayHandle, point?: Point): void;
+    closeInfoWindow(map: MapHandle | OverlayHandle): void;
+    openSimpleInfoWindow(map: MapHandle, iw: OverlayHandle, point: Point): void;
+    closeSimpleInfoWindow(map: MapHandle): void;
+    setMapStyle(map: MapHandle, config: unknown): void;
+    setMapStyleV2(map: MapHandle, options: unknown): void;
+    setTheme(map: MapHandle, theme: string, customVars?: Record<string, string>): void;
+    setCopyrightOffset(map: MapHandle, logo: unknown, cpy: unknown): void;
+    setDefaultCursor(map: MapHandle, cursor: string): void;
+    getDefaultCursor(map: MapHandle): string;
+    setDraggingCursor(map: MapHandle, cursor: string): void;
+    getDraggingCursor(map: MapHandle): string;
+    setOverlayMoveCursor(map: MapHandle, cursor: string): void;
+    startViewAnimation(map: MapHandle, viewAnimation: unknown): number;
+    pauseViewAnimation(map: MapHandle, viewAnimation?: unknown): void;
+    continueViewAnimation(map: MapHandle, viewAnimation?: unknown): void;
+    cancelViewAnimation(map: MapHandle, viewAnimation?: unknown): void;
+    getScreenshot(map: MapHandle): string;
+    isSupportEarth(map: MapHandle): boolean;
+    getEarth(map: MapHandle): unknown;
+    showEarthBoundary(map: MapHandle): void;
+    hideEarthBoundary(map: MapHandle): void;
+    setEarthMaxZoom(map: MapHandle, zoom: number): void;
+    setEarthMinZoom(map: MapHandle, zoom: number): void;
+    showIndoor(map: MapHandle, uid: string, floor: number): void;
+    setIndoor(map: MapHandle, uid: string, floor: number): void;
+    getIndoorInfo(map: MapHandle): unknown | null;
+    initIndoorLayer(map: MapHandle, opts?: unknown): unknown;
+    setNormalMapDisplay(map: MapHandle, display: boolean): void;
+    getVectorContainer(map: MapHandle): unknown;
+    showStreetLayer(map: MapHandle, show: boolean): void;
+    hideStreetLayer(map: MapHandle): void;
+    isStreetLayerShow(map: MapHandle): boolean;
+    showVectorStreetLayer(map: MapHandle): void;
+    hideVectorStreetLayer(map: MapHandle): void;
+    getLanguage(map: MapHandle): string;
+    changeLanguage(map: MapHandle, language: string): void;
+    enablePreferredLanguage(map: MapHandle, language: string): void;
+    disablePreferredLanguage(map: MapHandle): void;
+    setLock(map: MapHandle, lock: boolean): void;
+    setPrivateRegions(map: MapHandle, regions: unknown[]): void;
+    getPrivateRegions(map: MapHandle): unknown[];
+    setPrivateStatus(map: MapHandle, isOn: boolean): void;
+    getPrivateStatus(map: MapHandle): boolean;
+    setCustomArea(map: MapHandle, config: unknown): void;
+    addFocusMask(map: MapHandle, mask: unknown): void;
+    removeFocusMask(map: MapHandle, mask: unknown): void;
+    clearFocusMasks(map: MapHandle): void;
+    addCustomHtmlLayer(map: MapHandle, layer: unknown): void;
+    removeCustomHtmlLayer(map: MapHandle, layer: unknown): void;
+    addParkingSpot(map: MapHandle, layer: unknown): void;
+    removeParkingSpot(map: MapHandle, parking: unknown): void;
+    enableMapClick(map: MapHandle): void;
+    disableMapClick(map: MapHandle): void;
+    enable3DBuilding(map: MapHandle): void;
+    disable3DBuilding(map: MapHandle): void;
+    setPanorama(map: MapHandle, pano: unknown): void;
+    getPanorama(map: MapHandle): unknown;
+    setCurrentCity(map: MapHandle, city: string): void;
+    highResolutionEnabled(map: MapHandle): boolean;
+    addHotspot(map: MapHandle, hotspot: OverlayHandle): void;
+    removeHotspot(map: MapHandle, hotspot: OverlayHandle): void;
+    clearHotspots(map: MapHandle): void;
+    createMarker(position: Point, options?: unknown): OverlayHandle | null;
+    createLabel(content: unknown, options?: unknown): OverlayHandle | null;
+    createPolyline(path: Point[], options?: unknown): OverlayHandle | null;
+    createPolygon(path: Point[] | Point[][], options?: unknown): OverlayHandle | null;
+    createCircle(center: Point, radius: number, options?: unknown): OverlayHandle | null;
+    createRectangle(bounds: Bounds, options?: unknown): OverlayHandle | null;
+    /** controlPoints 为 SDK 必填位置参数：每两个路径点之间 1~2 个控制点，组数 = path.length - 1 */
+    createBezierCurve(path: Point[], controlPoints: Point[][], options?: unknown): OverlayHandle | null;
+    /**
+     * altitude 为 SDK 必填位置参数（棱柱高度，米）。
+     * path 支持单坐标串 Point[] 或多坐标串 Point[][]（后者仅 constructor 支持，setPath 只接受单串）。
+     */
+    createPrism(path: Point[] | Point[][], altitude: number, options?: unknown): OverlayHandle | null;
+    createMarker3D(position: Point, height: number, options?: unknown): OverlayHandle | null;
+    createGroundOverlay(bounds: Bounds, options?: unknown): OverlayHandle | null;
+    createGroundPoint(point: Point, options?: unknown): OverlayHandle | null;
+    createPointCollection(points: Point[], options?: unknown): OverlayHandle | null;
+    createInfoWindow(content: unknown, options?: unknown): OverlayHandle | null;
+    createSymbol(path: unknown, options?: unknown): OverlayHandle | null;
+    createIcon(url: string, size: Size, options?: unknown): OverlayHandle | null;
+    createIconSequence(symbol?: OverlayHandle, offset?: unknown, repeat?: string, fixedRotation?: boolean): OverlayHandle | null;
+    createHotspot(position: Point, options?: unknown): OverlayHandle | null;
+    createCustomOverlay(domCreate?: Function, options?: unknown): OverlayHandle | null;
+    setOverlayPosition(overlay: OverlayHandle, position: Point): void;
+    setOverlayPath(overlay: OverlayHandle, path: Point[] | Point[][]): void;
+    setOverlayOptions(overlay: OverlayHandle, options: unknown): void;
+    /**
+     * 读取 overlay 当前 option 的原始值快照，用于 prop 从有值变回 undefined 时还原。
+     * 只返回「SDK 提供 getter 且当前有值」的 key，其余 key 直接缺席——调用方据此判断哪些还原不了。
+     * 返回的是 SDK 原始对象（raw Icon / raw Size 等），只应交给 restoreOverlayOptions 写回。
+     */
+    snapshotOverlayOptions(overlay: OverlayHandle, keys: string[]): Record<string, unknown>;
+    /**
+     * 把 snapshotOverlayOptions 取到的原始值写回 overlay。
+     * 返回未能还原的 key（SDK 无对应 setter 或调用抛错），调用方据此告警。
+     */
+    restoreOverlayOptions(overlay: OverlayHandle, snapshot: Record<string, unknown>): string[];
+    /** Overlay 基类 show() — 显示覆盖物 */
+    showOverlay(overlay: OverlayHandle): void;
+    /** Overlay 基类 hide() — 隐藏覆盖物 */
+    hideOverlay(overlay: OverlayHandle): void;
+    /** Marker.openPlaceDetail — 打开地点详情窗口（仅 v4+） */
+    openPlaceDetail(marker: OverlayHandle, placeDetail: ServiceHandle): void;
+    /** Marker.closePlaceDetail — 关闭地点详情窗口（仅 v4+） */
+    closePlaceDetail(marker: OverlayHandle): void;
+    createNavigationControl(options?: unknown): ControlHandle | null;
+    createNavigationControl3D(options?: unknown): ControlHandle | null;
+    createScaleControl(options?: unknown): ControlHandle | null;
+    createOverviewMapControl(options?: unknown): ControlHandle | null;
+    createMapTypeControl(options?: unknown): ControlHandle | null;
+    createCopyrightControl(options?: unknown): ControlHandle | null;
+    createGeolocationControl(options?: unknown): ControlHandle | null;
+    createPanoramaControl(options?: unknown): ControlHandle | null;
+    createZoomControl(options?: unknown): ControlHandle | null;
+    createCityListControl(options?: unknown): ControlHandle | null;
+    createLocationControl(options?: unknown): ControlHandle | null;
+    createLogoControl(options?: unknown): ControlHandle | null;
+    createControl(options?: unknown): ControlHandle | null;
+    /** 自定义控件：domCreate 返回的 DOM 会被 initialize(map) 挂到地图容器上 */
+    createCustomControl(domCreate: () => HTMLElement, options?: unknown): ControlHandle | null;
+    createTileLayer(options?: unknown): LayerHandle | null;
+    createNormalLayer(options?: unknown): LayerHandle | null;
+    createGeoJSONLayer(options?: unknown): LayerHandle | null;
+    createDistrictLayer(options?: unknown): LayerHandle | null;
+    createTrafficLayer(options?: unknown): LayerHandle | null;
+    createCustomLayer(options?: unknown): LayerHandle | null;
+    createCanvasLayer(options?: unknown): LayerHandle | null;
+    createRasterTileLayer(options?: unknown): LayerHandle | null;
+    createWMSLayer(options?: unknown): LayerHandle | null;
+    createWMTSLayer(options?: unknown): LayerHandle | null;
+    createXYZLayer(options?: unknown): LayerHandle | null;
+    createMVTLayer(options?: unknown): LayerHandle | null;
+    createFeatureLayer(options?: unknown): LayerHandle | null;
+    createFillLayer(options?: unknown): LayerHandle | null;
+    createDOMLayer(options?: unknown): LayerHandle | null;
+    createPointIconLayer(options?: unknown): LayerHandle | null;
+    createPointShapeLayer(options?: unknown): LayerHandle | null;
+    createPanoramaCoverageLayer(options?: unknown): LayerHandle | null;
+    createLineLayer(options?: unknown): LayerHandle | null;
+    createPixelLayer(options?: unknown): LayerHandle | null;
+    createBaiduLayer(options?: unknown): LayerHandle | null;
+    createThreeLayer(options?: unknown): LayerHandle | null;
+    createContextMenu(options?: unknown): OverlayHandle | null;
+    createMenuItem(text: string, callback: (point?: {
+        lng: number;
+        lat: number;
+    }) => void, options?: unknown): OverlayHandle | null;
+    addMenuItem(menu: OverlayHandle, item: OverlayHandle, insertIndex?: number): void;
+    removeMenuItem(menu: OverlayHandle, item: OverlayHandle): void;
+    createPanorama(container: HTMLElement, options?: unknown): MapHandle | null;
+    createPanoramaLabel(options?: unknown): OverlayHandle | null;
+    destroyPanorama(handle: MapHandle): void;
+    createLocalSearch(location: unknown, options?: unknown): ServiceHandle;
+    createGeocoder(): ServiceHandle;
+    createDrivingRoute(options?: unknown): ServiceHandle;
+    createWalkingRoute(options?: unknown): ServiceHandle;
+    createRidingRoute(options?: unknown): ServiceHandle;
+    createTransitRoute(options?: unknown): ServiceHandle;
+    createBusLineSearch(options?: unknown): ServiceHandle;
+    createAutocomplete(options?: unknown): ServiceHandle;
+    createBoundary(): ServiceHandle;
+    createGeolocation(options?: unknown): ServiceHandle;
+    createLocalCity(options?: unknown): ServiceHandle;
+    createPlaceDetail(options?: unknown): ServiceHandle;
+    createConvertor(): ServiceHandle;
+    createPanoramaService(): ServiceHandle;
+    createTruckRoute(options?: unknown): ServiceHandle;
+    searchService(service: ServiceHandle, query: unknown, callbacks: {
+        onSuccess?: (data: unknown) => void;
+        onError?: (err: Error) => void;
+    }): () => void;
+    getServiceResults(service: ServiceHandle): unknown;
+    addEventListener(target: MapHandle | OverlayHandle | ControlHandle | LayerHandle, type: string, handler: (raw: unknown) => void): () => void;
+    removeEventListener(target: MapHandle | OverlayHandle | ControlHandle | LayerHandle, type: string, handler: (raw: unknown) => void): void;
+}
+export type { LoadKeyComponents, LayerKind };

package/dist/drivers/unsupported.d.ts

@@ -0,0 +1,66 @@
+import { BMapVersion, Capability, UnsupportedBehavior } from '../types';
+
+/**
+ * 不支持能力异常。
+ * 在 throw 策略下抛此异常；用户可用 try/catch 或 ErrorBoundary 捕获。
+ */
+export declare class UnsupportedCapabilityError extends Error {
+    capability: Capability;
+    version: BMapVersion;
+    constructor(capability: Capability, version: BMapVersion);
+}
+/**
+ * 报告不支持的能力。根据 behavior：
+ * - 'throw'：抛 UnsupportedCapabilityError
+ * - 'warn'：dev console.warn，正常返回（调用方返回兜底值）
+ * - 'ignore'：静默，正常返回（调用方返回兜底值）
+ *
+ * 只用于「确实不支持」：能力矩阵里没有，或原生成员不存在。
+ * 「成员存在但执行时抛错」请走 reportCallFailure，不要塞到这里 ——
+ * 那会把真实的运行时错误说成版本问题，排障时反而被误导。
+ *
+ * 用于命令（返回 void）：throw 抛错；warn/ignore noop。
+ */
+export declare function reportUnsupported(capability: Capability, version: BMapVersion, behavior: UnsupportedBehavior): void;
+/**
+ * 判断一个错误是不是「成员根本不存在」。
+ *
+ * 依据的是 JS 引擎自己产出的 TypeError 文案（`x is not a function` /
+ * `x is not a constructor`），V8/JSC/SpiderMonkey 都是这套措辞；不是匹配 SDK
+ * 的字符串，所以 SDK 压缩混淆换版本也不会失效。判错的最坏后果只是日志分类不准，
+ * 不会引入新的失败路径。
+ */
+export declare function isMissingMember(e: unknown): boolean;
+/**
+ * 调用原生 API 失败时的统一出口，按错误性质分流：
+ * - 成员不存在 → reportUnsupported，语义是「这个版本没这能力」
+ * - 成员存在但抛错（参数非法、SDK 内部空指针、销毁竞态……）→ debugWarn 带上原始错误
+ *
+ * 后者刻意不抛：behavior='throw' 的语义是「能力不支持时抛」，而且这些 catch 大多在
+ * React effect / cleanup 里，抛出会连带整棵树。
+ */
+export declare function reportCallFailure(capability: Capability, version: BMapVersion, behavior: UnsupportedBehavior, error: unknown): void;
+/**
+ * Getter 不支持时的兜底。先 reportUnsupported，然后返回类型断言的兜底值。
+ * - number 类型建议返回 NaN（业务可用 Number.isNaN 检测）
+ * - 对象类型字段为 undefined
+ *
+ * 调用方需根据语义传 fallback：
+ *   return unsupportedValue('getHeading', '3.0', behavior, NaN);
+ */
+export declare function unsupportedValue<T>(capability: Capability, version: BMapVersion, behavior: UnsupportedBehavior, fallback: T): T;
+/**
+ * tryOp 工具：在 throw 模式下捕获 UnsupportedCapabilityError，转成 Result。
+ * 业务想优雅处理时使用：
+ *   const r = tryOp(() => mapRef.flyTo(...));
+ *   if (!r.ok) { /* fallback *\/ }
+ */
+export type OpResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: 'unsupported';
+    capability: Capability;
+};
+export declare function tryOp<T>(fn: () => T): OpResult<T>;

package/dist/drivers/v3Driver.d.ts

@@ -0,0 +1,13 @@
+import { UnsupportedBehavior } from '../types';
+import { BMapDriver } from './types';
+
+/**
+ * v3 Driver — 3.0 适配。
+ * - 复用 v4 driver 的通用骨架
+ * - 3.0-only 方法真实实现
+ * - 4.0-only 方法走 unsupported
+ * - capabilities 用 v3 矩阵（与 v4 区分）
+ */
+export declare function createV3Driver(rawSDK: any, opts: {
+    unsupportedBehavior: UnsupportedBehavior;
+}): BMapDriver;

package/dist/drivers/v4Driver.d.ts

@@ -0,0 +1,15 @@
+import { BMapVersion, UnsupportedBehavior } from '../types';
+import { BMapDriver } from './types';
+
+/**
+ * v4 Driver — 4.0 baseline 实现。
+ * 直接 1:1 调用 window.BMap 上的类与方法；缺的能力（3.0-only）按 unsupportedBehavior 处理。
+ *
+ * opts.version 只影响日志文案（v3Driver 复用本实现，
+ * 不传的话 3.0 会话里也会打成 "JSAPI 4.0"）。
+ * capabilities 仍固定取 4.0 矩阵：v3Driver 依赖这一点绕过能力检查直建 v3-only 的类。
+ */
+export declare function createV4Driver(rawSDK: any, opts: {
+    unsupportedBehavior: UnsupportedBehavior;
+    version?: BMapVersion;
+}): BMapDriver;