控件类型 Control

标准版提供 19 种控件，覆盖地图操作、信息展示、图层切换等所有交互场景。所有类型继承自抽象基类 Control。

Control（抽象基类）

所有控件的公共基类。

abstract class Control {
  readonly id: string;
  position: string;

  constructor(options: ControlOptions);

  get visible(): boolean;
  setPosition(p: string): this;
  setVisible(v: boolean): this;
  abstract getElement(): HTMLElement;
  remove(): void;
}

interface ControlOptions {
  id?: string;
  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center';
}

属性

属性	类型	默认值	说明
`id`	`string`	自动生成	控件唯一标识
`position`	`string`	`'top-right'`	控件位置
`visible`	`boolean`	`true`	是否可见（getter）

方法

方法	参数	返回值	说明
`setPosition(p)`	`p: string`	`this`	设置位置
`setVisible(v)`	`v: boolean`	`this`	设置可见性
`getElement()`	—	`HTMLElement`	获取 DOM 元素（抽象方法）
`remove()`	—	`void`	移除控件

ZoomControl

缩放控件。

构造函数

class ZoomControl extends Control {
  constructor(options?: ControlOptions & {
    zoomInText?: string;
    zoomOutText?: string;
  });
}

属性

属性	类型	默认值	说明
`zoomInText`	`string`	`'+'`	放大按钮文本
`zoomOutText`	`string`	`'-'`	缩小按钮文本

示例

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

const zoom = new ZoomControl({ position: 'top-left' });
map.addControl(zoom);

CompassControl

指南针控件。

构造函数

class CompassControl extends Control {
  constructor(options?: ControlOptions);
}

示例

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

const compass = new CompassControl({ position: 'top-right' });
map.addControl(compass);

ScaleBarControl

比例尺控件。

构造函数

class ScaleBarControl extends Control {
  constructor(options?: ControlOptions & {
    unit?: 'metric' | 'imperial';
    maxWidth?: number;
  });
}

属性

属性	类型	默认值	说明
`unit`	`string`	`'metric'`	单位制
`maxWidth`	`number`	`100`	最大宽度（像素）

示例

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

const scale = new ScaleBarControl({
  position: 'bottom-left',
  unit: 'metric',
  maxWidth: 150,
});
map.addControl(scale);

AttributionControl

版权信息控件。

构造函数

class AttributionControl extends Control {
  constructor(options?: ControlOptions & {
    compact?: boolean;
  });
}

属性

属性	类型	默认值	说明
`compact`	`boolean`	`false`	是否紧凑显示

示例

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

const attr = new AttributionControl({
  position: 'bottom-right',
  compact: true,
});
map.addControl(attr);

LayerSwitcherControl

图层切换控件。

构造函数

class LayerSwitcherControl extends Control {
  constructor(options?: ControlOptions & {
    layers?: Array<{ id: string; name: string }>;
    collapsed?: boolean;
  });
}

属性

属性	类型	默认值	说明
`layers`	`Array<{id, name}>`	`[]`	图层列表
`collapsed`	`boolean`	`true`	是否折叠

示例

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

const switcher = new LayerSwitcherControl({
  position: 'top-right',
  layers: [
    { id: 'satellite', name: '卫星影像' },
    { id: 'terrain', name: '地形图' },
    { id: 'roads', name: '路网' },
  ],
  collapsed: false,
});
map.addControl(switcher);

BasemapSwitcherControl

底图切换控件。

构造函数

class BasemapSwitcherControl extends Control {
  constructor(options?: ControlOptions & {
    basemaps?: Array<{ id: string; name: string; url: string }>;
    collapsed?: boolean;
  });
}

示例

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

