mapbox-gl-draw API文档

原文地址

1. mapbox-gl-draw 的使用

import '@mapbox/mapbox-gl-draw/dist/mapbox-gl-draw.css'
import MapboxDraw from "@mapbox/mapbox-gl-draw";
export default {
    name: 'BasicMapContainer',
    setup(){
        onMounted(()=>{
            const map = new mapboxgl.Map({
                container: 'map',
                // Choose from Mapbox's core styles, or make your own style with Mapbox Studio
                style: style,
                zoom: 10,
                center: [-87.622088, 41.878781]
            });
            var Draw = new MapboxDraw();
            map.addControl(Draw, 'top-left');

            map.on('load', function() {
              // 所有你的应用代码
            });
        })
        
        return {}
    }
}

2. MapboxDraw()中options参数

• keybindings： 默认 true， 是否开启键盘交互绘制
• touchEnabled： 默认 true， 是否开启接触绘制
• boxSelect： 默认 true， 是否开启使用 shift + click + drag 框选要素，如果设置为 false，shift + click + drag 缩小到某一区域。
• clickBuffer： number 类型，默认值2， 要素捕捉的容差
• controls ： 对象类型， 显示或者因隐藏 controls 工具条，每一个 property 对应一个 controls 的控制单元(如point, line_string, polygon, trash, combine_features 和 uncombine_features)。对应的值是 boolean 类型（控制是否开启控制单元). 默认全部开启，改变这种默认设置需要是使用 displayControlsDefault
• displayControlsDefault： 默认值 true， controls 的默认值，例如果需要将全部的控制单元都关闭，并且指定一个允许出现的控制单元列表。，我们可以将 displayControlsDefault 的值设置为 false
• styles： Array:类型，一个 map style object 对象的数组。默认情况下，Draw 已经提供了一个map style 给你。学习如何重写 map style，请参考Styling Draw
• defaultMode： String类型，默认’simple_select’。
• userProperties： 默认 false。允许用户编辑要素的 styling 与

3. 模式

MapboxDraw 支持少量模式！这些模式主要目的是是的 MapboxDraw 有创建 GeoJSON 要素类型的功能。除此之外，MapboxDraw还支持自定义模式。单击此处了解更多详细信息。

Draw.modes 是一个 enum 类型，包含了不同模式中的名称！

3.1. simple_select

Draw.modes.SIMPLE_SELECT === ‘simple_select’

• 可以选择，删除和拖拽要素！
• 此模式中，用户可以要素的选中状态！
• Draw 默认处于 simple_select 模式中，并且每次完成绘制一个要素或者停止direct_select模式后，都会自动转换到 simple_select 模式！

3.2. direct_select

Draw.modes.SIMPLE_SELECT === ‘direct_select’

• 可以选择，删除和拖拽顶点,拖拽要素！
• direct_select 模式不能用于点要素文件，因为点要素没有顶点！
• 当用户点击线要素或者面要素顶点的时候，Draw 会进入 direct_select 模式中，因此，simple_select模式通常direct_select遵循相同的规则。

3.3. draw_line_string

Draw.modes.SIMPLE_SELECT === ‘draw_line_string’

• 绘制线要素

3.4. draw_polygon

Draw.modes.SIMPLE_SELECT === 'draw_polygon‘

• 绘制面要素

3.5. draw_point

Draw.modes.SIMPLE_SELECT === ‘draw_point’

• 绘制点要素

4. API Methods

new MapboxDraw() 返回一个 Draw 的实例对象1

4.1. add(geojson: Object) => Array

