版本：9.4.0

API 接口

用法

// 创建一个Mapmost地图
var map = new mapmost.Map(mapOptions);

// 创建一个Draw控件
var draw = new MapmostDraw(drawOptions);

该插件仅支持在地图加载后使用, 所以必须在map的 load 事件中添加:

map.on('load', function() {

  // 将Draw控件添加到你的地图
  map.addControl(draw);
  draw.add({ .. });
});

参数

名称	类型	默认值	描述
boxSelect	Boolean	true	可选是否启用使用 "shift + click + 拖拽" 进行框选要素功能。如果为 false，使用 "shift + click + 拖拽" 将会进行区域缩放。
clickBuffer	Number	2	可选点击时会响应的任何要素或顶点周围的像素数。
controls	Object		可选隐藏或显示单个控件。每个属性的名称是一个控件，值是一个布尔值，指示该控件是打开还是关闭。可用的控件名称为 point、line_string、polygon、trash、combine_features 和 uncombine_features。默认情况下，所有控件均处于打开状态。
defaultMode	String	simple_select	可选默认绘制模式。
displayControlsDefault	Boolean	true	可选 "controls" 的默认值。例如，如果希望所有控件默认关闭，并使用指定的 "controls" 时，可设置 "displayControlsDefault: false"。
keybindings	Boolean	true	可选是否启用键盘交互进行绘图。
modes	Object	true	可选自定义模式，"MapmostDraw.modes"可用于查看默认值。有关自定义模式的更多信息请参考模式文档。
styles	Array		可选样式对象的数组。有关自定义样式的更多信息请参考样式文档。
touchBuffer	Number	25	可选触摸时会响应的任何要素或顶点周围的像素数。
touchEnabled	Boolean	true	可选是否启用触摸交互进行绘图。
userProperties	Boolean	false	可选是否设置要素的属性用于样式设置，并以 user_ 为前缀，例如 "["==", "user_custom_label", "Example"]"

绘制模式

默认情况下，MapmostDraw 附带几种模式。这些模式旨在涵盖创建GeoJSON要素类型所需的基本功能，除此之外，MapmostDraw还支持自定义模式。

模式名称字符串以枚举形式提供，位于 Draw.modes。

direct_select

允许选择、删除和拖动顶点。不适用于点要素，因为它们没有顶点。当用户点击选定线段或多边形的顶点时，Draw会进入 direct_select 模式。因此，direct_select 模式通常遵循 simple_select 模式。

案例

Draw.modes.DIRECT_SELECT === 'direct_select'

draw_line_string

允许绘制一个 LineString 要素。

案例

Draw.modes.DRAW_LINE_STRING === 'draw_line_string'

draw_point

允许绘制一个点要素。

案例

Draw.modes.DRAW_POINT === 'draw_point'

draw_polygon

允许绘制一个面要素

案例

Draw.modes.DRAW_POLYGON === 'draw_polygon'

simple_select

允许选择、删除和拖动要素。在此模式下，可以更改要素的选中状态。绘制默认处于 simple_select 模式，每次用户完成绘制要素或退出 direct_select 模式时，都会自动再次变为 simple_select 模式。

案例

Draw.modes.SIMPLE_SELECT === 'simple_select'

方法

add

该方法可以将一个 GeoJSON Feature、FeatureCollection 或者 Geometry 添加到 Draw 中。它返回一个 id 数组，用于与添加的要素进行交互。如果要素没有自己的 id，则会自动生成一个。

参数

名称	类型	描述
geojson	Object	必填要添加的GeoJson数据，支持的GeoJSON要素类型有 "Point", "LineString", "Polygon", "MultiPoint", "MultiLineString" 和 "MultiPolygon"。

案例

如果添加的要素 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']

changeMode

更改绘制模式，返回绘制实例。mode 参数必须是上述模式名称之一并存在于 Draw.modes 中。

参数

名称	类型	描述
mode	String	必填要切换到的模式名称。
options	Object	必填不同模式下的可选参数。

simple_select, direct_select 和 draw_line_string 模式接受的 options 参数如下：

// `simple_select` 模式
{
  // 特征的 id 的数组将被首先选择
  featureIds: Array<string>
}

// `direct_select` 模式
{
  // 特征的 id 将被直接选择（必选）
  featureId: string
}

// `draw_line_string` 模式
{
  // 继续绘制的 LineString 的 id
  featureId: string,

  // 继续绘制的点
  from: Feature<Point>|Point|Array<number>
}

