组件、配送与工具 API

JS 0.1.0-alpha.37 · 2026-10-09。来源为当前源码生成的 TypeScript 声明。优先使用 load() 返回的 Namespace；底层类的 Client 参数由绑定构造器注入，业务不需自行创建。private/protected 成员不属于公开接入。

components

import { Evented, LngLatLike } from './core';
import { Map } from './map';
import { PlaceSearch, Driving, Poi, Route } from './services';
/** Search and selection use text nodes; place names never become HTML. */
export declare class SearchBox extends Evented {
    constructor(container: string | HTMLElement, search: PlaceSearch);
    hideSuggestions(): void;
    destroy(): void;
}
export declare class LocationPicker extends Evented {
    constructor(map: Map, searchBox?: SearchBox | undefined);
    setPosition(position: LngLatLike, poi?: Poi): void;
    getPosition(): LngLatLike | undefined;
    destroy(): void;
}
export declare class RoutePanel extends Evented {
    constructor(container: string | HTMLElement, driving: Driving);
    search(origin: LngLatLike, destination: LngLatLike): Promise<Route>;
    clear(): void;
    destroy(): void;
}

delivery

import { Client, Evented } from './core';
import { Map, MapOptions } from './map';
import { DeliveryPoint, DeliverySnapshot } from './delivery-state';
export type { DeliveryPoint, DeliveryPosition, DeliverySnapshot } from './delivery-state';
export interface DeliveryTrackingOptions {
    orderId: string;
    mapOptions?: MapOptions;
    staleAfterMillis?: number;
}
/** The customer platform owns authentication and transport. This component only consumes snapshots. */
export declare class DeliveryTrackingMap extends Evented {
    readonly map: Map;
    readonly ready: Promise<void>;
    constructor(container: string | HTMLElement, client: Client, options: DeliveryTrackingOptions);
    update(snapshot: DeliverySnapshot): boolean;
    getSnapshot(): DeliverySnapshot | undefined;
    destroy(): void;
}
export interface DeliveryPlaceResult {
    position: DeliveryPoint;
    navigationPoint: DeliveryPoint;
    name: string;
    address: string;
    addressStatus: 'loading' | 'matched' | 'empty' | 'error' | 'manual';
}
export interface DeliveryPlaceOptions {
    initialPosition?: DeliveryPoint;
    name?: string;
    address?: string;
    mapOptions?: MapOptions;
}
/** Search + point selection + confirmation. No browser geolocation permission is required. */
export declare class DeliveryPlacePicker extends Evented {
    readonly map: Map;
    readonly ready: Promise<void>;
    constructor(container: string | HTMLElement, client: Client, options?: DeliveryPlaceOptions);
    setPosition(position: DeliveryPoint, name?: string, address?: string): void;
    getValue(): DeliveryPlaceResult | undefined;
    destroy(): void;
}

delivery-state

import { LngLat } from './core';
/** Explicit coordinates at third-party boundaries. No implicit coordinate conversion. */
export interface DeliveryPoint {
    latitude: number;
    longitude: number;
    coordinateSystem: 'WGS84';
}
export interface DeliveryPosition extends DeliveryPoint {
    measuredAt: number;
    accuracyMeters: number;
}
export interface DeliverySnapshot {
    orderId: string;
    sequence: number;
    status: string;
    rider: DeliveryPosition | null;
    merchant?: DeliveryPoint | null;
    destination?: DeliveryPoint | null;
    distance?: {
        meters: number;
        kind: 'route' | 'straight';
        targetName: string;
        calculatedAt: number;
    } | null;
    route?: DeliveryPoint[] | null;
}
export declare function deliveryPoint(value: DeliveryPoint): LngLat;
export declare function namedPoint(value: LngLat): DeliveryPoint;
export declare function validateSnapshot(value: DeliverySnapshot, now?: number): DeliverySnapshot;
/** A view is bound to one order. Sequence belongs to the platform, never to animation frames. */
export declare class DeliverySnapshotStore {
    readonly orderId: string;
    constructor(orderId: string);
    update(input: DeliverySnapshot, now?: number): boolean;
    snapshot(): DeliverySnapshot | undefined;
    status(): {
        status: string;
        rider: {
            latitude: number;
            longitude: number;
            coordinateSystem: 'WGS84';
            measuredAt: number;
            accuracyMeters: number;
        } | null;
        distance: {
            meters: number;
            kind: 'route' | 'straight';
            targetName: string;
            calculatedAt: number;
        } | null;
    } | undefined;
}

geometry

import { LngLatLike } from './core';
/** Offline geometry in metres and square metres. All points must share one coordinate system.
 * Segment projection is intended for local map editing, not intercontinental geodesic arcs.
 */
