atchain-mapbox-vue/types.d.ts

A Vue 3 MapBox component library with subway lines, stations, markers and polygons support. Zero dependencies except Vue 3 and Mapbox GL JS.

/**
 * MapBox 组件库类型定义
 * 为其他项目提供完整的 TypeScript 支持
 */

import type { FeatureCollection, Point, LineString, Polygon } from 'geojson'

// 重新导出核心类型
export type {
  // 数据类型
  SubwayFeatureCollection,
  StationFeatureCollection,
  GeoJsonDataType,
  DataLoadConfig,
  DataLoadState
} from './composables/useMapBoxData'

export type {
  // 地图配置
  MapConfig,
  MapEventCallbacks
} from './composables/useMapBoxCore'

export type {
  // 数据获取
  DataFetcher,
  FetchOptions
} from './utils/dataFetcher'

export type {
  // 样式配置
  StyleConfig,
  MarkerStyleConfig
} from './styles/defaultStyles'

// 组件 Props 类型定义
export interface MapBoxProps {
  /** Mapbox 访问令牌 */
  token?: string
  /** 地图样式 URL */
  mapStyle?: string
  /** 地图中心点 [经度, 纬度] */
  center?: [number, number]
  /** 缩放级别 */
  zoom?: number
  /** 地标数据文件路径 */
  jsonPath?: string
  /** 外部 CSS 类名 */
  class?: string
  /** 自定义样式对象 */
  customStyle?: Record<string, string>
  /** 样式配置 */
  styleConfig?: Partial<StyleConfig>
  /** 是否使用内置样式 */
  useBuiltinStyles?: boolean
}

export interface MapBoxMarkerProps {
  /** 标记点 ID（对应 GeoJSON 中的 id） */
  id: string
  /** 图片源路径 */
  src?: string
  /** 标记点宽度 */
  width?: string
  /** 标记点高度 */
  height?: string
  /** 外部 CSS 类名 */
  class?: string
  /** 自定义样式对象 */
  customStyle?: Record<string, string>
  /** 标记样式配置 */
  styleConfig?: Partial<MarkerStyleConfig>
}

export interface MapBoxPolygonProps {
  /** 多边形 ID（对应 GeoJSON 中的 id） */
  id: string
}

export interface MapBoxSubWayProps {
  /** 地铁线路数据文件路径 */
  subwayJsonPath?: string
  /** 渲染半径（公里） */
  subwayRenderRadiusKm?: number
}

export interface MapBoxStationsProps {
  /** 地铁站点数据文件路径 */
  stationJsonPath?: string
  /** 是否显示站点名称 */
  showStationNames?: boolean
  /** 渲染半径（公里） */
  stationRenderRadiusKm?: number
}

// GeoJSON 数据结构类型
export interface LandmarkFeature {
  type: 'Feature'
  id: string
  properties: {
    point?: string
    polygon?: string
    [key: string]: any
  }
  geometry: Point | Polygon
}

export interface SubwayLineFeature {
  type: 'Feature'
  id?: string
  properties: {
    name?: string
    ref?: string
    color?: string
    [key: string]: any
  }
  geometry: LineString
}

export interface StationFeature {
  type: 'Feature'
  id?: string
  properties: {
    name: string
    interchange?: boolean
    line_numbers?: string[]
    color?: string
    [key: string]: any
  }
  geometry: Point
}

export type LandmarkCollection = FeatureCollection<Point | Polygon, LandmarkFeature['properties']>
export type SubwayCollection = FeatureCollection<LineString, SubwayLineFeature['properties']>
export type StationCollection = FeatureCollection<Point, StationFeature['properties']>

// 组件实例类型
export interface MapBoxInstance {
  /** 地图实例 */
  mapInstance: any
  /** 地图是否已加载 */
  mapLoaded: boolean
  /** 创建地图 */
  createMap: (config: MapConfig, callbacks?: MapEventCallbacks) => any
  /** 清理地图实例 */
  clearMapInstance: () => void
}

// 事件回调类型
export interface InteractionCallbacks {
  /** 标记点点击回调 */
  onMarkerClick?: (feature: LandmarkFeature) => void
  /** 多边形点击回调 */
  onPolygonClick?: (feature: LandmarkFeature) => void
  /** 标记点悬停回调 */
  onMarkerHover?: (feature: LandmarkFeature, isEnter: boolean) => void
  /** 多边形悬停回调 */
  onPolygonHover?: (feature: LandmarkFeature, isEnter: boolean) => void
}

// 配置选项类型
export interface MapBoxConfig {
  /** 默认 Mapbox token */
  defaultToken?: string
  /** 默认地图样式 */
  defaultStyle?: string
  /** 默认中心点 */
  defaultCenter?: [number, number]
  /** 默认缩放级别 */
  defaultZoom?: number
  /** 是否启用调试模式 */
  debug?: boolean
}

// 工具函数类型
export interface MapBoxUtils {
  /** 计算两点间距离 */
  haversineDistanceKm: (coordA: [number, number], coordB: [number, number]) => number
  /** 检查坐标是否在范围内 */
  isWithinRadius: (coord: [number, number], center: [number, number], radiusKm: number) => boolean
  /** 延时函数 */
  delay: (ms: number) => Promise<void>
  /** 安全 JSON 解析 */
  safeJsonParse: (jsonString: string, fallback?: any) => any
  /** 深度合并对象 */
  deepMerge: <T>(target: T, source: Partial<T>) => T
}

// 常量类型
export interface MapBoxConstants {
  /** 地球半径（公里） */
  EARTH_RADIUS_KM: number
  /** 地铁线路颜色配置 */
  SUBWAY_LINE_COLORS: Record<string, string>
  /** 默认样式配置 */
  DEFAULT_STYLES: any
  /** 动画配置 */
  ANIMATION_CONFIG: any
}

// 模块导出类型
declare module '@/components/mapbox' {
  export const MapBox: any
  export const MapBoxMarker: any
  export const MapBoxPolygon: any
  export const MapBoxSubWay: any
  export const MapBoxStations: any
  
  export const useMapBox: () => any
  export const useMapBoxCore: () => any
  export const useMapBoxData: () => any
  export const useMapBoxLayers: () => any
  
  export const defaultDataFetcher: DataFetcher
  export * from './composables/useMapBoxUtils'
  export * from './composables/useMapBoxConstants'
}