combineFeatures

调用当前模式的 combineFeatures 操作，返回绘制实例。

在 simple_select 模式下, 会将选中的所有要素合并为一个 Multi* 要素，只要它们具有相同的几何类型。例如：

选中的要素类型都为 LineStrings => MultiLineString
选中的要素类型分别为 MultiLineString 和 LineString => MultiLineString
选中的要素类型都为 MultiLineStrings => MultiLineString

当选中不同几何类型的要素时，不会引起任何变化。例如：

选中的要素类型为 Point 和 LineString => 保持不变
选中的要素类型为 MultiLineString 和 MultiPoint => 保持不变

在 direct_select 和绘制模式下, 不执行任何操作。

delete

删除具有指定 id 的要素，返回绘制实例。

参数

名称	类型	描述
ids	String\|Array	必填要切换到的模式名称。

在 direct_select 模式下, 删除要素将会退出该模式并恢复到 simple_select 模式.

案例

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

deleteAll

删除所有要素，返回绘制实例。

案例

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

get

返回具有指定 id 的要素，若匹配不到任何要素，则返回 undefined 。

参数

名称	类型	描述
featureId	String	必填要素 id 。

案例

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] } }

getAll

返回包含所有要素的要素集合。

案例

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]
//       }
//     }
//   ]
// }

getFeatureIdsAt

返回当前在指定点渲染的要素 id 数组。通过该函数，可以使用鼠标事件提供的坐标从 Draw 中获取信息。

参数

名称	类型	描述
point	Object	必填要素在像素空间中的坐标，形如 "{ x: number, y: number }" 。

案例

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

getMode

返回当前的绘制模式。

getSelected

返回当前选定的所有要素的要素集合。

getSelectedIds

返回当前选中所有要素的 id 数组。

getSelectedPoints

返回当前选中的所有顶点的要素集合。

set

将 Draw 中的要素设置为指定的要素集合。该函数会执行必要的删除、创建和更新操作，使 Draw 中的要素与指定的 FeatureCollection 匹配。实际上，它与先调用 Draw.deleteAll() ，再调用 Draw.add(featureCollection) 的效果相同，但它对性能的影响较小。

参数

名称	类型	描述
featureCollection	FeatureCollection	必填要指定的要素集合。

案例

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

setFeatureProperty

设置具有指定 id 的要素的属性值，返回绘制实例。如果您使用 Draw 的功能作为应用程序中的主要数据存储，这会很有帮助。

参数

名称	类型	描述
featureId	String	必填要素的 id 。
value	Any	必填属性值。

trash

调用当前模式的 trash 操作，返回绘制实例。

在 simple_select 模式下, 会删除所有选定的要素。
在 direct_select 模式下, 会删除所有选定的顶点。
在绘制模式下，会取消绘图并恢复为 simple_select 模式。
如果您想要删除功能，无论当前模式如何，请使用 delete 或者 deleteAll 方法。

uncombineFeatures

调用当前模式的 uncombineFeatures 操作，返回绘制实例。

在 simple_select 模式下,这会将每个选定的 Multi* 要素拆分为多个组成它的要素部分，并保持非 Multi 要素不变。例如：

选中的要素是由两个部分组成的 MultiLineString => LineString, LineString
选中的要素时由三个部分组成的 MultiLineStrings => LineString, LineString, LineString
选中的要素是由两个部分组成的 MultiLineString 和一个 Point => LineString, LineString, Point
选中的要素是 LineString => LineString

在 direct_select 和绘制模式下,不执行任何操作。

事件

Draw 会触发很多事件，所以这些事件都以 draw. 命名，并从 Mapmost map 地图对象发出。所有事件都是由用户交互触发的。

案例

map.on('draw.create', function (e) {
  console.log(e.features);
});

如果您以编程方式调用 Draw API 中的函数，则不会触发任何与 该函数直接对应 的事件。 例如，如果您调用了 draw.delete() ，那么就不会有对应的 draw.delete() 事件，因为您已经知道了您所做的操作。不过，后续可能会触发事件，但这些事件与调用的函数不直接对应。例如，如果您选择了一个要素，然后调用了 draw.changeMode('draw_polygon') ，您将不会看到一个 draw.modechange 事件（因为它直接对应于调用的函数），但你将会看到一个 draw.selectionchange 事件，因为通过改变模式，你间接地取消选择了一个要素。