export declare const GeometryUtil: Readonly<{
    distance(a: LngLatLike, b: LngLatLike): number;
    distanceOfLine(line: readonly LngLatLike[]): number;
    ringArea(ring: readonly LngLatLike[]): number;
    isClockwise(ring: readonly LngLatLike[]): boolean;
    makesureClockwise(ring: readonly LngLatLike[]): [number, number][];
    makesureAntiClockwise(ring: readonly LngLatLike[]): [number, number][];
    closestOnSegment(p: LngLatLike, a: LngLatLike, b: LngLatLike): [number, number];
    closestOnLine(p: LngLatLike, line: readonly LngLatLike[]): [number, number];
    distanceToSegment(p: LngLatLike, a: LngLatLike, b: LngLatLike): number;
    distanceToLine(p: LngLatLike, line: readonly LngLatLike[]): number;
    isPointInRing(p: LngLatLike, ring: readonly LngLatLike[]): boolean;
    isPointInPolygon(p: LngLatLike, rings: readonly (readonly LngLatLike[])[]): boolean;
    isPointOnSegment(p: LngLatLike, a: LngLatLike, b: LngLatLike, t?: number): boolean;
    isPointOnLine(p: LngLatLike, line: readonly LngLatLike[], t?: number): boolean;
    isPointOnRing(p: LngLatLike, ring: readonly LngLatLike[], t?: number): boolean;
}>;

coordinates

export type CoordinateSystem = 'GCJ02' | 'WGS84' | 'BD09';
export interface CoordinatePoint {
    readonly latitude: number;
    readonly longitude: number;
    readonly coordinateSystem: CoordinateSystem;
}
export interface Wgs84Point extends CoordinatePoint {
    readonly coordinateSystem: 'WGS84';
}
export declare const MAX_COORDINATE_BATCH_SIZE = 10000;
/**
 * Offline approximate inverse. JS convenience arguments are longitude first.
 * Raw inputs must actually be GCJ-02; tagged toWgs84 is preferred for repeatable migrations.
 * Formula adapted from wandergis/coordtransform (MIT); see COORDTRANSFORM-LICENSE.txt.
 */
export declare function gcj02ToWgs84(longitude: number, latitude: number): Wgs84Point;
/** Produces a fresh WGS84 point without mutating input; WGS84 never receives a second offset. */
export declare function toWgs84(point: CoordinatePoint): Wgs84Point;
/** Atomic, ordered batch. Large migrations should use a worker or Node.js. */
export declare function toWgs84Batch(points: readonly CoordinatePoint[]): Wgs84Point[];
/** Forward conversion uses the same regional model as the inverse. Outside it, fail explicitly. */
export declare function wgs84ToGcj02(longitude: number, latitude: number): CoordinatePoint;
export declare function gcj02ToBd09(longitude: number, latitude: number): CoordinatePoint;
export declare function bd09ToGcj02(longitude: number, latitude: number): CoordinatePoint;
export declare function convert(point: CoordinatePoint, target: CoordinateSystem): CoordinatePoint;
export declare const CoordinateConverter: Readonly<{
    gcj02ToWgs84: typeof gcj02ToWgs84;
    wgs84ToGcj02: typeof wgs84ToGcj02;
    gcj02ToBd09: typeof gcj02ToBd09;
    bd09ToGcj02: typeof bd09ToGcj02;
    convert: typeof convert;
    toWgs84: typeof toWgs84;
    toWgs84Batch: typeof toWgs84Batch;
}>;

coordinate-mode

export type ApiCoordinateSystem = 'WGS84' | 'GCJ02';
/** Per-client public coordinate space. The server always receives and stores WGS84. */
export declare class CoordinateMode {
    readonly system: ApiCoordinateSystem;
    constructor(system?: ApiCoordinateSystem);
    toWgs84(value: number[]): [number, number];
    fromWgs84(value: number[]): [number, number];
    request(path: string, params: Record<string, unknown>, body: unknown): {
        params: {
            [x: string]: unknown;
        };
        body: any;
    };
    response(path: string, value: any): any;
}

diagnostics

export interface SDKLogRecord {
    readonly source: string;
    readonly code: string;
    readonly message: string;
    readonly requestId: string;
    readonly httpStatus: number;
}
export type SDKErrorLogger = (record: SDKLogRecord) => void;
/** Replace or clear the process-local log sink. Records never include keys, tokens or request payloads. */
export declare function setErrorLogger(handler?: SDKErrorLogger | null): void;
export declare function reportError(error: unknown, source: string): void;