数据源类型 Source

标准版提供 11 种数据源类型，负责数据的加载与管理。所有类型继承自核心 Source 基类。

Source（基类）

所有数据源的公共基类，来自 @gmap/core。

abstract class Source {
  readonly id: string;
  readonly type: string;
}

属性

属性	类型	说明
id	string	数据源唯一标识
type	string	数据源类型（只读）

方法

方法	参数	返回值	说明
get(key)	key: string	unknown	获取配置项
set(key, value)	key: string, value: unknown	this	设置配置项
toSpec()	—	object	导出数据源规格

---

RasterTileSource

栅格瓦片数据源。

构造函数

class RasterTileSource extends Source {
  readonly type = 'raster';

  constructor(options: RasterTileSourceOptions);
}

interface RasterTileSourceOptions {
  id?: string;
  url?: string;
  tiles?: string[];
  subdomains?: string[];
  minZoom?: number;
  maxZoom?: number;
  tileSize?: number;
  scheme?: 'xyz' | 'tms';
  attribution?: string;
}

属性

属性	类型	默认值	说明
url	string | undefined	—	URL 模板（支持 {z}, {x}, {y}, {s}）
tiles	string[] | undefined	—	瓦片 URL 列表
subdomains	string[]	[]	子域名列表
minZoom	number	0	最小缩放级别
maxZoom	number	18	最大缩放级别
tileSize	number	256	瓦片尺寸（像素）
scheme	string	'xyz'	瓦片编号方案
attribution	string	''	版权信息

示例

import { RasterTileSource } from '@gmap/standard';

const osm = new RasterTileSource({
  id: 'osm',
  url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
  subdomains: ['a', 'b', 'c'],
  minZoom: 0,
  maxZoom: 19,
  tileSize: 256,
  attribution: '© OpenStreetMap contributors',
});

---

VectorTileSource

矢量瓦片数据源。

构造函数

class VectorTileSource extends Source {
  readonly type = 'vector-tile';

  constructor(options: VectorTileSourceOptions);
}

interface VectorTileSourceOptions {
  id?: string;
  url?: string;
  tiles?: string[];
  minZoom?: number;
  maxZoom?: number;
  bounds?: Extent;
}

属性

属性	类型	默认值	说明
url	string | undefined	—	URL 模板
tiles	string[] | undefined	—	瓦片 URL 列表
minZoom	number	0	最小缩放级别
maxZoom	number	14	最大缩放级别
bounds	Extent | undefined	—	瓦片有效范围

示例

import { VectorTileSource } from '@gmap/standard';

const source = new VectorTileSource({
  id: 'mvt',
  url: 'https://tiles.example.com/{z}/{x}/{y}.pbf',
  minZoom: 0,
  maxZoom: 14,
  bounds: [-180, -85.06, 180, 85.06],
});

---

GeoJsonSource

GeoJSON 数据源，支持聚合。

构造函数

class GeoJsonSource extends Source {
  readonly type = 'geojson';

  constructor(options: GeoJsonSourceOptions);
}

interface GeoJsonSourceOptions {
  id?: string;
  data: object | string;
  cluster?: boolean;
  clusterRadius?: number;
}

属性

属性	类型	默认值	说明
data	object | string	—	GeoJSON 对象或 URL
cluster	boolean	false	是否启用聚合
clusterRadius	number	50	聚合半径（像素）

方法

方法	参数	返回值	说明
setData(data)	data: object | string	this	替换数据
getData()	—	object	获取当前数据
addFeatures(features)	features: unknown[]	this	添加要素
removeFeatures(ids)	ids: string[]	this	按 ID 移除要素

示例

import { GeoJsonSource } from '@gmap/standard';

// 从对象创建
const source = new GeoJsonSource({
  id: 'my-geojson',
  data: {
    type: 'FeatureCollection',
    features: [
      {
        type: 'Feature',
        geometry: { type: 'Point', coordinates: [116.397, 39.908] },
        properties: { name: '天安门' },
      },
    ],
  },
  cluster: true,
  clusterRadius: 80,
});

// 动态更新数据
source.setData('https://api.example.com/geojson');

// 添加/移除要素
source.addFeatures([newFeature]);
source.removeFeatures(['feature-id-1', 'feature-id-2']);

---

WmsSource

WMS 服务数据源。

构造函数

class WmsSource extends Source {
  readonly type = 'wms';

  constructor(options: WmsSourceOptions);
}

interface WmsSourceOptions {
  id?: string;
  url: string;
  layers: string;
  version?: string;
  format?: string;
  transparent?: boolean;
  params?: Record<string, string>;
}

属性

属性	类型	默认值	说明
url	string	—	WMS 服务地址
layers	string	—	图层名称（逗号分隔）
version	string	'1.1.1'	WMS 版本
format	string	'image/png'	返回格式
transparent	boolean	true	是否透明
params	Record<string, string>	{}	额外参数

示例

import { WmsSource } from '@gmap/standard';

const source = new WmsSource({
  id: 'wms-dem',
  url: 'https://geo.example.com/wms',
  layers: 'DEM,Elevation',
  version: '1.3.0',
  format: 'image/png',
  transparent: true,
  params: { SRS: 'EPSG:4326' },
});