actionable

当 Draw 的状态发生变化时（启用/禁用）触发。下面这些事件将使您了解 draw.trash(), draw.combineFeatures() 和 draw.uncombineFeatures() 是否会产生效果。

案例

{
  actions: {
    trash: true
    combineFeatures: false,
    uncombineFeatures: false
  }
}

combine

合并要素时触发。以下交互将会触发此事件：

当在 simple_select 模式下，选择多个要素时，点击合并按钮。
当在 simple_select 模式下，选择多个要素时调用 draw.combineFeatures()。

该事件数据是类似以下形式的对象：

{
  deletedFeatures: Array<Feature>, // 被删除特征的数组 (那些包含新的多特征)
  createdFeatures: Array<Feature> // 被创建的多特征数组
}

create

创建要素时触发。以下交互将会触发此事件：

完成一个要素的绘制时。只需要单击即可创建一个点。只有在用户完成绘制一个 LineString 或 Polygon 并且绘制的要素是有效的时候，才会创建它。也就是说，用户双击了最后一个顶点或者按下回车键，这时绘制的要素才会被认为是完成并且有效的。

该事件数据是类似以下形式的对象：

{
  // GeoJSON对象数组表示被创建的特征
  features: Array<Object>
}

delete

当删除一个或多个要素时触发。以下交互将会触发此事件：

在 simple_select 模式下，选择一个或多个要素后，点击 trash 按钮。
在 simple_select 模式下，选择一个或多个要素后，按下 Backspace 或者 Delete 键。
在 simple_select 模式下，选择一个要素后调用 draw.trash() 。

该事件数据是类似以下形式的对象：

{
  // GeoJSON对象数组表示被删除的特征
  features: Array<Feature>
}

modechange

当模式更改时触发。以下交互将会触发此事件：

点击点、线或多边形按钮开始绘制（进入 draw_* 模式）。
完成绘制一个要素（进入 simple_select 模式）。
在 simple_select 模式下, 单击一个已选择的要素（进入 direct_select 模式）。
在 direct_select 模式下, 点击所以要素外部(进入 simple_select 模式)。

该事件在当前模式停止和下一个模式开始前触发。在所有事件处理程序触发之后，才会进行渲染，因此您可以通过在 draw.modechange 处理程序内调用 draw.changeMode() 来强制进行模式重定向。

该事件数据是类似以下形式的对象：

{  
  mode: string // 下一个模式，即绘制要改变的模式
}

simple_select 和 direct_select 模式可以使用特定于该模式的选项来初始化（请参阅上文）。

render

在 Draw 调用 setData() 更新地图时立即触发。这并不意味着已经完成更新地图，只是表示地图正在更新。

selectionchange

当选中状态更改时触发（即选中或取消一个或多个要素时）。以下交互将会触发此事件：

单击一个要素并将其选中。
当已选中一个要素时，按住 Shift 键并单击另一个要素，将其添加到选中要素集合中。
单击一个顶点并将其选中。
当已选中一个顶点时，按住 Shift 键并单击另一个顶点，将其添加到选中顶点集合中。
创建至少包含一个要素的框选择（box-selection）。
单击所选要素外部以取消选择。
单击远离选中顶点的位置以取消选择。
完成绘制一个要素（要素被绘制后立即被选中）。
当已选中一个要素时，调用 draw.changeMode() 取消选中该要素。
使用 draw.changeMode('simple_select', { featureIds: [..] }) 切换至 simple_select 模式并立即选中指定要素。
使用 draw.delete, draw.deleteAll 或者 draw.trash 删除要素。

该事件数据是类似以下形式的对象：

{
  features: Array<Feature> // 变化后被挑选的特征数组
}

uncombine

当要素未合并时触发。以下交互将会触发此事件：

在 simple_select 模式下，选中一个或多个 multifeatures 时，点击 uncombine 按钮。也可以选择 Non-multifeatures。
在 simple_select 模式下，选中一个或多个 multifeatures 时，调用 draw.uncombineFeatures() 事件。

该事件数据是类似以下形式的对象：

{
  deletedFeatures: Array<Object>, // 被删除的多样特征数组（拆分为特征）
  createdFeatures: Array<Object> // 被创建的特征数组
}

update

当一个或多个要素更新时触发。以下交互将触发此事件，并可以通过 action 进行细分：

