# 绘图控件（Draw）

# 构造函数

// 创建一个地图
const map = new aimap.Map({...});

// 创建绘图控件实例
const draw = new aimap.Draw(drawOptions);

// 将绘图控件添加到地图上
map.addControl(draw);

1
2
3
4
5
6
7
8

# 参数说明

字段名	类型	是否必须	默认值	说明
displayControlsDefault	boolean	否	true	是否显示所有的绘图图标。
controls	Object	否		用于确定每种绘图图标是否显示，可供配置的图标包括：`point`, `line_string`, `polygon`, `circle`, `rectangle`, `trash`, `combine_features` 和 `uncombine_features`。
styles	Array<Object>	否		自定义绘制样式，样式的写法可参照下文。

一共有point, line_string, polygon, circle, rectangle, trash, combine_features 和 uncombine_features这几种绘图图标，下面是这些模式的说明：

名称	说明
point	绘制单个点，鼠标左击地图，来添加点数据。
line_string	绘制折线，鼠标左击地图添加折线的端点，右击或双击地图退出编辑。
polygon	绘制多边形，鼠标左击地图添加多边形的端点，右击或双击地图退出编辑。
circle	绘制圆，鼠标左击地图作为圆心，左击后按住不放，拖动鼠标，确定圆的半径大小，圆心坐标和半径会在绘制完成后输出的GeoJSON的属性中。
rectangle	绘制矩形，鼠标左击地图作为矩形的一角，松开鼠标后移动到另外一个位置，并左击，即可构建矩形。
trash	点选某个已绘制的几何，点击删除按钮可删除被选中的几何。
combine_features	按住 Shift 键可以对已绘制的几何进行多选，选中后点击“合并”，即可将多个几何合并为一个。
uncombine_features	选择某合并后的几何，点击“拆解”，即可将一个几何拆解为多个几何。

除了上述的图标外，绘图控件可以通过modes来控制，下面的成员函数中的getMode()和changeMode(string)即使用了下面这些模式：

名称	值	说明
draw_point	draw.modes.DRAW_POINT	绘制单个点。
draw_line_string	draw.modes.DRAW_LINE_STRING	绘制折线。
draw_polygon	draw.modes.draw_polygon	绘制多边形。
draw_circle	draw.modes.DRAW_CIRCLE	绘制圆。
draw_rectangle	draw.modes.DRAW_RECTANGLE	绘制矩形。
draw_cut_line	draw.modes.DRAW_CUT_LINE	绘制裁剪线。
simple_select	draw.modes.SIMPLE_SELECT	选中某个对象。
direct_select	draw.modes.DIRECT_SELECT	选中某个节点。

自定义styles样式示例：

WARNING

自定义样式时，显示几个控件，就需要对相应的几个控件全部进行自定义配置，不能显示多个控件，只配置一个控件的样式。

即要么全部自定义控件，要么全不配置。

用户可对以下参数中paint属性下字段进行相应自定义配置

自定义绘图样式示例

styles: [
    // 绘制点样式配置
    {
        'id': 'points-are-blue',
        'type': 'circle',
        'filter': ['all',
            ['==', '$type', 'Point'],
            ['==', 'meta', 'feature'],
            ['==', 'active', 'false']
        ],
        'paint': {
            'circle-radius': 5, //点半径
            'circle-color': '#000088' //点颜色
        }
    },
    // 绘制线样式配置
    {
        "id": "gl-draw-line",
        "type": "line",
        "filter": ["all", ["==", "$type", "LineString"],
            ["!=", "mode", "static"]
        ],
        "layout": {
            "line-cap": "round",
            "line-join": "round"
        },
        "paint": {
            "line-color": "#D20C0C", //线颜色
            "line-dasharray": [0.2, 2], //虚线间隔，删除该字段后显示实线
            "line-width": 2 //线宽
        }
    },
    // 多边形填充样式配置
    {
        "id": "gl-draw-polygon-fill",
        "type": "fill",
        "filter": ["all", ["==", "$type", "Polygon"],
            ["!=", "mode", "static"]
        ],
        "paint": {
            "fill-color": "#D20C0C", //多边形填充色
            "fill-opacity": 0.1 //多边形填充透明度
        }
    },
    // 多边形边线样式配置
    {
        "id": "gl-draw-polygon-stroke-active",
        "type": "line",
        "filter": ["all", ["==", "$type", "Polygon"],
            ["!=", "mode", "static"]
        ],
        "layout": {
            "line-cap": "round",
            "line-join": "round"
        },
        "paint": {
            "line-color": "#D20C0C", // 线颜色
            "line-dasharray": [0.2, 2], // 虚线间隔，该字段删除后为实线
            "line-width": 2 //线宽
        }
    },
    // 多边形和线顶点样式
    {
        "id": "gl-draw-polygon-and-line-vertex-active",
        "type": "circle",
        "filter": ["all", ["==", "meta", "vertex"],
            ["==", "$type", "Point"],
            ["!=", "mode", "static"]
        ],
        "paint": {
            "circle-stroke-width": 2, //顶点点光晕大小
            "circle-stroke-color": "#FFF", //顶点光晕颜色
            "circle-radius": 3, //顶点半径
            "circle-color": "#D20C0C", //顶点颜色
        }
    },
]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# 示例代码