---

WmtsSource

WMTS 服务数据源。

构造函数

class WmtsSource extends Source {
  readonly type = 'wmts';

  constructor(options: WmtsSourceOptions);

  static async fromCapabilities(url: string, layer: string): Promise<WmtsSource>;
}

interface WmtsSourceOptions {
  id?: string;
  url: string;
  layer: string;
  tileMatrixSet?: string;
  style?: string;
  format?: string;
}

属性

属性	类型	默认值	说明
url	string	—	WMTS 服务地址
layer	string	—	图层名称
tileMatrixSet	string	'GoogleMapsCompatible'	矩阵集
style	string	'default'	样式
format	string	'image/png'	返回格式

静态方法

方法	参数	返回值	说明
WmtsSource.fromCapabilities(url, layer)	url: string, layer: string	Promise<WmtsSource>	从 GetCapabilities 自动解析创建

示例

import { WmtsSource } from '@gmap/standard';

// 手动配置
const source = new WmtsSource({
  id: 'wmts-img',
  url: 'https://wmts.example.com/service',
  layer: 'imagery',
  tileMatrixSet: 'GoogleMapsCompatible',
  style: 'default',
  format: 'image/jpeg',
});

// 从 GetCapabilities 自动解析
const auto = await WmtsSource.fromCapabilities(
  'https://wmts.example.com/service?SERVICE=WMTS&REQUEST=GetCapabilities',
  'imagery',
);

---

ImageSource

图片数据源，在指定范围内显示图片。

构造函数

class ImageSource extends Source {
  readonly type = 'image';

  constructor(options: ImageSourceOptions);
}

interface ImageSourceOptions {
  id?: string;
  url: string;
  extent: Extent;
}

示例

import { ImageSource } from '@gmap/standard';

const source = new ImageSource({
  id: 'aerial',
  url: '/images/aerial-2024.jpg',
  extent: [116.0, 39.0, 117.0, 40.0],
});

---

TerrainSource

地形数据源。

构造函数

class TerrainSource extends Source {
  readonly type = 'terrain';

  constructor(options: TerrainSourceOptions);
}

interface TerrainSourceOptions {
  id?: string;
  url?: string;
  type?: 'quantized-mesh' | 'heightmap' | 'terrarium' | 'mapbox';
}

属性

属性	类型	默认值	说明
url	string | undefined	—	地形瓦片 URL
type	string	—	地形编码格式

示例

import { TerrainSource } from '@gmap/standard';

const source = new TerrainSource({
  id: 'terrain',
  url: 'https://terrain.example.com/{z}/{x}/{y}.terrain',
  type: 'quantized-mesh',
});

---

Tileset3DSource

3D Tiles 数据源。

构造函数

class Tileset3DSource extends Source {
  readonly type = '3dtiles';

  constructor(options: Tileset3DSourceOptions);
}

interface Tileset3DSourceOptions {
  id?: string;
  url: string;
  maximumScreenSpaceError?: number;
}

示例

import { Tileset3DSource } from '@gmap/standard';

const source = new Tileset3DSource({
  id: 'city-3dtiles',
  url: 'https://3dtiles.example.com/tileset.json',
  maximumScreenSpaceError: 8,
});

---

ImageOverlaySource

图片覆盖数据源，在地球表面叠加图片。

构造函数

class ImageOverlaySource extends Source {
  readonly type = 'image-overlay';

  constructor(options: ImageOverlayOptions);
}

interface ImageOverlayOptions {
  id?: string;
  url: string;
  coordinates: [Coordinate, Coordinate, Coordinate, Coordinate];
}

属性

属性	类型	说明
url	string	图片 URL
coordinates	[Coordinate, Coordinate, Coordinate, Coordinate]	四角坐标（左上、右上、右下、左下）

示例

import { ImageOverlaySource } from '@gmap/standard';

const source = new ImageOverlaySource({
  id: 'overlay',
  url: '/images/historical-map.jpg',
  coordinates: [
    [115.5, 40.5],  // 左上
    [117.5, 40.5],  // 右上
    [117.5, 38.5],  // 右下
    [115.5, 38.5],  // 左下
  ],
});

---

StreamSource

流式数据源，支持 WebSocket / SSE 实时数据推送。

构造函数

class StreamSource extends Source {
  readonly type = 'stream';

  constructor(options: StreamSourceOptions);
}

interface StreamSourceOptions {
  id?: string;
  url?: string;
  protocol?: 'websocket' | 'sse';
}

属性

属性	类型	默认值	说明
url	string | undefined	—	服务端地址
protocol	string	'websocket'	通信协议

方法

方法	参数	返回值	说明
connect()	—	void	建立连接
disconnect()	—	void	断开连接
send(data)	data: unknown	void	发送数据

示例

import { StreamSource } from '@gmap/standard';

const source = new StreamSource({
  id: 'realtime',
  url: 'wss://stream.example.com/data',
  protocol: 'websocket',
});

source.connect();
source.send({ action: 'subscribe', channel: 'traffic' });

// ... 监听数据更新 ...

source.disconnect();