action: 'move'
- 在 simple_select 模式下，完成移动一个或多个选中要素。仅当移动完成时（即当用户释放鼠标按钮或点击 Enter 时），才会触发该事件。
action: 'change_coordinates'
- 在 direct_select 模式下，完成移动一个或多个选中顶点。仅当移动完成时（即当用户释放鼠标按钮或点击 Enter 或鼠标离开地图容器时），才会触发该事件。
- 在 direct_select 模式下，删除所选要素的一个或多个顶点。可以通过以下方式删除一个或多个选定要素的顶点：按下 Backspace 或者 Delete 键；点击 Trash 按钮；调用 draw.trash() 方法。
- 在 direct_select 模式下，通过在选定要素上点中点来添加一个顶点。

创建或删除要素时不会触发该事件。要跟踪这些交互，请监听 draw.create 和 draw.delete 事件。

该事件数据是类似以下形式的对象：

{  
  features: Array<Feature>, // 更新特征数组
  action: string // 触发更新的操作名称
}

绘制样式

Draw 使用符合 Mapmost GL 样式规范的地图样式，但有一些注意事项。

source

GL样式规范要求每个图层都有一个数据源。但是， 在设置 Draw 样式时不要提供 source 。

为了优化性能，在移动要素时，Draw 会自动调整它们的来源。因此，Draw会自动为你提供一个 source 。

Draw 提供的 source 名为 mapmost-draw-hot 和 mapmost-draw-cold。

id

GL样式规范要求每个图层都有一个id。 您必须提供一个 id，Draw 会将后缀 .hot 和.cold 添加到您的 id 中。

在您自定义的样式中，将需要使用以下要素属性：

参数	值	描述
meta	feature, midpoint, vertex	`midpoint` 和 `vertex` 是用于在地图上添加的点来表示多边形和线段的控制点。 `feature` 则用于表示所有的要素。
active	true, false	在当前模式下，某个要素被选中后即处于 active 状态。`true` 和 `false` 是字符串。
mode	simple_select, direct_select, draw_point, draw_line_string, draw_polygon	显示 Draw 当前所处的模式。

Draw 还为要素提供了一些其他属性，但不应该用于样式设置。有关这些属性的详细信息，请参阅下方的要素查询。

如果将 opts.userProperties 设置为 true，则要素的属性也可以用于样式设置。所有用户属性都以 user_ 作为前缀，以确保它们不会与 Draw 的属性冲突。

自定义样式示例

请参阅文档样式。

要素查询

与 Mapmost JS 的 queryRenderedFeatures 搭配绘制。

名称	类型	描述
id	String	可选仅当 "meta" 是 "feature" 时可用。
parent	String	可选仅当 "meta" 不是 "feature" 时可用。
coord_path	String	可选指向父级坐标中的 [经度，纬度] 实体的一个以 "." 分隔的路径。
lon	Number	可选控制点的经度值。只有当 "meta" 为 "midpoint" 时可用。
lat	Number	可选控制点的纬度值。只有当 "meta" 为 "midpoint" 时可用。

API 接口

用法​

参数​

绘制模式​

direct_select​

案例​

draw_line_string​

案例​

draw_point​

案例​

draw_polygon​

案例​

simple_select​

案例​

方法​

add​

参数​

案例​

changeMode​

参数​

combineFeatures​

delete​

参数​

案例​

deleteAll​

案例​

get​

参数​

案例​

getAll​

案例​

getFeatureIdsAt​

参数​

案例​

getMode​

getSelected​

getSelectedIds​

getSelectedPoints​

set​

参数​

案例​

setFeatureProperty​

参数​

trash​

uncombineFeatures​

事件​

案例​

actionable​

案例​

combine​

create​

delete​

modechange​

render​

selectionchange​

uncombine​

update​

绘制样式​

source​

id​

自定义样式示例​

要素查询​

用法

参数

绘制模式

direct_select

案例

draw_line_string

案例

draw_point

案例

draw_polygon

案例

simple_select

案例

方法

add

参数

案例

changeMode

参数

combineFeatures

delete

参数

案例

deleteAll

案例

get

参数

案例

getAll

案例

getFeatureIdsAt

参数

案例

getMode

getSelected

getSelectedIds

getSelectedPoints

set

参数

案例

setFeatureProperty

参数

trash

uncombineFeatures

事件

案例

actionable

案例

combine

create

delete

modechange

render

selectionchange

uncombine

update

绘制样式

source

id

自定义样式示例

要素查询