const draw = new aimap.Draw({
    displayControlsDefault: false,
    controls: {
        polygon: true,
        line_string: true,
        point: true,
        circle: true,
        rectangle: true,
        trash: true,
    }
});

1
2
3
4
5
6
7
8
9
10
11

线上示例：地图控件 -- 绘制控件-几何形状 (opens new window)。

线上示例：地图控件 -- 绘制控件-合并，缓冲，裁剪 (opens new window)。

# 成员函数

add(geojson: Object)，添加 geojson 数据

向绘图控件中添加一个或一组 geojson 数据，如果提供的 Feature 中没有 id，工具会自动为其补充随机的 id。如果 id 对应的 Feature 已存在，则会替换已有的 Feature。

# 参数

geojson：支持 GeoJSON Feature，FeatureCollection，或者 Geometry。feature 的类型支持 Point，LineString，Polygon，MultiPoint， MultiLineString，以及MultiPolygon。

# 返回值

Array<string>：被添加的对象的 id 组成的数组。

# 示例

// 不带 id
var feature = { type: 'Point', coordinates: [0, 0] };
var featureIds = draw.add(feature);
console.log(featureIds);
//=> ['some-random-string']

// 带 id
var feature = {
  id: 'unique-id',
  type: 'Feature',
  properties: {},
  geometry: { type: 'Point', coordinates: [0, 0] }
};
var featureIds = draw.add(feature);
console.log(featureIds)
//=> ['unique-id']

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

get(featureId: string)，获取已绘制的几何对象

通过 id 获取已绘制的几何中的 GeoJSON feature，如果没有对应的，则会返回 undefined。

# 参数

featureId：featureId

# 返回值

Feature：Feature对象

# 示例

var featureIds = draw.add({ type: 'Point', coordinates: [0, 0] });
var pointId = featureIds[0];
console.log(draw.get(pointId));
//=> { type: 'Feature', geometry: { type: 'Point', coordinates: [0, 0] } }

1
2
3
4

getFeatureIdsAt(point: { x: number, y: number })，获取指定位置的绘制对象

获取某个屏幕坐标附近的绘制的对象。

# 参数

point: { x: number, y: number }：屏幕坐标

# 返回值

Array<string>：传入坐标附近的几何对象的 id 数组

# 示例

var featureIds = Draw.getFeatureIdsAt({x: 20, y: 20});
console.log(featureIds)
//=> ['top-feature-at-20-20', 'another-feature-at-20-20']

1
2
3

getSelectedIds()，获取被选中的对象的 id

获取被选中的对象的 id 列表。

# 返回值

Array<string>：被选中的对象的 id 列表

getSelected()，获取被选中的对象

获取被选中的对象的 FeatureCollection。

# 返回值

FeatureCollection：被选中的对象的 FeatureCollection

getSelectedPoints()，获取被选中的对象的顶点

获取被选中的对象的顶点组成的 FeatureCollection。

# 返回值

FeatureCollection：被选中的对象的顶点组成的 FeatureCollection

getAll()，获取所有的已绘制的对象

获取绘图控件中所有的已绘制的对象组成的 FeatureCollection。

# 返回值

FeatureCollection：绘图控件中所有的已绘制的对象组成的 FeatureCollection

# 示例

draw.add({ type: 'Point', coordinates: [0, 0] });
draw.add({ type: 'Point', coordinates: [1, 1] });
draw.add({ type: 'Point', coordinates: [2, 2] });
console.log(draw.getAll());
// {
//   type: 'FeatureCollection',
//   features: [
//     {
//       id: 'random-0'
//       type: 'Feature',
//       geometry: {
//         type: 'Point',
//         coordinates: [0, 0]
//       }
//     },
//     {
//       id: 'random-1'
//       type: 'Feature',
//       geometry: {
//         type: 'Point',
//         coordinates: [1, 1]
//       }
//     },
//     {
//       id: 'random-2'
//       type: 'Feature',
//       geometry: {
//         type: 'Point',
//         coordinates: [2, 2]
//       }
//     }
//   ]
// }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

delete(ids: string | Array<string>)，删除某个 id 的对象

删除某个 id 或者一组 id 对应的对象。

# 参数

ids: string | Array<string>：需要删除的对象的 id

# 返回值

draw：绘图控件的实例

# 示例

var feature = { type: 'Point', coordinates: [0, 0] };
var ids = draw.add(feature);
draw
  .delete(ids)
  .getAll();
// { type: 'FeatureCollection', features: [] }

1
2
3
4
5
6

deleteAll()，删除所有已绘制对象

删除绘图控件中，所有的已绘制的对象。

# 返回值

draw：绘图控件的实例

# 示例

draw.add({ type: 'Point', coordinates: [0, 0] });
draw
  .deleteAll()
  .getAll();
// { type: 'FeatureCollection', features: [] }