• 这个方法可以将一个 GeoJSON Feature, FeatureCollection, 或者 Geometry加入到Draw当中。它返回一个数组（包含添加要素的ids）用来与添加的要素进行交互。如果一个要素没有他自己的id，那么 Draw生成一个id给该要素
• 支持的要素geojson 类型有：Point, LineString, Polygon, MultiPoint, MultiLineString, and MultiPolygon.
• 如果你 add(）的要素id在Draw中已经存在，那么Draw会对该要素进行覆盖！
• • 简单示例

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

• 指定一个 id添加Draw中

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

4.2. get(featureId: string): ?Feature

根据要素的id返回Draw中的要素。没有返回 undefined！

• 实例

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

4.3. getFeatureIdsAt(point: { x: number, y: number }): Array

• 返回一个数组包含一组渲染在特定点的 featrue 的ids
• 注意点要素的轴坐标是（x，y）坐标所在的像素空间，而不是经纬度度坐标！
• 通过这个函数，你可以使用鼠标提供的坐标来获取Draw的相关信息。

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

4.4. getSelectedIds(): Array

• 返回被选中要素的id集合。

4.5. getSelected(): FeatureCollection

• 返回被选中要素的 Featrue集合

4.6. getSelectedPoints(): FeatureCollection

• 返回一个要素集合包含被选中的所有顶点。

4.7. getAll(): FeatureCollection

• 返回Draw中多有的Featrue
  示例：

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

4.8. delete(ids: string | Array): draw

• 根据 ids 删除Draw中的要素，并返回 Draw 的实例。
• 在 direct-mode模式中，删除一个激活的要素会停止direct-mode模式转换到 simple_select中

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

4.9. deleteAll(): draw

• 删除素有Featrue

4.10. set(featureCollection: FeatureCollection): Array

• 将 Draw中的要素替换为指定集合的 Featrue.

4.11. trash(): draw

• 调用当前模式中的 trash 方法，返回 draw 实例。
• 在 simple_mode模式中，此方法会删除所有选中的要素！
• 在 diret_mode模式中，此方法会删所有的选中顶点！
• 在 drawing modes 模式中，此方法会删除正在绘制的要素，并将Draw调整至simple_mode模式。
• 如果需要在无视不同模式的情况下删除要素，则建议使用delete 或 deleteAll 方法。

ps:不管是 simple-mode 还是 direct_mode, trash trash方法只能删除模式未被切换之前正在被绘制的要素！！！

4.12. combineFeatures(): draw

• 在 simple_mode 模式中，这将会吧所有的选中要素合并为一个多部份要素。只要他们属于以同一种类型！比如：
  1. 选中的是两个单一线要素 --> 一个多部份要素
  2. 选中的是一个单一线要素，一个多部份现在要素 --> 一个多部份要素
  3. 选中的是两个多部份现在要素 --> 一个多部份要素

当选择不同几何类型的特征时调用此函数不会导致任何更改。例如：

1. 一个点要素，线要素 --> 没有任何反应
2. 一个点=多部份线要素，多部份点要素 --> 没有任何反应

在 direct_mode模式中没有任何方法被调用！

4.13. uncombineFeatures(): draw

在 simple_select 模式中，这种方法将所有多部份要素分解到组成该要素的但各要素部分。

4.14. getMode(): string

• 返回当前的模式名称！

4.15. changeMode(mode: string, options?: Object): draw

• mode模式桉树必须是 Draw.modes 类中的类型！
• simple_select, direct_select, 和 draw_line_string modes 接受一个 options 对象！
  .

// `simple_select` options
{
  // Array of ids of features that will be initially selected
  featureIds: Array<string>
}
// `direct_select` options
{
  // The id of the feature that will be directly selected (required)
  featureId: string
}

// `draw_line_string` options
{
  // The id of the LineString to continue drawing
  featureId: string,
  // The point to continue drawing from
  from: Feature<Point>|Point|Array<number>
}

4.16. setFeatureProperty(featureId: string, property: string, value: any): draw

• 使用指定的id设置要素的属性值。返回用于链接的绘图实例。
• 如果您将Draw的功能用作应用程序中的主要数据存储，这将非常有用。

5. Events

Draw可以出发一些Events事件。所有的事件名称都由 draw. 开头，并且由Mapbox GL JS中的map对象执行回调函数，用户交互触发。

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

如果你通过程序手动调用 Draw API中的一个函数，任何与这个函数对应的事件不会被触发。 比如，如果你调用了draw.delete() 方法，就不会有相应的 draw.delete事件被触发。因为你已经知道自己干了什么。然而，后续事件可能会触发，这些事件与调用的函数没有直接对应关系。比如，你已经选择了一个要素，并且调用了 **draw.changeMode(‘draw_polygon’)**方法，你会看到 draw.modechange 事件也被调用了(这是因为draw.modechange事件与draw.changeMode('draw_polygon方法相关联)。但同时，你也可以发现 draw.selectionchange 方法也被调用了。这是因为在改变模式的时候，你也直接取消选择了这个要素。

5.1. draw.create

当一个要素被创建完成时触发。以下交互将会触发这个事件。

• 用户通过简单点击会创建一个点要素、一个线要素或者一个面要素的部分顶点，只有在用户双击时创建要素的组后一个顶点，或者按下 enter 键时，此时，Featrue才被创建完成。draw.create事件才被触发。
• draw.create回调函数中的参数 data 遵循一下格式。

{
  // Array of GeoJSON objects representing the features that were created
  features: Array<Object>
}

5.3. draw.combine

当一个要素或多个要素被合并时触发。以下交互将会触发这个事件。

• 在 simple_mode模式中，当要素被选中的时候，点击了 **Combine *** 按钮。
• 在 simple_mode模式中，在选中一个要素时，调用了**draw.combineFeatures()**方法。
• draw.combine回调函数中的参数 data 遵循一下格式。

{
  deletedFeatures: Array<Feature>, // Array of deleted features (those incorporated into new multifeatures)
  createdFeatures: Array<Feature> // Array of created multifeatures
}

5.4. draw.uncombine

当一个要素或多个要素被拆分时触发。以下交互将会触发这个事件。

• 在 simple_mode模式中，当一个或多个多部份要素被选中的时候，点击了 **Uncombine *** 按钮。非多部份要素要有可能被选择。
• 在 simple_mode模式中，当一个或多个多部份要素被选中的时候，调用了**draw.uncombineFeatures()**方法。非多部份要素要有可能被选择。
• draw.uncombine回调函数中的参数 data 遵循一下格式。

{
  deletedFeatures: Array<Object>, // Array of deleted multifeatures (split into features)
  createdFeatures: Array<Object> // Array of created features
}

5.5. draw.update

当一个要素或多个要素被更新时触发。以下交互事件将会触发这个事件，这些事件可以分为一下几类i。

• action: ‘move’
  • 在 simple_mode模式中，完成选中要素的移动操作。
• action: ‘change_coordinates’
  • 在 direct_select 模式中，完成选中要素的移动操作。
  • 在 direct_select 模式中，完成删除或者移动一个要素的顶点。
  • 在 direct_select 模式中，添加完成一个要素的顶点。
• draw.uncombine回调函数中的参数 data 遵循一下格式。

{  
  features: Array<Feature>, // Array of features that were updated
  action: string // Name of the action that triggered the update
}

5.6. draw.selectionchange

当一个要素或多个要素被选中或者被取消选中时触发。以下交互事件将会触发这个事件，

• 选中一个要素。

• 取消选中一个要素

• 当一个要素被选中时，点击选中另一个要素。

• 选中一个要素的顶点。

• 当一个要素的某一顶点被选中时，点击选中另一个顶点。

• 框线至少一个要素

• 完成绘制一个要素时（只有当完成创建要素后，要素才会被选中）

• 当一个要素已经被选中时，调用了 **draw.changeMode()**方法，这使得该要素被取消选中。

• 使用 draw.changeMode(‘simple_select’, { featureIds: […] }) 方法切换至 simple_select模式后，立刻选中某一个要素。

• 使用 draw.delete, draw.deleteAll 或者 draw.trash 方法删除要素。.

• draw.selectionchange回调函数中的参数 data 遵循一下格式。

{
  features: Array<Feature> // Array of features that are selected after the change
}

5.6. draw.modechange

当draw的模式改变时触发。以下交互事件将会触发这个事件，

• 点击绘制点要素、线要素或者面要素的按钮开始绘制（进入 draw_* 模式）。
• 在simple_select 模式中的时候，点击一个已经被选中的要素。（进入 direct_select 模式）
• 在direct_select 模式中的时候，点击空白区域没有选择任何一个要素。（进入 simple_select 模式）
  这个事件的调用时刻是在当前模式停止，另一个模式开始之前。在所有事件处理程序都被触发之前，渲染不会发生，因此您可以通过在draw.modechange处理程序中调用draw.changeMode（）来强制模式重定向。
• draw.modechange回调函数中的参数 data 遵循一下格式。

{  
  mode: string // The next mode, i.e. the mode that Draw is changing to
}

5.7. draw.render

当 Draw 在Mapbox GL JS的 map 对象上调用 setData() 后立即触发。这并不意味着setData()调用已经完成了 map 的更新，只是 map 正在被更新。

5.8. draw.actionable

随着Draw状态的变化而触发，以启用和禁用不同的操作。通过此事件，您可以知道draw.trash（）、draw.combineFeatures（）和draw.uncombineFeature（）是否有效。

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

6. Styling Draw

Draw使用的地图样式遵循Mapbox GL样式规范，但有一些注意事项。

• source
  GL Style Spec 要求 Mapbox GL JS 中的每一个 layer 有一个 source，然而，在Draw配置设置样式时，不需要提供一个 source。Draw为了提升是性能，会在不同 source 之间移动 Feaetrues。 因此，Draw 会自动提供一个叫作 mapbox-gl-draw-hot 和 mapbox-gl-draw-cold 的 source.

• id
  GL Style Spec 还需要一个 id. 你必须提供一个 id， Draw会在这个 id 之前添加 .hot 和 .cold 后最。

• 在自定义样式中，您将需要使用以下特征特性：
  
  Draw还提供了一些关于特征的属性，但它们不应用于样式。有关它们的详细信息，请参阅下面的“使用Mapbox GL JS的queryRenderedFeatures绘制”
  如果opts.userProperties设置为true，则功能的属性也可用于样式设置。所有用户属性都以user_作为前缀，以确保它们不会与Draw属性冲突。

6.1. Example Custom Styles

自定义样式

6.2. Using Draw with Mapbox GL JS’s queryRenderedFeatures