const basemap = new BasemapSwitcherControl({
  position: 'top-right',
  basemaps: [
    { id: 'osm', name: 'OpenStreetMap', url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png' },
    { id: 'satellite', name: '卫星影像', url: 'https://server/aerial/{z}/{x}/{y}.jpg' },
  ],
  collapsed: true,
});
map.addControl(basemap);

FullscreenControl

全屏控件。

构造函数

class FullscreenControl extends Control {
  constructor(options?: ControlOptions);
}

示例

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

const fullscreen = new FullscreenControl({ position: 'top-right' });
map.addControl(fullscreen);

GeolocationControl

定位控件。

构造函数

class GeolocationControl extends Control {
  constructor(options?: ControlOptions & {
    enableHighAccuracy?: boolean;
    timeout?: number;
    maximumAge?: number;
    track?: boolean;
  });
}

属性

属性	类型	默认值	说明
`enableHighAccuracy`	`boolean`	`false`	高精度定位
`timeout`	`number`	`60000`	超时时间（毫秒）
`maximumAge`	`number`	`0`	最大缓存时间（毫秒）
`track`	`boolean`	`false`	是否持续追踪

示例

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

const geoloc = new GeolocationControl({
  position: 'top-left',
  enableHighAccuracy: true,
  track: true,
});
map.addControl(geoloc);

NavigationControl

导航控件（3D 视角控制）。

构造函数

class NavigationControl extends Control {
  constructor(options?: ControlOptions & {
    showZoom?: boolean;
    showCompass?: boolean;
    visualizePitch?: boolean;
  });
}

属性

属性	类型	默认值	说明
`showZoom`	`boolean`	`true`	显示缩放按钮
`showCompass`	`boolean`	`true`	显示指南针
`visualizePitch`	`boolean`	`false`	可视化俯仰角

示例

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

const nav = new NavigationControl({
  position: 'top-left',
  showZoom: true,
  showCompass: true,
  visualizePitch: true,
});
map.addControl(nav);

InfoPanelControl

信息面板控件。

构造函数

class InfoPanelControl extends Control {
  constructor(options?: ControlOptions & {
    content?: string | HTMLElement;
    title?: string;
    collapsed?: boolean;
  });
}

属性

属性	类型	默认值	说明
`content`	`string \| HTMLElement`	`''`	面板内容
`title`	`string`	`''`	面板标题
`collapsed`	`boolean`	`true`	是否折叠

示例

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

const panel = new InfoPanelControl({
  position: 'bottom-left',
  title: '地图信息',
  content: '<p>当前缩放级别: <span id="zoom-level">12</span></p>',
  collapsed: false,
});
map.addControl(panel);

SwipeControl

卷帘对比控件。

构造函数

class SwipeControl extends Control {
  constructor(options?: ControlOptions & {
    leftLayer?: Layer;
    rightLayer?: Layer;
    position?: number;
  });
}

属性

属性	类型	默认值	说明
`leftLayer`	`Layer \| undefined`	—	左侧图层
`rightLayer`	`Layer \| undefined`	—	右侧图层
`position`	`number`	`50`	分割线位置（百分比）

示例

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

const swipe = new SwipeControl({
  position: 'top-left',
  leftLayer: satelliteLayer,
  rightLayer: roadLayer,
  position: 50,
});
map.addControl(swipe);

OverviewMapControl

鹰眼（总览）控件。

构造函数

class OverviewMapControl extends Control {
  constructor(options?: ControlOptions & {
    collapsed?: boolean;
    size?: number;
    basemap?: string;
  });
}

属性

属性	类型	默认值	说明
`collapsed`	`boolean`	`true`	是否折叠
`size`	`number`	`150`	鹰眼尺寸（像素）
`basemap`	`string \| undefined`	—	鹰眼底图

示例

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

const overview = new OverviewMapControl({
  position: 'bottom-right',
  collapsed: false,
  size: 200,
  basemap: 'osm',
});
map.addControl(overview);

MousePositionControl

鼠标坐标控件。

构造函数

class MousePositionControl extends Control {
  constructor(options?: ControlOptions & {
    format?: string;
    precision?: number;
    projection?: string;
  });
}

属性

属性	类型	默认值	说明
`format`	`string`	`'xy'`	坐标格式
`precision`	`number`	`6`	小数精度
`projection`	`string`	`'EPSG:4326'`	输出坐标系

示例

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

const mousePos = new MousePositionControl({
  position: 'bottom-right',
  precision: 4,
  projection: 'EPSG:4326',
});
map.addControl(mousePos);

HashStateControl

URL Hash 状态控件，将地图状态同步到 URL hash。

构造函数

class HashStateControl extends Control {
  constructor(options?: ControlOptions & {
    prefix?: string;
  });
}

属性

属性	类型	默认值	说明
`prefix`	`string`	`''`	hash 前缀

示例

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

const hash = new HashStateControl({ prefix: 'map' });
map.addControl(hash);
// URL 变为: https://example.com/#map=12/39.9/116.4

Legend

图例控件。

构造函数

class Legend extends Control {
  constructor(options?: ControlOptions & {
    layer?: Layer;
    collapsible?: boolean;
  });
}

属性

属性	类型	默认值	说明
`layer`	`Layer \| undefined`	—	关联图层
`collapsible`	`boolean`	`true`	是否可折叠

示例

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

const legend = new Legend({
  position: 'bottom-right',
  layer: myFeatureLayer,
  collapsible: true,
});
map.addControl(legend);

ScaleRangeSlider

比例尺范围滑块控件，控制图层的缩放可见范围。

构造函数

class ScaleRangeSlider extends Control {
  constructor(options?: ControlOptions & {
    layer?: Layer;
    minZoom?: number;
    maxZoom?: number;
  });
}

属性

属性	类型	默认值	说明
`layer`	`Layer \| undefined`	—	关联图层
`minZoom`	`number`	`0`	最小缩放
`maxZoom`	`number`	`18`	最大缩放

示例

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

const slider = new ScaleRangeSlider({
  position: 'bottom-left',
  layer: detailLayer,
  minZoom: 12,
  maxZoom: 18,
});
map.addControl(slider);

ContextMenuControl

右键菜单控件。

构造函数

class ContextMenuControl extends Control {
  constructor(options?: ControlOptions & {
    items?: Array<{
      label: string;
      callback?: (e: any) => void;
      separator?: boolean;
    }>;
  });
}

属性

属性	类型	说明
`items`	`Array<{label, callback?, separator?}>`	菜单项列表

示例

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

const ctxMenu = new ContextMenuControl({
  position: 'top-left',
  items: [
    { label: '放大', callback: () => map.zoomIn() },
    { label: '缩小', callback: () => map.zoomOut() },
    { separator: true },
    { label: '居中到此处', callback: (e) => map.setCenter(e.coordinate) },
  ],
});
map.addControl(ctxMenu);

SearchControl

搜索控件。

构造函数

class SearchControl extends Control {
  constructor(options?: ControlOptions & {
    provider?: string;
    placeholder?: string;
    onSelect?: (result: any) => void;
  });
}

属性

属性	类型	默认值	说明
`provider`	`string`	—	搜索服务提供方
`placeholder`	`string`	`'搜索...'`	输入框占位文本

方法（回调）

回调	参数	说明
`onSelect`	`(result: any) => void`	选中搜索结果时触发

示例

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

const search = new SearchControl({
  position: 'top-center',
  provider: 'amap',
  placeholder: '搜索地点...',
  onSelect: (result) => {
    console.log('选中:', result.name, result.location);
    map.flyTo(result.location, 15);
  },
});
map.addControl(search);

控件类型 Control ​

Control（抽象基类） ​

属性 ​

方法 ​

ZoomControl ​

构造函数 ​

属性 ​

示例 ​

CompassControl ​

构造函数 ​

示例 ​

ScaleBarControl ​

构造函数 ​

属性 ​

示例 ​

AttributionControl ​

构造函数 ​

属性 ​

示例 ​

LayerSwitcherControl ​

构造函数 ​

属性 ​

示例 ​

BasemapSwitcherControl ​

构造函数 ​

示例 ​

FullscreenControl ​

构造函数 ​

示例 ​

GeolocationControl ​

构造函数 ​

属性 ​

示例 ​

NavigationControl ​

构造函数 ​

属性 ​

示例 ​

InfoPanelControl ​

构造函数 ​

属性 ​

示例 ​

SwipeControl ​

构造函数 ​

属性 ​

示例 ​

OverviewMapControl ​

构造函数 ​

属性 ​

示例 ​

MousePositionControl ​

构造函数 ​

属性 ​

示例 ​

HashStateControl ​

构造函数 ​

属性 ​

示例 ​

Legend ​

构造函数 ​

属性 ​

示例 ​

ScaleRangeSlider ​

构造函数 ​

属性 ​

示例 ​

ContextMenuControl ​

构造函数 ​

属性 ​

示例 ​

SearchControl ​

构造函数 ​

属性 ​

方法（回调） ​

示例 ​

控件类型 Control

Control（抽象基类）

属性

方法

ZoomControl

构造函数

属性

示例

CompassControl

构造函数

示例

ScaleBarControl

构造函数

属性

示例

AttributionControl

构造函数

属性

示例

LayerSwitcherControl

构造函数

属性

示例

BasemapSwitcherControl

构造函数

示例

FullscreenControl

构造函数

示例

GeolocationControl

构造函数

属性

示例

NavigationControl

构造函数

属性

示例

InfoPanelControl

构造函数

属性

示例

SwipeControl

构造函数

属性

示例

OverviewMapControl

构造函数

属性

示例

MousePositionControl

构造函数

属性

示例

HashStateControl

构造函数

属性

示例

Legend

构造函数

属性

示例

ScaleRangeSlider

构造函数

属性

示例

ContextMenuControl

构造函数

属性

示例

SearchControl

构造函数

属性

方法（回调）

示例