1
2
3
4
5

set(featureCollection: FeatureCollection)，初始化绘图控件中的对象

指定绘图控件中的对象，此操作会 清除掉所有已绘制的对象 。并且执行效率略高于先Draw.deleteAll() 再 Draw.add(featureCollection)。

# 参数

featureCollection: FeatureCollection：FeatureCollection，feature 的类型支持 Point，LineString，Polygon，MultiPoint， MultiLineString，以及MultiPolygon

# 返回值

Array<string>：添加到绘图控件中的对象的 id 列表

# 示例

var ids = draw.set({
  type: 'FeatureCollection',
  features: [{
    type: 'Feature',
    properties: {},
    id: 'example-id',
    geometry: { type: 'Point', coordinates: [0, 0] }
  }]
});
// ['example-id']

1
2
3
4
5
6
7
8
9
10

trash()，删除掉当前指定的对象

如果当前正在绘制，则删除掉当前绘制的对象；如果当前选中了某个对象，则删除被选中的对象；如果当前选中了某个顶点，则删除被选中的顶点。

# 返回值

draw：绘图控件的实例

getMode()，获取绘图控件当前的模式

获取绘图控件当前的模式。模式可参考上面的描述，包括draw_point, draw_line_string, draw_polygon, draw_circle, draw_rectangle, simple_select 和 direct_select。

# 返回值

string：绘图控件的模式

changeMode(mode: string)，改变绘图控件当前的模式

改变绘图控件当前的模式，模式可参考上面的描述。

# 参数

mode: string：绘图控件的模式

# 返回值

draw：绘图控件的实例

setFeatureProperty(featureId: string, property: string, value: any)，为某个 Feature 指定属性值

为某个 Feature 指定属性值。注意，本操作只能指定单个 Feature 的属性，如果需要对所有的对象指定属性，可以通过遍历来实现。

# 参数

featureId: string：希望指定的对象的 id

property: string：属性名称

value: any：属性值

# 返回值

draw：绘图控件的实例

deleteFeatureProperty(featureId: string, property: string)，删除某个 Feature 的属性

删除某个 Feature 的指定属性。

# 参数

featureId: string：希望指定的对象的 id

property: string：属性名称

# 返回值

draw：绘图控件的实例

combineFeatures(options: Options)，合并选中的几何对象

合并选中的几何对象，默认情况下等同于combine_features按钮，可以通过options参数自定义合并方式。

# 参数

Options.unionGeometry: boolean：是否合并选中的几何，如果是，有重叠区域的面会合并为一个单一的面。 Options.propertiesMergeFunction: (featuresArr) => {}：默认情况下，会使用选中的几何中的第一个对象的属性。可以通过本参数，自定义一个函数来计算合并后的属性，函数的输入为选中的几何对象数组。

# 事件

绘图控件在操作的过程中，提供了很多事件，开发者可以通过监听这些事件来实现一些功能。

WARNING

当开发者主动调用上述的接口时，不会触发这些事件，因为，作为开发者，已经明确知道了某些操作的发生。

例如：当用户创建绘制了一个几何后，绘图控件会发出 draw.create 事件。但是，当开发者用 draw.add(geojson) 接口添加了某个几何后，不会触发 draw.create 事件。

draw.create，绘制完成事件

当一个几何对象被绘制完成后，会触发这个事件。

# 回调参数

features：绘制完成的对象的 geojson 数组

# 示例

map.on('draw.create', (event) => {
    //输出绘制后的图形
    console.info('create', event.features[0]);
});

1
2
3
4

draw.delete，删除事件

当一个几何对象被删除后，会触发这个事件。

# 回调参数

features：被删除的对象的 geojson 数组

draw.combine，对象合并事件

当一组几何对象被合并后，会触发这个事件。

# 回调参数

createdFeatures：合并后的对象的 geojson 数组

deletedFeatures：被合并的对象的 geojson 数组

draw.uncombine，对象拆分事件

当一个几何对象被拆分后，会触发这个事件。

# 回调参数

createdFeatures：拆分后的对象的 geojson 数组

deletedFeatures：被拆分的对象的 geojson 数组

draw.update，对象更新事件

当一个对象被整体移动，或者某个顶点被拖动后，会触发这个事件。

# 回调参数

action：'move'，表示对象被整体移动了；'change_coordinates'，表示对象的某个顶点坐标发生了变化。

features：数据发生更新的对象的 geojson 数组

draw.selectionchange，对象选取事件

当被选中的几何对象发生变化后，会触发这个事件。

# 回调参数

features：被选中的对象的 geojson 数组

draw.modechange，控件模式变更事件

当绘图控件的模式发生变化时，会触发这个事件。

# 回调参数

mode：绘图控件当前的模式

draw.cut，对象被切割事件

当绘图控件在draw.modes.DRAW_CUT_LINE模式下完成切割操作后，会触发这个事件。

# 回调参数

newfeatures：裁剪后的对象的 geojson 数组

deletedFeatures：被裁剪的对象的 geojson 数组

← 地图 Markers 和 Popup →