# L7 — Full Documentation > 蚂蚁集团 AntV 数据可视化团队推出的基于 WebGL 的开源大规模地理空间数据可视分析引擎。 - [Resource index](/llms.txt) - Canonical site: https://l7.antv.antgroup.com/zh/ - Source repository: https://github.com/antvis/L7 - Languages: zh ## 中文文档 ### api #### Component 组件 - Canonical page: https://l7.antv.antgroup.com/zh/api/component/component/ - Markdown source: https://l7.antv.antgroup.com/zh/api/component/component.md - Description: Component 组件 --- title: "Component 组件" description: "Component 组件" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/component/component/" --- L7 中的 Component 主要包含以下三种类型: - [Control 控件类型](/zh/api/component/control):指的是悬停在地图四周,可以对地图以及图层等元素进行信息呈现或交互的组件。 - [Popup 气泡类型](/zh/api/component/popup):用于在地图上指定经纬度位置展示气泡,气泡内容完全交由开发者自定义。 - [Marker 类型](/zh/api/component/marker):与 Popup 相似,不同的是 Marker 展示的内容不会在气泡内展示,而是完全交由开发者自定义。 #### Popup 信息框 - Canonical page: https://l7.antv.antgroup.com/zh/api/component/popup/ - Markdown source: https://l7.antv.antgroup.com/zh/api/component/popup.md - Description: Popup 信息框 --- title: "Popup 信息框" description: "Popup 信息框" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/component/popup/" --- Popup 是用于在地图上指定经纬度位置,展示自定义内容的气泡。 ## 说明 Popup 的锚点位置是由经纬度来表达的,当地图缩放/平移时,Popup 会自动计算相对于当前地图的坐标并且自动位移。换句话说,如果开发者需要在地图的**指定经纬度位置**展示信息气泡,可以考虑使用 Popup 组件来实现对应效果。 开发者可以自定义 Popup 主体展示内容: - 纯文本可以通过 `text` 配置或者 `setText` 方法控制 Popup 的展示文本。 - 自定义 DOM 可以通过 `html` 配置或者 `setHTML` 方法,支持传入 HTML 字符串或者 DOM 元素或数组的方式控制 Popup 的展示内容。 ## 使用 [示例](/zh/examples/component/popup/popup/) ```ts import { Scene, Popup } from '@antv/l7'; const scene = new Scene({ id: 'map', map: new GaodeMapV2({ // ... }), }); scene.on('loaded', () => { const popup = new Popup({ // 初始锚点经纬度 lngLat: { lng: 120, lat: 30, }, // Popup 标题 title: 'Popup Title', // Popup 内容 html: 'Popup Content', }); scene.addPopup(popup); // 更新 Popup 锚点经纬度 popup.setLngLat({ lng: 130, lat: 40, }); // 更新 Popup 内容 popup.setHTML('New Popup Content'); }); ``` ## 配置 | 名称 | 说明 | 类型 | 默认值 | | ------------------ | ------------------------------------------------------------------------ | ------------------------------ | ---------- | | lngLat | Popup 所在的经纬度 | `{ lng: number; lat: number }` | - | | text | Popup 内容展示的文本内容 | `string` | - | | html | Popup 内容展示的自定义 HTML,可以传 HTML 字符串,也可以传 DOM 对象或数组 | [ElementType](#elementtype) | - | | title | Popup 标题展示的自定义 HTML,可以传 HTML 字符串,也可以传 DOM 对象或数组 | [ElementType](#elementtype) | - | | closeOnClick | 点击地图区域时,是否关闭当前 Popup | `boolean` | `false` | | closeOnEsc | 点击 Esc 键时,是否关闭当前 Popup | `boolean` | `false` | | maxWidth | Popup 的最大宽度 | `string` | `240px` | | anchor | Popup 箭头位置,可以控制 Popup 相对于经纬度点的展示位置 | [AnchorType](#anchortype) | `'bottom'` | | offsets | Popup 相对于锚点的偏移 | `[number, number]` | `[0, 0]` | | autoPan | 当 Popup 展示或者位置发生变化时,地图是否要自动平移至 Popup 所在位置 | `boolean` | `false` | | autoClose | 当有其他 Popup 展示时,是否自动关闭当前气泡 | `boolean` | `true` | | followCursor | Popup 是否跟随光标移动,若设为 `true`,则 `lngLat` 配置无效 | `boolean` | `false` | | closeButton | 是否展示关闭 Popup 图标 | `boolean` | `true` | | closeButtonOffsets | 关闭 Popup 图标的相对偏移 | `[number, number]` | - | | stopPropagation | Popup 上的鼠标事件是否要阻止其冒泡 | `boolean` | `true` | ### ElementType ```ts type ElementType = HTMLElement | HTMLElement[] | DocumentFragment | Text | string; ``` ### AnchorType ```ts type AnchorType = | 'center' | 'top' | 'top-left' | 'top-right' | 'bottom' | 'bottom-left' | 'bottom-right' | 'left' | 'right'; ``` ## 方法 | 名称 | 说明 | 类型 | | ---------- | --------------------------- | -------------------------------------------------------------------- | | getOptions | 获取当前 Popup 配置 | `() => IPopupOption` | | setOptions | 更新当前 Popup 配置 | `(newOption: Partial) => this` | | show | 显示 Popup | `() => this` | | hide | 隐藏 Popup | `() => this` | | getIsShow | 判断当前气泡是否展示 | `() => boolean` | | setTitle | 设置 Popup 标题展示的 HTML | `(title: ElementType) => this` | | setHTML | 设置 Popup 内容展示的 HTML | `(html: ElementType) => this` | | setText | 设置 Popup 内容展示的文本 | `(text: string) => this` | | setLngLat | 设置 Popup 锚点所在经纬度 | `(lngLat: { lng: number; lat: number } \| [number, number]) => this` | | panToPopup | 将地图平移至当前 Popup 位置 | `() => this` | ## 事件 | 名称 | 说明 | 类型 | | ----- | ------------------ | ------------ | | open | Popup 被添加时触发 | `() => void` | | close | Popup 被移除时触发 | `() => void` | | show | Popup 显示时触发 | `() => void` | | hide | Popup 隐藏时触发 | `() => void` | #### DebugService - Canonical page: https://l7.antv.antgroup.com/zh/api/debug/debugservice/ - Markdown source: https://l7.antv.antgroup.com/zh/api/debug/debugservice.md - Description: DebugService --- title: "DebugService" description: "DebugService" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/debug/debugservice/" --- ## 简介 L7 在通过 debugService 的形式对外提供调试服务,通过 debugService 用户可以获得一些有助于性能监控的信息。 ### serEnable(enable: boolean) 用户可以通过 scene 初始化的时候和 debugService 提供的方法来开启监控。 ```js // 可以在 scene 初始化的时候打开监控 const scene = new Scene({ debug: true, // 默认为 false }); // 可以通过 debugService 单独控制监控 const debugService = scene.getDebugService(); debugService.serEnable(true); // 开启监控 ``` ### getLog(field: undefined | string | string[]): ILog[] | ILog | undefined 用户通过 getLog 方法获取日志,通过传入不通的参数,用户可以准确获得自己需要的日志内容。 ```js // 获取地图初始化日志 debugService.getLog('map'); // map 为固定值 // 在获取图层的创建日志时,为了获取到全部的数据,需要在 layer 创建完成之后获取 layer.on('inited', () => { debugService.getLog(layer.id); // 获取单个图层创建日志 }); layerAllLoad([pointLayer1, pointLayer2], () => { // layerAllLoad 自己实现监听 debugService.getLog([pointLayer1.id, pointLayer2.id]); // 获取多个图层创建日志 }); // 获取所有日志 debugService.getLog(); ``` - 通过 getLog 方法可以获得如下的日志信息 ```js const enum IDebugLog { MapInitStart = 'mapInitStart', // 地图初始化时间 LayerInitStart = 'layerInitStart', // 图层初始化开始时间 LayerInitEnd = 'layerInitEnd', // 图层初始化结束时间 SourceInitStart = 'sourceInitStart',// souce 初始化开始时间 SourceInitEnd = 'sourceInitEnd', // souce 初始化结束时间 // scale:将数据进行 scale 映射处理 => 将数据从定义域转化到值域 // 如: layer.size('v', [1, 10]); // 根据字段 v 表示的定义域将 size 的结果映射到 1 ~ 10 之间 ScaleInitStart = 'scaleInitStart', // scale 初始化开始时间 ScaleInitEnd = 'scaleInitEnd', // scale 初始化结束时间 // mapping:构建渲染数据 MappingStart = 'mappingStart', // mapping 初始化开始时间 MappingEnd = 'mappingEnd', // mapping 初始化结束时间 // build model:构建渲染使用的程序对象、构建网格、纹理等 BuildModelStart = 'buildModelStart',// souce 初始化开始时间 BuildModelEnd = 'buildModelEnd', // souce 初始化结束时间 } ``` ### renderDebug(enable: boolean) debugService 提供了监听图层渲染时间的便捷方法, 通过 renderDebug 开启。 ### on(name: string, options: any) debugService 支持事件监听,常用与监听渲染。 ```js debugService.on('renderEnd', renderInfo => { const { renderUid, // 当前帧渲染唯一编号 renderStart, // 当前帧渲染开始时间 renderEnd, // 当前帧渲染结束时间 renderDuration // 当前帧渲染时间 } = renderInfo; ... } ``` ### off(name: string, func: Function) debugService 事件取消监听。 #### Heatmap - Canonical page: https://l7.antv.antgroup.com/zh/api/heatmap_layer/heatmap/ - Markdown source: https://l7.antv.antgroup.com/zh/api/heatmap_layer/heatmap.md - Description: Heatmap --- title: "Heatmap" description: "Heatmap" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/heatmap_layer/heatmap/" --- ## 简介 热力图以特殊高亮的形式显示数据在地理区域的聚集程度,L7 提供了多种表现形式的热力图,通过切换 `shape` 参数,用户可以得到不同类型的热力图。 | shape 值 | 说明 | | ---------------- | -------------- | | `heatmap` | 经典高斯热力图 | | `heatmap3D` | 3D 热力图 | | `hexagon` | 六边形聚合 | | `hexagonColumn` | 六边形柱状聚合 | | `square` | 正方形聚合 | | `squareColumn` | 正方形柱状聚合 | | `triangle` | 三角形聚合 | | `triangleColumn` | 三角形柱状聚合 | | `cylinder` | 圆柱聚合 |
案例
```javascript import { HeatmapLayer } from '@antv/l7'; const layer = new HeatmapLayer() .source(data) .shape('heatmap') .size('mag', [0, 1.0]) // weight 映射通道 .style({ radius: 20, rampColors: { colors: ['#FF4818', '#F7B74A', '#FFF598', '#91EABC', '#2EA9A1', '#206C7C'], positions: [0, 0.2, 0.4, 0.6, 0.8, 1.0], }, }); ``` ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## source 图层数据使用经纬度格式,数据源支持 JSON、GeoJSON、CSV 三种数据格式。 - [GeoJSON](/zh/api/source/geojson/#point) - [CSV](/zh/api/source/csv/#parser) - [JSON](/zh/api/source/json/#点数据) 🌟 通常每种数据都需要相应的 parser 解析数据 🌟 热力图的数据使用和点图层保持一致。 ### GeoJSON ```js // 传入 GeoJSON 类型数据 *** L7 默认支持,不需要 parser 解析 var data = { type: 'FeatureCollection', features: [ { type: 'Feature', properties: {}, geometry: { type: 'Polygon', coordinates: [ [120, 30], ... ] }, }, ], }; var layer = new HeatmapLayer() .source(data) ``` ### CSV ```js // 传入 txt 类型数据 var data = `from,to,value,type,lng1,lat1,lng2,lat2 鎷夎惃,娴疯タ,6.91,move_out,91.111891,29.662557,97.342625,37.373799 鎷夎惃,鎴愰兘,4.79,move_out,91.111891,29.662557,104.067923,30.679943 鎷夎惃,閲嶅簡,2.41,move_out,91.111891,29.662557,106.530635,29.544606 鎷夎惃,鍖椾含,2.05,move_out,91.111891,29.662557,116.395645,39.929986 ...`; var layer = new HeatmapLayer().source(data, { parser: { type: 'csv', x: 'lng1', y: 'lat1', }, }); ``` ### JSON ```js // 传入 JSON 类型的数据 var data = [ { lng: 120, lat: 30 }, ... ] var layer = new HeatmapLayer() .source(data, { parser: { type: 'json', x: 'lng', y: 'lat', } }) ``` ## shape `shape` 方法用于指定热力图层绘制热力的类型,支持经典热力、蜂窝热力、网格热力等多种类型。 ```js layer.shape('heatmap'); ``` | shape 值 | 说明 | | ---------------- | ---------------------------------- | | `heatmap` | 2D 经典高斯热力图 | | `heatmap3D` | 3D 热力图,在 Z 轴方向展示热力强度 | | `hexagon` | 六边形网格(2D 平面) | | `hexagonColumn` | 六边形柱状网格(3D 拉伸) | | `square` | 正方形网格(2D 平面) | | `squareColumn` | 正方形柱状网格(3D 拉伸) | | `triangle` | 三角形网格(2D 平面) | | `triangleColumn` | 三角形柱状网格(3D 拉伸) | | `cylinder` | 圆柱聚合(3D 拉伸) | ### shape('heatmap') `shape` 为 `heatmap` 时,绘制 2D 经典高斯热力图,通过颜色渐变反映数据密度。 ### shape('heatmap3D') `shape` 为 `heatmap3D` 时,绘制 3D 热力图,在 Z 轴方向通过高度反映热力强度,需开启地图的 3D 视角。 ### shape('hexagon') / shape('hexagonColumn') 基于六边形网格的聚合热力,`hexagon` 为 2D 填充,`hexagonColumn` 为 3D 柱状拉伸。需配合 `transforms` 中 `type: 'hexagon'` 使用。 ### shape('square') / shape('squareColumn') 基于正方形网格的聚合热力,`square` 为 2D 填充,`squareColumn` 为 3D 柱状拉伸。需配合 `transforms` 中 `type: 'square'` 使用。 ### shape('triangle') / shape('triangleColumn') 基于三角形网格的聚合热力,`triangle` 为 2D 填充,`triangleColumn` 为 3D 柱状拉伸。需配合 `transforms` 中 `type: 'triangle'` 使用。 ### shape('cylinder') 基于圆形网格的聚合热力,以 3D 圆柱形式展示。需配合 `transforms` 中 `type: 'grid'` 使用。 ### transforms 网格热力和蜂窝热力的实现依赖配置 `transforms` 的参数,[具体说明使用](/zh/api/source/source/#transforms)。 ```js fetch('https://gw.alipayobjects.com/os/basement_prod/513add53-dcb2-4295-8860-9e7aa5236699.json') .then((res) => res.json()) .then((data) => { const layer = new HeatmapLayer({}) .source(data, { transforms: [ { type: 'hexagon', size: 100, field: 'h12', method: 'sum', }, ], }) .size('sum', [0, 600]) .shape('hexagonColumn') .style({ coverage: 0.8, angle: 0, }) .color( 'sum', [ '#094D4A', '#146968', '#1D7F7E', '#289899', '#34B6B7', '#4AC5AF', '#5FD3A6', '#7BE39E', '#A1EDB8', '#CEF8D6', ].reverse(), ); scene.addLayer(layer); }); ``` ## size size 方法用于映射权重字段,将数值范围归一化到 `[0, 1]`,作为热力强度使用。 ```js layer.size('weight', [0, 1.0]); ``` | 参数 | 类型 | 说明 | | ----- | ------------------ | ------------------------------- | | field | `string` | 数据字段名,用于映射热力权重 | | range | `[number, number]` | 映射的值域范围,通常为 `[0, 1]` | ## scale `scale` 方法设置数据字段映射方法,用于设将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 ### scale(field: string, scaleConfig: IScaleConfig) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleConfig` 列定义配置,对象类型 ```javascript interface IScaleConfig { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` ### ScaleTypeName `scale` 的类型可以分为 `3` 类 `11` 种,不同 `Scale` 的差异在于 `domain->range` 的转换方法的不同。
`range` 和 `domain` 是 `Scale` 中非常重要的两个参数。 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类型 | 度量类型 | | -------- | ----------------------------------------------------------------- | | 连续 | linear、log、pow、time、sequential、quantize、quantile、threshold | | 分类 | cat、time | | 常量 | identity | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 常量度量 某个字段是不变的常量。 #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging || Sequential 用于返回给定的颜色数组的统一非有理 B-spline 插值器函数,该数组将转换为RGB颜色。 ```js const scaleColors = d3interpolate.interpolateRgbBasis(colors); ``` ### IScaleConfig ```js interface IScaleConfig { type: ScaleTypeName; domain?: any[]; range?: any[]; neutral?: number; field?: string; unknown?: string; ticks?: any[]; nice?: boolean; clamp?: boolean; format?: () => any; } ``` ## style `style` 方法用于配制图层的样式,相同图层拥有不同的 `shape` 图形,不同 `shape` 的图层 `style` 方法接受不同的参数。 🌟 蜂窝热力图和网格热力图的 `style` 样式可以参考实际绘制的图层。 ```js layer.style({ opacity: 0.5, }); ``` ### common 通用 `style` 参数,所有图形都支持的参数。 | style | 类型 | 描述 | 默认值 | | ------- | -------- | ------------ | ------ | | opacity | `number` | 图形的透明度 | `1` | ### heatmap `shape` 为 `heatmap`、`heatmap3D` 类型的时候,绘制经典热力图。 | style | 类型 | 描述 | 默认值 | | ---------- | -------- | ------------ | ------ | | intensity | `number` | 热力的强度 | `10` | | radius | `number` | 热力点的半径 | `10` | | rampColors | `number` | 热力的色值 | `1` | #### rampColors - colors  颜色数组 - positions 数据区间 配置值域映射颜色的色带,值域的范围为 `[0 - 1]`, 对应的我们需要为每一个 `position` 位置设置一个颜色值。 ⚠️ colors, positions 的长度要相同 ```javascript layer.style({ rampColors: { colors: ['#FF4818', '#F7B74A', '#FFF598', '#91EABC', '#2EA9A1', '#206C7C'], positions: [0, 0.2, 0.4, 0.6, 0.8, 1.0], }, }); ``` ### hexagon 绘制蜂窝热力图。 | style | 类型 | 描述 | 默认值 | | -------- | -------- | ------------ | ------ | | angle | `number` | 图形旋转角度 | `0` | | coverage | `number` | 图形覆盖比率 | `0.9` | ### grid 绘制网格热力图。 | style | 类型 | 描述 | 默认值 | | -------- | -------- | ------------ | ------ | | coverage | `number` | 图形覆盖比率 | `1` | ## 图层通用方法 ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## 数据方法 ### source 数据 设置图层数据以及解析配置 `source(data, config)`。 - data { geojson | json | csv } - config   可选   数据源配置项 - parser 数据解析,默认是解析层 geojson - transforms [transform,transform ]  数据处理转换可设置多个 `parser` 和  `transforms` [见 source 文档](/zh/api/source/source)。 ```javascript layer.source(data, { parser: { type: 'csv', x: 'lng', y: 'lat', }, transforms: [ { type: 'map', callback: function (item) { const [x, y] = item.coordinates; item.lat = item.lat * 1; item.lng = item.lng * 1; item.v = item.v * 1; item.coordinates = [x * 1, y * 1]; return item; }, }, { type: 'hexagon', size: 6000, field: 'v', method: 'sum', }, ], }); ``` ### cluster 我们在使用 `cluster` 配置聚合图之后就可以使用一些聚合方法来获取对应参数。 #### getClusters(zoom: number): IFeatureCollection 获取指定缩放等级的聚合数据 - `zoom` 缩放等级 #### getClustersLeaves(id: string): IFeatureCollection 根据 `id` 获取聚合节点的数据,每个聚合节点会有一个唯一 `ID`。 - `id` 聚合节点的 `id` ```ts const source = layer.getSource(); source.getClustersLeaves(id); layer.on('click', (e) => { console.log(source.getClustersLeaves(e.feature.cluster_id)); }); ``` ## scale 数据度量 Scale 度量是将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 L7 目前支持连续、离散、枚举类型数据的Scale,并支持位置、形状、大小和颜色编码的映射。 在使用 L7 过程中,默认情况下不需要进行 Scale 的配置,因为 L7 会根据数据类型对 scale 推断,推断过程如下: 查看用户是否设置了 Scale,如果没有: 判断字段的第一条数据的字段类型,如果数据中不存在对应的字段: 认为是常量为固定值 如果是数字则为 'linear'; 如果是字符串类型 'cat'; ### scale [Scale 详细介绍](https://mp.weixin.qq.com/s/QyD1_ypu0PDwMxEz45v6Jg) 参数: (field: string, scaleOptions: IscaleOptions) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleOptions` 列定义配置,对象类型 - type scale 类型 - unknown 未匹配颜色 可选 默认透明 - domain 值域 可选 ```javascript interface IscaleOptions { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` #### 类型 Range 和 domain 是 Scale 中非常重要的两个参数 domain: 地图数据值的定义区间 range:视觉值的区间 不同Scale 的差异在于 domain->range 的转换方法的不同 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类 | 度量类型 | | --------- | ------------------------------------- | | 连续 | linear、log、pow | | 连续分类 | quantize quantile,threshold,diverging | | 分类 枚举 | cat | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 数据值和映射值相同 比如数据中value 字段记录了每个要素的颜色,数值既为要映射的结果值s ``` // 设置为 identify layer.scale('value', { type: 'identify' }); // 或者 layer.scale('value'); // L7 能够自动推断为 identify ``` #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging 离散分类通常与两种相反的色调一起使用,以显示从负值到中心到正值的变化。这些类型的地图显示了彼此相关的值的大小。 ### getScale(scaleName:string) 根据视觉通道名称获取 scale 实例,调用之前确保 layer 已经初始化完成 ```ts const scale = layer.getScale('color'); const color = scale(1); // 将数值转换成颜色 ``` 更多是方法 scale 示例使用 ## 视觉编码方法 可视化编码是将数据转换为可视形式的过程,L7 目前支持形状,大小,颜色 3 种视觉通道,你可以指定数据字段,为不同要素设置不同的图形属性。 案例 ### filter 数据过滤方法,支持回调函数,将数据映射为true | false, 结果为true 时可见 ```ts pointLayer.filter('type', (type) => { // 回调函数 if (type === 'a') { return false; } return true; }); ``` ### size 将数据值映射到图形的大小上的方法,size 方法具体的参数使用可以查看对应图层的详细文档 ```javascript pointLayer.size(10); // 常量 pointLayer.size('type'); // 使用字段映射到大小 pointLayer.size('type', [0, 10]); // 使用字段映射到大小,并指定最大值和最小值 pointLayer.size('type', (type) => { // 回调函数 if (type === 'a') { return 10; } return 5; }); ``` #### size(value) 传入数字常量,如  `pointLayer.size(20)` #### size(field) 根据 field 字段的值映射大小,使用默认的`最大值 max:10`  和`最小值 min: 1`。 #### size(field, callback) 使用回调函数控制图形大小。 - `callback`: function 回调函数。 ```javascript pointLayer.size('age', (value) => { if (value === 1) { return 5; } return 10; }); ``` ### color 将数据值映射到图形的颜色上的方法。 ```javascript layer.color('red'); // 常量颜色 layer.color('type'); // 对 type 字段进行映射,使用内置的颜色 layer.color('type', ['red', 'blue']); // 指定颜色 layer.color('type', (type) => { // 通过回调函数 if (type === 'a') { return 'red'; } return 'blue'; }); layer.color('type*value', (type, value) => { //多个参数,通过回调函数 if (type === 'a' && value > 100) { return 'red'; } return 'blue'; }); ``` #### color(value) 参数:`value` :string 只支持接收一个参数,value 可以是: - 映射至颜色属性的数据源字段名,如果数据源中不存在这个字段名的话,则按照常量进行解析,这个时候会使用 L7 默认提供的颜色。 - 也可以直接指定某一个具体的颜色值 color,如 '#fff', 'white','rgba(255,0,0,0.5)' ,rgb(255,0,1) 等。 如果数据为映射到颜色,默认为透明色不显示,如果需要设置该颜色,需要在scale 中设置 示例 ```javascript layer.color('name'); // 映射数据字段 layer.color('white'); // 指定颜色 ``` #### color(field, colors) 参数: - `field`: stringfield 为映射至颜色属性的数据源字段名,也支持指定多个参数。 - `colors`: string | array | function colors 的参数有以下情况:  如果为空,即未指定颜色的数组,那么使用内置的全局的颜色;如果需要指定颜色,则需要以数组格式传入,那么分类的颜色按照数组中的颜色确定。 ```javascript layer.scale('name',{ type:'quantile' unknown:'#ccc' // 设置无效颜色 }) layer.color('name'); // 使用identity layer.color('name', ['red', 'blue']); // 使用传入的指定颜色 ``` - colors 如果是回调函数,则该回调函数的参数为对应字段的数值,具体使用如下,当 color 映射为多个字段时,参数按照字段声明的顺序传入: ```javascript layer.color('gender', (value) => { if (value === 1) { return 'red'; } return 'blue'; }); layer.color('gender*age', (gender, age) => { if (age === 20 && gender == ' 男') { return 'red'; } return 'blue'; }); ``` ### shape 通常一种图层可以有多种表现形式,shape 方法用于指定图层具体的表现形式,以 PointLayer 的 shape 为例: ```javascript shape('circle'); // 圆形 shape('triangle'); // 三角形 shape('cylinder'); // 圆柱 ``` 案例 **shape(shape)** 参数 `shape` string - 只支持接收一个参数,指定几何图像对象绘制的形状。下表列出了不同的 图层 几何图形对象支持的 shape 形状 | layer 类型 | shape 类型 | 备注 | | ---------- | -------------------------------------------------------------------------------------- | ---- | | point | 2d:point,circle, square, triangle,hexagon,image,text 3d:circle,triangle,hexagon,square | | | line | line,arc, arc3d, greatcircle | | | polygon | fill,line, extrude | | **shape(field, shapes)** - shape 根据字段指定行形状,比如根据字段指定 PointLayer/imageLayer 的 icon 类型 ```javascript scene.addImage( '00', 'https://gw.alipayobjects.com/zos/basement_prod/604b5e7f-309e-40db-b95b-4fac746c5153.svg', ); scene.addImage( '01', 'https://gw.alipayobjects.com/zos/basement_prod/30580bc9-506f-4438-8c1a-744e082054ec.svg', ); scene.addImage( '02', 'https://gw.alipayobjects.com/zos/basement_prod/7aa1f460-9f9f-499f-afdf-13424aa26bbf.svg', ); const imageLayer = new PointLayer() .source(data, { parser: { type: 'json', x: 'longitude', y: 'latitude', }, }) .shape('name', ['00', '01', '02']) .size(20); scene.addLayer(imageLayer); ``` 案例 [在线案例](/zh/examples/point/image/image/) **shape(field, callback)** - shape 也支持回调函数的写法 ```javascript .shape('key', value => { if(value > 10) { return 'circle'; } else { return 'triangle'; } } ``` ### rotate 将数据值映射到图形的旋转角度上的方法,用于控制点图层图标/图形的旋转。 ```javascript layer.rotate(45); // 常量,所有元素旋转 45 度 layer.rotate('angle'); // 字段映射 layer.rotate('angle', [0, 360]); // 字段映射到角度范围 layer.rotate('angle', (angle) => { return angle * (Math.PI / 180); // 回调函数 }); ``` ### label 为图层设置标注(文字标签),将数据字段映射为标注内容显示在图层元素旁边。主要在特定图层类型(如 PointLayer 的文字标注)中生效。 ```javascript layer.label('name'); // 以 name 字段的值作为标注文本 layer.label('name', (name) => `${name}市`); // 回调函数处理标注文本 ``` ### style style 方法通常用于描述图层具体的样式,大多数图层会支持一些比较通用的属性, 如 opacity 属性,同时每个图层也会有仅限本图层支持的属性,如只有 CityBuildingLayer 支持的 windowColor 属性,每个图层具体要如何配置属性请查看每个图层的详细文档。 - opacity 设置透明度 大部分图层都支持 - stroke 线填充颜色 仅点图层支持 - strokeWidth 线的宽度 仅点图层支持 ```javascript layer.style({ opacity: 0.8, stroke: 'white', }); ``` - 样式数据映射🌟
在正常情况下,style 的参数会作用到一个图层上的所有图形,如一个 PointLayer 中有十个点,我们设置 opacity = 0.5, 这样十个点的透明度都是 0.5。
而在特殊情况下,我们可能需要为每个点分别设置一个透明度,这时候按照原来的方式直接设置 style 方法的 opacity 的值就无法满足需求了,为此我们需要提供特殊的赋值方式。
通常我们会根据传入图层的数据为图层的每个图形设置单独的值,因此我们称之为“样式数据映射”。
我们支持几种设置 style 中的参数从 source 数据中动态取值的写法。 ```javascript // 根据数据中的 v 字段的值设置点图层各个点的透明度 const data = [ { lng: 120, lat: 30, v: 0.5 }, ... ] const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat' } }) .shape('circle') .color('#f00') .size({ // 第一种写法 根据字段从 data 中直接取值 opacity: 'v'// opacity = 0.5 }); scene.addLayer(layer); ``` [在线案例](/zh/examples/point/text/style-map/) 从 `L7 2.5` 开始,各图层样式将逐步支持样式数据映射,目前支持样式数据映射的 `style` 参数如下: | layer 类型/shape | 支持的样式字段 | 备注 | | ---------------------- | ---------------------------------------------------- | --------------------------------- | | pointLayer/fill | opacity、strokeOpacity、strokeWidth、stroke、offsets | shape circle、triangle... | | pointLayer/image | opacity、offsets | offsets 经纬度偏移 | | pointLayer/normal | opacity、offsets | | | pointLayer/text | opacity、strokeWidth、stroke、textOffset | textOffset 相对文字画布位置的偏移 | | pointLayer/extrude | opacity | | | polygonLayer/fill | opacity | | | polygonLayer/extrude | opacity | | | lineLayer/line | opacity | | | lineLayer/arc | opacity、thetaOffset | thetaOffset 弧线的弯曲弧度 | | lineLayer/arc3d | opacity | | | lineLayer/great_circle | opacity | | 案例 [在线案例](/zh/examples/point/scatter/scatter-style-map/) ### texture 目前只在线图层上支持了纹理方法 - texture 方法支持传入由 scene.addImage 方法添加的全局 icon 贴图资源 ```javascript // 首先在全局加载图片资源 scene.addImage( 'plane', 'https://gw.alipayobjects.com/zos/bmw-prod/0ca1668e-38c2-4010-8568-b57cb33839b9.svg', ); const layer = new LineLayer({ blend: 'normal', }) .source(data, { parser: { type: 'json', x: 'lng1', y: 'lat1', x1: 'lng2', y1: 'lat2', }, }) .size(25) .shape('arc') .texture('plane') // 为图层绑定纹理 .color('#8C1EB2') .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 30, // 设置贴图纹理的间距 textureBlend: 'replace', // 设置纹理混合方式,默认值为 normal,可选值有 normal/replace 两种 }); ``` 案例 [在线案例](/zh/examples/line/animate/plane-animate2/) ## 图层更新方法 如果已经添加了图层,需要修改图层显示样式可以再次调用图形映射方法,然后调用 `scene.render()`更新渲染即可 ### scale 更新 重新调用scale 方法 ```tsx layer.scale('value', { type: 'quantile', }); scene.render(); ``` ### 数据映射 重新调用 color/size/filter/shape等方法 ```javascript layer.color('blue'); layer.size(10); scene.render(); ``` ### layer.style ```javascript layer.style({ opacity: 1, }); scene.render(); ``` ### setData(data, option?: {}) 更新 Source 数据 参数: - data 数据 - option 默认和初始配置项一致,如果数据格式相同可不设置 调用 setData 方法会自动更新图层渲染 ```javascript layer.setData(data); ``` ### setBlend(type: string) 设置图层叠加方法 参数: - type blend 类型 normal | additive | subtractive | max ## 图层控制方法 ### show() 图层显示 ```javascript layer.show(); ``` ### hide() 图层隐藏 ```javascript layer.hide(); ``` ### isVisible(): boolean 图层是否可见 ```javascript layer.isVisible(); ``` ### setIndex(zIndex: int) 设置图层绘制顺序 ```javascript layer.setIndex(1); ``` ### fitBounds() 缩放到图层范围 ```javascript layer.fitBounds(); ``` ### setMinZoom(zoom: number) 设置图层最小缩放等级 ```javascript layer.setMinZoom(zoom); ``` ### setMaxZoom(zoom: number) 设置图层最大缩放等级 参数 - zoom {number} ```javascript layer.setMaxZoom(zoom); ``` ### getMinZoom(): number 获取图层最小缩放等级 ```javascript const minZoom = layer.getMinZoom(); ``` ### getMaxZoom(): number 获取图层最大缩放等级 ```javascript const maxZoom = layer.getMaxZoom(); ``` ### destroy() 销毁图层,释放相关资源。场景调用 `removeLayer` 时会自动销毁图层,一般不需要手动调用。 ```javascript layer.destroy(); ``` ## 图层交互方法 ### active(activeOption | boolean) - 开启或者关闭 mousehover 元素高亮效果 - `activeOption` - `color`: 高亮颜色 - `mix`: 可选参数,默认为 0,表示高亮颜色是指定纯色,最大有效值是1,表示高亮色全部是底色 ```javascript activeOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.active(true); // 开启 Active 自定义高亮颜色 layer.active({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.active(false); ``` ### setActive(featureId: int) 根据元素 ID 设置指定元素 hover 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setActive(featureId); ``` ### select(selectOption | boolean) - 开启或者关闭 mouseclick 元素选中高亮效果 - selectOption - `color`: 选中高亮颜色 - `mix`: 可选参数,默认为 0,表示选中高亮颜色是指定纯色,最大有效值是1,表示选中高亮色全部是底色 ```javascript selectOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.select(true); // 开启 Active 自定义高亮颜色 layer.select({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.select(false); ``` ### setSelect(featureId: int) 根据元素 ID 设置指定元素 click 选中 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setSelect(featureId); ``` ### setAutoFit(autoFit: boolean) 让用户可以主动设置图层的 autoFit 参数
🌟 设置完该方法后会在图层发生更新的时候生效,如在 setData 之后触发 ```javascript // 使用方法 layer.setAutoFit(true); // 内部实现 public setAutoFit(autoFit: boolean): ILayer { this.updateLayerConfig({ autoFit, }); return this; } ``` ### getScale(attr: string) 支持单独获取某个图形经过 scale 计算后的值, 满足用户获取图层某些 feature 值的需求。 - attr scale 的属性值 ```javascript const data = [ { lng: 120, lat: 30, name: 'n1' }, { lng: 120, lat: 30, name: 'n2' }, ]; const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat', type: 'json', }, }) .shape('circle') .color('name', ['#f00', '#ff0']) .size('name', [20, 40]); scene.addLayer(layer); // 此时在 scene 上绘制两个点 // 一个颜色为黄色,大小为 40 的点,对应 name 为 n1 // 一个颜色为红色,大小为 20 的点,对应 name 为 n2 const colorScale = layer.getScale('color'); // 获取 color 方法产生的 scale const color1 = colorScale('n1'); // '#ff0' const color1 = colorScale('n2'); // '#f00' const sizeScale = layer.getScale('size'); // 获取 size 方法产生的 scale const size1 = sizeScale('n1'); // 40 const size2 = sizeScale('n2'); // 20 ``` ### getLegendItems(type: string) 不推荐使用,将废弃, 获取图例配置 - type 图例类型 - index 可选 默认 ```javascript layer.getLegendItems('color'); layer.getLegendItems('size'); ``` ### getLegend(type: string) getLegendItems方法的替代方法 该方法需要 返回值 - type 图例类型 - field 映射字段 - items 图例项 ```javascript layer.getLegend('color'); layer.getLegend('size'); ``` 注:rasterayer 只支持 color 类型 ## 图层掩模方法 ### addMask 添加 Mask 图层 ```ts const polygonLayer = new Polygon(); layer.addMask(polygonLayer); scene.render(); ``` ### removeMask ```ts const polygonLayer = new Polygon(); layer.removeMask(polygonLayer); scene.render(); ``` ### disableMask ```ts layer.disableMask(); scene.render(); ``` ### enableMask ```ts layer.enableMask(); scene.render(); ``` ## 鼠标事件 鼠标事件回调参数 target ```javascript layer.on(eventName, (target) => console.log(target)); ``` - x: number 鼠标  在地图位置 x 坐标 - y: number 鼠标  在地图位置 y 坐标 - type: string 鼠标事件类型 - lngLat: 经度度对象 {lng:number, lat: number }; 鼠标所在位置经纬度 - feature: any; 数据选中的地理要素信息 - featureId: number | null; 数据选中的地理要素的 ID ### click 点击事件 ```javascript layer.on('click', (e) => console.log(e)); ``` ### dblclick 双击 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mousemove 鼠标移动事件 ```javascript layer.on('mousemove', (e) => console.log(e)); ``` ### mouseout 鼠标移除 ```javascript layer.on('mouseout', (e) => console.log(e)); ``` ### mouseup 鼠标抬起 ```javascript layer.on('mouseup', (e) => console.log(e)); ``` ### mousedown 鼠标按下 ```javascript layer.on('mousedown', (e) => console.log(e)); ``` ### contextmenu 鼠标右键 ```javascript layer.on('contextmenu', (e) => console.log(e)); ``` ### dblclick 双击拾取元素 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mouseenter 鼠标进入图层要素时触发 ```javascript layer.on('mouseenter', (e) => console.log(e)); ``` ### unclick 点击未拾取到元素 ```javascript layer.on('unclick', (e) => console.log(e)); ``` ### unmousemove 鼠标移动未拾取到元素 ```javascript layer.on('unmousemove', (e) => console.log(e)); ``` ### unmouseup 鼠标抬起未拾取到元素 ```javascript layer.on('unmouseup', (e) => console.log(e)); ``` ### unmousedown 鼠标按下未拾取到元素 ```javascript layer.on('unmousedown', (e) => console.log(e)); ``` ### uncontextmenu 鼠标右键位拾取到元素 ```javascript layer.on('uncontextmenu', (e) => console.log(e)); ``` ### unpick 所有鼠标事件未拾取到 ```javascript layer.on('unpick', (e) => console.log(e)); ``` ### touchstart 移动端事件 touchstart ```javascript layer.on('touchstart', (e) => console.log(e)); ``` ### touchend 移动端事件 touchend ```javascript layer.on('touchend', (e) => console.log(e)); ``` 使用示例 ```javascript layer.on('click', (ev) => {}); // 鼠标左键点击图层事件 layer.on('mouseenter', (ev) => {}); // 鼠标进入图层要素 layer.on('mousemove', (ev) => {}); // 鼠标在图层上移动时触发 layer.on('mouseout', (ev) => {}); // 鼠标移出图层要素时触发 layer.on('mouseup', (ev) => {}); // 鼠标在图层上单击抬起时触发 layer.on('mousedown', (ev) => {}); // 鼠标在图层上单击按下时触发 layer.on('contextmenu', (ev) => {}); // 图层要素点击右键菜单 // 鼠标在图层外的事件 layer.on('unclick', (ev) => {}); // 图层外点击 layer.on('unmousemove', (ev) => {}); // 图层外移动 layer.on('unmouseup', (ev) => {}); // 图层外鼠标抬起 layer.on('unmousedown', (ev) => {}); // 图层外单击按下时触发 layer.on('uncontextmenu', (ev) => {}); // 图层外点击右键 layer.on('unpick', (ev) => {}); // 图层外的操作的所有事件 ``` ## 图层事件 ### inited 参数 option - target 当前 layer - type 事件类型 图层初始化完成后触发 ```javascript layer.on('inited', (option) => {}); ``` ### add 图层添加到 scene 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('add', (type) => console.log(type)); ``` ### remove 图层移除时触发 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('remove', (type) => console.log(type)); ``` ### legend 数据映射更新,图例发生变化,主要 color、size ### `legend:color` 数据映射更新,图例 color 颜色改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:color', (ev) => console.log(ev)); ``` ### `legend:size` 数据映射更新,图例 size 大小改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:size', (ev) => console.log(ev)); ``` ## 图层框选 ### boxSelect 参数 option - box [x1: number, y1: number, x2: number, y2: number] 相较于 - cb (...args: any[]) => void 传入的回调方法,返回框选内部的 feature ```javascript layer.boxSelect(box, cb); // (x1, y1), (x2, y2) 框选的方框左上角和右下角相对于地图左上角的像素坐标 // cb 是传入的回调函数,回调函数返回的参数是选中的 feature 对象数组,对象的字段和用户传入的数据相关 ``` #### ImageLayer - Canonical page: https://l7.antv.antgroup.com/zh/api/image_layer/imagelayer/ - Markdown source: https://l7.antv.antgroup.com/zh/api/image_layer/imagelayer.md - Description: ImageLayer --- title: "ImageLayer" description: "ImageLayer" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/image_layer/imagelayer/" --- ## 简介 图片图层将图片叠加到地图上,需要指定图片的经纬度范围(`extent`)和数据解析类型。支持 PNG、JPG、WebP 等常见图片格式。
案例
```javascript import { ImageLayer } from '@antv/l7'; const layer = new ImageLayer({}); layer.source('https://gw.alipayobjects.com/zos/rmsportal/FnHFeFklTzKDdUESRNDv.jpg', { parser: { type: 'image', extent: [121.168, 30.2828, 121.384, 30.4219], }, }); ``` ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## source `imagelayer` 通过提供在线图片的 `url` 指定数据,通过 `extent` 指定图片在地图上的矩形范围的位置。 ```js layer.source('https://gw.alipayobjects.com/zos/rmsportal/FnHFeFklTzKDdUESRNDv.jpg', { parser: { type: 'image', extent: [121.168, 30.2828, 121.384, 30.4219], }, }); ``` 也可通过 `coordinates` 指定一系列坐,来定义图片在地图上的不规则形状范围的位置。 ```js layer.source('https://gw.alipayobjects.com/zos/rmsportal/FnHFeFklTzKDdUESRNDv.jpg', { parser: { type: 'image', coordinates: [ [100.959388, 41.619522], [101.229887, 41.572654], [101.16971, 41.377836], [100.900015, 41.424628], ], }, }); ``` ## style `imagelayer` 的 `style` 参数只支持 `opacity`。 | style | 类型 | 描述 | 默认值 | | ---------- | -------- | ------------ | ------ | | opacity | `number` | 图形的透明度 | `1` | | brightness | `number` | 图形的亮度 | `1` | | contrast | `number` | 图形的对比度 | `1` | | saturation | `number` | 图形的饱和度 | `1` | | gamma | `number` | 图形的伽马值 | `1` | ## 图层通用方法 ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## 数据方法 ### source 数据 设置图层数据以及解析配置 `source(data, config)`。 - data { geojson | json | csv } - config   可选   数据源配置项 - parser 数据解析,默认是解析层 geojson - transforms [transform,transform ]  数据处理转换可设置多个 `parser` 和  `transforms` [见 source 文档](/zh/api/source/source)。 ```javascript layer.source(data, { parser: { type: 'csv', x: 'lng', y: 'lat', }, transforms: [ { type: 'map', callback: function (item) { const [x, y] = item.coordinates; item.lat = item.lat * 1; item.lng = item.lng * 1; item.v = item.v * 1; item.coordinates = [x * 1, y * 1]; return item; }, }, { type: 'hexagon', size: 6000, field: 'v', method: 'sum', }, ], }); ``` ### cluster 我们在使用 `cluster` 配置聚合图之后就可以使用一些聚合方法来获取对应参数。 #### getClusters(zoom: number): IFeatureCollection 获取指定缩放等级的聚合数据 - `zoom` 缩放等级 #### getClustersLeaves(id: string): IFeatureCollection 根据 `id` 获取聚合节点的数据,每个聚合节点会有一个唯一 `ID`。 - `id` 聚合节点的 `id` ```ts const source = layer.getSource(); source.getClustersLeaves(id); layer.on('click', (e) => { console.log(source.getClustersLeaves(e.feature.cluster_id)); }); ``` ## scale 数据度量 Scale 度量是将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 L7 目前支持连续、离散、枚举类型数据的Scale,并支持位置、形状、大小和颜色编码的映射。 在使用 L7 过程中,默认情况下不需要进行 Scale 的配置,因为 L7 会根据数据类型对 scale 推断,推断过程如下: 查看用户是否设置了 Scale,如果没有: 判断字段的第一条数据的字段类型,如果数据中不存在对应的字段: 认为是常量为固定值 如果是数字则为 'linear'; 如果是字符串类型 'cat'; ### scale [Scale 详细介绍](https://mp.weixin.qq.com/s/QyD1_ypu0PDwMxEz45v6Jg) 参数: (field: string, scaleOptions: IscaleOptions) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleOptions` 列定义配置,对象类型 - type scale 类型 - unknown 未匹配颜色 可选 默认透明 - domain 值域 可选 ```javascript interface IscaleOptions { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` #### 类型 Range 和 domain 是 Scale 中非常重要的两个参数 domain: 地图数据值的定义区间 range:视觉值的区间 不同Scale 的差异在于 domain->range 的转换方法的不同 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类 | 度量类型 | | --------- | ------------------------------------- | | 连续 | linear、log、pow | | 连续分类 | quantize quantile,threshold,diverging | | 分类 枚举 | cat | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 数据值和映射值相同 比如数据中value 字段记录了每个要素的颜色,数值既为要映射的结果值s ``` // 设置为 identify layer.scale('value', { type: 'identify' }); // 或者 layer.scale('value'); // L7 能够自动推断为 identify ``` #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging 离散分类通常与两种相反的色调一起使用,以显示从负值到中心到正值的变化。这些类型的地图显示了彼此相关的值的大小。 ### getScale(scaleName:string) 根据视觉通道名称获取 scale 实例,调用之前确保 layer 已经初始化完成 ```ts const scale = layer.getScale('color'); const color = scale(1); // 将数值转换成颜色 ``` 更多是方法 scale 示例使用 ## 视觉编码方法 可视化编码是将数据转换为可视形式的过程,L7 目前支持形状,大小,颜色 3 种视觉通道,你可以指定数据字段,为不同要素设置不同的图形属性。 案例 ### filter 数据过滤方法,支持回调函数,将数据映射为true | false, 结果为true 时可见 ```ts pointLayer.filter('type', (type) => { // 回调函数 if (type === 'a') { return false; } return true; }); ``` ### size 将数据值映射到图形的大小上的方法,size 方法具体的参数使用可以查看对应图层的详细文档 ```javascript pointLayer.size(10); // 常量 pointLayer.size('type'); // 使用字段映射到大小 pointLayer.size('type', [0, 10]); // 使用字段映射到大小,并指定最大值和最小值 pointLayer.size('type', (type) => { // 回调函数 if (type === 'a') { return 10; } return 5; }); ``` #### size(value) 传入数字常量,如  `pointLayer.size(20)` #### size(field) 根据 field 字段的值映射大小,使用默认的`最大值 max:10`  和`最小值 min: 1`。 #### size(field, callback) 使用回调函数控制图形大小。 - `callback`: function 回调函数。 ```javascript pointLayer.size('age', (value) => { if (value === 1) { return 5; } return 10; }); ``` ### color 将数据值映射到图形的颜色上的方法。 ```javascript layer.color('red'); // 常量颜色 layer.color('type'); // 对 type 字段进行映射,使用内置的颜色 layer.color('type', ['red', 'blue']); // 指定颜色 layer.color('type', (type) => { // 通过回调函数 if (type === 'a') { return 'red'; } return 'blue'; }); layer.color('type*value', (type, value) => { //多个参数,通过回调函数 if (type === 'a' && value > 100) { return 'red'; } return 'blue'; }); ``` #### color(value) 参数:`value` :string 只支持接收一个参数,value 可以是: - 映射至颜色属性的数据源字段名,如果数据源中不存在这个字段名的话,则按照常量进行解析,这个时候会使用 L7 默认提供的颜色。 - 也可以直接指定某一个具体的颜色值 color,如 '#fff', 'white','rgba(255,0,0,0.5)' ,rgb(255,0,1) 等。 如果数据为映射到颜色,默认为透明色不显示,如果需要设置该颜色,需要在scale 中设置 示例 ```javascript layer.color('name'); // 映射数据字段 layer.color('white'); // 指定颜色 ``` #### color(field, colors) 参数: - `field`: stringfield 为映射至颜色属性的数据源字段名,也支持指定多个参数。 - `colors`: string | array | function colors 的参数有以下情况:  如果为空,即未指定颜色的数组,那么使用内置的全局的颜色;如果需要指定颜色,则需要以数组格式传入,那么分类的颜色按照数组中的颜色确定。 ```javascript layer.scale('name',{ type:'quantile' unknown:'#ccc' // 设置无效颜色 }) layer.color('name'); // 使用identity layer.color('name', ['red', 'blue']); // 使用传入的指定颜色 ``` - colors 如果是回调函数,则该回调函数的参数为对应字段的数值,具体使用如下,当 color 映射为多个字段时,参数按照字段声明的顺序传入: ```javascript layer.color('gender', (value) => { if (value === 1) { return 'red'; } return 'blue'; }); layer.color('gender*age', (gender, age) => { if (age === 20 && gender == ' 男') { return 'red'; } return 'blue'; }); ``` ### shape 通常一种图层可以有多种表现形式,shape 方法用于指定图层具体的表现形式,以 PointLayer 的 shape 为例: ```javascript shape('circle'); // 圆形 shape('triangle'); // 三角形 shape('cylinder'); // 圆柱 ``` 案例 **shape(shape)** 参数 `shape` string - 只支持接收一个参数,指定几何图像对象绘制的形状。下表列出了不同的 图层 几何图形对象支持的 shape 形状 | layer 类型 | shape 类型 | 备注 | | ---------- | -------------------------------------------------------------------------------------- | ---- | | point | 2d:point,circle, square, triangle,hexagon,image,text 3d:circle,triangle,hexagon,square | | | line | line,arc, arc3d, greatcircle | | | polygon | fill,line, extrude | | **shape(field, shapes)** - shape 根据字段指定行形状,比如根据字段指定 PointLayer/imageLayer 的 icon 类型 ```javascript scene.addImage( '00', 'https://gw.alipayobjects.com/zos/basement_prod/604b5e7f-309e-40db-b95b-4fac746c5153.svg', ); scene.addImage( '01', 'https://gw.alipayobjects.com/zos/basement_prod/30580bc9-506f-4438-8c1a-744e082054ec.svg', ); scene.addImage( '02', 'https://gw.alipayobjects.com/zos/basement_prod/7aa1f460-9f9f-499f-afdf-13424aa26bbf.svg', ); const imageLayer = new PointLayer() .source(data, { parser: { type: 'json', x: 'longitude', y: 'latitude', }, }) .shape('name', ['00', '01', '02']) .size(20); scene.addLayer(imageLayer); ``` 案例 [在线案例](/zh/examples/point/image/image/) **shape(field, callback)** - shape 也支持回调函数的写法 ```javascript .shape('key', value => { if(value > 10) { return 'circle'; } else { return 'triangle'; } } ``` ### rotate 将数据值映射到图形的旋转角度上的方法,用于控制点图层图标/图形的旋转。 ```javascript layer.rotate(45); // 常量,所有元素旋转 45 度 layer.rotate('angle'); // 字段映射 layer.rotate('angle', [0, 360]); // 字段映射到角度范围 layer.rotate('angle', (angle) => { return angle * (Math.PI / 180); // 回调函数 }); ``` ### label 为图层设置标注(文字标签),将数据字段映射为标注内容显示在图层元素旁边。主要在特定图层类型(如 PointLayer 的文字标注)中生效。 ```javascript layer.label('name'); // 以 name 字段的值作为标注文本 layer.label('name', (name) => `${name}市`); // 回调函数处理标注文本 ``` ### style style 方法通常用于描述图层具体的样式,大多数图层会支持一些比较通用的属性, 如 opacity 属性,同时每个图层也会有仅限本图层支持的属性,如只有 CityBuildingLayer 支持的 windowColor 属性,每个图层具体要如何配置属性请查看每个图层的详细文档。 - opacity 设置透明度 大部分图层都支持 - stroke 线填充颜色 仅点图层支持 - strokeWidth 线的宽度 仅点图层支持 ```javascript layer.style({ opacity: 0.8, stroke: 'white', }); ``` - 样式数据映射🌟
在正常情况下,style 的参数会作用到一个图层上的所有图形,如一个 PointLayer 中有十个点,我们设置 opacity = 0.5, 这样十个点的透明度都是 0.5。
而在特殊情况下,我们可能需要为每个点分别设置一个透明度,这时候按照原来的方式直接设置 style 方法的 opacity 的值就无法满足需求了,为此我们需要提供特殊的赋值方式。
通常我们会根据传入图层的数据为图层的每个图形设置单独的值,因此我们称之为“样式数据映射”。
我们支持几种设置 style 中的参数从 source 数据中动态取值的写法。 ```javascript // 根据数据中的 v 字段的值设置点图层各个点的透明度 const data = [ { lng: 120, lat: 30, v: 0.5 }, ... ] const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat' } }) .shape('circle') .color('#f00') .size({ // 第一种写法 根据字段从 data 中直接取值 opacity: 'v'// opacity = 0.5 }); scene.addLayer(layer); ``` [在线案例](/zh/examples/point/text/style-map/) 从 `L7 2.5` 开始,各图层样式将逐步支持样式数据映射,目前支持样式数据映射的 `style` 参数如下: | layer 类型/shape | 支持的样式字段 | 备注 | | ---------------------- | ---------------------------------------------------- | --------------------------------- | | pointLayer/fill | opacity、strokeOpacity、strokeWidth、stroke、offsets | shape circle、triangle... | | pointLayer/image | opacity、offsets | offsets 经纬度偏移 | | pointLayer/normal | opacity、offsets | | | pointLayer/text | opacity、strokeWidth、stroke、textOffset | textOffset 相对文字画布位置的偏移 | | pointLayer/extrude | opacity | | | polygonLayer/fill | opacity | | | polygonLayer/extrude | opacity | | | lineLayer/line | opacity | | | lineLayer/arc | opacity、thetaOffset | thetaOffset 弧线的弯曲弧度 | | lineLayer/arc3d | opacity | | | lineLayer/great_circle | opacity | | 案例 [在线案例](/zh/examples/point/scatter/scatter-style-map/) ### texture 目前只在线图层上支持了纹理方法 - texture 方法支持传入由 scene.addImage 方法添加的全局 icon 贴图资源 ```javascript // 首先在全局加载图片资源 scene.addImage( 'plane', 'https://gw.alipayobjects.com/zos/bmw-prod/0ca1668e-38c2-4010-8568-b57cb33839b9.svg', ); const layer = new LineLayer({ blend: 'normal', }) .source(data, { parser: { type: 'json', x: 'lng1', y: 'lat1', x1: 'lng2', y1: 'lat2', }, }) .size(25) .shape('arc') .texture('plane') // 为图层绑定纹理 .color('#8C1EB2') .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 30, // 设置贴图纹理的间距 textureBlend: 'replace', // 设置纹理混合方式,默认值为 normal,可选值有 normal/replace 两种 }); ``` 案例 [在线案例](/zh/examples/line/animate/plane-animate2/) ## 图层更新方法 如果已经添加了图层,需要修改图层显示样式可以再次调用图形映射方法,然后调用 `scene.render()`更新渲染即可 ### scale 更新 重新调用scale 方法 ```tsx layer.scale('value', { type: 'quantile', }); scene.render(); ``` ### 数据映射 重新调用 color/size/filter/shape等方法 ```javascript layer.color('blue'); layer.size(10); scene.render(); ``` ### layer.style ```javascript layer.style({ opacity: 1, }); scene.render(); ``` ### setData(data, option?: {}) 更新 Source 数据 参数: - data 数据 - option 默认和初始配置项一致,如果数据格式相同可不设置 调用 setData 方法会自动更新图层渲染 ```javascript layer.setData(data); ``` ### setBlend(type: string) 设置图层叠加方法 参数: - type blend 类型 normal | additive | subtractive | max ## 图层控制方法 ### show() 图层显示 ```javascript layer.show(); ``` ### hide() 图层隐藏 ```javascript layer.hide(); ``` ### isVisible(): boolean 图层是否可见 ```javascript layer.isVisible(); ``` ### setIndex(zIndex: int) 设置图层绘制顺序 ```javascript layer.setIndex(1); ``` ### fitBounds() 缩放到图层范围 ```javascript layer.fitBounds(); ``` ### setMinZoom(zoom: number) 设置图层最小缩放等级 ```javascript layer.setMinZoom(zoom); ``` ### setMaxZoom(zoom: number) 设置图层最大缩放等级 参数 - zoom {number} ```javascript layer.setMaxZoom(zoom); ``` ### getMinZoom(): number 获取图层最小缩放等级 ```javascript const minZoom = layer.getMinZoom(); ``` ### getMaxZoom(): number 获取图层最大缩放等级 ```javascript const maxZoom = layer.getMaxZoom(); ``` ### destroy() 销毁图层,释放相关资源。场景调用 `removeLayer` 时会自动销毁图层,一般不需要手动调用。 ```javascript layer.destroy(); ``` ## 图层交互方法 ### active(activeOption | boolean) - 开启或者关闭 mousehover 元素高亮效果 - `activeOption` - `color`: 高亮颜色 - `mix`: 可选参数,默认为 0,表示高亮颜色是指定纯色,最大有效值是1,表示高亮色全部是底色 ```javascript activeOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.active(true); // 开启 Active 自定义高亮颜色 layer.active({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.active(false); ``` ### setActive(featureId: int) 根据元素 ID 设置指定元素 hover 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setActive(featureId); ``` ### select(selectOption | boolean) - 开启或者关闭 mouseclick 元素选中高亮效果 - selectOption - `color`: 选中高亮颜色 - `mix`: 可选参数,默认为 0,表示选中高亮颜色是指定纯色,最大有效值是1,表示选中高亮色全部是底色 ```javascript selectOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.select(true); // 开启 Active 自定义高亮颜色 layer.select({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.select(false); ``` ### setSelect(featureId: int) 根据元素 ID 设置指定元素 click 选中 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setSelect(featureId); ``` ### setAutoFit(autoFit: boolean) 让用户可以主动设置图层的 autoFit 参数
🌟 设置完该方法后会在图层发生更新的时候生效,如在 setData 之后触发 ```javascript // 使用方法 layer.setAutoFit(true); // 内部实现 public setAutoFit(autoFit: boolean): ILayer { this.updateLayerConfig({ autoFit, }); return this; } ``` ### getScale(attr: string) 支持单独获取某个图形经过 scale 计算后的值, 满足用户获取图层某些 feature 值的需求。 - attr scale 的属性值 ```javascript const data = [ { lng: 120, lat: 30, name: 'n1' }, { lng: 120, lat: 30, name: 'n2' }, ]; const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat', type: 'json', }, }) .shape('circle') .color('name', ['#f00', '#ff0']) .size('name', [20, 40]); scene.addLayer(layer); // 此时在 scene 上绘制两个点 // 一个颜色为黄色,大小为 40 的点,对应 name 为 n1 // 一个颜色为红色,大小为 20 的点,对应 name 为 n2 const colorScale = layer.getScale('color'); // 获取 color 方法产生的 scale const color1 = colorScale('n1'); // '#ff0' const color1 = colorScale('n2'); // '#f00' const sizeScale = layer.getScale('size'); // 获取 size 方法产生的 scale const size1 = sizeScale('n1'); // 40 const size2 = sizeScale('n2'); // 20 ``` ### getLegendItems(type: string) 不推荐使用,将废弃, 获取图例配置 - type 图例类型 - index 可选 默认 ```javascript layer.getLegendItems('color'); layer.getLegendItems('size'); ``` ### getLegend(type: string) getLegendItems方法的替代方法 该方法需要 返回值 - type 图例类型 - field 映射字段 - items 图例项 ```javascript layer.getLegend('color'); layer.getLegend('size'); ``` 注:rasterayer 只支持 color 类型 ## 图层掩模方法 ### addMask 添加 Mask 图层 ```ts const polygonLayer = new Polygon(); layer.addMask(polygonLayer); scene.render(); ``` ### removeMask ```ts const polygonLayer = new Polygon(); layer.removeMask(polygonLayer); scene.render(); ``` ### disableMask ```ts layer.disableMask(); scene.render(); ``` ### enableMask ```ts layer.enableMask(); scene.render(); ``` ## 鼠标事件 鼠标事件回调参数 target ```javascript layer.on(eventName, (target) => console.log(target)); ``` - x: number 鼠标  在地图位置 x 坐标 - y: number 鼠标  在地图位置 y 坐标 - type: string 鼠标事件类型 - lngLat: 经度度对象 {lng:number, lat: number }; 鼠标所在位置经纬度 - feature: any; 数据选中的地理要素信息 - featureId: number | null; 数据选中的地理要素的 ID ### click 点击事件 ```javascript layer.on('click', (e) => console.log(e)); ``` ### dblclick 双击 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mousemove 鼠标移动事件 ```javascript layer.on('mousemove', (e) => console.log(e)); ``` ### mouseout 鼠标移除 ```javascript layer.on('mouseout', (e) => console.log(e)); ``` ### mouseup 鼠标抬起 ```javascript layer.on('mouseup', (e) => console.log(e)); ``` ### mousedown 鼠标按下 ```javascript layer.on('mousedown', (e) => console.log(e)); ``` ### contextmenu 鼠标右键 ```javascript layer.on('contextmenu', (e) => console.log(e)); ``` ### dblclick 双击拾取元素 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mouseenter 鼠标进入图层要素时触发 ```javascript layer.on('mouseenter', (e) => console.log(e)); ``` ### unclick 点击未拾取到元素 ```javascript layer.on('unclick', (e) => console.log(e)); ``` ### unmousemove 鼠标移动未拾取到元素 ```javascript layer.on('unmousemove', (e) => console.log(e)); ``` ### unmouseup 鼠标抬起未拾取到元素 ```javascript layer.on('unmouseup', (e) => console.log(e)); ``` ### unmousedown 鼠标按下未拾取到元素 ```javascript layer.on('unmousedown', (e) => console.log(e)); ``` ### uncontextmenu 鼠标右键位拾取到元素 ```javascript layer.on('uncontextmenu', (e) => console.log(e)); ``` ### unpick 所有鼠标事件未拾取到 ```javascript layer.on('unpick', (e) => console.log(e)); ``` ### touchstart 移动端事件 touchstart ```javascript layer.on('touchstart', (e) => console.log(e)); ``` ### touchend 移动端事件 touchend ```javascript layer.on('touchend', (e) => console.log(e)); ``` 使用示例 ```javascript layer.on('click', (ev) => {}); // 鼠标左键点击图层事件 layer.on('mouseenter', (ev) => {}); // 鼠标进入图层要素 layer.on('mousemove', (ev) => {}); // 鼠标在图层上移动时触发 layer.on('mouseout', (ev) => {}); // 鼠标移出图层要素时触发 layer.on('mouseup', (ev) => {}); // 鼠标在图层上单击抬起时触发 layer.on('mousedown', (ev) => {}); // 鼠标在图层上单击按下时触发 layer.on('contextmenu', (ev) => {}); // 图层要素点击右键菜单 // 鼠标在图层外的事件 layer.on('unclick', (ev) => {}); // 图层外点击 layer.on('unmousemove', (ev) => {}); // 图层外移动 layer.on('unmouseup', (ev) => {}); // 图层外鼠标抬起 layer.on('unmousedown', (ev) => {}); // 图层外单击按下时触发 layer.on('uncontextmenu', (ev) => {}); // 图层外点击右键 layer.on('unpick', (ev) => {}); // 图层外的操作的所有事件 ``` ## 图层事件 ### inited 参数 option - target 当前 layer - type 事件类型 图层初始化完成后触发 ```javascript layer.on('inited', (option) => {}); ``` ### add 图层添加到 scene 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('add', (type) => console.log(type)); ``` ### remove 图层移除时触发 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('remove', (type) => console.log(type)); ``` ### legend 数据映射更新,图例发生变化,主要 color、size ### `legend:color` 数据映射更新,图例 color 颜色改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:color', (ev) => console.log(ev)); ``` ### `legend:size` 数据映射更新,图例 size 大小改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:size', (ev) => console.log(ev)); ``` ## 图层框选 ### boxSelect 参数 option - box [x1: number, y1: number, x2: number, y2: number] 相较于 - cb (...args: any[]) => void 传入的回调方法,返回框选内部的 feature ```javascript layer.boxSelect(box, cb); // (x1, y1), (x2, y2) 框选的方框左上角和右下角相对于地图左上角的像素坐标 // cb 是传入的回调函数,回调函数返回的参数是选中的 feature 对象数组,对象的字段和用户传入的数据相关 ``` #### LineLayer - Canonical page: https://l7.antv.antgroup.com/zh/api/line_layer/linelayer/ - Markdown source: https://l7.antv.antgroup.com/zh/api/line_layer/linelayer.md - Description: LineLayer --- title: "LineLayer" description: "LineLayer" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/line_layer/linelayer/" --- ## 简介 线图层通过一组经纬度数据组来描述地图上的一条或者多条路径。通过路径的类型,将其区分为路径、弧线、3D 弧线以及其他的类型。
用户可以通过配置 `shape` 参数来选择线的类型,同时通过 `style`、`size`、`color` 方法调整线的样式。
案例
```js import { LineLayer } from '@antv/l7'; const layer = new LineLayer() .source([{ lng: 120, lat: 30, lng1: 125, lat1: 30 }], { parser: { type: 'json', x: 'lng', y: 'lat', x1: 'lng1', y1: 'lat1', }, }) .shape('line') .size(2) .color('#f00'); ``` ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## source 图层数据使用经纬度格式,数据源支持 JSON、GeoJSON、CSV 三种数据格式。 - [GeoJSON](/zh/api/source/geojson/#point) - [CSV](/zh/api/source/csv/#parser) - [JSON](/zh/api/source/json/#点数据) 🌟 通常每种数据都需要相应的 parser 解析数据 ### GeoJSON ```js // 传入 GeoJSON 类型数据 *** L7 默认支持,不需要 parser 解析 const data = { type: 'FeatureCollection', features: [ { type: 'Feature', properties: {}, geometry: { type: 'LineString', coordinates: [ [106.5234375, 57.51582286553883], [136.40625, 61.77312286453146], ], }, }, ], }; const layer = new LineLayer().source(data); ``` ### CSV ```js // 传入 txt 类型数据 var data = `from,to,value,type,lng1,lat1,lng2,lat2 鎷夎惃,娴疯タ,6.91,move_out,91.111891,29.662557,97.342625,37.373799 鎷夎惃,鎴愰兘,4.79,move_out,91.111891,29.662557,104.067923,30.679943 鎷夎惃,閲嶅簡,2.41,move_out,91.111891,29.662557,106.530635,29.544606 鎷夎惃,鍖椾含,2.05,move_out,91.111891,29.662557,116.395645,39.929986 ...`; new LineLayer().source(data, { parser: { type: 'csv', x: 'lng1', y: 'lat1', x1: 'lng2', y1: 'lat2', }, }); ``` ### JSON ```js // 传入 JSON 类型的数据 var data = [ { lng: 120, lat: 30, lng1: 125, lat1: 30 }, ... ] var layer = new LineLayer() .source(data, { parser: { type: 'json', x: 'lng', y: 'lat', x1: 'lng1', y1: 'lat1' } }) ``` ## shape `shape` 方法用于指定线图层绘制什么样的线。 ### shape('line') 绘制路径图。 `line` 路径是最普通的线图层,支持配置宽度和高度,支持配置纹理和动画。 ```js layer.shape('line'); ``` ### shape('arc') `arc` 弧线通过贝塞尔曲线算法计算出弧线的的路径,支持配置纹理和动画。 ```js layer.shape('arc'); ``` ### shape('arc3d') `arc3d` 3d 弧线是在垂直地图两点之间的弧线,具有高度,支持配置纹理和动画。 ```js layer.shape('arc3d'); ``` ### shape('greatcircle') `greatcircle` 大圆航线是地图两个点最近距离的连线,支持配置纹理和动画。 ```js layer.shape('greatcircle'); ``` ### shape('wall') `wall` 是垂直地图的围墙,支持配置高度,纹理和动画。 ```js layer.shape('wall'); ``` ### shape('simple') `simple` 线图层,宽度始终为 `1px`。 ```js layer.shape('simple'); ``` ### shape('flowline') `flowline` 流向图, 2.17 版本新增 ## color `color` 方法用于设置图形的颜色。 ### IColor: string `color` 类型的字符串。 - color 类型可以为 rgb 的写法 `rgb(200, 100, 100)`、`rgba(255, 0, 0, 1)` - color 类型可以为十六进制的写法 `#ffffff`、`#000` - color 类型可以是颜色名称的写法 `red`、`yellow` ### color(color: IColor) 图层可以直接设置颜色值。 ```js layer.color('#f00'); ``` ### color(field: string) 图层的颜色可以根据图层接受的数据值进行映射,接受传入数据的字段作为参数。 ```js layer.source([ { lng: 120, lat: 30, c: '#f00', }, ]); layer.color('c'); ``` ### color(field: string, domain: IColor[]) `color` 方法支持简单的值映射,将根据 `field` 从传入图层的数据中提取的值映射到 `domain` 值域中。 ```js layer.color('type', ['#f00', '#0f0', '#00f']); ``` ### color(field: string, callback: () => IColor ) `color` 方法支持回调函数的写法,将根据 `field` 作为 `callback` 方法的参数,`callback` 方法的返回值作为图层实际的颜色。 ```js layer.color('type', (value) => { switch (value) { case 'water': return '#f00'; case 'wood': return '#0f0'; } }); ``` ## size 线图层的 `size` 方法可以设置线的宽度和高度。 ### ILineSize: number | [number, number] - size 类型为 number 则表示 line 的宽度 - size 类型为 [number , number] 分别表示宽度和高度 ```javascript lineLayer.size(1); // 线的宽度为 1 lineLayer.size([1, 2]); // 宽度为1,高度2 ``` ### size(width: ILineSize) 线图层可以直接设置宽度值。图层中所有的线使用一个宽度。 ```js layer.size(2); ``` ### size(field: string) 线图层的宽度可以根据图层接受的数据值进行映射,接受传入数据的字段作为参数。 ```js layer.source({ type: 'Feature', properties: { lineSize: 2, }, geometry: { type: 'LineString', coordinates: [ [119.988511, 30.269614], [119.9851, 30.269323], [119.99271, 30.22088], ], }, }); layer.size('lineSize'); ``` ### size(field: string, domain: ILineSize[]) `size` 方法支持简单的值映射,将根据 `field` 从传入图层的数据中提取的值映射到 `domain` 值域中。 ```js layer.size('type', [1, 2, 3]); ``` ### size(field: string, callback: () => ILineSize ) `size` 方法支持回调函数的写法,将根据 `field` 作为 `callback` 方法的参数,`callback` 方法的返回值作为线图层实际的宽高。 ```js layer.size('type', (value) => { switch (value) { case 'path': return 1; case 'road': return 2; } }); ``` ## scale `scale` 方法设置数据字段映射方法,用于设将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 ### scale(field: string, scaleConfig: IScaleConfig) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleConfig` 列定义配置,对象类型 ```javascript interface IScaleConfig { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` ### ScaleTypeName `scale` 的类型可以分为 `3` 类 `11` 种,不同 `Scale` 的差异在于 `domain->range` 的转换方法的不同。
`range` 和 `domain` 是 `Scale` 中非常重要的两个参数。 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类型 | 度量类型 | | -------- | ----------------------------------------------------------------- | | 连续 | linear、log、pow、time、sequential、quantize、quantile、threshold | | 分类 | cat、time | | 常量 | identity | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 常量度量 某个字段是不变的常量。 #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging || Sequential 用于返回给定的颜色数组的统一非有理 B-spline 插值器函数,该数组将转换为RGB颜色。 ```js const scaleColors = d3interpolate.interpolateRgbBasis(colors); ``` ### IScaleConfig ```js interface IScaleConfig { type: ScaleTypeName; domain?: any[]; range?: any[]; neutral?: number; field?: string; unknown?: string; ticks?: any[]; nice?: boolean; clamp?: boolean; format?: () => any; } ``` ## style `style` 方法用于配制图层的样式,相同图层拥有不同的 `shape` 图形,不同 `shape` 的图层 `style` 方法接受不同的参数。 ```js layer.style({ opacity: 0.5, }); ``` ### common 通用 `style` 参数,所有图形都支持的参数。 | style | 类型 | 描述 | 数据映射 | 默认值 | | ------- | -------- | ------------ | -------- | ------ | | opacity | `number` | 图形的透明度 | 支持 | `1` | ### line `shape` 为 `line` 的普通线图层。 - [line](/zh/api/line_layer/shape#shapeline) - [支持渐变](/zh/api/line_layer/style#linear) - [支持纹理](/zh/api/line_layer/style#texture) - [支持虚线](/zh/api/line_layer/style#dash) | style | 类型 | 描述 | 支持数据映射 | 默认值 | | ------------- | -------------------------- | -------------------------- | ------------ | ----------- | | stroke | `string` | 图形边框颜色 | 是 | `#fff` | | strokeWidth | `number` | 图形边框半径 | 否 | `0` | | blur | `[number, number, number]` | 图形模糊分布 | 否 | `[1, 1, 1]` | | raisingHeight | `number` | 抬升高度 | 否 | `0` | | heightfixed | `boolean` | 抬升高度是否随 `zoom` 变化 | 否 | `false` | ### arc `shape` 为 `arc` 平面的弧线。 - [arc](/zh/api/line_layer/shape#shapearc) - [支持渐变](/zh/api/line_layer/style#linear) - [支持纹理](/zh/api/line_layer/style#texture) - [支持虚线](/zh/api/line_layer/style#dash) | style | 类型 | 描述 | 支持数据映射 | 默认值 | | ------------- | -------- | ---------------------------------- | ------------ | ------- | | segmentNumber | `number` | 弧线分段,分段越多越平滑,消耗越大 | 否 | `30` | | opacity | `number` | 透明度,支持数据映射 | 是 | `1` | | thetaOffset | `number` | 弧线的弧度参数 | 是 | `0.314` | ### arc3d `shape` 为 `arc3d` 的弧线图层。 - [arc3d](/zh/api/line_layer/shape#shapearc3d) - [支持渐变](/zh/api/line_layer/style#linear) - [支持纹理](/zh/api/line_layer/style#texture) - [支持虚线](/zh/api/line_layer/style#dash) | style | 类型 | 描述 | 支持数据映射 | 默认值 | | ------------- | -------- | ---------------------------------- | ------------ | ------ | | opacity | `number` | 透明度,支持数据映射 | 是 | `1` | | segmentNumber | `number` | 弧线分段,分段越多越平滑,消耗越大 | 否 | `30` | | thetaOffset | `number` | 弧线的弧度参数 | 是 | `1` | ### greatcircle `shape` 为大圆弧线图层。 - [greatcircle](/zh/api/line_layer/shape#shapegreatcircle) - [支持渐变](/zh/api/line_layer/style#linear) - [支持纹理](/zh/api/line_layer/style#texture) - [支持虚线](/zh/api/line_layer/style#dash) | style | 类型 | 描述 | 支持数据映射 | 默认值 | | ------------- | -------- | ---------------------------------- | ------------ | ------ | | opacity | `number` | 透明度,支持数据映射 | 是 | `1` | | segmentNumber | `number` | 弧线分段,分段越多越平滑,消耗越大 | 否 | `30` | ### flowline | style | 类型 | 描述 | 支持数据映射 | 默认值 | | ------------- | ----------------- | ------------------------ | ------------ | ------- | | opacity | `number` | 透明度,支持数据映射 | 是 | `1` | | strokeOpacity | `number` | 描边透明度 | 否 | `30` | | stroke | `number` | 描边颜色 | 是 | `#000` | | strokeWidth | `number` | 描边宽度 | `1` | 否 | | gapWidth | `number` | 不同方向两条线间距 | `2` | 否 | | offsets | `[number,number]` | 两端偏移量,支持数据映射 | 是 | `[0,0]` | flowline opacity 和 offsets 支持数据映射,数据驱动设置数据大小 #### opacity ```ts layer.style({ opacity: { field: 'count', // 映射字段 value: [0.2,0.4,0.6,0.8], // 映射值,支持回调函数,支持设置scale } // field 和 value 等同于 layer.color('count',[0.2,0.4,0.6,0.8]) ``` #### offsets ```ts layer.style({ offsets:{ field: 'count', values:() => { return [10 + Math.random()*20, 10 + Math.random()*20] } }) ``` ### wall `shape` 为 `wall` 地理围栏弧线图层。 - [wall](/zh/api/line_layer/shape#shapewall) - [支持渐变](/zh/api/line_layer/style#linear) - [支持纹理](/zh/api/line_layer/style#texture) ### simple `shape` 为 `simple` 简单线图层。 - [simple](/zh/api/line_layer/shape#shapesimple) - [支持渐变](/zh/api/line_layer/style#linear) ### linear - line、arc、arc3d、greatcircle、wall、simple 线图层支持配置渐变效果,在配置渐变效果后会覆盖 `layer.color` 方法设置的颜色。 | style | 类型 | 描述 | 默认值 | | ----------- | ------------ | ---------- | ---------- | | sourceColor | `IColor` | 线起始颜色 | `/` | | targetColor | `IColor` | 线结尾颜色 | `/` | | linearDir | `ILinearDir` | 线渐变方向 | `vertical` | #### IColor ```js const color = `rgb(200, 100, 50)`; const color2 = '#ff0'; ``` #### ILinearDir - vertical 纵向(沿线方向) - horizontal 横向 ```js type ILinearDir = 'vertical' | 'horizontal'; ``` ### texture - line、arc、arc3d、greatcircle 线图层支持纹理以及纹理动画,纹理样式有自己的参数。 | style | 类型 | 描述 | 默认值 | | ------------ | --------------- | ------------------------------ | -------- | | lineTexture | `boolean` | 时候开启纹理能力 | `false` | | textureBlend | `ITextureBlend` | 纹理混合方式 | `normal` | | iconStep | `number` | 纹理贴图在线图层上面排布的间隔 | `100` | #### ITextureBlend 线图层的纹理在和线本身的颜色进行融合的时候支持两种,`normal` 和 `replace`。 - normal 纹理和线颜色混合 - replace 使用纹理替换线颜色 ```js type ITextureBlend = 'normal' | 'replace'; ``` #### texture advance ✨ animate
当线图层 (shape 为 arc/arc3d) 开启动画模式的时候,纹理在线图层上的分布还会和 animate 的参数相关 线图层上排列的纹理的数量大致为 duration/interval ```javascript .animate({ duration: 1, interval: 0.2, trailLength: 0.1 }); // 此时 纹理贴图数量为 duration / interval = 5 ``` ✨ textureBlend 参数
通过控制 style 方法中的 textureBlend 参数,我们可以控制纹理图层和线图层的混合情况 - normal - replace ```javascript .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 30, // 设置贴图纹理的间距 textureBlend: 'replace', // 设置纹理混合方式,默认值为 normal,可选值有 normal/replace 两种 }); ``` ### dash - line、arc、arc3d、greatcircle 线图层支持配置虚线,虚线有自己额外的样式参数。 ```js layer.style({ lineType: 'dash' dashArray: [5, 5] }) ``` | style | 类型 | 描述 | 默认值 | | --------- | ------------ | ---------- | ------- | | lineType | `ILineType` | 线的类别 | `solid` | | dashArray | `IDashArray` | 虚线的间隔 | `/` | #### ILineType - solid 实线 - dash 虚线 #### IDashArray `dashArray` 只有在 `ILineType` 为 `dashed` 的时候才会生效。 ```js // len1 实线长度 len2 间隔长度 type IDashArray = [len1: number, len2: number] ``` ## animate 线图层图层在开启 `animate` 方法后会得到沿线方向的线动画。
案例
### animate(boolean | IAnimateOption) `animate` 方法支持布尔值和对象传值。 ```javascript layer.animate(true); layer.animate({ enable: true, }); ``` ### IAnimateOption ```javascript interface IAnimateOption { enable: boolean; speed: number; rings: number; } ``` ### animate #### 开启关闭动画 ```javascript layer.animate(true); layer.animate(false); ``` #### 设置动画参数 - duration 动画时间 单位(s)秒 - interval 轨迹间隔, 取值区间 0 - 1 - trailLength 轨迹长度 取值区间 0 - 1 ```javascript layer.animate({ duration: 4, interval: 0.2, trailLength: 0.1, }); ``` ##### 参数动画介绍 L7 目前动画参数为相对单位,我们默认一条线段的长度为 1 ![L7 动画参数](https://gw.alipayobjects.com/mdn/rms_855bab/afts/img/A*IBBfSIkb51cAAAAAAAAAAABkARQnAQ) 如果 interval = 0.2,则一条轨迹将会分成 5 段,如果 interval = 0.5 则为两段。 案例 [在线案例](/zh/examples/line/animate/plane-animate2/) ## texture 线图层支持纹理贴图和多种表现形式,通过 `scene.addImage` 方法添加到全局的资源,使用 `texture` 方法指定贴图。 ```javascript scene.addImage( '02', 'https://gw.alipayobjects.com/zos/bmw-prod/ce83fc30-701f-415b-9750-4b146f4b3dd6.svg', ); const layer = new LineLayer() .source(data) .size(4) .shape('line') .texture('02') .color('#25d8b7') .animate({ interval: 1, // 间隔 duration: 1, // 持续时间,延时 trailLength: 2, // 流线长度 }) .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 20, // 设置贴图纹理的间距 }); ```
案例
- lineTexture 指定是否开启纹理贴图能力 - iconStep 指定贴图在线图层上面排布的间隔 [在线案例](/zh/examples/gallery/animate/animate-path-texture/) #### texture advance ✨ animate
当线图层 (`shape` 为 `arc`/`arc3d`) 开启动画模式的时候,纹理在线图层上的分布还会和 `animate` 的参数相关. 线图层上排列的纹理的数量大致为 duration/interval ```javascript .animate({ duration: 1, interval: 0.2, trailLength: 0.1 }); // 此时 纹理贴图数量为 duration / interval = 5 ``` ✨ textureBlend 参数
通过控制 style 方法中的 textureBlend 参数,我们可以控制纹理图层和线图层的混合情况 - normal - replace ```javascript .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 30, // 设置贴图纹理的间距 textureBlend: 'replace', // 设置纹理混合方式,默认值为 normal,可选值有 normal/replace 两种 }); ``` [在线案例](zh/examples/line/animate#plane_animate2) ## 图层通用方法 ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## 数据方法 ### source 数据 设置图层数据以及解析配置 `source(data, config)`。 - data { geojson | json | csv } - config   可选   数据源配置项 - parser 数据解析,默认是解析层 geojson - transforms [transform,transform ]  数据处理转换可设置多个 `parser` 和  `transforms` [见 source 文档](/zh/api/source/source)。 ```javascript layer.source(data, { parser: { type: 'csv', x: 'lng', y: 'lat', }, transforms: [ { type: 'map', callback: function (item) { const [x, y] = item.coordinates; item.lat = item.lat * 1; item.lng = item.lng * 1; item.v = item.v * 1; item.coordinates = [x * 1, y * 1]; return item; }, }, { type: 'hexagon', size: 6000, field: 'v', method: 'sum', }, ], }); ``` ### cluster 我们在使用 `cluster` 配置聚合图之后就可以使用一些聚合方法来获取对应参数。 #### getClusters(zoom: number): IFeatureCollection 获取指定缩放等级的聚合数据 - `zoom` 缩放等级 #### getClustersLeaves(id: string): IFeatureCollection 根据 `id` 获取聚合节点的数据,每个聚合节点会有一个唯一 `ID`。 - `id` 聚合节点的 `id` ```ts const source = layer.getSource(); source.getClustersLeaves(id); layer.on('click', (e) => { console.log(source.getClustersLeaves(e.feature.cluster_id)); }); ``` ## scale 数据度量 Scale 度量是将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 L7 目前支持连续、离散、枚举类型数据的Scale,并支持位置、形状、大小和颜色编码的映射。 在使用 L7 过程中,默认情况下不需要进行 Scale 的配置,因为 L7 会根据数据类型对 scale 推断,推断过程如下: 查看用户是否设置了 Scale,如果没有: 判断字段的第一条数据的字段类型,如果数据中不存在对应的字段: 认为是常量为固定值 如果是数字则为 'linear'; 如果是字符串类型 'cat'; ### scale [Scale 详细介绍](https://mp.weixin.qq.com/s/QyD1_ypu0PDwMxEz45v6Jg) 参数: (field: string, scaleOptions: IscaleOptions) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleOptions` 列定义配置,对象类型 - type scale 类型 - unknown 未匹配颜色 可选 默认透明 - domain 值域 可选 ```javascript interface IscaleOptions { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` #### 类型 Range 和 domain 是 Scale 中非常重要的两个参数 domain: 地图数据值的定义区间 range:视觉值的区间 不同Scale 的差异在于 domain->range 的转换方法的不同 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类 | 度量类型 | | --------- | ------------------------------------- | | 连续 | linear、log、pow | | 连续分类 | quantize quantile,threshold,diverging | | 分类 枚举 | cat | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 数据值和映射值相同 比如数据中value 字段记录了每个要素的颜色,数值既为要映射的结果值s ``` // 设置为 identify layer.scale('value', { type: 'identify' }); // 或者 layer.scale('value'); // L7 能够自动推断为 identify ``` #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging 离散分类通常与两种相反的色调一起使用,以显示从负值到中心到正值的变化。这些类型的地图显示了彼此相关的值的大小。 ### getScale(scaleName:string) 根据视觉通道名称获取 scale 实例,调用之前确保 layer 已经初始化完成 ```ts const scale = layer.getScale('color'); const color = scale(1); // 将数值转换成颜色 ``` 更多是方法 scale 示例使用 ## 视觉编码方法 可视化编码是将数据转换为可视形式的过程,L7 目前支持形状,大小,颜色 3 种视觉通道,你可以指定数据字段,为不同要素设置不同的图形属性。 案例 ### filter 数据过滤方法,支持回调函数,将数据映射为true | false, 结果为true 时可见 ```ts pointLayer.filter('type', (type) => { // 回调函数 if (type === 'a') { return false; } return true; }); ``` ### size 将数据值映射到图形的大小上的方法,size 方法具体的参数使用可以查看对应图层的详细文档 ```javascript pointLayer.size(10); // 常量 pointLayer.size('type'); // 使用字段映射到大小 pointLayer.size('type', [0, 10]); // 使用字段映射到大小,并指定最大值和最小值 pointLayer.size('type', (type) => { // 回调函数 if (type === 'a') { return 10; } return 5; }); ``` #### size(value) 传入数字常量,如  `pointLayer.size(20)` #### size(field) 根据 field 字段的值映射大小,使用默认的`最大值 max:10`  和`最小值 min: 1`。 #### size(field, callback) 使用回调函数控制图形大小。 - `callback`: function 回调函数。 ```javascript pointLayer.size('age', (value) => { if (value === 1) { return 5; } return 10; }); ``` ### color 将数据值映射到图形的颜色上的方法。 ```javascript layer.color('red'); // 常量颜色 layer.color('type'); // 对 type 字段进行映射,使用内置的颜色 layer.color('type', ['red', 'blue']); // 指定颜色 layer.color('type', (type) => { // 通过回调函数 if (type === 'a') { return 'red'; } return 'blue'; }); layer.color('type*value', (type, value) => { //多个参数,通过回调函数 if (type === 'a' && value > 100) { return 'red'; } return 'blue'; }); ``` #### color(value) 参数:`value` :string 只支持接收一个参数,value 可以是: - 映射至颜色属性的数据源字段名,如果数据源中不存在这个字段名的话,则按照常量进行解析,这个时候会使用 L7 默认提供的颜色。 - 也可以直接指定某一个具体的颜色值 color,如 '#fff', 'white','rgba(255,0,0,0.5)' ,rgb(255,0,1) 等。 如果数据为映射到颜色,默认为透明色不显示,如果需要设置该颜色,需要在scale 中设置 示例 ```javascript layer.color('name'); // 映射数据字段 layer.color('white'); // 指定颜色 ``` #### color(field, colors) 参数: - `field`: stringfield 为映射至颜色属性的数据源字段名,也支持指定多个参数。 - `colors`: string | array | function colors 的参数有以下情况:  如果为空,即未指定颜色的数组,那么使用内置的全局的颜色;如果需要指定颜色,则需要以数组格式传入,那么分类的颜色按照数组中的颜色确定。 ```javascript layer.scale('name',{ type:'quantile' unknown:'#ccc' // 设置无效颜色 }) layer.color('name'); // 使用identity layer.color('name', ['red', 'blue']); // 使用传入的指定颜色 ``` - colors 如果是回调函数,则该回调函数的参数为对应字段的数值,具体使用如下,当 color 映射为多个字段时,参数按照字段声明的顺序传入: ```javascript layer.color('gender', (value) => { if (value === 1) { return 'red'; } return 'blue'; }); layer.color('gender*age', (gender, age) => { if (age === 20 && gender == ' 男') { return 'red'; } return 'blue'; }); ``` ### shape 通常一种图层可以有多种表现形式,shape 方法用于指定图层具体的表现形式,以 PointLayer 的 shape 为例: ```javascript shape('circle'); // 圆形 shape('triangle'); // 三角形 shape('cylinder'); // 圆柱 ``` 案例 **shape(shape)** 参数 `shape` string - 只支持接收一个参数,指定几何图像对象绘制的形状。下表列出了不同的 图层 几何图形对象支持的 shape 形状 | layer 类型 | shape 类型 | 备注 | | ---------- | -------------------------------------------------------------------------------------- | ---- | | point | 2d:point,circle, square, triangle,hexagon,image,text 3d:circle,triangle,hexagon,square | | | line | line,arc, arc3d, greatcircle | | | polygon | fill,line, extrude | | **shape(field, shapes)** - shape 根据字段指定行形状,比如根据字段指定 PointLayer/imageLayer 的 icon 类型 ```javascript scene.addImage( '00', 'https://gw.alipayobjects.com/zos/basement_prod/604b5e7f-309e-40db-b95b-4fac746c5153.svg', ); scene.addImage( '01', 'https://gw.alipayobjects.com/zos/basement_prod/30580bc9-506f-4438-8c1a-744e082054ec.svg', ); scene.addImage( '02', 'https://gw.alipayobjects.com/zos/basement_prod/7aa1f460-9f9f-499f-afdf-13424aa26bbf.svg', ); const imageLayer = new PointLayer() .source(data, { parser: { type: 'json', x: 'longitude', y: 'latitude', }, }) .shape('name', ['00', '01', '02']) .size(20); scene.addLayer(imageLayer); ``` 案例 [在线案例](/zh/examples/point/image/image/) **shape(field, callback)** - shape 也支持回调函数的写法 ```javascript .shape('key', value => { if(value > 10) { return 'circle'; } else { return 'triangle'; } } ``` ### rotate 将数据值映射到图形的旋转角度上的方法,用于控制点图层图标/图形的旋转。 ```javascript layer.rotate(45); // 常量,所有元素旋转 45 度 layer.rotate('angle'); // 字段映射 layer.rotate('angle', [0, 360]); // 字段映射到角度范围 layer.rotate('angle', (angle) => { return angle * (Math.PI / 180); // 回调函数 }); ``` ### label 为图层设置标注(文字标签),将数据字段映射为标注内容显示在图层元素旁边。主要在特定图层类型(如 PointLayer 的文字标注)中生效。 ```javascript layer.label('name'); // 以 name 字段的值作为标注文本 layer.label('name', (name) => `${name}市`); // 回调函数处理标注文本 ``` ### style style 方法通常用于描述图层具体的样式,大多数图层会支持一些比较通用的属性, 如 opacity 属性,同时每个图层也会有仅限本图层支持的属性,如只有 CityBuildingLayer 支持的 windowColor 属性,每个图层具体要如何配置属性请查看每个图层的详细文档。 - opacity 设置透明度 大部分图层都支持 - stroke 线填充颜色 仅点图层支持 - strokeWidth 线的宽度 仅点图层支持 ```javascript layer.style({ opacity: 0.8, stroke: 'white', }); ``` - 样式数据映射🌟
在正常情况下,style 的参数会作用到一个图层上的所有图形,如一个 PointLayer 中有十个点,我们设置 opacity = 0.5, 这样十个点的透明度都是 0.5。
而在特殊情况下,我们可能需要为每个点分别设置一个透明度,这时候按照原来的方式直接设置 style 方法的 opacity 的值就无法满足需求了,为此我们需要提供特殊的赋值方式。
通常我们会根据传入图层的数据为图层的每个图形设置单独的值,因此我们称之为“样式数据映射”。
我们支持几种设置 style 中的参数从 source 数据中动态取值的写法。 ```javascript // 根据数据中的 v 字段的值设置点图层各个点的透明度 const data = [ { lng: 120, lat: 30, v: 0.5 }, ... ] const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat' } }) .shape('circle') .color('#f00') .size({ // 第一种写法 根据字段从 data 中直接取值 opacity: 'v'// opacity = 0.5 }); scene.addLayer(layer); ``` [在线案例](/zh/examples/point/text/style-map/) 从 `L7 2.5` 开始,各图层样式将逐步支持样式数据映射,目前支持样式数据映射的 `style` 参数如下: | layer 类型/shape | 支持的样式字段 | 备注 | | ---------------------- | ---------------------------------------------------- | --------------------------------- | | pointLayer/fill | opacity、strokeOpacity、strokeWidth、stroke、offsets | shape circle、triangle... | | pointLayer/image | opacity、offsets | offsets 经纬度偏移 | | pointLayer/normal | opacity、offsets | | | pointLayer/text | opacity、strokeWidth、stroke、textOffset | textOffset 相对文字画布位置的偏移 | | pointLayer/extrude | opacity | | | polygonLayer/fill | opacity | | | polygonLayer/extrude | opacity | | | lineLayer/line | opacity | | | lineLayer/arc | opacity、thetaOffset | thetaOffset 弧线的弯曲弧度 | | lineLayer/arc3d | opacity | | | lineLayer/great_circle | opacity | | 案例 [在线案例](/zh/examples/point/scatter/scatter-style-map/) ### texture 目前只在线图层上支持了纹理方法 - texture 方法支持传入由 scene.addImage 方法添加的全局 icon 贴图资源 ```javascript // 首先在全局加载图片资源 scene.addImage( 'plane', 'https://gw.alipayobjects.com/zos/bmw-prod/0ca1668e-38c2-4010-8568-b57cb33839b9.svg', ); const layer = new LineLayer({ blend: 'normal', }) .source(data, { parser: { type: 'json', x: 'lng1', y: 'lat1', x1: 'lng2', y1: 'lat2', }, }) .size(25) .shape('arc') .texture('plane') // 为图层绑定纹理 .color('#8C1EB2') .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 30, // 设置贴图纹理的间距 textureBlend: 'replace', // 设置纹理混合方式,默认值为 normal,可选值有 normal/replace 两种 }); ``` 案例 [在线案例](/zh/examples/line/animate/plane-animate2/) ## 图层更新方法 如果已经添加了图层,需要修改图层显示样式可以再次调用图形映射方法,然后调用 `scene.render()`更新渲染即可 ### scale 更新 重新调用scale 方法 ```tsx layer.scale('value', { type: 'quantile', }); scene.render(); ``` ### 数据映射 重新调用 color/size/filter/shape等方法 ```javascript layer.color('blue'); layer.size(10); scene.render(); ``` ### layer.style ```javascript layer.style({ opacity: 1, }); scene.render(); ``` ### setData(data, option?: {}) 更新 Source 数据 参数: - data 数据 - option 默认和初始配置项一致,如果数据格式相同可不设置 调用 setData 方法会自动更新图层渲染 ```javascript layer.setData(data); ``` ### setBlend(type: string) 设置图层叠加方法 参数: - type blend 类型 normal | additive | subtractive | max ## 图层控制方法 ### show() 图层显示 ```javascript layer.show(); ``` ### hide() 图层隐藏 ```javascript layer.hide(); ``` ### isVisible(): boolean 图层是否可见 ```javascript layer.isVisible(); ``` ### setIndex(zIndex: int) 设置图层绘制顺序 ```javascript layer.setIndex(1); ``` ### fitBounds() 缩放到图层范围 ```javascript layer.fitBounds(); ``` ### setMinZoom(zoom: number) 设置图层最小缩放等级 ```javascript layer.setMinZoom(zoom); ``` ### setMaxZoom(zoom: number) 设置图层最大缩放等级 参数 - zoom {number} ```javascript layer.setMaxZoom(zoom); ``` ### getMinZoom(): number 获取图层最小缩放等级 ```javascript const minZoom = layer.getMinZoom(); ``` ### getMaxZoom(): number 获取图层最大缩放等级 ```javascript const maxZoom = layer.getMaxZoom(); ``` ### destroy() 销毁图层,释放相关资源。场景调用 `removeLayer` 时会自动销毁图层,一般不需要手动调用。 ```javascript layer.destroy(); ``` ## 图层交互方法 ### active(activeOption | boolean) - 开启或者关闭 mousehover 元素高亮效果 - `activeOption` - `color`: 高亮颜色 - `mix`: 可选参数,默认为 0,表示高亮颜色是指定纯色,最大有效值是1,表示高亮色全部是底色 ```javascript activeOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.active(true); // 开启 Active 自定义高亮颜色 layer.active({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.active(false); ``` ### setActive(featureId: int) 根据元素 ID 设置指定元素 hover 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setActive(featureId); ``` ### select(selectOption | boolean) - 开启或者关闭 mouseclick 元素选中高亮效果 - selectOption - `color`: 选中高亮颜色 - `mix`: 可选参数,默认为 0,表示选中高亮颜色是指定纯色,最大有效值是1,表示选中高亮色全部是底色 ```javascript selectOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.select(true); // 开启 Active 自定义高亮颜色 layer.select({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.select(false); ``` ### setSelect(featureId: int) 根据元素 ID 设置指定元素 click 选中 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setSelect(featureId); ``` ### setAutoFit(autoFit: boolean) 让用户可以主动设置图层的 autoFit 参数
🌟 设置完该方法后会在图层发生更新的时候生效,如在 setData 之后触发 ```javascript // 使用方法 layer.setAutoFit(true); // 内部实现 public setAutoFit(autoFit: boolean): ILayer { this.updateLayerConfig({ autoFit, }); return this; } ``` ### getScale(attr: string) 支持单独获取某个图形经过 scale 计算后的值, 满足用户获取图层某些 feature 值的需求。 - attr scale 的属性值 ```javascript const data = [ { lng: 120, lat: 30, name: 'n1' }, { lng: 120, lat: 30, name: 'n2' }, ]; const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat', type: 'json', }, }) .shape('circle') .color('name', ['#f00', '#ff0']) .size('name', [20, 40]); scene.addLayer(layer); // 此时在 scene 上绘制两个点 // 一个颜色为黄色,大小为 40 的点,对应 name 为 n1 // 一个颜色为红色,大小为 20 的点,对应 name 为 n2 const colorScale = layer.getScale('color'); // 获取 color 方法产生的 scale const color1 = colorScale('n1'); // '#ff0' const color1 = colorScale('n2'); // '#f00' const sizeScale = layer.getScale('size'); // 获取 size 方法产生的 scale const size1 = sizeScale('n1'); // 40 const size2 = sizeScale('n2'); // 20 ``` ### getLegendItems(type: string) 不推荐使用,将废弃, 获取图例配置 - type 图例类型 - index 可选 默认 ```javascript layer.getLegendItems('color'); layer.getLegendItems('size'); ``` ### getLegend(type: string) getLegendItems方法的替代方法 该方法需要 返回值 - type 图例类型 - field 映射字段 - items 图例项 ```javascript layer.getLegend('color'); layer.getLegend('size'); ``` 注:rasterayer 只支持 color 类型 ## 图层掩模方法 ### addMask 添加 Mask 图层 ```ts const polygonLayer = new Polygon(); layer.addMask(polygonLayer); scene.render(); ``` ### removeMask ```ts const polygonLayer = new Polygon(); layer.removeMask(polygonLayer); scene.render(); ``` ### disableMask ```ts layer.disableMask(); scene.render(); ``` ### enableMask ```ts layer.enableMask(); scene.render(); ``` ## 鼠标事件 鼠标事件回调参数 target ```javascript layer.on(eventName, (target) => console.log(target)); ``` - x: number 鼠标  在地图位置 x 坐标 - y: number 鼠标  在地图位置 y 坐标 - type: string 鼠标事件类型 - lngLat: 经度度对象 {lng:number, lat: number }; 鼠标所在位置经纬度 - feature: any; 数据选中的地理要素信息 - featureId: number | null; 数据选中的地理要素的 ID ### click 点击事件 ```javascript layer.on('click', (e) => console.log(e)); ``` ### dblclick 双击 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mousemove 鼠标移动事件 ```javascript layer.on('mousemove', (e) => console.log(e)); ``` ### mouseout 鼠标移除 ```javascript layer.on('mouseout', (e) => console.log(e)); ``` ### mouseup 鼠标抬起 ```javascript layer.on('mouseup', (e) => console.log(e)); ``` ### mousedown 鼠标按下 ```javascript layer.on('mousedown', (e) => console.log(e)); ``` ### contextmenu 鼠标右键 ```javascript layer.on('contextmenu', (e) => console.log(e)); ``` ### dblclick 双击拾取元素 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mouseenter 鼠标进入图层要素时触发 ```javascript layer.on('mouseenter', (e) => console.log(e)); ``` ### unclick 点击未拾取到元素 ```javascript layer.on('unclick', (e) => console.log(e)); ``` ### unmousemove 鼠标移动未拾取到元素 ```javascript layer.on('unmousemove', (e) => console.log(e)); ``` ### unmouseup 鼠标抬起未拾取到元素 ```javascript layer.on('unmouseup', (e) => console.log(e)); ``` ### unmousedown 鼠标按下未拾取到元素 ```javascript layer.on('unmousedown', (e) => console.log(e)); ``` ### uncontextmenu 鼠标右键位拾取到元素 ```javascript layer.on('uncontextmenu', (e) => console.log(e)); ``` ### unpick 所有鼠标事件未拾取到 ```javascript layer.on('unpick', (e) => console.log(e)); ``` ### touchstart 移动端事件 touchstart ```javascript layer.on('touchstart', (e) => console.log(e)); ``` ### touchend 移动端事件 touchend ```javascript layer.on('touchend', (e) => console.log(e)); ``` 使用示例 ```javascript layer.on('click', (ev) => {}); // 鼠标左键点击图层事件 layer.on('mouseenter', (ev) => {}); // 鼠标进入图层要素 layer.on('mousemove', (ev) => {}); // 鼠标在图层上移动时触发 layer.on('mouseout', (ev) => {}); // 鼠标移出图层要素时触发 layer.on('mouseup', (ev) => {}); // 鼠标在图层上单击抬起时触发 layer.on('mousedown', (ev) => {}); // 鼠标在图层上单击按下时触发 layer.on('contextmenu', (ev) => {}); // 图层要素点击右键菜单 // 鼠标在图层外的事件 layer.on('unclick', (ev) => {}); // 图层外点击 layer.on('unmousemove', (ev) => {}); // 图层外移动 layer.on('unmouseup', (ev) => {}); // 图层外鼠标抬起 layer.on('unmousedown', (ev) => {}); // 图层外单击按下时触发 layer.on('uncontextmenu', (ev) => {}); // 图层外点击右键 layer.on('unpick', (ev) => {}); // 图层外的操作的所有事件 ``` ## 图层事件 ### inited 参数 option - target 当前 layer - type 事件类型 图层初始化完成后触发 ```javascript layer.on('inited', (option) => {}); ``` ### add 图层添加到 scene 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('add', (type) => console.log(type)); ``` ### remove 图层移除时触发 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('remove', (type) => console.log(type)); ``` ### legend 数据映射更新,图例发生变化,主要 color、size ### `legend:color` 数据映射更新,图例 color 颜色改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:color', (ev) => console.log(ev)); ``` ### `legend:size` 数据映射更新,图例 size 大小改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:size', (ev) => console.log(ev)); ``` ## 图层框选 ### boxSelect 参数 option - box [x1: number, y1: number, x2: number, y2: number] 相较于 - cb (...args: any[]) => void 传入的回调方法,返回框选内部的 feature ```javascript layer.boxSelect(box, cb); // (x1, y1), (x2, y2) 框选的方框左上角和右下角相对于地图左上角的像素坐标 // cb 是传入的回调函数,回调函数返回的参数是选中的 feature 对象数组,对象的字段和用户传入的数据相关 ``` #### 地图 Map - Canonical page: https://l7.antv.antgroup.com/zh/api/map/map/ - Markdown source: https://l7.antv.antgroup.com/zh/api/map/map.md - Description: 地图 Map --- title: "地图 Map" description: "地图 Map" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/map/map/" --- ## 简介 L7 地理可视化侧重于地理数据的可视化表达,地图层需要依赖第三方地图,第三方地图通过 Scene 统一创建,创建管理 只需要通过 Scene 传入地图配置项即可。 L7 在内部解决了不同地图底图之间差异,同时 L7 层面统一管理地图的操作方法。 - Map 独立地图引擎,不需要底图、或者加载地图瓦片服务,不需要 Token ## import ```javascript import { Map } from '@antv/l7-maps'; ``` ## Map 实例化 ```ts import { Scene, PointLayer } from '@antv/l7'; import { Map } from '@antv/l7-maps'; const scene = new Scene({ id: 'map', map: new Map({ zoom: 10, minZoom: 0, maxZoom: 18, }), }); scene.on('loaded', () => { // 添加地图底图 const layer = new RasterLayer(); layer.source( 'https://webrd0{1-3}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z}', { parser: { type: 'rasterTile', tileSize: 256, minZoom: 2, maxZoom: 18, }, }, ); scene.addLayer(layer); }); ``` ## options ### zoom 初始化缩放等级 _number_ 地图初始显示级别 {number} Mapbox (0-24) 高德 (2-19) ### center 地图中心 地图初始中心经纬度 {Lnglat} ### pitch 地图倾角 地图初始俯仰角度 {number} default 0 ### bearing 地图偏转角 地图初始旋转角度(相对于正北方向顺时针偏转的度数) {number} default 0 ### minZoom 最小缩放等级 地图最小缩放等级 {number} default 0 Mapbox 0-24) 高德 (2-19) ### maxZoom 最大缩放等级 地图最大缩放等级 {number} default 22 Mapbox(0-24) 高德 (2-19) ### minPitch 最小倾角 地图最小俯仰角 {number} default 0 ### maxPitch 最大倾角 地图最大俯仰角 {number} default 60 ### rotateEnable 是否允许旋转 地图是否可旋转 {Boolean} default true ### interactive 是否允许交互 _boolean_ **optional** _default:_ true 是否允许地图交互(包括鼠标、触摸、键盘等),设为 `false` 后地图变为静态展示状态 ### scrollZoom 是否允许滚轮缩放 _boolean_ **optional** _default:_ true 是否启用滚轮缩放交互 ### boxZoom 是否允许框选缩放 _boolean_ **optional** _default:_ true 是否启用框选缩放交互(按住 Shift 拖拽) ### dragRotate 是否允许拖拽旋转 _boolean_ **optional** _default:_ true 是否启用拖拽旋转交互 ### dragPan 是否允许拖拽平移 _boolean_ **optional** _default:_ true 是否启用拖拽平移交互 ### keyboard 是否允许键盘控制 _boolean_ **optional** _default:_ true 是否启用键盘快捷键控制地图 ### doubleClickZoom 是否允许双击缩放 _boolean_ **optional** _default:_ true 是否启用双击缩放交互 ### touchZoomRotate 是否允许触摸缩放旋转 _boolean_ **optional** _default:_ true 是否启用双指捏合缩放旋转交互 ### renderWorldCopies 是否渲染世界副本 _boolean_ **optional** _default:_ true 超出 -180 和 180 经度范围时,是否在两侧重复渲染地图 ### maxBounds 地图最大边界范围 限制地图可视范围在指定的地理范围内 ### bearingSnap 北向吸附阈值 _number_ **optional** _default:_ 7 当用户旋转地图接近正北方向时,自动吸附到正北方向的角度阈值(度数) ## 地图事件 Scene 统一代理,见 [Scene 文档](/zh/api/scene) 或者 scene.map 直接调用 map 实例方法 #### PlaneGeometry - Canonical page: https://l7.antv.antgroup.com/zh/api/other/plane/ - Markdown source: https://l7.antv.antgroup.com/zh/api/other/plane.md - Description: PlaneGeometry --- title: "PlaneGeometry" description: "PlaneGeometry" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/other/plane/" --- ## 简介 PlaneGeometry 是 L7 提供的通用的平面几何体图形,表现为可以自定义为位置,大小和分段数的贴地矩形。 ### demo 设置普通矩形 ```javascript import { Scene, GeometryLayer } from '@antv/l7'; const layer = new GeometryLayer() .shape('plane') .style({ opacity: 0.8, width: 0.074, height: 0.061, center: [120.1025, 30.2594], }) .active(true) .color('#ff0'); scene.addLayer(layer); ``` 案例 [在线案例](/zh/examples/geometry/geometry/plane/) 设置 3D 地形模式 ```javascript import { Scene, GeometryLayer } from '@antv/l7'; const layer = new GeometryLayer().shape('plane').style({ width: 0.074, height: 0.061, center: [120.1025, 30.2594], widthSegments: 200, heightSegments: 200, terrainClipHeight: 1, mapTexture: 'https://gw.alipayobjects.com/mdn/rms_23a451/afts/img/A*gA0NRbuOF5cAAAAAAAAAAAAAARQnAQ', terrainTexture: 'https://gw.alipayobjects.com/mdn/rms_23a451/afts/img/A*eYFaRYlnnOUAAAAAAAAAAAAAARQnAQ', rgb2height: (r, g, b) => { let h = (r * 255.0 * 256.0 * 256.0 + g * 255.0 * 256.0 + b * 255.0) * 0.1; h = h / 200 - 12750; h = Math.max(0, h); return h; }, }); scene.addLayer(layer); ``` 案例 [在线案例](/zh/examples/geometry/geometry/terrain/) ### source 🌟 PlaneGeometry 不需要设置 source,我们在 style 中通过 center 赋予其位置信息。 ### style PlaneGeometry 主要通过 style 方法设置位置、大小以及其他属性。 #### center: [lng: number, lat: number] 设置 PlaneGeometry 的位置,定位是 PlaneGeometry 的几何中心。PlaneGeometry 贴地放置。 #### width: number 设置 PlaneGeometry 的宽度,单位是经度。 #### height: number 设置 PlaneGeometry 的高度,单位是纬度。 #### widthSegments: number 设置 PlaneGeometry 在 纬度方向上的分段数。 #### heightSegments: number 设置 PlaneGeometry 在 经度方向上的分段数。 #### mapTexture: string PlaneGeometry 纹理贴图 URL。 #### terrainTexture: string PlaneGeometry 高度贴图 URL,当存在该参数的时候 L7 会自动解析高程信息。 #### terrainClipHeight: number 指定 3D 地形的裁剪高度。在一些情况下我们可能只需要保留存在丘陵山地的部分,通过这个参数我们可以指定地形高度低于这个参数值的部分不显示. 案例 #### rgb2height: (r: number, g: number, b: number) => number 这是一个回调函数,参数是 L7 解析出的地形贴图的 rgb 信息,用户可以使用该函数定义高度值的计算逻辑(不同的地形贴图计算逻辑不同)。 🌟 widthSegments/heightSegments 指定 planeGeometry 的分段数,分段越多,地形越平滑,同时性能消耗越大。 #### PointLayer - Canonical page: https://l7.antv.antgroup.com/zh/api/point_layer/pointlayer/ - Markdown source: https://l7.antv.antgroup.com/zh/api/point_layer/pointlayer.md - Description: PointLayer --- title: "PointLayer" description: "PointLayer" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/point_layer/pointlayer/" --- ## 简介 点图层通过一组经纬度数据来描述一系列点在地图上的位置,这些点可以是普通的圆点,也可以是文字、图标、柱子等。
用户可以通过配置 `shape` 参数来选择点的类型,同时通过 `style`、`size`、`color` 方法调整点的样式。 ```javascript import { PointLayer } from '@antv/l7'; const layer = new PointLayer({ zIndex: 2, }) .source(data.list, { type: 'array', x: 'j', y: 'w', }) .shape('cylinder') .size('t', (level) => { return [4, 4, level + 40]; }) .color('t', [ '#002466', '#105CB3', '#2894E0', '#CFF6FF', '#FFF5B8', '#FFAB5C', '#F27049', '#730D1C', ]); ``` ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## source 图层数据使用经纬度格式,数据源支持 JSON、GeoJSON、CSV 三种数据格式。 - [GeoJSON](/zh/api/source/geojson/#point) - [CSV](/zh/api/source/csv/#parser) - [JSON](/zh/api/source/json/#点数据) 🌟 通常每种数据都需要相应的 parser 解析数据 ### GeoJSON ```js // 传入 GeoJSON 类型数据 *** L7 默认支持,不需要 parser 解析 var data = { type: 'FeatureCollection', features: [ { type: 'Feature', properties: {}, geometry: { type: 'Polygon', coordinates: [ [120, 30], ... ] }, }, ], }; var layer = new PointLayer() .source(data) ``` ### CSV ```js // 传入 txt 类型数据 var data = `from,to,value,type,lng1,lat1,lng2,lat2 鎷夎惃,娴疯タ,6.91,move_out,91.111891,29.662557,97.342625,37.373799 鎷夎惃,鎴愰兘,4.79,move_out,91.111891,29.662557,104.067923,30.679943 鎷夎惃,閲嶅簡,2.41,move_out,91.111891,29.662557,106.530635,29.544606 鎷夎惃,鍖椾含,2.05,move_out,91.111891,29.662557,116.395645,39.929986 ...`; var layer = new PointLayer().source(data, { parser: { type: 'csv', x: 'lng1', y: 'lat1', }, }); ``` ### JSON ```js // 传入 JSON 类型的数据 var data = [ { lng: 120, lat: 30 }, ... ] var layer = new PointLayer() .source(data, { parser: { type: 'json', x: 'lng', y: 'lat', } }) ``` ## shape `shape` 方法用于指定点图层绘制什么样的图形,如绘制三角形或者是正方形,还是文字、图标之类的。 ### shape(fillShape: IFillShape) 点图层的贴地的几何图形,如圆形、正方形、三角形等。 🌟 若是使用简单的圆点图层,建议使用 `simple` 代替 `circle` 以获得更好的性能。
案例
```js // shape 支持的各种形状 type IFillShape = | 'circle' | 'square' | 'hexagon' | 'triangle' | 'pentagon' | 'octogon' | 'hexagram' | 'rhombus' | 'vesica'; layer.shape('circle'); ``` ### shape(column: IColumn) 点的类型为垂直地图的柱子。
案例
```js type IColumn = 'cylinder' | 'triangleColumn' | 'hexagonColumn' | 'squareColumn'; layer.shape('cylinder'); layer.shape('triangleColumn'); layer.shape('hexagonColumn'); layer.shape('squareColumn'); ``` ### shape('simple') `simple` 点精灵是特殊的点图层,始终面向相机,且大小受到设备的限制。 ```js layer.shape('simple'); ``` ### shape('dot') `dot` 点精灵是特殊的点图层,始终面向相机,且大小受到设备的限制。 ```js layer.shape('dot'); ``` ### shape(field: string, 'text') 绘制文字,第一个参数为数值中的字段,第二个参数固定为 `text`。 ```js const point = new PointLayer() .source([{ lng: 120, lat: 30, name: 'test' }], { parser: 'json', x: 'lng', y: 'lat', }) .shape('test', 'text'); ``` ### shape(iconName: string) `shape` 的值为 `scene.addImage` 全局添加的图片资源的名称。 ```js scene.addImage( '00', 'https://gw.alipayobjects.com/zos/basement_prod/604b5e7f-309e-40db-b95b-4fac746c5153.svg', ); scene.addImage( '01', 'https://gw.alipayobjects.com/zos/basement_prod/30580bc9-506f-4438-8c1a-744e082054ec.svg', ); scene.addImage( '02', 'https://gw.alipayobjects.com/zos/basement_prod/7aa1f460-9f9f-499f-afdf-13424aa26bbf.svg', ); const imageLayer = new PointLayer() .source( [ { longitude: 120, latitude: 30, name: 'name', }, ], { parser: { type: 'json', x: 'longitude', y: 'latitude', }, }, ) .shape('name', ['00', '01', '02']) // shape 支持映射写法 .size(25); scene.addLayer(imageLayer); const imageLayer2 = new PointLayer() .source( [ { longitude: 122, latitude: 30, name: 'name', }, ], { parser: { type: 'json', x: 'longitude', y: 'latitude', }, }, ) .shape('00') // shape 直接传值 .size(25); scene.addLayer(imageLayer2); ``` ### shape('radar') ```js const layer = new PointLayer() .source( [ { lng: 120, lat: 30, }, ], { parser: { type: 'json', x: 'lng', y: 'lat', }, }, ) .size(25) .color('#f00') .shape('radar') .animate(true); ``` 🌟 雷达图需要设置 `animate` 为 `true` ## color `color` 方法用于设置图形的颜色。 ### IColor: string `color` 类型的字符串。 - color 类型可以为 rgb 的写法 `rgb(200, 100, 100)`、`rgba(255, 0, 0, 1)` - color 类型可以为十六进制的写法 `#ffffff`、`#000` - color 类型可以是颜色名称的写法 `red`、`yellow` ### color(color: IColor) 图层可以直接设置颜色值。 ```js layer.color('#f00'); ``` ### color(field: string) 图层的颜色可以根据图层接受的数据值进行映射,接受传入数据的字段作为参数。 ```js layer.source([ { lng: 120, lat: 30, c: '#f00', }, ]); layer.color('c'); ``` ### color(field: string, domain: IColor[]) `color` 方法支持简单的值映射,将根据 `field` 从传入图层的数据中提取的值映射到 `domain` 值域中。 ```js layer.color('type', ['#f00', '#0f0', '#00f']); ``` ### color(field: string, callback: () => IColor ) `color` 方法支持回调函数的写法,将根据 `field` 作为 `callback` 方法的参数,`callback` 方法的返回值作为图层实际的颜色。 ```js layer.color('type', (value) => { switch (value) { case 'water': return '#f00'; case 'wood': return '#0f0'; } }); ``` ## size `size` 方法用于设置点图层图形的大小。 ### IPointSize: number |[number, number] | [number, number, number] - size 类型为 number 则表示 point 的半径 - size 类型可以为 [number, number]|[number, number, number] 表示柱子的半径和高度 ```javascript pointLayer.size(1); pointLayer.size([2, 10]); // 柱子半径为 2x2.高为 10 pointLayer.size([2, 4, 10]); // 柱子半径为 2x4,高为 10 ``` ### size(width: IPointSize) 点图层可以直接设置半径。图层中所有的点使用一个宽度。 ```js layer.size(2); ``` ### size(field: string) 点图层的宽度可以根据图层接受的数据值进行映射,接受传入数据的字段作为参数。 ```js layer.source([ { lng: 120, lat: 30, r: 2, }, ]); layer.size('r'); ``` ### size(field: string, domain: IPointSize[]) `size` 方法支持简单的值映射,将根据 `field` 从传入图层的数据中提取的值映射到 `domain` 值域中。 ```js layer.size('type', [1, 2, 3]); ``` ### size(field: string, callback: () => IPointSize ) `size` 方法支持回调函数的写法,将根据 `field` 作为 `callback` 方法的参数,`callback` 方法的返回值作为点图层实际的半径。 ```js layer.size('type', (value) => { switch (value) { case 'path': return 1; case 'road': return 2; } }); ``` ## scale `scale` 方法设置数据字段映射方法,用于设将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 ### scale(field: string, scaleConfig: IScaleConfig) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleConfig` 列定义配置,对象类型 ```javascript interface IScaleConfig { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` ### ScaleTypeName `scale` 的类型可以分为 `3` 类 `11` 种,不同 `Scale` 的差异在于 `domain->range` 的转换方法的不同。
`range` 和 `domain` 是 `Scale` 中非常重要的两个参数。 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类型 | 度量类型 | | -------- | ----------------------------------------------------------------- | | 连续 | linear、log、pow、time、sequential、quantize、quantile、threshold | | 分类 | cat、time | | 常量 | identity | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 常量度量 某个字段是不变的常量。 #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging || Sequential 用于返回给定的颜色数组的统一非有理 B-spline 插值器函数,该数组将转换为RGB颜色。 ```js const scaleColors = d3interpolate.interpolateRgbBasis(colors); ``` ### IScaleConfig ```js interface IScaleConfig { type: ScaleTypeName; domain?: any[]; range?: any[]; neutral?: number; field?: string; unknown?: string; ticks?: any[]; nice?: boolean; clamp?: boolean; format?: () => any; } ``` ## style `style` 方法用于配制图层的样式,相同图层拥有不同的 `shape` 图形,不同 `shape` 的图层 `style` 方法接受不同的参数。 ```js layer.style({ opacity: 0.5, }); ``` ### common 通用 `style` 参数,所有图形都支持的参数。 | style | 类型 | 描述 | 默认值 | | ------- | -------- | ------------ | ------ | | opacity | `number` | 图形的透明度 | `1` | #### 样式数据映射 默认样式配置为常量值,某些配置也支持数据映射,映射定义同 color、size参数一致。 - field: 映射字段 - value: 映射区间或者自定义回调函数 如: ```ts layer.style({ opacity:{ field:'name' value:[0.1,0.5,1], } }) ``` ### 2D shape `shape` 为平面图形、如三角形、正方等。 - [IFillShape](/zh/api/point_layer/shape#shapefillshape-ifillshape) | style | 类型 | 是否支持数据映射 | 描述 | 默认值 | | ------------- | -------------------------------------------------- | ---------------- | -------------------------------------------- | -------- | | stroke | `string` | 是 | 图形边框颜色 | `#fff` | | strokeWidth | `number` | 否 | 图形边框宽度 | `0` | | strokeOpacity | `number` | 否 | 图形边框透明度 | `1` | | blur | `number` | 否 | 图形模糊半径 | `0` | | offsets | `[number, number]` | 是 | 点偏移 | `[0, 0]` | | rotation | `number` | 是 | 旋转角度 | `0` | | anchor | [anchorType](/zh/api/point_layer/style#anchortype) | 是 | 图形锚点位置,控制图形相对于坐标点的对齐方式 | `center` | | raisingHeight | `number` | 否 | 抬升高度 | `0` | | heightfixed | `boolean` | 否 | 点大小单位 | `pixel` | #### unit - pixel 默认值 - meter 单位为米 ```js type IUnit = 'pixel' | 'meter'; ``` 点图层支持等面积点,点大小的单位是米,同样通过 size 方法设置大小 ```javascript import { PointLayer } from '@antv/l7'; const layer = PointLayer().source(data).shape('circle').size(100).color('#f00').style({ unit: 'meter', }); ``` 🌟 从 v2.7.9 版本开始支持高德地图、高德地图 2.0、Mapbox 地图 ### 3D column `shape` 为 3D 柱图。 - [IColumn](/zh/api/point_layer/shape#shapecolumn-icolumn) | style | 类型 | 描述 | 默认值 | | ----------- | --------- | -------------------- | ------- | | depth | `boolean` | 图形是否开启深度检测 | `true` | | pickLight | `boolean` | 拾取高亮是否计算光照 | `false` | | lightEnable | `boolean` | 颜色是否参与光照计算 | `true` | | heightfixed | `boolean` | 是否是固定高度 | `false` | ### 3D column linear 柱图支持配置渐变色,在配置渐变效果后会覆盖 `layer.color` 方法设置的颜色。 | style | 类型 | 描述 | 默认值 | | ------------- | --------------- | ---------------- | ------ | | sourceColor | `color` | 柱子底部颜色 | `/` | | targetColor | `color` | 柱子顶部颜色 | `/` | | opacityLinear | `IOpcityLinear` | 柱子的透明度渐变 | `/` | #### color ```js const color = `rgb(200, 100, 50)`; const color2 = '#ff0'; ``` #### opacityLinear ```js type IDir = 'up' | 'down'; interface IOpcityLinear = { enable: boolean; dir: IDir; } ``` ### text `shape` 为文字。 - [text](/zh/api/point_layer/shape#shapefield-string-text) | style | 类型 | 描述 | 是否支持数据映射 | 默认值 | | ---------------- | -------------------------------------------------- | -------------------------- | ---------------- | ------------ | | opacity | `number` | 透明度 | 是 | `#fff` | | stroke | `string` | 图形边框颜色 | 是 | `#fff` | | strokeWidth | `number` | 图形边框颜色 | 否 | `0` | | textOffset | `[number, number]` | 文字的偏移 | 是 | `[0, 0]` | | textAnchor | [anchorType](/zh/api/point_layer/style#anchortype) | 文字对齐锚点 `text` | 是 | `center` | | spacing | `number` | 文字间隔 | 否 | `2` | | rotation | `number` | 旋转角度 | 是 | `0` | | padding | `number` | 文字内边框宽度 | 否 | `2` | | halo | `number` | 文字边缘光晕宽度 | 否 | `0.5` | | gamma | `number` | 文字的颜色参数 | 否 | `2` | | fontWeight | `string` | 文字的大小 | 否 | `400` | | fontFamily | [font](/zh/api/point_layer/style#font) | 字体 | 否 | `sans-serif` | | textAllowOverlap | `boolean` | 文字是否允许覆盖 | 否 | `false` | | raisingHeight | `number` | 抬升高度 | 否 | `0` | | heightfixed | `boolean` | 抬升高度是否随 `zoom` 变化 | 否 | `false` | #### anchorType 图形/文字对齐锚点,用于控制图形或文字相对于坐标点的对齐方式。 - 在 2D shape(如 `circle`、`square` 等)中通过 `anchor` 属性使用,控制图形相对于坐标点的位置 - 在 text shape 中通过 `textAnchor` 属性使用,控制文字相对于坐标点的位置 ```javascript export enum anchorType { 'CENTER' = 'center', 'TOP' = 'top', 'TOP-LEFT' = 'top-left', 'TOP-RIGHT' = 'top-right', 'BOTTOM' = 'bottom', 'BOTTOM-CENTER' = 'bottom-center', 'BOTTOM-LEFT' = 'bottom-left', 'BOTTOM-RIGHT' = 'bottom-right', 'LEFT' = 'left', 'RIGHT' = 'right', } ``` **anchor 使用示例(2D shape)** ```javascript // 气泡底部对齐到坐标位置,常用于地图标注场景 const bubbleLayer = new PointLayer() .source(data, { parser: { type: 'json', x: 'lng', y: 'lat' }, }) .shape('circle') .size(30) .color('#5B8FF9') .style({ anchor: 'bottom', }); // anchor 支持数据映射 const layer = new PointLayer() .source(data, { parser: { type: 'json', x: 'lng', y: 'lat' }, }) .shape('circle') .size(20) .color('#5B8FF9') .style({ anchor: { field: 'type', value: ['center', 'bottom', 'top'], }, }); ``` #### font css fontFamily。 ```js const font = 'sans-serif'; const font2 = 'Times New Roman'; ``` ### simple `shape` 为简单点图形(精灵)。 - [simple](/zh/api/point_layer/shape#shapesimple) | style | 类型 | 描述 | 默认值 | | ------------- | ------------------ | ------------ | -------- | | stroke | `string` | 图形边框颜色 | `#fff` | | strokeWidth | `number` | 图形边框颜色 | `0` | | strokeOpacity | `number` | 图形边框宽度 | `1` | | offsets | `[number, number]` | 点偏移 | `[0, 0]` | ### icon `shape` 为图标类型。 - [icon](/zh/api/point_layer/shape#shapeiconname-string) | style | 类型 | 描述 | 数据映射 | 默认值 | | ------------- | ------------------ | -------------------------------------------------------------------------- | -------- | -------- | | offsets | `[number, number]` | 点偏移 | 否 | `[0, 0]` | | raisingHeight | `number` | 抬升高度 | 否 | `0` | | heightfixed | `boolean` | 抬升高度是否随 `zoom` 变化 | 否 | `false` | | rotation | `number` | 旋转角度 | 是 | `0` | | allowOverlap | `boolean` | 图标是否允许压盖,`false` 时开启碰撞避让自动隐藏重叠图标 | 否 | `true` | | padding | `[number, number]` | 碰撞检测包围盒的额外边距 `[水平, 垂直]`,仅在 `allowOverlap: false` 时生效 | 否 | `[0, 0]` | #### rotation 图标的旋转角度。 ```js const imageLayer = new PointLayer({ layerType: 'fillImage' }) .source(data) .shape('wind', (wind) => { if (wind === 'up') { return 'arrBlue'; } return 'arrRed'; }) .size(15) .style({ rotation: 0, }); ``` #### allowOverlap 控制图标在屏幕上是否允许相互压盖。设置为 `false` 时,L7 会在每次地图缩放或平移后对所有图标执行碰撞检测,自动隐藏与已放置图标重叠的图标,效果与 `textAllowOverlap` 一致。 ```js const imageLayer = new PointLayer() .source(data, { parser: { type: 'json', x: 'lng', y: 'lat' } }) .shape('icon') .size(15) .style({ allowOverlap: false, // 开启碰撞避让 padding: [4, 4], // 图标之间保留 4px 间距 }); ``` ### radar `shape` 为雷达图。 - [radar](/zh/api/point_layer/shape#shaperadar) | style | 类型 | 描述 | 默认值 | | ----- | -------- | ---------------- | ------ | | speed | `number` | 雷达图旋转的速度 | `1` | ## animate 点图层在开启 `animate` 方法后根据点是 `2D` 点还是 `3D` 点支持两种不同的动画:水波点和生长动画。 点图层在开启 `animate` 方法后会得到特殊的水波图形。图层由一圈圈向外扩散的圆环构成。
案例 案例
### 水波点 #### animate(boolean | IAnimateOption) `animate` 方法支持布尔值和对象传值。 ```javascript layer.animate(true); layer.animate({ enable: true, }); ``` #### IAnimateOption ```javascript interface IAnimateOption { enable: boolean; speed: number; rings: number; } ``` ### 生长动画 #### animate(boolean | IAnimateOption) `animate` 方法支持布尔值和对象传值。 ```javascript animate(true) animate(false) animate(animateOptions) interface IAnimateOptions: { enable: boolean; speed?: number = 0.01; repeat?: number = 1; } ``` ``` #### IAnimateOptions `animate` 方法的参数: - `enable` 是否开启动画,布尔值,默认为 `false`。 - `speed` 生长速度,数值,默认为 `0.01`。 - `repeat` 生长动画的播放次数,数值,默认为 `1`。 ``` ## 图层通用方法 ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## 数据方法 ### source 数据 设置图层数据以及解析配置 `source(data, config)`。 - data { geojson | json | csv } - config   可选   数据源配置项 - parser 数据解析,默认是解析层 geojson - transforms [transform,transform ]  数据处理转换可设置多个 `parser` 和  `transforms` [见 source 文档](/zh/api/source/source)。 ```javascript layer.source(data, { parser: { type: 'csv', x: 'lng', y: 'lat', }, transforms: [ { type: 'map', callback: function (item) { const [x, y] = item.coordinates; item.lat = item.lat * 1; item.lng = item.lng * 1; item.v = item.v * 1; item.coordinates = [x * 1, y * 1]; return item; }, }, { type: 'hexagon', size: 6000, field: 'v', method: 'sum', }, ], }); ``` ### cluster 我们在使用 `cluster` 配置聚合图之后就可以使用一些聚合方法来获取对应参数。 #### getClusters(zoom: number): IFeatureCollection 获取指定缩放等级的聚合数据 - `zoom` 缩放等级 #### getClustersLeaves(id: string): IFeatureCollection 根据 `id` 获取聚合节点的数据,每个聚合节点会有一个唯一 `ID`。 - `id` 聚合节点的 `id` ```ts const source = layer.getSource(); source.getClustersLeaves(id); layer.on('click', (e) => { console.log(source.getClustersLeaves(e.feature.cluster_id)); }); ``` ## scale 数据度量 Scale 度量是将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 L7 目前支持连续、离散、枚举类型数据的Scale,并支持位置、形状、大小和颜色编码的映射。 在使用 L7 过程中,默认情况下不需要进行 Scale 的配置,因为 L7 会根据数据类型对 scale 推断,推断过程如下: 查看用户是否设置了 Scale,如果没有: 判断字段的第一条数据的字段类型,如果数据中不存在对应的字段: 认为是常量为固定值 如果是数字则为 'linear'; 如果是字符串类型 'cat'; ### scale [Scale 详细介绍](https://mp.weixin.qq.com/s/QyD1_ypu0PDwMxEz45v6Jg) 参数: (field: string, scaleOptions: IscaleOptions) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleOptions` 列定义配置,对象类型 - type scale 类型 - unknown 未匹配颜色 可选 默认透明 - domain 值域 可选 ```javascript interface IscaleOptions { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` #### 类型 Range 和 domain 是 Scale 中非常重要的两个参数 domain: 地图数据值的定义区间 range:视觉值的区间 不同Scale 的差异在于 domain->range 的转换方法的不同 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类 | 度量类型 | | --------- | ------------------------------------- | | 连续 | linear、log、pow | | 连续分类 | quantize quantile,threshold,diverging | | 分类 枚举 | cat | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 数据值和映射值相同 比如数据中value 字段记录了每个要素的颜色,数值既为要映射的结果值s ``` // 设置为 identify layer.scale('value', { type: 'identify' }); // 或者 layer.scale('value'); // L7 能够自动推断为 identify ``` #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging 离散分类通常与两种相反的色调一起使用,以显示从负值到中心到正值的变化。这些类型的地图显示了彼此相关的值的大小。 ### getScale(scaleName:string) 根据视觉通道名称获取 scale 实例,调用之前确保 layer 已经初始化完成 ```ts const scale = layer.getScale('color'); const color = scale(1); // 将数值转换成颜色 ``` 更多是方法 scale 示例使用 ## 视觉编码方法 可视化编码是将数据转换为可视形式的过程,L7 目前支持形状,大小,颜色 3 种视觉通道,你可以指定数据字段,为不同要素设置不同的图形属性。 案例 ### filter 数据过滤方法,支持回调函数,将数据映射为true | false, 结果为true 时可见 ```ts pointLayer.filter('type', (type) => { // 回调函数 if (type === 'a') { return false; } return true; }); ``` ### size 将数据值映射到图形的大小上的方法,size 方法具体的参数使用可以查看对应图层的详细文档 ```javascript pointLayer.size(10); // 常量 pointLayer.size('type'); // 使用字段映射到大小 pointLayer.size('type', [0, 10]); // 使用字段映射到大小,并指定最大值和最小值 pointLayer.size('type', (type) => { // 回调函数 if (type === 'a') { return 10; } return 5; }); ``` #### size(value) 传入数字常量,如  `pointLayer.size(20)` #### size(field) 根据 field 字段的值映射大小,使用默认的`最大值 max:10`  和`最小值 min: 1`。 #### size(field, callback) 使用回调函数控制图形大小。 - `callback`: function 回调函数。 ```javascript pointLayer.size('age', (value) => { if (value === 1) { return 5; } return 10; }); ``` ### color 将数据值映射到图形的颜色上的方法。 ```javascript layer.color('red'); // 常量颜色 layer.color('type'); // 对 type 字段进行映射,使用内置的颜色 layer.color('type', ['red', 'blue']); // 指定颜色 layer.color('type', (type) => { // 通过回调函数 if (type === 'a') { return 'red'; } return 'blue'; }); layer.color('type*value', (type, value) => { //多个参数,通过回调函数 if (type === 'a' && value > 100) { return 'red'; } return 'blue'; }); ``` #### color(value) 参数:`value` :string 只支持接收一个参数,value 可以是: - 映射至颜色属性的数据源字段名,如果数据源中不存在这个字段名的话,则按照常量进行解析,这个时候会使用 L7 默认提供的颜色。 - 也可以直接指定某一个具体的颜色值 color,如 '#fff', 'white','rgba(255,0,0,0.5)' ,rgb(255,0,1) 等。 如果数据为映射到颜色,默认为透明色不显示,如果需要设置该颜色,需要在scale 中设置 示例 ```javascript layer.color('name'); // 映射数据字段 layer.color('white'); // 指定颜色 ``` #### color(field, colors) 参数: - `field`: stringfield 为映射至颜色属性的数据源字段名,也支持指定多个参数。 - `colors`: string | array | function colors 的参数有以下情况:  如果为空,即未指定颜色的数组,那么使用内置的全局的颜色;如果需要指定颜色,则需要以数组格式传入,那么分类的颜色按照数组中的颜色确定。 ```javascript layer.scale('name',{ type:'quantile' unknown:'#ccc' // 设置无效颜色 }) layer.color('name'); // 使用identity layer.color('name', ['red', 'blue']); // 使用传入的指定颜色 ``` - colors 如果是回调函数,则该回调函数的参数为对应字段的数值,具体使用如下,当 color 映射为多个字段时,参数按照字段声明的顺序传入: ```javascript layer.color('gender', (value) => { if (value === 1) { return 'red'; } return 'blue'; }); layer.color('gender*age', (gender, age) => { if (age === 20 && gender == ' 男') { return 'red'; } return 'blue'; }); ``` ### shape 通常一种图层可以有多种表现形式,shape 方法用于指定图层具体的表现形式,以 PointLayer 的 shape 为例: ```javascript shape('circle'); // 圆形 shape('triangle'); // 三角形 shape('cylinder'); // 圆柱 ``` 案例 **shape(shape)** 参数 `shape` string - 只支持接收一个参数,指定几何图像对象绘制的形状。下表列出了不同的 图层 几何图形对象支持的 shape 形状 | layer 类型 | shape 类型 | 备注 | | ---------- | -------------------------------------------------------------------------------------- | ---- | | point | 2d:point,circle, square, triangle,hexagon,image,text 3d:circle,triangle,hexagon,square | | | line | line,arc, arc3d, greatcircle | | | polygon | fill,line, extrude | | **shape(field, shapes)** - shape 根据字段指定行形状,比如根据字段指定 PointLayer/imageLayer 的 icon 类型 ```javascript scene.addImage( '00', 'https://gw.alipayobjects.com/zos/basement_prod/604b5e7f-309e-40db-b95b-4fac746c5153.svg', ); scene.addImage( '01', 'https://gw.alipayobjects.com/zos/basement_prod/30580bc9-506f-4438-8c1a-744e082054ec.svg', ); scene.addImage( '02', 'https://gw.alipayobjects.com/zos/basement_prod/7aa1f460-9f9f-499f-afdf-13424aa26bbf.svg', ); const imageLayer = new PointLayer() .source(data, { parser: { type: 'json', x: 'longitude', y: 'latitude', }, }) .shape('name', ['00', '01', '02']) .size(20); scene.addLayer(imageLayer); ``` 案例 [在线案例](/zh/examples/point/image/image/) **shape(field, callback)** - shape 也支持回调函数的写法 ```javascript .shape('key', value => { if(value > 10) { return 'circle'; } else { return 'triangle'; } } ``` ### rotate 将数据值映射到图形的旋转角度上的方法,用于控制点图层图标/图形的旋转。 ```javascript layer.rotate(45); // 常量,所有元素旋转 45 度 layer.rotate('angle'); // 字段映射 layer.rotate('angle', [0, 360]); // 字段映射到角度范围 layer.rotate('angle', (angle) => { return angle * (Math.PI / 180); // 回调函数 }); ``` ### label 为图层设置标注(文字标签),将数据字段映射为标注内容显示在图层元素旁边。主要在特定图层类型(如 PointLayer 的文字标注)中生效。 ```javascript layer.label('name'); // 以 name 字段的值作为标注文本 layer.label('name', (name) => `${name}市`); // 回调函数处理标注文本 ``` ### style style 方法通常用于描述图层具体的样式,大多数图层会支持一些比较通用的属性, 如 opacity 属性,同时每个图层也会有仅限本图层支持的属性,如只有 CityBuildingLayer 支持的 windowColor 属性,每个图层具体要如何配置属性请查看每个图层的详细文档。 - opacity 设置透明度 大部分图层都支持 - stroke 线填充颜色 仅点图层支持 - strokeWidth 线的宽度 仅点图层支持 ```javascript layer.style({ opacity: 0.8, stroke: 'white', }); ``` - 样式数据映射🌟
在正常情况下,style 的参数会作用到一个图层上的所有图形,如一个 PointLayer 中有十个点,我们设置 opacity = 0.5, 这样十个点的透明度都是 0.5。
而在特殊情况下,我们可能需要为每个点分别设置一个透明度,这时候按照原来的方式直接设置 style 方法的 opacity 的值就无法满足需求了,为此我们需要提供特殊的赋值方式。
通常我们会根据传入图层的数据为图层的每个图形设置单独的值,因此我们称之为“样式数据映射”。
我们支持几种设置 style 中的参数从 source 数据中动态取值的写法。 ```javascript // 根据数据中的 v 字段的值设置点图层各个点的透明度 const data = [ { lng: 120, lat: 30, v: 0.5 }, ... ] const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat' } }) .shape('circle') .color('#f00') .size({ // 第一种写法 根据字段从 data 中直接取值 opacity: 'v'// opacity = 0.5 }); scene.addLayer(layer); ``` [在线案例](/zh/examples/point/text/style-map/) 从 `L7 2.5` 开始,各图层样式将逐步支持样式数据映射,目前支持样式数据映射的 `style` 参数如下: | layer 类型/shape | 支持的样式字段 | 备注 | | ---------------------- | ---------------------------------------------------- | --------------------------------- | | pointLayer/fill | opacity、strokeOpacity、strokeWidth、stroke、offsets | shape circle、triangle... | | pointLayer/image | opacity、offsets | offsets 经纬度偏移 | | pointLayer/normal | opacity、offsets | | | pointLayer/text | opacity、strokeWidth、stroke、textOffset | textOffset 相对文字画布位置的偏移 | | pointLayer/extrude | opacity | | | polygonLayer/fill | opacity | | | polygonLayer/extrude | opacity | | | lineLayer/line | opacity | | | lineLayer/arc | opacity、thetaOffset | thetaOffset 弧线的弯曲弧度 | | lineLayer/arc3d | opacity | | | lineLayer/great_circle | opacity | | 案例 [在线案例](/zh/examples/point/scatter/scatter-style-map/) ### texture 目前只在线图层上支持了纹理方法 - texture 方法支持传入由 scene.addImage 方法添加的全局 icon 贴图资源 ```javascript // 首先在全局加载图片资源 scene.addImage( 'plane', 'https://gw.alipayobjects.com/zos/bmw-prod/0ca1668e-38c2-4010-8568-b57cb33839b9.svg', ); const layer = new LineLayer({ blend: 'normal', }) .source(data, { parser: { type: 'json', x: 'lng1', y: 'lat1', x1: 'lng2', y1: 'lat2', }, }) .size(25) .shape('arc') .texture('plane') // 为图层绑定纹理 .color('#8C1EB2') .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 30, // 设置贴图纹理的间距 textureBlend: 'replace', // 设置纹理混合方式,默认值为 normal,可选值有 normal/replace 两种 }); ``` 案例 [在线案例](/zh/examples/line/animate/plane-animate2/) ## 图层更新方法 如果已经添加了图层,需要修改图层显示样式可以再次调用图形映射方法,然后调用 `scene.render()`更新渲染即可 ### scale 更新 重新调用scale 方法 ```tsx layer.scale('value', { type: 'quantile', }); scene.render(); ``` ### 数据映射 重新调用 color/size/filter/shape等方法 ```javascript layer.color('blue'); layer.size(10); scene.render(); ``` ### layer.style ```javascript layer.style({ opacity: 1, }); scene.render(); ``` ### setData(data, option?: {}) 更新 Source 数据 参数: - data 数据 - option 默认和初始配置项一致,如果数据格式相同可不设置 调用 setData 方法会自动更新图层渲染 ```javascript layer.setData(data); ``` ### setBlend(type: string) 设置图层叠加方法 参数: - type blend 类型 normal | additive | subtractive | max ## 图层控制方法 ### show() 图层显示 ```javascript layer.show(); ``` ### hide() 图层隐藏 ```javascript layer.hide(); ``` ### isVisible(): boolean 图层是否可见 ```javascript layer.isVisible(); ``` ### setIndex(zIndex: int) 设置图层绘制顺序 ```javascript layer.setIndex(1); ``` ### fitBounds() 缩放到图层范围 ```javascript layer.fitBounds(); ``` ### setMinZoom(zoom: number) 设置图层最小缩放等级 ```javascript layer.setMinZoom(zoom); ``` ### setMaxZoom(zoom: number) 设置图层最大缩放等级 参数 - zoom {number} ```javascript layer.setMaxZoom(zoom); ``` ### getMinZoom(): number 获取图层最小缩放等级 ```javascript const minZoom = layer.getMinZoom(); ``` ### getMaxZoom(): number 获取图层最大缩放等级 ```javascript const maxZoom = layer.getMaxZoom(); ``` ### destroy() 销毁图层,释放相关资源。场景调用 `removeLayer` 时会自动销毁图层,一般不需要手动调用。 ```javascript layer.destroy(); ``` ## 图层交互方法 ### active(activeOption | boolean) - 开启或者关闭 mousehover 元素高亮效果 - `activeOption` - `color`: 高亮颜色 - `mix`: 可选参数,默认为 0,表示高亮颜色是指定纯色,最大有效值是1,表示高亮色全部是底色 ```javascript activeOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.active(true); // 开启 Active 自定义高亮颜色 layer.active({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.active(false); ``` ### setActive(featureId: int) 根据元素 ID 设置指定元素 hover 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setActive(featureId); ``` ### select(selectOption | boolean) - 开启或者关闭 mouseclick 元素选中高亮效果 - selectOption - `color`: 选中高亮颜色 - `mix`: 可选参数,默认为 0,表示选中高亮颜色是指定纯色,最大有效值是1,表示选中高亮色全部是底色 ```javascript selectOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.select(true); // 开启 Active 自定义高亮颜色 layer.select({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.select(false); ``` ### setSelect(featureId: int) 根据元素 ID 设置指定元素 click 选中 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setSelect(featureId); ``` ### setAutoFit(autoFit: boolean) 让用户可以主动设置图层的 autoFit 参数
🌟 设置完该方法后会在图层发生更新的时候生效,如在 setData 之后触发 ```javascript // 使用方法 layer.setAutoFit(true); // 内部实现 public setAutoFit(autoFit: boolean): ILayer { this.updateLayerConfig({ autoFit, }); return this; } ``` ### getScale(attr: string) 支持单独获取某个图形经过 scale 计算后的值, 满足用户获取图层某些 feature 值的需求。 - attr scale 的属性值 ```javascript const data = [ { lng: 120, lat: 30, name: 'n1' }, { lng: 120, lat: 30, name: 'n2' }, ]; const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat', type: 'json', }, }) .shape('circle') .color('name', ['#f00', '#ff0']) .size('name', [20, 40]); scene.addLayer(layer); // 此时在 scene 上绘制两个点 // 一个颜色为黄色,大小为 40 的点,对应 name 为 n1 // 一个颜色为红色,大小为 20 的点,对应 name 为 n2 const colorScale = layer.getScale('color'); // 获取 color 方法产生的 scale const color1 = colorScale('n1'); // '#ff0' const color1 = colorScale('n2'); // '#f00' const sizeScale = layer.getScale('size'); // 获取 size 方法产生的 scale const size1 = sizeScale('n1'); // 40 const size2 = sizeScale('n2'); // 20 ``` ### getLegendItems(type: string) 不推荐使用,将废弃, 获取图例配置 - type 图例类型 - index 可选 默认 ```javascript layer.getLegendItems('color'); layer.getLegendItems('size'); ``` ### getLegend(type: string) getLegendItems方法的替代方法 该方法需要 返回值 - type 图例类型 - field 映射字段 - items 图例项 ```javascript layer.getLegend('color'); layer.getLegend('size'); ``` 注:rasterayer 只支持 color 类型 ## 图层掩模方法 ### addMask 添加 Mask 图层 ```ts const polygonLayer = new Polygon(); layer.addMask(polygonLayer); scene.render(); ``` ### removeMask ```ts const polygonLayer = new Polygon(); layer.removeMask(polygonLayer); scene.render(); ``` ### disableMask ```ts layer.disableMask(); scene.render(); ``` ### enableMask ```ts layer.enableMask(); scene.render(); ``` ## 鼠标事件 鼠标事件回调参数 target ```javascript layer.on(eventName, (target) => console.log(target)); ``` - x: number 鼠标  在地图位置 x 坐标 - y: number 鼠标  在地图位置 y 坐标 - type: string 鼠标事件类型 - lngLat: 经度度对象 {lng:number, lat: number }; 鼠标所在位置经纬度 - feature: any; 数据选中的地理要素信息 - featureId: number | null; 数据选中的地理要素的 ID ### click 点击事件 ```javascript layer.on('click', (e) => console.log(e)); ``` ### dblclick 双击 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mousemove 鼠标移动事件 ```javascript layer.on('mousemove', (e) => console.log(e)); ``` ### mouseout 鼠标移除 ```javascript layer.on('mouseout', (e) => console.log(e)); ``` ### mouseup 鼠标抬起 ```javascript layer.on('mouseup', (e) => console.log(e)); ``` ### mousedown 鼠标按下 ```javascript layer.on('mousedown', (e) => console.log(e)); ``` ### contextmenu 鼠标右键 ```javascript layer.on('contextmenu', (e) => console.log(e)); ``` ### dblclick 双击拾取元素 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mouseenter 鼠标进入图层要素时触发 ```javascript layer.on('mouseenter', (e) => console.log(e)); ``` ### unclick 点击未拾取到元素 ```javascript layer.on('unclick', (e) => console.log(e)); ``` ### unmousemove 鼠标移动未拾取到元素 ```javascript layer.on('unmousemove', (e) => console.log(e)); ``` ### unmouseup 鼠标抬起未拾取到元素 ```javascript layer.on('unmouseup', (e) => console.log(e)); ``` ### unmousedown 鼠标按下未拾取到元素 ```javascript layer.on('unmousedown', (e) => console.log(e)); ``` ### uncontextmenu 鼠标右键位拾取到元素 ```javascript layer.on('uncontextmenu', (e) => console.log(e)); ``` ### unpick 所有鼠标事件未拾取到 ```javascript layer.on('unpick', (e) => console.log(e)); ``` ### touchstart 移动端事件 touchstart ```javascript layer.on('touchstart', (e) => console.log(e)); ``` ### touchend 移动端事件 touchend ```javascript layer.on('touchend', (e) => console.log(e)); ``` 使用示例 ```javascript layer.on('click', (ev) => {}); // 鼠标左键点击图层事件 layer.on('mouseenter', (ev) => {}); // 鼠标进入图层要素 layer.on('mousemove', (ev) => {}); // 鼠标在图层上移动时触发 layer.on('mouseout', (ev) => {}); // 鼠标移出图层要素时触发 layer.on('mouseup', (ev) => {}); // 鼠标在图层上单击抬起时触发 layer.on('mousedown', (ev) => {}); // 鼠标在图层上单击按下时触发 layer.on('contextmenu', (ev) => {}); // 图层要素点击右键菜单 // 鼠标在图层外的事件 layer.on('unclick', (ev) => {}); // 图层外点击 layer.on('unmousemove', (ev) => {}); // 图层外移动 layer.on('unmouseup', (ev) => {}); // 图层外鼠标抬起 layer.on('unmousedown', (ev) => {}); // 图层外单击按下时触发 layer.on('uncontextmenu', (ev) => {}); // 图层外点击右键 layer.on('unpick', (ev) => {}); // 图层外的操作的所有事件 ``` ## 图层事件 ### inited 参数 option - target 当前 layer - type 事件类型 图层初始化完成后触发 ```javascript layer.on('inited', (option) => {}); ``` ### add 图层添加到 scene 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('add', (type) => console.log(type)); ``` ### remove 图层移除时触发 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('remove', (type) => console.log(type)); ``` ### legend 数据映射更新,图例发生变化,主要 color、size ### `legend:color` 数据映射更新,图例 color 颜色改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:color', (ev) => console.log(ev)); ``` ### `legend:size` 数据映射更新,图例 size 大小改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:size', (ev) => console.log(ev)); ``` ## 图层框选 ### boxSelect 参数 option - box [x1: number, y1: number, x2: number, y2: number] 相较于 - cb (...args: any[]) => void 传入的回调方法,返回框选内部的 feature ```javascript layer.boxSelect(box, cb); // (x1, y1), (x2, y2) 框选的方框左上角和右下角相对于地图左上角的像素坐标 // cb 是传入的回调函数,回调函数返回的参数是选中的 feature 对象数组,对象的字段和用户传入的数据相关 ``` #### PolygonLayer - Canonical page: https://l7.antv.antgroup.com/zh/api/polygon_layer/polygonlayer/ - Markdown source: https://l7.antv.antgroup.com/zh/api/polygon_layer/polygonlayer.md - Description: PolygonLayer --- title: "PolygonLayer" description: "PolygonLayer" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/polygon_layer/polygonlayer/" --- ## 简介 面图层用于绘制 2D 多边形以及沿 Z 轴拉伸后的 3D 图形,支持 GeoJSON Polygon / MultiPolygon 数据。 ```javascript import { PolygonLayer } from '@antv/l7'; const layer = new PolygonLayer() .source({ type: 'FeatureCollection', features: [ { type: 'Feature', properties: {}, geometry: { type: 'Polygon', coordinates: [ [ [104.4140625, 35.460669951495305], [98.7890625, 24.206889622398023], [111.796875, 27.371767300523047], [104.4140625, 35.460669951495305], ], ], }, }, ], }) .shape('fill') .color('#f00') .style({ opacity: 0.6, }); ``` ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## source 几何体图层数据推荐使用 GeoJSON 格式的数据。 - [GeoJSON](/zh/api/source/geojson/#point) ### GeoJSON ```js // 传入 GeoJSON 类型数据 *** L7 默认支持,不需要 parser 解析 const data = { type: 'FeatureCollection', features: [ { type: 'Feature', properties: {}, geometry: { type: 'Polygon', coordinates: [ [ [104.4140625, 35.460669951495305], [98.7890625, 24.206889622398023], [111.796875, 27.371767300523047], [104.4140625, 35.460669951495305], ], ], }, }, ], }; const layer = new PolygonLayer().source(data); ``` ## shape `shape` 方法用于指定面图层绘制图形的类型,如填充图,填充线,挤出集合体等。 ### shape('fill') `shape` 为 `fill` 几何图层用于绘制平面的几何图形。 ```js layer.shape('fill'); ``` ### shape('extrude') `shape` 为 `extrude` 几何图层用于绘制 3D 的几何体。 ```js layer.shape('extrude'); ``` ### extrusion extrude 图层的升级版, 支持 extrusionBase(基础高度)数据映射 ```js layer.shape('extrusion'); ``` ### shape('water') `shape` 为 `water` 几何图层用于绘制平面水体。 ```js layer.shape('water'); ``` ### shape('ocean') `shape` 为 `ocean` 几何图层用于绘制平面海洋水体。 ```js layer.shape('ocean'); ``` ### shape('line') `shape` 为 `line` 几何图层用于绘制线。 ```js layer.shape('line'); ``` ### shape('point_fill') `shape` 为 `point_fill` 几何图层用于绘制填充点。 ```js layer.shape('point_fill'); ``` ### shape('point_image') `shape` 为 `point_image` 几何图层用于绘制点图标。 ```js layer.shape('point_image'); ``` ### shape('point_extrude') `shape` 为 `point_extrude` 几何图层用于绘制柱子。 ```js layer.shape('point_extrude'); ``` ### shape('text') `shape` 为 `text` 几何图层用于绘制文字。 ```js layer.shape('text'); ``` ## color `color` 方法用于设置图形的颜色。 ### IColor: string `color` 类型的字符串。 - color 类型可以为 rgb 的写法 `rgb(200, 100, 100)`、`rgba(255, 0, 0, 1)` - color 类型可以为十六进制的写法 `#ffffff`、`#000` - color 类型可以是颜色名称的写法 `red`、`yellow` ### color(color: IColor) 图层可以直接设置颜色值。 ```js layer.color('#f00'); ``` ### color(field: string) 图层的颜色可以根据图层接受的数据值进行映射,接受传入数据的字段作为参数。 ```js layer.source([ { lng: 120, lat: 30, c: '#f00', }, ]); layer.color('c'); ``` ### color(field: string, domain: IColor[]) `color` 方法支持简单的值映射,将根据 `field` 从传入图层的数据中提取的值映射到 `domain` 值域中。 ```js layer.color('type', ['#f00', '#0f0', '#00f']); ``` ### color(field: string, callback: () => IColor ) `color` 方法支持回调函数的写法,将根据 `field` 作为 `callback` 方法的参数,`callback` 方法的返回值作为图层实际的颜色。 ```js layer.color('type', (value) => { switch (value) { case 'water': return '#f00'; case 'wood': return '#0f0'; } }); ``` ## size `size` 方法用于设置 Polygon 的高度 ### IPointSize: number |[number, number] | [number, number, number] - size 类型为 number 则表示 Polygon 的高度 ```javascript pointLayer.size(1); ``` ### size(width: IPointSize) 面图层可以直接设置半径。图层中所有的点使用一个高度。 ```js layer.size(2); ``` ### size(field: string) 面图层的高度可以根据图层接受的数据值进行映射,接受传入数据的字段作为参数。 ```js layer.source([ { lng: 120, lat: 30, r: 2, }, ]); layer.size('r'); ``` ### size(field: string, domain: IPointSize[]) `size` 方法支持简单的值映射,将根据 `field` 从传入图层的数据中提取的值映射到 `domain` 值域中。 ```js layer.size('type', [1, 2, 3]); ``` ### size(field: string, callback: () => IPointSize ) `size` 方法支持回调函数的写法,将根据 `field` 作为 `callback` 方法的参数,`callback` 方法的返回值作为面图层实际高度。 ```js layer.size('type', (value) => { switch (value) { case 'path': return 1; case 'road': return 2; } }); ``` ## scale `scale` 方法设置数据字段映射方法,用于设将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 ### scale(field: string, scaleConfig: IScaleConfig) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleConfig` 列定义配置,对象类型 ```javascript interface IScaleConfig { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` ### ScaleTypeName `scale` 的类型可以分为 `3` 类 `11` 种,不同 `Scale` 的差异在于 `domain->range` 的转换方法的不同。
`range` 和 `domain` 是 `Scale` 中非常重要的两个参数。 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类型 | 度量类型 | | -------- | ----------------------------------------------------------------- | | 连续 | linear、log、pow、time、sequential、quantize、quantile、threshold | | 分类 | cat、time | | 常量 | identity | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 常量度量 某个字段是不变的常量。 #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging || Sequential 用于返回给定的颜色数组的统一非有理 B-spline 插值器函数,该数组将转换为RGB颜色。 ```js const scaleColors = d3interpolate.interpolateRgbBasis(colors); ``` ### IScaleConfig ```js interface IScaleConfig { type: ScaleTypeName; domain?: any[]; range?: any[]; neutral?: number; field?: string; unknown?: string; ticks?: any[]; nice?: boolean; clamp?: boolean; format?: () => any; } ``` ## style `style` 方法用于配制图层的样式,相同图层拥有不同的 `shape` 图形,不同 `shape` 的图层 `style` 方法接受不同的参数。 ```js layer.style({ opacity: 0.5, }); ``` ### common 通用 `style` 参数,所有图形都支持的参数。 | style | 类型 | 描述 | 默认值 | | ------- | -------- | ------------ | ------ | | opacity | `number` | 图形的透明度 | `1` | ### fill `shape` 为平面填充几何体。 - [fill](/zh/api/polygon_layer/shape#shapefill) | style | 类型 | 描述 | 默认值 | | ------------- | ---------------- | -------- | ------ | | raisingHeight | `number` | 抬升高度 | `0` | | opacityLinear | `IOpacityLinear` | 透明渐变 | `/` | #### opacityLinear ```js type IDir = 'in' | 'out'; interface IOpacityLinear { enable: false; dir: IDir; } ``` ### extrude `shape` 为挤出几何体。 - [extrude](/zh/api/polygon_layer/shape#shapeextrude) | style | 类型 | 描述 | 默认值 | | ------------- | --------- | -------------------------- | ------- | | raisingHeight | `number` | 抬升高度 | `0` | | heightfixed | `boolean` | 抬升高度是否随 `zoom` 变化 | `false` | | topsurface | `boolean` | 顶部是否显示 | `true` | | sidesurface | `boolean` | 侧面是否显示 | `true` | | sourceColor | `IColor` | 侧面底部颜色 | `/` | | targetColor | `IColor` | 侧面顶部颜色 | `/` | ### extrusion `shape` 为挤出几何体。 - [extrusion](/zh/api/polygon_layer/shape#extrusion) | style | 类型 | 描述 | 是否支持数据映射 | 默认值 | | ------------- | -------- | ---------------- | ---------------- | ------ | | extrusionBase | `number` | 基础高度,单位米 | 支持 | `0` | #### linear 几何体图层支持配置渐变效果(sourceColor、targetColor),在配置渐变效果后会覆盖 `layer.color` 方法设置的颜色。 ### water `shape` 为水体表面几何体。 - [water](/zh/api/polygon_layer/shape#shapewater) | style | 类型 | 描述 | 默认值 | | ------------ | -------- | -------- | ------ | | speed | `number` | 水波速度 | `0.5` | | waterTexture | `string` | 水面贴图 | `0` | `waterTexture` 默认值为 'https://gw.alipayobjects.com/mdn/rms_816329/afts/img/A*EojwT4VzSiYAAAAAAAAAAAAAARQnAQ' ### ocean `shape` 为海洋表面几何体。 - [ocean](/zh/api/polygon_layer/shape#shapeocean) | style | 类型 | 描述 | 默认值 | | ----------- | -------- | -------- | --------- | | watercolor | `IColor` | 水面颜色 | `#6D99A8` | | watercolor2 | `IColor` | 水面颜色 | `#0F121C` | ### other 几何体图层支持的其他 `shape` 都有对应的图层,可以参考对应图层的样式参数。 ## animate 几何体图层在 `shape` 为 `water` 或 `ocean` 的时候会得到流动的水面,此时我们需要使用 `animate` 方法开启动画。
案例
### animate(boolean) `animate` 方法支持布尔值和对象传值。 ```javascript layer.animate(true); layer.animate({ enable: true, }); ``` ## 图层通用方法 ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## 数据方法 ### source 数据 设置图层数据以及解析配置 `source(data, config)`。 - data { geojson | json | csv } - config   可选   数据源配置项 - parser 数据解析,默认是解析层 geojson - transforms [transform,transform ]  数据处理转换可设置多个 `parser` 和  `transforms` [见 source 文档](/zh/api/source/source)。 ```javascript layer.source(data, { parser: { type: 'csv', x: 'lng', y: 'lat', }, transforms: [ { type: 'map', callback: function (item) { const [x, y] = item.coordinates; item.lat = item.lat * 1; item.lng = item.lng * 1; item.v = item.v * 1; item.coordinates = [x * 1, y * 1]; return item; }, }, { type: 'hexagon', size: 6000, field: 'v', method: 'sum', }, ], }); ``` ### cluster 我们在使用 `cluster` 配置聚合图之后就可以使用一些聚合方法来获取对应参数。 #### getClusters(zoom: number): IFeatureCollection 获取指定缩放等级的聚合数据 - `zoom` 缩放等级 #### getClustersLeaves(id: string): IFeatureCollection 根据 `id` 获取聚合节点的数据,每个聚合节点会有一个唯一 `ID`。 - `id` 聚合节点的 `id` ```ts const source = layer.getSource(); source.getClustersLeaves(id); layer.on('click', (e) => { console.log(source.getClustersLeaves(e.feature.cluster_id)); }); ``` ## scale 数据度量 Scale 度量是将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 L7 目前支持连续、离散、枚举类型数据的Scale,并支持位置、形状、大小和颜色编码的映射。 在使用 L7 过程中,默认情况下不需要进行 Scale 的配置,因为 L7 会根据数据类型对 scale 推断,推断过程如下: 查看用户是否设置了 Scale,如果没有: 判断字段的第一条数据的字段类型,如果数据中不存在对应的字段: 认为是常量为固定值 如果是数字则为 'linear'; 如果是字符串类型 'cat'; ### scale [Scale 详细介绍](https://mp.weixin.qq.com/s/QyD1_ypu0PDwMxEz45v6Jg) 参数: (field: string, scaleOptions: IscaleOptions) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleOptions` 列定义配置,对象类型 - type scale 类型 - unknown 未匹配颜色 可选 默认透明 - domain 值域 可选 ```javascript interface IscaleOptions { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` #### 类型 Range 和 domain 是 Scale 中非常重要的两个参数 domain: 地图数据值的定义区间 range:视觉值的区间 不同Scale 的差异在于 domain->range 的转换方法的不同 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类 | 度量类型 | | --------- | ------------------------------------- | | 连续 | linear、log、pow | | 连续分类 | quantize quantile,threshold,diverging | | 分类 枚举 | cat | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 数据值和映射值相同 比如数据中value 字段记录了每个要素的颜色,数值既为要映射的结果值s ``` // 设置为 identify layer.scale('value', { type: 'identify' }); // 或者 layer.scale('value'); // L7 能够自动推断为 identify ``` #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging 离散分类通常与两种相反的色调一起使用,以显示从负值到中心到正值的变化。这些类型的地图显示了彼此相关的值的大小。 ### getScale(scaleName:string) 根据视觉通道名称获取 scale 实例,调用之前确保 layer 已经初始化完成 ```ts const scale = layer.getScale('color'); const color = scale(1); // 将数值转换成颜色 ``` 更多是方法 scale 示例使用 ## 视觉编码方法 可视化编码是将数据转换为可视形式的过程,L7 目前支持形状,大小,颜色 3 种视觉通道,你可以指定数据字段,为不同要素设置不同的图形属性。 案例 ### filter 数据过滤方法,支持回调函数,将数据映射为true | false, 结果为true 时可见 ```ts pointLayer.filter('type', (type) => { // 回调函数 if (type === 'a') { return false; } return true; }); ``` ### size 将数据值映射到图形的大小上的方法,size 方法具体的参数使用可以查看对应图层的详细文档 ```javascript pointLayer.size(10); // 常量 pointLayer.size('type'); // 使用字段映射到大小 pointLayer.size('type', [0, 10]); // 使用字段映射到大小,并指定最大值和最小值 pointLayer.size('type', (type) => { // 回调函数 if (type === 'a') { return 10; } return 5; }); ``` #### size(value) 传入数字常量,如  `pointLayer.size(20)` #### size(field) 根据 field 字段的值映射大小,使用默认的`最大值 max:10`  和`最小值 min: 1`。 #### size(field, callback) 使用回调函数控制图形大小。 - `callback`: function 回调函数。 ```javascript pointLayer.size('age', (value) => { if (value === 1) { return 5; } return 10; }); ``` ### color 将数据值映射到图形的颜色上的方法。 ```javascript layer.color('red'); // 常量颜色 layer.color('type'); // 对 type 字段进行映射,使用内置的颜色 layer.color('type', ['red', 'blue']); // 指定颜色 layer.color('type', (type) => { // 通过回调函数 if (type === 'a') { return 'red'; } return 'blue'; }); layer.color('type*value', (type, value) => { //多个参数,通过回调函数 if (type === 'a' && value > 100) { return 'red'; } return 'blue'; }); ``` #### color(value) 参数:`value` :string 只支持接收一个参数,value 可以是: - 映射至颜色属性的数据源字段名,如果数据源中不存在这个字段名的话,则按照常量进行解析,这个时候会使用 L7 默认提供的颜色。 - 也可以直接指定某一个具体的颜色值 color,如 '#fff', 'white','rgba(255,0,0,0.5)' ,rgb(255,0,1) 等。 如果数据为映射到颜色,默认为透明色不显示,如果需要设置该颜色,需要在scale 中设置 示例 ```javascript layer.color('name'); // 映射数据字段 layer.color('white'); // 指定颜色 ``` #### color(field, colors) 参数: - `field`: stringfield 为映射至颜色属性的数据源字段名,也支持指定多个参数。 - `colors`: string | array | function colors 的参数有以下情况:  如果为空,即未指定颜色的数组,那么使用内置的全局的颜色;如果需要指定颜色,则需要以数组格式传入,那么分类的颜色按照数组中的颜色确定。 ```javascript layer.scale('name',{ type:'quantile' unknown:'#ccc' // 设置无效颜色 }) layer.color('name'); // 使用identity layer.color('name', ['red', 'blue']); // 使用传入的指定颜色 ``` - colors 如果是回调函数,则该回调函数的参数为对应字段的数值,具体使用如下,当 color 映射为多个字段时,参数按照字段声明的顺序传入: ```javascript layer.color('gender', (value) => { if (value === 1) { return 'red'; } return 'blue'; }); layer.color('gender*age', (gender, age) => { if (age === 20 && gender == ' 男') { return 'red'; } return 'blue'; }); ``` ### shape 通常一种图层可以有多种表现形式,shape 方法用于指定图层具体的表现形式,以 PointLayer 的 shape 为例: ```javascript shape('circle'); // 圆形 shape('triangle'); // 三角形 shape('cylinder'); // 圆柱 ``` 案例 **shape(shape)** 参数 `shape` string - 只支持接收一个参数,指定几何图像对象绘制的形状。下表列出了不同的 图层 几何图形对象支持的 shape 形状 | layer 类型 | shape 类型 | 备注 | | ---------- | -------------------------------------------------------------------------------------- | ---- | | point | 2d:point,circle, square, triangle,hexagon,image,text 3d:circle,triangle,hexagon,square | | | line | line,arc, arc3d, greatcircle | | | polygon | fill,line, extrude | | **shape(field, shapes)** - shape 根据字段指定行形状,比如根据字段指定 PointLayer/imageLayer 的 icon 类型 ```javascript scene.addImage( '00', 'https://gw.alipayobjects.com/zos/basement_prod/604b5e7f-309e-40db-b95b-4fac746c5153.svg', ); scene.addImage( '01', 'https://gw.alipayobjects.com/zos/basement_prod/30580bc9-506f-4438-8c1a-744e082054ec.svg', ); scene.addImage( '02', 'https://gw.alipayobjects.com/zos/basement_prod/7aa1f460-9f9f-499f-afdf-13424aa26bbf.svg', ); const imageLayer = new PointLayer() .source(data, { parser: { type: 'json', x: 'longitude', y: 'latitude', }, }) .shape('name', ['00', '01', '02']) .size(20); scene.addLayer(imageLayer); ``` 案例 [在线案例](/zh/examples/point/image/image/) **shape(field, callback)** - shape 也支持回调函数的写法 ```javascript .shape('key', value => { if(value > 10) { return 'circle'; } else { return 'triangle'; } } ``` ### rotate 将数据值映射到图形的旋转角度上的方法,用于控制点图层图标/图形的旋转。 ```javascript layer.rotate(45); // 常量,所有元素旋转 45 度 layer.rotate('angle'); // 字段映射 layer.rotate('angle', [0, 360]); // 字段映射到角度范围 layer.rotate('angle', (angle) => { return angle * (Math.PI / 180); // 回调函数 }); ``` ### label 为图层设置标注(文字标签),将数据字段映射为标注内容显示在图层元素旁边。主要在特定图层类型(如 PointLayer 的文字标注)中生效。 ```javascript layer.label('name'); // 以 name 字段的值作为标注文本 layer.label('name', (name) => `${name}市`); // 回调函数处理标注文本 ``` ### style style 方法通常用于描述图层具体的样式,大多数图层会支持一些比较通用的属性, 如 opacity 属性,同时每个图层也会有仅限本图层支持的属性,如只有 CityBuildingLayer 支持的 windowColor 属性,每个图层具体要如何配置属性请查看每个图层的详细文档。 - opacity 设置透明度 大部分图层都支持 - stroke 线填充颜色 仅点图层支持 - strokeWidth 线的宽度 仅点图层支持 ```javascript layer.style({ opacity: 0.8, stroke: 'white', }); ``` - 样式数据映射🌟
在正常情况下,style 的参数会作用到一个图层上的所有图形,如一个 PointLayer 中有十个点,我们设置 opacity = 0.5, 这样十个点的透明度都是 0.5。
而在特殊情况下,我们可能需要为每个点分别设置一个透明度,这时候按照原来的方式直接设置 style 方法的 opacity 的值就无法满足需求了,为此我们需要提供特殊的赋值方式。
通常我们会根据传入图层的数据为图层的每个图形设置单独的值,因此我们称之为“样式数据映射”。
我们支持几种设置 style 中的参数从 source 数据中动态取值的写法。 ```javascript // 根据数据中的 v 字段的值设置点图层各个点的透明度 const data = [ { lng: 120, lat: 30, v: 0.5 }, ... ] const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat' } }) .shape('circle') .color('#f00') .size({ // 第一种写法 根据字段从 data 中直接取值 opacity: 'v'// opacity = 0.5 }); scene.addLayer(layer); ``` [在线案例](/zh/examples/point/text/style-map/) 从 `L7 2.5` 开始,各图层样式将逐步支持样式数据映射,目前支持样式数据映射的 `style` 参数如下: | layer 类型/shape | 支持的样式字段 | 备注 | | ---------------------- | ---------------------------------------------------- | --------------------------------- | | pointLayer/fill | opacity、strokeOpacity、strokeWidth、stroke、offsets | shape circle、triangle... | | pointLayer/image | opacity、offsets | offsets 经纬度偏移 | | pointLayer/normal | opacity、offsets | | | pointLayer/text | opacity、strokeWidth、stroke、textOffset | textOffset 相对文字画布位置的偏移 | | pointLayer/extrude | opacity | | | polygonLayer/fill | opacity | | | polygonLayer/extrude | opacity | | | lineLayer/line | opacity | | | lineLayer/arc | opacity、thetaOffset | thetaOffset 弧线的弯曲弧度 | | lineLayer/arc3d | opacity | | | lineLayer/great_circle | opacity | | 案例 [在线案例](/zh/examples/point/scatter/scatter-style-map/) ### texture 目前只在线图层上支持了纹理方法 - texture 方法支持传入由 scene.addImage 方法添加的全局 icon 贴图资源 ```javascript // 首先在全局加载图片资源 scene.addImage( 'plane', 'https://gw.alipayobjects.com/zos/bmw-prod/0ca1668e-38c2-4010-8568-b57cb33839b9.svg', ); const layer = new LineLayer({ blend: 'normal', }) .source(data, { parser: { type: 'json', x: 'lng1', y: 'lat1', x1: 'lng2', y1: 'lat2', }, }) .size(25) .shape('arc') .texture('plane') // 为图层绑定纹理 .color('#8C1EB2') .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 30, // 设置贴图纹理的间距 textureBlend: 'replace', // 设置纹理混合方式,默认值为 normal,可选值有 normal/replace 两种 }); ``` 案例 [在线案例](/zh/examples/line/animate/plane-animate2/) ## 图层更新方法 如果已经添加了图层,需要修改图层显示样式可以再次调用图形映射方法,然后调用 `scene.render()`更新渲染即可 ### scale 更新 重新调用scale 方法 ```tsx layer.scale('value', { type: 'quantile', }); scene.render(); ``` ### 数据映射 重新调用 color/size/filter/shape等方法 ```javascript layer.color('blue'); layer.size(10); scene.render(); ``` ### layer.style ```javascript layer.style({ opacity: 1, }); scene.render(); ``` ### setData(data, option?: {}) 更新 Source 数据 参数: - data 数据 - option 默认和初始配置项一致,如果数据格式相同可不设置 调用 setData 方法会自动更新图层渲染 ```javascript layer.setData(data); ``` ### setBlend(type: string) 设置图层叠加方法 参数: - type blend 类型 normal | additive | subtractive | max ## 图层控制方法 ### show() 图层显示 ```javascript layer.show(); ``` ### hide() 图层隐藏 ```javascript layer.hide(); ``` ### isVisible(): boolean 图层是否可见 ```javascript layer.isVisible(); ``` ### setIndex(zIndex: int) 设置图层绘制顺序 ```javascript layer.setIndex(1); ``` ### fitBounds() 缩放到图层范围 ```javascript layer.fitBounds(); ``` ### setMinZoom(zoom: number) 设置图层最小缩放等级 ```javascript layer.setMinZoom(zoom); ``` ### setMaxZoom(zoom: number) 设置图层最大缩放等级 参数 - zoom {number} ```javascript layer.setMaxZoom(zoom); ``` ### getMinZoom(): number 获取图层最小缩放等级 ```javascript const minZoom = layer.getMinZoom(); ``` ### getMaxZoom(): number 获取图层最大缩放等级 ```javascript const maxZoom = layer.getMaxZoom(); ``` ### destroy() 销毁图层,释放相关资源。场景调用 `removeLayer` 时会自动销毁图层,一般不需要手动调用。 ```javascript layer.destroy(); ``` ## 图层交互方法 ### active(activeOption | boolean) - 开启或者关闭 mousehover 元素高亮效果 - `activeOption` - `color`: 高亮颜色 - `mix`: 可选参数,默认为 0,表示高亮颜色是指定纯色,最大有效值是1,表示高亮色全部是底色 ```javascript activeOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.active(true); // 开启 Active 自定义高亮颜色 layer.active({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.active(false); ``` ### setActive(featureId: int) 根据元素 ID 设置指定元素 hover 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setActive(featureId); ``` ### select(selectOption | boolean) - 开启或者关闭 mouseclick 元素选中高亮效果 - selectOption - `color`: 选中高亮颜色 - `mix`: 可选参数,默认为 0,表示选中高亮颜色是指定纯色,最大有效值是1,表示选中高亮色全部是底色 ```javascript selectOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.select(true); // 开启 Active 自定义高亮颜色 layer.select({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.select(false); ``` ### setSelect(featureId: int) 根据元素 ID 设置指定元素 click 选中 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setSelect(featureId); ``` ### setAutoFit(autoFit: boolean) 让用户可以主动设置图层的 autoFit 参数
🌟 设置完该方法后会在图层发生更新的时候生效,如在 setData 之后触发 ```javascript // 使用方法 layer.setAutoFit(true); // 内部实现 public setAutoFit(autoFit: boolean): ILayer { this.updateLayerConfig({ autoFit, }); return this; } ``` ### getScale(attr: string) 支持单独获取某个图形经过 scale 计算后的值, 满足用户获取图层某些 feature 值的需求。 - attr scale 的属性值 ```javascript const data = [ { lng: 120, lat: 30, name: 'n1' }, { lng: 120, lat: 30, name: 'n2' }, ]; const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat', type: 'json', }, }) .shape('circle') .color('name', ['#f00', '#ff0']) .size('name', [20, 40]); scene.addLayer(layer); // 此时在 scene 上绘制两个点 // 一个颜色为黄色,大小为 40 的点,对应 name 为 n1 // 一个颜色为红色,大小为 20 的点,对应 name 为 n2 const colorScale = layer.getScale('color'); // 获取 color 方法产生的 scale const color1 = colorScale('n1'); // '#ff0' const color1 = colorScale('n2'); // '#f00' const sizeScale = layer.getScale('size'); // 获取 size 方法产生的 scale const size1 = sizeScale('n1'); // 40 const size2 = sizeScale('n2'); // 20 ``` ### getLegendItems(type: string) 不推荐使用,将废弃, 获取图例配置 - type 图例类型 - index 可选 默认 ```javascript layer.getLegendItems('color'); layer.getLegendItems('size'); ``` ### getLegend(type: string) getLegendItems方法的替代方法 该方法需要 返回值 - type 图例类型 - field 映射字段 - items 图例项 ```javascript layer.getLegend('color'); layer.getLegend('size'); ``` 注:rasterayer 只支持 color 类型 ## 图层掩模方法 ### addMask 添加 Mask 图层 ```ts const polygonLayer = new Polygon(); layer.addMask(polygonLayer); scene.render(); ``` ### removeMask ```ts const polygonLayer = new Polygon(); layer.removeMask(polygonLayer); scene.render(); ``` ### disableMask ```ts layer.disableMask(); scene.render(); ``` ### enableMask ```ts layer.enableMask(); scene.render(); ``` ## 鼠标事件 鼠标事件回调参数 target ```javascript layer.on(eventName, (target) => console.log(target)); ``` - x: number 鼠标  在地图位置 x 坐标 - y: number 鼠标  在地图位置 y 坐标 - type: string 鼠标事件类型 - lngLat: 经度度对象 {lng:number, lat: number }; 鼠标所在位置经纬度 - feature: any; 数据选中的地理要素信息 - featureId: number | null; 数据选中的地理要素的 ID ### click 点击事件 ```javascript layer.on('click', (e) => console.log(e)); ``` ### dblclick 双击 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mousemove 鼠标移动事件 ```javascript layer.on('mousemove', (e) => console.log(e)); ``` ### mouseout 鼠标移除 ```javascript layer.on('mouseout', (e) => console.log(e)); ``` ### mouseup 鼠标抬起 ```javascript layer.on('mouseup', (e) => console.log(e)); ``` ### mousedown 鼠标按下 ```javascript layer.on('mousedown', (e) => console.log(e)); ``` ### contextmenu 鼠标右键 ```javascript layer.on('contextmenu', (e) => console.log(e)); ``` ### dblclick 双击拾取元素 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mouseenter 鼠标进入图层要素时触发 ```javascript layer.on('mouseenter', (e) => console.log(e)); ``` ### unclick 点击未拾取到元素 ```javascript layer.on('unclick', (e) => console.log(e)); ``` ### unmousemove 鼠标移动未拾取到元素 ```javascript layer.on('unmousemove', (e) => console.log(e)); ``` ### unmouseup 鼠标抬起未拾取到元素 ```javascript layer.on('unmouseup', (e) => console.log(e)); ``` ### unmousedown 鼠标按下未拾取到元素 ```javascript layer.on('unmousedown', (e) => console.log(e)); ``` ### uncontextmenu 鼠标右键位拾取到元素 ```javascript layer.on('uncontextmenu', (e) => console.log(e)); ``` ### unpick 所有鼠标事件未拾取到 ```javascript layer.on('unpick', (e) => console.log(e)); ``` ### touchstart 移动端事件 touchstart ```javascript layer.on('touchstart', (e) => console.log(e)); ``` ### touchend 移动端事件 touchend ```javascript layer.on('touchend', (e) => console.log(e)); ``` 使用示例 ```javascript layer.on('click', (ev) => {}); // 鼠标左键点击图层事件 layer.on('mouseenter', (ev) => {}); // 鼠标进入图层要素 layer.on('mousemove', (ev) => {}); // 鼠标在图层上移动时触发 layer.on('mouseout', (ev) => {}); // 鼠标移出图层要素时触发 layer.on('mouseup', (ev) => {}); // 鼠标在图层上单击抬起时触发 layer.on('mousedown', (ev) => {}); // 鼠标在图层上单击按下时触发 layer.on('contextmenu', (ev) => {}); // 图层要素点击右键菜单 // 鼠标在图层外的事件 layer.on('unclick', (ev) => {}); // 图层外点击 layer.on('unmousemove', (ev) => {}); // 图层外移动 layer.on('unmouseup', (ev) => {}); // 图层外鼠标抬起 layer.on('unmousedown', (ev) => {}); // 图层外单击按下时触发 layer.on('uncontextmenu', (ev) => {}); // 图层外点击右键 layer.on('unpick', (ev) => {}); // 图层外的操作的所有事件 ``` ## 图层事件 ### inited 参数 option - target 当前 layer - type 事件类型 图层初始化完成后触发 ```javascript layer.on('inited', (option) => {}); ``` ### add 图层添加到 scene 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('add', (type) => console.log(type)); ``` ### remove 图层移除时触发 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('remove', (type) => console.log(type)); ``` ### legend 数据映射更新,图例发生变化,主要 color、size ### `legend:color` 数据映射更新,图例 color 颜色改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:color', (ev) => console.log(ev)); ``` ### `legend:size` 数据映射更新,图例 size 大小改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:size', (ev) => console.log(ev)); ``` ## 图层框选 ### boxSelect 参数 option - box [x1: number, y1: number, x2: number, y2: number] 相较于 - cb (...args: any[]) => void 传入的回调方法,返回框选内部的 feature ```javascript layer.boxSelect(box, cb); // (x1, y1), (x2, y2) 框选的方框左上角和右下角相对于地图左上角的像素坐标 // cb 是传入的回调函数,回调函数返回的参数是选中的 feature 对象数组,对象的字段和用户传入的数据相关 ``` #### RasterLayer - Canonical page: https://l7.antv.antgroup.com/zh/api/raster_layer/raster/ - Markdown source: https://l7.antv.antgroup.com/zh/api/raster_layer/raster.md - Description: RasterLayer --- title: "RasterLayer" description: "RasterLayer" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/raster_layer/raster/" --- ## 简介 `RasterLayer` 图层主要实现栅格数据的可视化,栅格数据主要来源是卫星遥感数据,如数字高程图、植被分布图、夜光图等。L7 支持三种栅格可视化模式: | 模式 | shape 值 | 说明 | | ----------- | ----------- | ---------------------------------------------------- | | Raster Data | `raster` | 单波段,根据栅格数据值映射为颜色 | | Raster RGB | `rasterRgb` | 多波段,不同波段映射为 R/G/B 三通道展示 | | Raster NDI | `rasterNdi` | 多波段,提供两个波段进行归一化指数计算 `(b-a)/(b+a)` | ```javascript import { RasterLayer } from '@antv/l7'; // Raster Data 模式示例 const layer = new RasterLayer() .source(rasterData, { parser: { type: 'raster', width: 256, height: 256, extent: [73, 3, 136, 54], }, }) .style({ rampColors: { colors: ['#FF4818', '#F7B74A', '#FFF598', '#91EABC', '#2EA9A1', '#206C7C'], positions: [0, 0.2, 0.4, 0.6, 0.8, 1.0], }, }); ``` ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## Raster Data ## 简介 单波段栅格数据渲染、根据栅格数据进行可视化着色 ## source Raster data 数据栅格的可视化,栅格数据主要来源是卫星遥感数据,如数字高程图、植被分布图和夜光图。 - data 数据 - option 配置项 - parser 数据解析参数 ### data data 解析后的数据,为数组 ```ts type RasterDataType = | Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array; ``` 以 geotiff 为例需要先将数据解析出来,作为 data 输入给 source ```tsx import * as GeoTIFF from 'geotiff'; async function getTiffData() { async function getTiffData() { const response = await fetch( 'https://gw.alipayobjects.com/zos/antvdemo/assets/light_clip/lightF182013.tiff', ); const arrayBuffer = await response.arrayBuffer(); const tiff = await GeoTIFF.fromArrayBuffer(arrayBuffer); const image = await tiff.getImage(); const width = image.getWidth(); const height = image.getHeight(); const values = await image.readRasters(); return { data: values[0], width, height, }; } } const tiffdata = await getTiffData(); layer.source(tiffdata.data, { parser: { type: 'raster', width: tiffdata.width, height: tiffdata.height, extent: [73.4821902409999979, 3.8150178409999995, 135.1066187319999869, 57.6300459959999998], }, }); ``` ### parser - type: raster - extent: 栅格的经纬度范围 [minlng, minlat,maxLng, maxLat] - width 数据宽度 - height 数据高度 根据栅格数据的经纬度范围,将其添加到地图上。 ```javascript layer.source(rasterData, { parser: { type: 'raster', extent: [121.168, 30.2828, 121.384, 30.4219], }, }); ``` ### 完整示例 [Raster ndi](../../../../examples/raster/data/#dem) ## style `style` 方法用于配制图层的样式, - 单通道 绘制结果由是单一的数值控制,如灰度图,数值对应的颜色可以通过表示配置 `rampColors` 色带控制。 ```js layer.style({ opacity: 0.5, }); ``` ### 配置 | style | 类型 | 描述 | 默认值 | | ----------- | ------------------ | ------------------------------------------- | ------------- | | opacity | `number` | 图形的透明度 | `1` | | clampLow | `boolean` | 设置为 `true`,低于 `domain` 的数据将不显示 | `false` | | clampHigh | `boolean` | 设置为 `true`,高于 `domain` 的数据将不显示 | `false` | | domain | `[number, number]` | 数据映射区间 | `[ 0, 8000 ]` | | noDataValue | `number` | 不会显示的值 | `-9999999` | | rampColors | `IRampColors` | 值域映射颜色的色带 | `/` | ### rampColors 颜色色带 - type 类型 支持 `linear','quantize','custom','cat' - colors  颜色数组 - positions 数据分段区间,可选,quantize 不需要设置 position,position 为原始数据值 ⚠️ 2.13 新增特性 #### cat 枚举类型色带 枚举类型色带只支持 0 -255 的整数类型,positions 用来设置枚举 ```tsx { type:'cat', colors:['#e41a1c','#377eb8','#4daf4a','#984ea3','#ff7f00'], positions:[1,20,101,102,200], } ``` #### quantize 等间距分类色带 等间距只根据数据的区间 domain 进行均匀分段,如 domain [0,10000],如果分 5 段,每段间距 2000。 等间距不需要设置 positions,只需要设置colors,根据colors 的长度设置分段数 ```tsx rampColors: { type:'quantize', colors: ['#f0f9e8','#bae4bc','#7bccc4','#43a2ca','#0868ac'] } ``` #### linear 线性连续色带 linear 为现有连续类型的加强版,positions 支持设置源数据,不需要转换成 0-1 ```tsx rampColors: { type:'linear', colors: ['#f0f9e8','#bae4bc','#7bccc4','#43a2ca','#0868ac'], positions [0,200,1000,4000,8000] } ⚠️ 兼容 2.13.0 之前版本,未设置type 时,position 值域为 0-1。 ``` #### custom 自定义分段色带 自定义分段色带区别等间距色带,用户自定义分段间隔。 自定义 positions 的长度需要比 colors 的长度多1个,同时poisitions ```tsx rampColors: { type:'custom', colors: ['#f0f9e8','#bae4bc','#7bccc4','#43a2ca','#0868ac'], positions: [0,200,1000,4000,8000,10000] } ``` ## Raster RGB ## 简介 `Raster RGB ` 波段组合可视化,不同波段映射到 R/G/B 通道可视化 ## source raster-rgb source 是将多波段数据合成 RGB数据进行展示,如对 LandSat8 数据我们可以按照 5,4,3 或者 4,3,2 波段进行RGB组合显示 - data 数据 - option 配置项 - parser 数据解析参数 - type 解析类型 `rgb` ```ts layer.source(bandsValues, { parser: { type: 'rgb', width: bandsValues.width, height: bandsValues.height, bands: [4, 3, 2], // 从零开始 extent: [130.39565357746957, 46.905730725742366, 130.73364094187343, 47.10217234153133], }, }); ``` ### data ```ts type RasterDataType = | Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array; ``` data 为数组类型 `RasterDataType[]` - 如果是多波段 Tiff 可以直接使用geotiff,js 读取所有波段, - 如果是单文件单波段数据,需要单独读取并合并成一个数据。 单文件多波段读取示例 ```ts async function getTiffData(url: string) { const response = await fetch(url); const arrayBuffer = await response.arrayBuffer(); const tiff = await GeoTIFF.fromArrayBuffer(arrayBuffer); const image1 = await tiff.getImage(); const bandsValues = await image1.readRasters(); return bandsValues; } ``` ### parser - type 解析类型 'rgb' `必选` - bands `[number,number,number] 指定 R/G/B 通道对应的数据索引,data 数组长度需要大于等于 3 `必选` 注:bands 序号从零开始(landsat 8 里的 5,4,3 波段这样要设置为 4,3, 2) - width 长度 `必选` - height 宽度 `必选` - countCut 颜色拉伸参数 `[number,number]` 数值为百分比,默认值 `[2,98]` `可选` ### 完整示例 [Raster RGB](../../../../examples/raster/rgb/#543) ## style ### opacity 透明度 ```js layer.style({ opacity: 0.5, }); ``` ## Raster NDI ## 简介 `Raster NDI` Normalized Difference Indices 归一化指数计算,提供另个波段,进行归一化计算 ## source raster-ndi(Normalized Difference Indices) source 是将多波段数据进行归一化指数计算,比如计算NDVI/NDWI 等指数, - data 数据 - option 配置项 - parser 数据解析参数 - type 解析类型 `ndi` ```ts layer.source(bandsValues, { parser: { type: 'ndi', width: bandsValues.width, height: bandsValues.height, bands: [4, 3], // 从零开始 extent: [130.39565357746957, 46.905730725742366, 130.73364094187343, 47.10217234153133], }, }); ``` ### data ```ts type RasterDataType = | Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array; ``` data 为数组类型 `RasterDataType[]` - 如果是多波段 Tiff 可以直接使用geotiff,js 读取所有波段, - 如果是单文件单波段数据,需要单独读取并合并成一个数据。 单文件多波段读取示例 ```ts async function getTiffData(url: string) { const response = await fetch(url); const arrayBuffer = await response.arrayBuffer(); const tiff = await GeoTIFF.fromArrayBuffer(arrayBuffer); const image1 = await tiff.getImage(); const bandsValues = await image1.readRasters(); return bandsValues; } ``` ### parser - type 解析类型 'rgb' `必选` - bands `[number,number] 指定需要归一化的波段,data 数组长度需要大于等于 2 `必选` 注:bands 序号从零开始(landsat 8 里的 5,4, 波段这样要设置为 4,3) - width 长度 `必选` - height 宽度 `必选` ### 完整示例 [Raster ndi](../../../../examples/raster/ndi/#ndbi) ## style `style` 方法用于配制图层的样式, - 单通道 绘制结果由是单一的数值控制,如灰度图,数值对应的颜色可以通过表示配置 `rampColors` 色带控制。 ```js layer.style({ opacity: 0.5, }); ``` ### 配置 | style | 类型 | 描述 | 默认值 | | ----------- | ------------------ | ------------------------------------------- | ------------- | | opacity | `number` | 图形的透明度 | `1` | | clampLow | `boolean` | 设置为 `true`,低于 `domain` 的数据将不显示 | `false` | | clampHigh | `boolean` | 设置为 `true`,高于 `domain` 的数据将不显示 | `false` | | domain | `[number, number]` | 数据映射区间 | `[ 0, 8000 ]` | | noDataValue | `number` | 不会显示的值 | `-9999999` | | rampColors | `IRampColors` | 值域映射颜色的色带 | `/` | ### rampColors 颜色色带 - type 类型 支持 `linear','quantize','custom','cat' - colors  颜色数组 - positions 数据分段区间,可选,quantize 不需要设置 position,position 为原始数据值 ⚠️ 2.13 新增特性 #### cat 枚举类型色带 枚举类型色带只支持 0 -255 的整数类型,positions 用来设置枚举 ```tsx { type:'cat', colors:['#e41a1c','#377eb8','#4daf4a','#984ea3','#ff7f00'], positions:[1,20,101,102,200], } ``` #### quantize 等间距分类色带 等间距只根据数据的区间 domain 进行均匀分段,如 domain [0,10000],如果分 5 段,每段间距 2000。 等间距不需要设置 positions,只需要设置colors,根据colors 的长度设置分段数 ```tsx rampColors: { type:'quantize', colors: ['#f0f9e8','#bae4bc','#7bccc4','#43a2ca','#0868ac'] } ``` #### linear 线性连续色带 linear 为现有连续类型的加强版,positions 支持设置源数据,不需要转换成 0-1 ```tsx rampColors: { type:'linear', colors: ['#f0f9e8','#bae4bc','#7bccc4','#43a2ca','#0868ac'], positions [0,200,1000,4000,8000] } ⚠️ 兼容 2.13.0 之前版本,未设置type 时,position 值域为 0-1。 ``` #### custom 自定义分段色带 自定义分段色带区别等间距色带,用户自定义分段间隔。 自定义 positions 的长度需要比 colors 的长度多1个,同时poisitions ```tsx rampColors: { type:'custom', colors: ['#f0f9e8','#bae4bc','#7bccc4','#43a2ca','#0868ac'], positions: [0,200,1000,4000,8000,10000] } ``` ## 图层通用方法 ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## 数据方法 ### source 数据 设置图层数据以及解析配置 `source(data, config)`。 - data { geojson | json | csv } - config   可选   数据源配置项 - parser 数据解析,默认是解析层 geojson - transforms [transform,transform ]  数据处理转换可设置多个 `parser` 和  `transforms` [见 source 文档](/zh/api/source/source)。 ```javascript layer.source(data, { parser: { type: 'csv', x: 'lng', y: 'lat', }, transforms: [ { type: 'map', callback: function (item) { const [x, y] = item.coordinates; item.lat = item.lat * 1; item.lng = item.lng * 1; item.v = item.v * 1; item.coordinates = [x * 1, y * 1]; return item; }, }, { type: 'hexagon', size: 6000, field: 'v', method: 'sum', }, ], }); ``` ### cluster 我们在使用 `cluster` 配置聚合图之后就可以使用一些聚合方法来获取对应参数。 #### getClusters(zoom: number): IFeatureCollection 获取指定缩放等级的聚合数据 - `zoom` 缩放等级 #### getClustersLeaves(id: string): IFeatureCollection 根据 `id` 获取聚合节点的数据,每个聚合节点会有一个唯一 `ID`。 - `id` 聚合节点的 `id` ```ts const source = layer.getSource(); source.getClustersLeaves(id); layer.on('click', (e) => { console.log(source.getClustersLeaves(e.feature.cluster_id)); }); ``` ## scale 数据度量 Scale 度量是将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 L7 目前支持连续、离散、枚举类型数据的Scale,并支持位置、形状、大小和颜色编码的映射。 在使用 L7 过程中,默认情况下不需要进行 Scale 的配置,因为 L7 会根据数据类型对 scale 推断,推断过程如下: 查看用户是否设置了 Scale,如果没有: 判断字段的第一条数据的字段类型,如果数据中不存在对应的字段: 认为是常量为固定值 如果是数字则为 'linear'; 如果是字符串类型 'cat'; ### scale [Scale 详细介绍](https://mp.weixin.qq.com/s/QyD1_ypu0PDwMxEz45v6Jg) 参数: (field: string, scaleOptions: IscaleOptions) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleOptions` 列定义配置,对象类型 - type scale 类型 - unknown 未匹配颜色 可选 默认透明 - domain 值域 可选 ```javascript interface IscaleOptions { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` #### 类型 Range 和 domain 是 Scale 中非常重要的两个参数 domain: 地图数据值的定义区间 range:视觉值的区间 不同Scale 的差异在于 domain->range 的转换方法的不同 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类 | 度量类型 | | --------- | ------------------------------------- | | 连续 | linear、log、pow | | 连续分类 | quantize quantile,threshold,diverging | | 分类 枚举 | cat | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 数据值和映射值相同 比如数据中value 字段记录了每个要素的颜色,数值既为要映射的结果值s ``` // 设置为 identify layer.scale('value', { type: 'identify' }); // 或者 layer.scale('value'); // L7 能够自动推断为 identify ``` #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging 离散分类通常与两种相反的色调一起使用,以显示从负值到中心到正值的变化。这些类型的地图显示了彼此相关的值的大小。 ### getScale(scaleName:string) 根据视觉通道名称获取 scale 实例,调用之前确保 layer 已经初始化完成 ```ts const scale = layer.getScale('color'); const color = scale(1); // 将数值转换成颜色 ``` 更多是方法 scale 示例使用 ## 视觉编码方法 可视化编码是将数据转换为可视形式的过程,L7 目前支持形状,大小,颜色 3 种视觉通道,你可以指定数据字段,为不同要素设置不同的图形属性。 案例 ### filter 数据过滤方法,支持回调函数,将数据映射为true | false, 结果为true 时可见 ```ts pointLayer.filter('type', (type) => { // 回调函数 if (type === 'a') { return false; } return true; }); ``` ### size 将数据值映射到图形的大小上的方法,size 方法具体的参数使用可以查看对应图层的详细文档 ```javascript pointLayer.size(10); // 常量 pointLayer.size('type'); // 使用字段映射到大小 pointLayer.size('type', [0, 10]); // 使用字段映射到大小,并指定最大值和最小值 pointLayer.size('type', (type) => { // 回调函数 if (type === 'a') { return 10; } return 5; }); ``` #### size(value) 传入数字常量,如  `pointLayer.size(20)` #### size(field) 根据 field 字段的值映射大小,使用默认的`最大值 max:10`  和`最小值 min: 1`。 #### size(field, callback) 使用回调函数控制图形大小。 - `callback`: function 回调函数。 ```javascript pointLayer.size('age', (value) => { if (value === 1) { return 5; } return 10; }); ``` ### color 将数据值映射到图形的颜色上的方法。 ```javascript layer.color('red'); // 常量颜色 layer.color('type'); // 对 type 字段进行映射,使用内置的颜色 layer.color('type', ['red', 'blue']); // 指定颜色 layer.color('type', (type) => { // 通过回调函数 if (type === 'a') { return 'red'; } return 'blue'; }); layer.color('type*value', (type, value) => { //多个参数,通过回调函数 if (type === 'a' && value > 100) { return 'red'; } return 'blue'; }); ``` #### color(value) 参数:`value` :string 只支持接收一个参数,value 可以是: - 映射至颜色属性的数据源字段名,如果数据源中不存在这个字段名的话,则按照常量进行解析,这个时候会使用 L7 默认提供的颜色。 - 也可以直接指定某一个具体的颜色值 color,如 '#fff', 'white','rgba(255,0,0,0.5)' ,rgb(255,0,1) 等。 如果数据为映射到颜色,默认为透明色不显示,如果需要设置该颜色,需要在scale 中设置 示例 ```javascript layer.color('name'); // 映射数据字段 layer.color('white'); // 指定颜色 ``` #### color(field, colors) 参数: - `field`: stringfield 为映射至颜色属性的数据源字段名,也支持指定多个参数。 - `colors`: string | array | function colors 的参数有以下情况:  如果为空,即未指定颜色的数组,那么使用内置的全局的颜色;如果需要指定颜色,则需要以数组格式传入,那么分类的颜色按照数组中的颜色确定。 ```javascript layer.scale('name',{ type:'quantile' unknown:'#ccc' // 设置无效颜色 }) layer.color('name'); // 使用identity layer.color('name', ['red', 'blue']); // 使用传入的指定颜色 ``` - colors 如果是回调函数,则该回调函数的参数为对应字段的数值,具体使用如下,当 color 映射为多个字段时,参数按照字段声明的顺序传入: ```javascript layer.color('gender', (value) => { if (value === 1) { return 'red'; } return 'blue'; }); layer.color('gender*age', (gender, age) => { if (age === 20 && gender == ' 男') { return 'red'; } return 'blue'; }); ``` ### shape 通常一种图层可以有多种表现形式,shape 方法用于指定图层具体的表现形式,以 PointLayer 的 shape 为例: ```javascript shape('circle'); // 圆形 shape('triangle'); // 三角形 shape('cylinder'); // 圆柱 ``` 案例 **shape(shape)** 参数 `shape` string - 只支持接收一个参数,指定几何图像对象绘制的形状。下表列出了不同的 图层 几何图形对象支持的 shape 形状 | layer 类型 | shape 类型 | 备注 | | ---------- | -------------------------------------------------------------------------------------- | ---- | | point | 2d:point,circle, square, triangle,hexagon,image,text 3d:circle,triangle,hexagon,square | | | line | line,arc, arc3d, greatcircle | | | polygon | fill,line, extrude | | **shape(field, shapes)** - shape 根据字段指定行形状,比如根据字段指定 PointLayer/imageLayer 的 icon 类型 ```javascript scene.addImage( '00', 'https://gw.alipayobjects.com/zos/basement_prod/604b5e7f-309e-40db-b95b-4fac746c5153.svg', ); scene.addImage( '01', 'https://gw.alipayobjects.com/zos/basement_prod/30580bc9-506f-4438-8c1a-744e082054ec.svg', ); scene.addImage( '02', 'https://gw.alipayobjects.com/zos/basement_prod/7aa1f460-9f9f-499f-afdf-13424aa26bbf.svg', ); const imageLayer = new PointLayer() .source(data, { parser: { type: 'json', x: 'longitude', y: 'latitude', }, }) .shape('name', ['00', '01', '02']) .size(20); scene.addLayer(imageLayer); ``` 案例 [在线案例](/zh/examples/point/image/image/) **shape(field, callback)** - shape 也支持回调函数的写法 ```javascript .shape('key', value => { if(value > 10) { return 'circle'; } else { return 'triangle'; } } ``` ### rotate 将数据值映射到图形的旋转角度上的方法,用于控制点图层图标/图形的旋转。 ```javascript layer.rotate(45); // 常量,所有元素旋转 45 度 layer.rotate('angle'); // 字段映射 layer.rotate('angle', [0, 360]); // 字段映射到角度范围 layer.rotate('angle', (angle) => { return angle * (Math.PI / 180); // 回调函数 }); ``` ### label 为图层设置标注(文字标签),将数据字段映射为标注内容显示在图层元素旁边。主要在特定图层类型(如 PointLayer 的文字标注)中生效。 ```javascript layer.label('name'); // 以 name 字段的值作为标注文本 layer.label('name', (name) => `${name}市`); // 回调函数处理标注文本 ``` ### style style 方法通常用于描述图层具体的样式,大多数图层会支持一些比较通用的属性, 如 opacity 属性,同时每个图层也会有仅限本图层支持的属性,如只有 CityBuildingLayer 支持的 windowColor 属性,每个图层具体要如何配置属性请查看每个图层的详细文档。 - opacity 设置透明度 大部分图层都支持 - stroke 线填充颜色 仅点图层支持 - strokeWidth 线的宽度 仅点图层支持 ```javascript layer.style({ opacity: 0.8, stroke: 'white', }); ``` - 样式数据映射🌟
在正常情况下,style 的参数会作用到一个图层上的所有图形,如一个 PointLayer 中有十个点,我们设置 opacity = 0.5, 这样十个点的透明度都是 0.5。
而在特殊情况下,我们可能需要为每个点分别设置一个透明度,这时候按照原来的方式直接设置 style 方法的 opacity 的值就无法满足需求了,为此我们需要提供特殊的赋值方式。
通常我们会根据传入图层的数据为图层的每个图形设置单独的值,因此我们称之为“样式数据映射”。
我们支持几种设置 style 中的参数从 source 数据中动态取值的写法。 ```javascript // 根据数据中的 v 字段的值设置点图层各个点的透明度 const data = [ { lng: 120, lat: 30, v: 0.5 }, ... ] const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat' } }) .shape('circle') .color('#f00') .size({ // 第一种写法 根据字段从 data 中直接取值 opacity: 'v'// opacity = 0.5 }); scene.addLayer(layer); ``` [在线案例](/zh/examples/point/text/style-map/) 从 `L7 2.5` 开始,各图层样式将逐步支持样式数据映射,目前支持样式数据映射的 `style` 参数如下: | layer 类型/shape | 支持的样式字段 | 备注 | | ---------------------- | ---------------------------------------------------- | --------------------------------- | | pointLayer/fill | opacity、strokeOpacity、strokeWidth、stroke、offsets | shape circle、triangle... | | pointLayer/image | opacity、offsets | offsets 经纬度偏移 | | pointLayer/normal | opacity、offsets | | | pointLayer/text | opacity、strokeWidth、stroke、textOffset | textOffset 相对文字画布位置的偏移 | | pointLayer/extrude | opacity | | | polygonLayer/fill | opacity | | | polygonLayer/extrude | opacity | | | lineLayer/line | opacity | | | lineLayer/arc | opacity、thetaOffset | thetaOffset 弧线的弯曲弧度 | | lineLayer/arc3d | opacity | | | lineLayer/great_circle | opacity | | 案例 [在线案例](/zh/examples/point/scatter/scatter-style-map/) ### texture 目前只在线图层上支持了纹理方法 - texture 方法支持传入由 scene.addImage 方法添加的全局 icon 贴图资源 ```javascript // 首先在全局加载图片资源 scene.addImage( 'plane', 'https://gw.alipayobjects.com/zos/bmw-prod/0ca1668e-38c2-4010-8568-b57cb33839b9.svg', ); const layer = new LineLayer({ blend: 'normal', }) .source(data, { parser: { type: 'json', x: 'lng1', y: 'lat1', x1: 'lng2', y1: 'lat2', }, }) .size(25) .shape('arc') .texture('plane') // 为图层绑定纹理 .color('#8C1EB2') .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 30, // 设置贴图纹理的间距 textureBlend: 'replace', // 设置纹理混合方式,默认值为 normal,可选值有 normal/replace 两种 }); ``` 案例 [在线案例](/zh/examples/line/animate/plane-animate2/) ## 图层更新方法 如果已经添加了图层,需要修改图层显示样式可以再次调用图形映射方法,然后调用 `scene.render()`更新渲染即可 ### scale 更新 重新调用scale 方法 ```tsx layer.scale('value', { type: 'quantile', }); scene.render(); ``` ### 数据映射 重新调用 color/size/filter/shape等方法 ```javascript layer.color('blue'); layer.size(10); scene.render(); ``` ### layer.style ```javascript layer.style({ opacity: 1, }); scene.render(); ``` ### setData(data, option?: {}) 更新 Source 数据 参数: - data 数据 - option 默认和初始配置项一致,如果数据格式相同可不设置 调用 setData 方法会自动更新图层渲染 ```javascript layer.setData(data); ``` ### setBlend(type: string) 设置图层叠加方法 参数: - type blend 类型 normal | additive | subtractive | max ## 图层控制方法 ### show() 图层显示 ```javascript layer.show(); ``` ### hide() 图层隐藏 ```javascript layer.hide(); ``` ### isVisible(): boolean 图层是否可见 ```javascript layer.isVisible(); ``` ### setIndex(zIndex: int) 设置图层绘制顺序 ```javascript layer.setIndex(1); ``` ### fitBounds() 缩放到图层范围 ```javascript layer.fitBounds(); ``` ### setMinZoom(zoom: number) 设置图层最小缩放等级 ```javascript layer.setMinZoom(zoom); ``` ### setMaxZoom(zoom: number) 设置图层最大缩放等级 参数 - zoom {number} ```javascript layer.setMaxZoom(zoom); ``` ### getMinZoom(): number 获取图层最小缩放等级 ```javascript const minZoom = layer.getMinZoom(); ``` ### getMaxZoom(): number 获取图层最大缩放等级 ```javascript const maxZoom = layer.getMaxZoom(); ``` ### destroy() 销毁图层,释放相关资源。场景调用 `removeLayer` 时会自动销毁图层,一般不需要手动调用。 ```javascript layer.destroy(); ``` ## 图层交互方法 ### active(activeOption | boolean) - 开启或者关闭 mousehover 元素高亮效果 - `activeOption` - `color`: 高亮颜色 - `mix`: 可选参数,默认为 0,表示高亮颜色是指定纯色,最大有效值是1,表示高亮色全部是底色 ```javascript activeOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.active(true); // 开启 Active 自定义高亮颜色 layer.active({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.active(false); ``` ### setActive(featureId: int) 根据元素 ID 设置指定元素 hover 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setActive(featureId); ``` ### select(selectOption | boolean) - 开启或者关闭 mouseclick 元素选中高亮效果 - selectOption - `color`: 选中高亮颜色 - `mix`: 可选参数,默认为 0,表示选中高亮颜色是指定纯色,最大有效值是1,表示选中高亮色全部是底色 ```javascript selectOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.select(true); // 开启 Active 自定义高亮颜色 layer.select({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.select(false); ``` ### setSelect(featureId: int) 根据元素 ID 设置指定元素 click 选中 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setSelect(featureId); ``` ### setAutoFit(autoFit: boolean) 让用户可以主动设置图层的 autoFit 参数
🌟 设置完该方法后会在图层发生更新的时候生效,如在 setData 之后触发 ```javascript // 使用方法 layer.setAutoFit(true); // 内部实现 public setAutoFit(autoFit: boolean): ILayer { this.updateLayerConfig({ autoFit, }); return this; } ``` ### getScale(attr: string) 支持单独获取某个图形经过 scale 计算后的值, 满足用户获取图层某些 feature 值的需求。 - attr scale 的属性值 ```javascript const data = [ { lng: 120, lat: 30, name: 'n1' }, { lng: 120, lat: 30, name: 'n2' }, ]; const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat', type: 'json', }, }) .shape('circle') .color('name', ['#f00', '#ff0']) .size('name', [20, 40]); scene.addLayer(layer); // 此时在 scene 上绘制两个点 // 一个颜色为黄色,大小为 40 的点,对应 name 为 n1 // 一个颜色为红色,大小为 20 的点,对应 name 为 n2 const colorScale = layer.getScale('color'); // 获取 color 方法产生的 scale const color1 = colorScale('n1'); // '#ff0' const color1 = colorScale('n2'); // '#f00' const sizeScale = layer.getScale('size'); // 获取 size 方法产生的 scale const size1 = sizeScale('n1'); // 40 const size2 = sizeScale('n2'); // 20 ``` ### getLegendItems(type: string) 不推荐使用,将废弃, 获取图例配置 - type 图例类型 - index 可选 默认 ```javascript layer.getLegendItems('color'); layer.getLegendItems('size'); ``` ### getLegend(type: string) getLegendItems方法的替代方法 该方法需要 返回值 - type 图例类型 - field 映射字段 - items 图例项 ```javascript layer.getLegend('color'); layer.getLegend('size'); ``` 注:rasterayer 只支持 color 类型 ## 图层掩模方法 ### addMask 添加 Mask 图层 ```ts const polygonLayer = new Polygon(); layer.addMask(polygonLayer); scene.render(); ``` ### removeMask ```ts const polygonLayer = new Polygon(); layer.removeMask(polygonLayer); scene.render(); ``` ### disableMask ```ts layer.disableMask(); scene.render(); ``` ### enableMask ```ts layer.enableMask(); scene.render(); ``` ## 鼠标事件 鼠标事件回调参数 target ```javascript layer.on(eventName, (target) => console.log(target)); ``` - x: number 鼠标  在地图位置 x 坐标 - y: number 鼠标  在地图位置 y 坐标 - type: string 鼠标事件类型 - lngLat: 经度度对象 {lng:number, lat: number }; 鼠标所在位置经纬度 - feature: any; 数据选中的地理要素信息 - featureId: number | null; 数据选中的地理要素的 ID ### click 点击事件 ```javascript layer.on('click', (e) => console.log(e)); ``` ### dblclick 双击 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mousemove 鼠标移动事件 ```javascript layer.on('mousemove', (e) => console.log(e)); ``` ### mouseout 鼠标移除 ```javascript layer.on('mouseout', (e) => console.log(e)); ``` ### mouseup 鼠标抬起 ```javascript layer.on('mouseup', (e) => console.log(e)); ``` ### mousedown 鼠标按下 ```javascript layer.on('mousedown', (e) => console.log(e)); ``` ### contextmenu 鼠标右键 ```javascript layer.on('contextmenu', (e) => console.log(e)); ``` ### dblclick 双击拾取元素 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mouseenter 鼠标进入图层要素时触发 ```javascript layer.on('mouseenter', (e) => console.log(e)); ``` ### unclick 点击未拾取到元素 ```javascript layer.on('unclick', (e) => console.log(e)); ``` ### unmousemove 鼠标移动未拾取到元素 ```javascript layer.on('unmousemove', (e) => console.log(e)); ``` ### unmouseup 鼠标抬起未拾取到元素 ```javascript layer.on('unmouseup', (e) => console.log(e)); ``` ### unmousedown 鼠标按下未拾取到元素 ```javascript layer.on('unmousedown', (e) => console.log(e)); ``` ### uncontextmenu 鼠标右键位拾取到元素 ```javascript layer.on('uncontextmenu', (e) => console.log(e)); ``` ### unpick 所有鼠标事件未拾取到 ```javascript layer.on('unpick', (e) => console.log(e)); ``` ### touchstart 移动端事件 touchstart ```javascript layer.on('touchstart', (e) => console.log(e)); ``` ### touchend 移动端事件 touchend ```javascript layer.on('touchend', (e) => console.log(e)); ``` 使用示例 ```javascript layer.on('click', (ev) => {}); // 鼠标左键点击图层事件 layer.on('mouseenter', (ev) => {}); // 鼠标进入图层要素 layer.on('mousemove', (ev) => {}); // 鼠标在图层上移动时触发 layer.on('mouseout', (ev) => {}); // 鼠标移出图层要素时触发 layer.on('mouseup', (ev) => {}); // 鼠标在图层上单击抬起时触发 layer.on('mousedown', (ev) => {}); // 鼠标在图层上单击按下时触发 layer.on('contextmenu', (ev) => {}); // 图层要素点击右键菜单 // 鼠标在图层外的事件 layer.on('unclick', (ev) => {}); // 图层外点击 layer.on('unmousemove', (ev) => {}); // 图层外移动 layer.on('unmouseup', (ev) => {}); // 图层外鼠标抬起 layer.on('unmousedown', (ev) => {}); // 图层外单击按下时触发 layer.on('uncontextmenu', (ev) => {}); // 图层外点击右键 layer.on('unpick', (ev) => {}); // 图层外的操作的所有事件 ``` ## 图层事件 ### inited 参数 option - target 当前 layer - type 事件类型 图层初始化完成后触发 ```javascript layer.on('inited', (option) => {}); ``` ### add 图层添加到 scene 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('add', (type) => console.log(type)); ``` ### remove 图层移除时触发 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('remove', (type) => console.log(type)); ``` ### legend 数据映射更新,图例发生变化,主要 color、size ### `legend:color` 数据映射更新,图例 color 颜色改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:color', (ev) => console.log(ev)); ``` ### `legend:size` 数据映射更新,图例 size 大小改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:size', (ev) => console.log(ev)); ``` ## 图层框选 ### boxSelect 参数 option - box [x1: number, y1: number, x2: number, y2: number] 相较于 - cb (...args: any[]) => void 传入的回调方法,返回框选内部的 feature ```javascript layer.boxSelect(box, cb); // (x1, y1), (x2, y2) 框选的方框左上角和右下角相对于地图左上角的像素坐标 // cb 是传入的回调函数,回调函数返回的参数是选中的 feature 对象数组,对象的字段和用户传入的数据相关 ``` #### 场景 Scene - Canonical page: https://l7.antv.antgroup.com/zh/api/scene/ - Markdown source: https://l7.antv.antgroup.com/zh/api/scene.md - Description: 地图场景初始 --- title: "场景 Scene" description: "地图场景初始" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/scene/" --- ## 简介 场景对象 `scene` 是包含地图、地图控件、组件、加载资源的全局对象,通过 `scene` 场景对象,我们可以获取到操作地图需要的所有内容。
案例
## options ### id _string | HTMLElement_ **必选** 需传入 dom 容器或者容器 id。 ### map MapInstance **必选** 可以通过 scene map 属性获取 map 实例。 ```javascript const map = scene.map; ``` 为了统一不同底图之前的接口差异 `L7` 在 `Scene` 层对 `map` 的方法做了统一,因此一些地图的操作方法可以通过 `Scene` 调用,这样,切换不同底图时可以保证表现一致。 示例代码 ```javascript const scene = new L7.Scene({ id: 'map', map: new L7.GaodeMap({ style: 'dark', center: [110.770672, 34.159869], pitch: 45, }), }); ``` ### logoPosition _string_ **可选** _default: 'bottomleft'_ `L7` 默认提供的 `Logo` 可以配置显示位置,默认在左下角。 - bottomright - topright - bottomleft - topleft - topcenter - bottomcenter - leftcenter - rightcenter ### logoVisible logo 是否可见 _boolean_ **可选** _default: true_ 配置 `L7` 的 `Logo` 是否显示,默认显示。 ### antialias 是否开启抗锯齿 _boolean_ **可选** _default: true_ 是否开启抗锯齿。 ### stencil 是否开启裁剪 _boolean_ **可选** _default: true_ 是否开启裁剪(stencil)。图层 `Mask` 掩模能力以及矢量瓦片需要开启该配置。 🌟 从 v2.7.2 版本开始支持。 ### preserveDrawingBuffer _boolean_ **可选** _default: false_ 是否保留缓冲区数据。设置为 `true` 时可通过 `canvas.toDataURL()` 导出地图图片。 ### renderer 渲染器 _'regl' | 'device'_ **可选** _default: 'device'_ 指定渲染器类型。`regl` 为旧版渲染器,`device` 为新版渲染器(基于 `@antv/g-device-api`),默认使用 `device` 渲染器。 ```javascript const scene = new Scene({ id: 'map', map: new Map({}), renderer: 'device', // 或 'regl' }); ``` ### animate 是否启用动画 _boolean_ **可选** _default: undefined_ 是否启用动画渲染。 ### debug 是否开启调试 _boolean_ **可选** _default: false_ 是否开启调试模式,开启后会输出调试信息。 ### pickBufferScale 选取缓冲区缩放比 _number_ **可选** _default: 1.0_ 设置像素选取(picking)缓冲区的缩放比。 ### fitBoundsOptions 适配边界选项 _object_ **可选** 当调用 `fitBounds` 方法时默认的选项配置,包含 `animate` 等参数。 ## Layer 方法 ### addLayer(layer): void 增加图层对象 把图层添加到 `Scene` 场景中。 参数 : - `layer` 图层对象 ```javascript scene.addLayer(layer); ``` ### getLayer(id: string): ILayer 获取对应的图层对象 获取对应的图层。 ```javascript scene.getLayer('layerID'); ``` ### getLayers(): ILayer[] 获取所有的地图图层 获取所有的地图图层。 ```javascript scene.getLayers(); ``` ### getLayerByName(name: string): ILayer 根据图层名称获取图层 根据图层名称获取图层。 - `name` 图层在初始化的时候配置图层的 `name`。 ```javascript scene.getLayerByName(name); ``` ### removeLayer(layer: ILayer): void 移除 layer 图层 移除 `layer` 图层。 ```javascript scene.removeLayer(layer); ``` 🌟 移除的同时会将图层进行销毁。 ### removeAllLayer(): Promise\ 移除所有的图层对象 移除所有的图层对象。 ```javascript await scene.removeAllLayer(); ``` 🌟 移除的同时会将图层进行销毁。 ### render(): void 手动触发渲染 手动触发场景重新渲染。 ```javascript scene.render(); ``` ### setEnableRender(flag: boolean): void 设置是否启用渲染 控制是否允许图层渲染更新。当设置为 `false` 时,图层的渲染将被暂停。 ```javascript scene.setEnableRender(false); // 暂停渲染 scene.setEnableRender(true); // 恢复渲染 ``` ### getPickedLayer(): string 获取当前拾取的图层 获取当前被鼠标拾取(hover/click)的图层 ID。 ```javascript const layerId = scene.getPickedLayer(); ``` ## 控制组件方法 ### addControl(ctl: IControl): void 添加组件控件 添加组件控件。 - `crl` 用户创建的控件对象。 ```javascript scene.addControl(ctl); ``` ### removeControl(ctr: IControl): void 移除用户添加的组件控件 移除用户添加的组件控件。 - `ctl` 用户创建的控件对象。 ```javascript scene.removeControl(ctl); ``` ### getControlByName(name: string): IControl 根据控件的名称来获取控件 根据控件的名称来获取控件。 ```javascript const zoomControl = new Zoom({ // zoom 控件 name: 'z1', // 用户传入的控件名称(也可以不传入,该控件默认名称为 zoom) position: 'topright', }); scene.getControlByName('z1'); ``` ## 气泡方法 ### addPopup(popup: Popup): void 添加气泡 往场景中添加气泡对象,气泡用于展示用户自定义信息。 ```javascript scene.addPopup(popup); ``` ### removePopup(popup: Popup): void 移除气泡 往场景中移除气泡对象 ```javascript scene.removePopup(popup); ``` ## 标记方法 ### addMarker(maker: IMarker): void 添加标记 往场景中添加标记对象,`Marker` 实例是用户自由控制的 `DOM`。 - `maker` 用户创建的 `Marker` 实例。 ```javascript const marker = new Marker({ element: el, }).setLnglat({ lng: nodes[i].x * 1, lat: nodes[i].y }); scene.addMarker(marker); ``` ### addMarkerLayer(layer: IMarkerLayer): void 添加 Marker 统一管理图层 当用户需要添加许多个 `Marker` 实例时,为了方便管理可以使用 `MarkerLayer` 对象统一管理。 - `layer` 标记图层对象。 ```javascript const markerLayer = new MarkerLayer(); scene.addMarkerLayer(markerLayer); ``` ### removeMarkerLayer(layer: IMarkerLayer): void 移除标签图层 移除标签图层。 - `layer` 标记图层对象。 ```javascript scene.removeMarkerLayer(markerLayer); ``` ### removeAllMarkers(): void 移除场景中所有的标签对象 移除场景中所有的标签对象。 ```javascript scene.removeAllMarkers(); ``` ### removeAllMakers(): void ⚠️ 已废弃 > ⚠️ 此方法已废弃,请使用 `removeAllMarkers()` 替代。 ## 静态方法 静态方法通过 Scene 类去调用,不是 scene 实例 ### addProtocol 添加自定义数据协议,设置一个自定义加载瓦片函数,当使用以自定义 URL 模式开头的数据时,该函数将被调用。 - protocol 协议名称 - handler 数据处理回调函数 - requestParameters: RequestParameters, - url 瓦片 URL,携带瓦片行列号 x,y,z - callback: ResponseCallback) => Cancelable - Cancelable: { cancel: () => void; }; #### 自定义函数 ```ts Scene.addProtocol('custom', (params, callback) => { fetch(`https://${params.url.split('://')[1]}`) .then((t) => { if (t.status == 200) { t.arrayBuffer().then((arr) => { callback(null, arr, null, null); }); } else { callback(new Error(`Tile fetch error: ${t.statusText}`)); } }) .catch((e) => { callback(new Error(e)); }); return { cancel: () => {} }; }); // the following is an example of a way to return an error when trying to load a tile Scene.addProtocol('custom2', (params, callback) => { callback(new Error('someErrorMessage')); return { cancel: () => {} }; }); ``` #### 加载 PMTiles ```ts import * as pmtiles from 'pmtiles'; const protocol = new pmtiles.Protocol(); const scene = new Scene({ id: 'map', map: new Map({ center: [11.2438, 43.7799], zoom: 12, }), }); scene.addProtocol('pmtiles', protocol.tile); const source = new Source( 'pmtiles://https://mdn.alipayobjects.com/afts/file/A*HYvHSZ-wQmIAAAAAAAAAAAAADrd2AQ/protomaps(vector)ODbL_firenze.bin', { parser: { type: 'mvt', tileSize: 256, maxZoom: 14, extent: [-180, -85.051129, 179, 85.051129], }, }, ); ``` ### removeProtocol 删除之前添加的协议 - name: 协议名称 ```ts scene.removeProtocol('pmtiles', protocol.tile); ``` ## 地图方法 ### getZoom(): number 获取缩放等级 获取当前缩放等级。 ```javascript scene.getZoom(); ``` ### getCenter(): ILngLat 获取地图中心 获取地图中心点 ```javascript interface ILngLat { lng: number; lat: number; } scene.getCenter(); ``` ### getSize(): [number, number] 获取地图容器大小 获取地图容器大小,width、height。 ```javascript scene.getSize(); ``` ### getPitch(): number 获取地图倾角 获取地图俯仰角。 ```javascript scene.getPitch(); ``` ### getContainer(): HTMLElement | null 获取地图容器 获取地图容器。 ```javascript scene.getContainer(); ``` ### setMapStyle(style: string): void 设置地图样式 参数 `style` 参数是字符串,可以选择内置的地图样式 具体样式格式和各底图设置方法一致。 `L7` 内置了三种地图样式,`AMAP` 和 `MapBox` 都适用。 - light - dark - normal 设置地图底图样式的方法。 ```javascript // 快捷名称设置 scene.setMapStyle('light'); // mapbox 主题设置 scene.setMapStyle('mapbox://styles/mapbox/streets-v11'); // AMap scene.setMapStyle('amap://styles/2a09079c3daac9420ee53b67307a8006?isPublic=true'); ``` ### setCenter(center: ICenter, option?: ICameraOptions): void 设置地图中心点 设置地图中心点坐标。`L7` 提供了 `setCenter` 方法,允许用户动态的设置地图的中心点位,同时允许通过可选的 `options` 属性设置偏移。 ```js type ICenter = [number, number]; interface ICameraOptions { padding: | number | [number, number, number, number] | { top?: number, bottom?: number, right?: number, left?: number, }; } scene.setCenter([lng, lat]); scene.setCenter([lng, lat], { padding: { top: 100, }, }); ``` 🌟 `padding` 参数支持如下的三种传值方式,数值的单位是 `px`,表示地图中心点距离容器边缘的偏移距离。 ```javascript export interface ICameraOptions { padding: | number | [number, number, number, number] | { top?: number, bottom?: number, right?: number, left?: number, }; } ``` [在线案例](/zh/examples/point/bubble/point/) ### setZoomAndCenter(zoom: number, center: ICenter): void 设置地图缩放等级和中心点 设置地图等级和中心。 ```javascript type ICenter = [number, number]; scene.setZoomAndCenter(zoom, center); ``` ### setZoom(zoom: number): void 设置地图缩放等级 设置地图缩放等级 ```javascript scene.setZoom(10); ``` ### setRotation(rotation: number): void 设置地图旋转 设置地图顺时针旋转角度,旋转原点为地图容器中心点,取值范围 [0-360]。 ```javascript scene.setRotation(rotation); ``` ### zoomIn(); void 地图放大一级 地图放大一级。 ```javascript scene.zoomIn(); ``` ### zoomOut(): void 地图缩小一级 地图缩小一级。 ```javascript scene.zoomOut(); ``` ### panTo(lnglat: ILngLat): void 地图移动 地图平移到指定的经纬度位置。 ```javascript type ILngLat = [number, number]; scene.panTo(LngLat); ``` ### panBy(x: number, y: number): void 地图平移 以像素为单位沿 X 方向和 Y 方向移动地图。 - `x` 水平方向移动像素 向右为正方向。 - `y` 垂直方向移动像素 向下为正方向。 ```javascript scene.panBy(x, y); ``` ### setPitch(pitch: number): void 设置地图倾角 设置地图仰俯角度。 ```javascript scene.setPitch(pitch); ``` ### setMapStatus(statusOption: IStatusOptions): void 设置地图状态 用来设置地图的一些交互配置。 ```javascript interface IStatusOptions { showIndoorMap: boolean; resizeEnable: boolean; dragEnable: boolean; keyboardEnable: boolean; doubleClickZoom: boolean; zoomEnable: boolean; rotateEnable: boolean; } scene.setMapStatus({ dragEnable: false }); ``` ### fitBounds(bound: IBounds, options?: IOptions): void 设置地图缩放范围 地图缩放到某个范围内。 - `bound` 表示经纬度范围 [[minlng,minlat],[maxlng,maxlat]]。 - `options` 用户传入,覆盖 `animate` 直接配置,覆盖 `Scene` 传入的配置项。 ```javascript type IBounds = [[number, number], [number, number]]; interface IOptions { [key]: any; animate: boolean; } scene.fitBounds([ [112, 32], [114, 35], ]); ``` ### containerToLngLat(point: IPoint): ILngLat 画布坐标转经纬度 将画布坐标转经纬度坐标 ```javascript type IPoint = [number, number]; interface ILngLat { lng: number; lat: number; } scene.containerToLngLat([10, 10]); ``` ### lngLatToContainer(lnglat: ILngLat): IPoint 经纬度转画布坐标 经纬度坐标转画布坐标。 ```javascript type ILngLat = [number, number]; interface IPoint { x: number; y: number; } scene.lngLatToContainer([120, 10]); ``` ### pixelToLngLat(pixel: IPoint): ILngLat 像素坐标转经纬度 地图像素坐标转经纬度坐标,像素坐标地图上某点距离容器左上角的位置。 ```javascript type IPoint = [number, number]; interface ILngLat { lng: number; lat: number; } scene.pixelToLngLat([10, 10]); ``` ### lngLatToPixel(lnglat: ILngLat): IPoint 经纬度转像素坐标 经纬度坐标转像素坐标。 ```javascript type ILngLat = [number, number]; interface IPoint { x: number; y: number; } scene.lngLatToPixel([120, 10]); ``` ### exportMap(type?: IImage): string 导出 导出地图,目前仅支持导出可视化层,不支持底图导出。 ```javascript type IImage = 'png' | 'jpg'; scene.exportMap('png'); ``` ### exportPng(type?: 'png' | 'jpg'): string 导出图片 `exportMap` 的别名方法,导出地图为图片。 ```javascript scene.exportPng('png'); // 等同于 scene.exportMap('png') scene.exportPng('jpg'); // 等同于 scene.exportMap('jpg') ``` ### setBgColor(color: string): void 设置背景色 设置场景背景颜色。 ```javascript scene.setBgColor('#000000'); ``` ### registerPostProcessingPass(constructor: any, name: string): void 注册后处理通道 注册后处理特效通道,用于实现如泛光(Bloom)、色彩校正等后处理效果。 ```javascript import { Scene, PostProcessingPass } from '@antv/l7'; scene.registerPostProcessingPass(PostProcessingPass, 'bloom'); ``` ### enableShaderPick(): void 启用着色器拾取 启用着色器拾取模式。 ```javascript scene.enableShaderPick(); ``` ### disableShaderPick(): void 禁用着色器拾取 禁用着色器拾取模式。 ```javascript scene.disableShaderPick(); ``` ### diasbleShaderPick(): void ⚠️ 已废弃 > ⚠️ 此方法名拼写错误已废弃,请使用 `disableShaderPick()` 替代。 ### enableBoxSelect(once?: boolean): void 启用框选 启用框选功能,允许用户通过拖拽矩形框来选择区域。`once` 参数为 `true` 时表示只触发一次框选后自动关闭。 ```javascript scene.enableBoxSelect(); // 持续框选 scene.enableBoxSelect(true); // 框选一次后自动关闭 ``` 框选事件可通过 `boxselect` 事件监听: ```javascript scene.on('boxselect', (e) => { console.log(e.bounds); // 框选的经纬度范围 }); ``` ### disableBoxSelect(): void 禁用框选 禁用框选功能。 ```javascript scene.disableBoxSelect(); ``` ### boxSelectEnable: boolean 框选状态 属性,表示当前框选是否启用。 ### startAnimate(): void 启动动画 启动持续渲染动画。默认情况下 L7 按需渲染,调用此方法可开启实时渲染循环,在需要持续动画或使用 SpectorJS 调试时非常有用。 ```javascript scene.startAnimate(); ``` ### stopAnimate(): void 停止动画 停止实时渲染动画,恢复按需渲染模式。 ```javascript scene.stopAnimate(); ``` ### getPointSizeRange(): Float32Array 获取点精灵大小范围 获取当前设备支持绘制的 `WebGL` 点精灵的大小范围。 ```javascript const range = scene.getPointSizeRange(); // range[0] 最小值, range[1] 最大值 ``` ### getMapService(): IMapService 获取地图服务 获取底层地图服务实例,可用于直接调用底图特有方法。 ```javascript const mapService = scene.getMapService(); ``` ### getMapContainer(): HTMLElement 获取地图容器 获取地图的主容器 DOM 元素。 ```javascript const container = scene.getMapContainer(); ``` ### getMapCanvasContainer(): HTMLElement 获取地图画布容器 获取地图画布容器的 DOM 元素。 ```javascript const canvasContainer = scene.getMapCanvasContainer(); ``` ### getServiceContainer(): IContainer 获取服务容器 获取依赖注入容器,可用于获取注册的服务实例。 ```javascript const container = scene.getServiceContainer(); ``` ### getType(): string 获取地图类型 获取当前使用的地图类型。 ```javascript const mapType = scene.getType(); // 如 'gaode', 'mapbox', 'map' 等 ``` ### getMinZoom(): number 获取最小缩放等级 获取地图支持的最小缩放等级。 ```javascript const minZoom = scene.getMinZoom(); ``` ### getMaxZoom(): number 获取最大缩放等级 获取地图支持的最大缩放等级。 ```javascript const maxZoom = scene.getMaxZoom(); ``` ### addIconFontGlyphs(fontFamily: string, glyphs: string[]): void 添加 IconFont 字形 为指定字体族添加字形数据,用于 SDF 文本渲染。 - `fontFamily` 字体族名称 - `glyphs` 字形数据数组 ```javascript scene.addIconFontGlyphs('iconfont', ['glyph1', 'glyph2']); ``` ### destroy(): void 场景销毁 `scene` 销毁方法,离开页面,不需要使用地图的时候调用,调用后 `scene` 中的资源和都会被销毁。 ```javascript scene.destroy(); ``` ## iconfont 映射支持 ### addIconFont(name: string, unicode: string): void 增加映射支持 支持对用户传入的数据进行 `unicode` 的映射,在内部维护一组名称和对应 `key` 的键值对。 ```javascript scene.addIconFont('icon1', ''); scene.addIconFont('icon2', ''); scene.addFontFace(fontFamily, fontPath); const pointIconFontLayer = new PointLayer({}) .source( [ { j: 140, w: 34, m: 'icon1', }, { j: 140, w: 36, m: 'icon2', }, ], { parser: { type: 'json', x: 'j', y: 'w', }, }, ) .shape('m', 'text') .size(12) .color('w', ['#f00', '#f00', '#0f0']) .style({ fontFamily, iconfont: true, textAllowOverlap: true, }); ``` ### addIconFonts(option: IOption): void 同时传入多组 name - unicode 的键值对 同时传入多组 `name - unicode` 的键值对。 ```javascript type IKeyValue = [name: string, unicode: string]; type IOption = Array; scene.addIconFonts([ ['icon1', ''], ['icon2', ''], ]); ``` ## 全局资源 ### addImage(id: string, img: IImage): void 添加全局资源 在 `scene` 全局中添加 `L7` 的图层对象可以使用的图片资源在。 ```javascript type IImage = HTMLImageElement | string | File; scene.addImage( '02','https://gw.alipayobjects.com/zos/bmw-prod/ce83fc30-701f-415b-9750-4b146f4b3dd6.svg'); ``` [示例地址](/zh/examples/gallery/animate/animate-path-texture/) ### hasImage(id: string): boolean 判断全局图片资源 判断是否已经在全局添加过相应的图片资源。 ```javascript scene.hasImage('imageID'); ``` ### removeImage(id: string): void 全局删除图片资源 从全局删除对应的图片资源。 ```javascript scene.removeImage('imageID'); ``` ### addFontFace(fontFamily: string, fontPath: string): void 添加字体文件 添加 `iconfont` 字体文件。 - `fontFamily` 用户为自己定义的字体名称 - `fontPath` 导入的文件地址 ```javascript let fontFamily = 'iconfont'; let fontPath = '//at.alicdn.com/t/font_2534097_iiet9d3nekn.woff2?t=1620444089776'; scene.addFontFace(fontFamily, fontPath); ``` ## 属性 ### loaded: boolean 场景是否加载完成。 ```javascript if (scene.loaded) { console.log('场景已加载'); } ``` ### map: IMapInstance 获取底层地图实例,可用于调用底图特有的 API。 ```javascript const mapInstance = scene.map; ``` ## 事件 ### on(eventName: string, handler: function): void 在 `scene` 上绑定事件监听。 - `eventName` 事件名。 - `handler` 事件回调函数。 ### off(eventName: string, handler: function): void 移除在 `scene` 上绑定的事件监听。 - `eventName` 事件名。 - `handler` 事件回调函数。 ### once(eventName: string, handler: function): void 在 `scene` 上绑定一次性事件监听,触发一次后自动移除。 - `eventName` 事件名。 - `handler` 事件回调函数。 ### 场景事件 `scene` 会触发一些常见的场景事件,用户在需要的时候可以进行监听。 #### loaded `scene` 初始化完成事件,我们经常在 `scene` 初始化完成后添加 `Layer`。 ```javascript scene.on('loaded', () => { scene.addLayer(layer); }); ``` #### maploaded 底层地图加载完成事件。 ```javascript scene.on('maploaded', () => { console.log('底图加载完成'); }); ``` #### fontloaded 字体加载完成事件。 ```javascript scene.on('fontloaded', () => { console.log('字体加载完成'); }); ``` #### resize 地图容器变化事件 ```javascript scene.on('resize', () => {}); // 地图容器大小改变事件 ``` #### destroy 场景销毁事件。 ```javascript scene.on('destroy', () => { console.log('场景已销毁'); }); ``` #### startAnimate 默认 L7 按需重绘,通过启动动画开启实时渲染,便于 SpectorJS 插件捕捉帧渲染。 #### stopAnimate 调试时使用,停止实时渲染 ### 地图事件 ```javascript scene.on('loaded', () => {}); //地图加载完成触发 scene.on('mapmove', () => {}); // 地图平移时触发事件 scene.on('movestart', () => {}); // 地图平移开始时触发 scene.on('moveend', () => {}); // 地图移动结束后触发,包括平移,以及中心点变化的缩放。如地图有拖拽缓动效果,则在缓动结束后触发 scene.on('zoomchange', () => {}); // 地图缩放级别更改后触发 scene.on('zoomstart', () => {}); // 缩放开始时触发 scene.on('zoomend', () => {}); // 缩放停止时触发 ``` 其他地图事件可以查看相应底图的事件文档,地图事件也可以通过 `Scene.map` 进行设置。 [Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/#map.event) [高德](https://lbs.amap.com/api/javascript-api/reference/map) ### 鼠标事件 ```javascript scene.on('click', (ev) => {}); // 鼠标左键点击事件 scene.on('dblclick', (ev) => {}); // 鼠标左键双击事件 scene.on('mousemove', (ev) => {}); // 鼠标在地图上移动时触发 scene.on('mousewheel', (ev) => {}); // 鼠标滚轮开始缩放地图时触发 scene.on('mouseover', (ev) => {}); // 鼠标移入地图容器内时触发 scene.on('mouseout', (ev) => {}); // 鼠标移出地图容器时触发 scene.on('mouseup', (ev) => {}); // 鼠标在地图上单击抬起时触发 scene.on('mousedown', (ev) => {}); // 鼠标在地图上单击按下时触发 scene.on('contextmenu', (ev) => {}); // 鼠标右键单击事件 scene.on('dragstart', (ev) => {}); //开始拖拽地图时触发 scene.on('dragging', (ev) => {}); // 拖拽地图过程中触发 scene.on('dragend', (ev) => {}); //停止拖拽地图时触发。如地图有拖拽缓动效果,则在拽停止,缓动开始前触发 scene.on('webglcontextlost', () => {}); // webgl 上下文丢失 ``` ### 拖拽事件 ```javascript scene.on('dragstart', (ev) => {}); // 开始拖拽地图时触发 scene.on('dragging', (ev) => {}); // 拖拽地图过程中触发 scene.on('dragend', (ev) => {}); // 停止拖拽地图时触发。如地图有拖拽缓动效果,则在拖拽停止,缓动开始前触发 scene.on('dragcancel', (ev) => {}); // 拖拽取消时触发 ``` ### 框选事件 当调用 `scene.enableBoxSelect()` 后,框选操作会触发以下事件: ```javascript scene.on('boxselect', (ev) => { console.log(ev.bounds); // 框选的经纬度范围 [[minLng, minLat], [maxLng, maxLat]] }); scene.on('boxselectstart', (ev) => {}); // 框选开始 scene.on('boxselecting', (ev) => {}); // 框选中 scene.on('boxselectend', (ev) => {}); // 框选结束 ``` ## 实验参数 实验参数可能会废弃。 ### offsetCoordinate: boolean 高德地图适用,是否关闭偏移坐标系, 默认为 `true`。 ```js const scene = new Scene({ offsetCoordinate: true, }); ``` #### Source - Canonical page: https://l7.antv.antgroup.com/zh/api/source/source/ - Markdown source: https://l7.antv.antgroup.com/zh/api/source/source.md - Description: Source --- title: "Source" description: "Source" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/source/source/" --- ## 简介 source 地理数据处理模块,主要包含数据解析(parser)和数据处理(transforms)。 ```js const source = new Source(data, option); ``` - data - option - cluster **boolean** 是否聚合 - clusterOptions 聚合配置项 - parser 数据解析配置 - transforms 数据处理配置 ## 兼容性 本次渐进式重构(阶段 0–6)保证**对外 API 完全向后兼容**,旧写法无需改动即可继续工作: - `new Source(data, cfg)` 与 `new Source(data)` 写法保持不变(`cfg` 与 `registry` 均可选)。 - `cluster: true` 配置静默走新 `ClusterManager` 直调路径,**无任何 warning**。 - `ISourceCFG` 旧字段(`cluster` / `clusterOptions` / `parser` / `transforms` / `autoRender`)全部保留。 - 事件 `'update' { type: 'inited' | 'update' }` 行为不变;新增 `'error'` 事件仅用于显式 surfacing 失败(无监听即静默)。 新增的 `Source.create` / `createSource` / `source.ready` / `source.stats()` / `source.dataVersion` 为可选的更优路径,旧代码可按需逐步迁移,非强制。 > `transforms` 配置项中 `{ type: 'cluster' }` 已弃用(运行时会 warn 一次,但仍可工作)。聚合请改用顶层 `cluster: true` 配置项,详见下方 [cluster](#cluster)。 ## data 不同 parser 类型对应不同 data 类型 - 瓦片图层 data 为 url 模板,支持 TMS、WMS、WMTS 数据服务 - 非瓦片图层 data 为数据对象 ## option `source` 通过 `option` 来描述或处理数据, 其中主要包括 `parser` 和 `transforms`。 ### parser parser 可以将不同类型的空间数据处理成统一数据格式。空间数据分为矢量数据、栅格数据和瓦片服务三大类: - 矢量数据 支持 [GeoJSON](/zh/api/source/geojson)、[CSV](/zh/api/source/csv)、[JSON](/zh/api/source/json) 类型 - 栅格数据 支持 [Raster](/zh/api/source/raster)、[Image](/zh/api/source/image) 类型 - 瓦片服务 支持 [MVT](/zh/api/source/mvt)、[RasterTile](/zh/api/source/raster_tile)、GeoJSON VT 类型 ```js type IParserType = | 'csv' | 'json' | 'geojson' | 'image' | 'raster' | 'rasterTile' | 'mvt' | 'geojsonvt'; interface IParser { type: IParserType; x?: string; y?: string; x1?: string; y1?: string; coordinates?: string; geometry?: string; [key: string]: any; } ``` #### geojson [geojson](https://www.yuque.com/antv/l7/dm2zll) 为默认数据格式,可以不设置 parser 参数 ```javascript layer.source(data); ``` ### transforms transforms 处理的是标准化后的数据,可进行数据转换、数据统计、网格布局、数据聚合等数据操作,处理完后返回的也是标准数据。标准化后的数据结构包括 coordinates 地理坐标字段,以及其他属性字段。 ```json [ { "coordinates": [[]], // 地理坐标字段 "_id": "122", // 标准化之后新增字段 "name": "test", "value": 1 // .... } ] ``` 目前 grid、hexagon 两种热力图支持使用数据处理方法 transforms 配置项 - type 数据处理类型 - transforms cfg  数据处理配置项 #### grid 生成方格网布局,根据数据字段统计,主要在网格热力图中使用 - type: 'grid' - size: 网格半径 - field: 数据统计字段 - method: 聚合方法,有 count、max、min、sum、mean 5 个统计维度 ```javascript layer.source(data, { transforms: [ { type: 'grid', size: 15000, field: 'v', method: 'sum', }, ], }); ``` #### hexagon 生成六边形网格布局,根据数据字段统计 - type: 'hexagon' - size: 网格半径 - field: 数据统计字段 - method: 聚合方法,有 count、max、min、sum、mean 5 个统计维度 #### join 数据连接,业务中跟多情况是地理数据和业务数据分开的两套数据,我们可与通过 join 方法将地理数据和业务数据进行关联。 **配置项** - type: join - sourceField: 需要连接的业务数据字段名称 - data: 需要连接的数据源,仅支持 json 格式 - targetField: 关联的地理数据字段名称 ```javascript // geoData 是地理数据 const geoData = { type: 'FeatureCollection', features: [ { type: 'Feature', properties: { city: '北京', }, geometry: {}, }, ], }; // customData 属性数据或者业务数据 const customData = [ { name: '北京', value: 13, }, { name: '天津', value: 20, }, ]; // 通过 join 方法我们就可以将两个数据连接到一起 layer .source(geoData, { transforms: [ { type: 'join', sourceField: 'name', //customData 对应字段名 targetField: 'city', // geoData 对应字段名,绑定到的地理数据 data: customData, }, ], }) .color('value'); // 可以采用 customData 的 value 字段进行数据到颜色的映射 ``` #### map 对数据进行映射转换,可对每一个数据元素进行处理并返回新的数据元素。 **配置项** - type: 'map' - callback: `(feature: any) => any` 对每条数据进行处理的回调函数 ```javascript layer.source(data, { transforms: [ { type: 'map', callback: (feature) => { feature.value = feature.value * 2; return feature; }, }, ], }); ``` #### filter 对数据进行过滤,仅保留满足条件的数据元素。 **配置项** - type: 'filter' - callback: `(feature: any) => boolean` 过滤条件回调函数,返回 `true` 时保留该条数据 ```javascript layer.source(data, { transforms: [ { type: 'filter', callback: (feature) => { return feature.value > 10; // 仅保留 value 大于 10 的数据 }, }, ], }); ``` ### cluster - cluster: `boolean` `cluster` 表示是否对数据进行聚合操作, 目前只有点图层支持。 > 推荐使用 `cluster: true` 顶层配置项开启聚合。 > `transforms: [{ type: 'cluster' }]` 已弃用(会破坏 `source.data` 语义并 warn),仅为向后兼容保留。 ### clusterOption 可选 - radius: 聚合半径 **number** default 40 - minZoom: 最小聚合缩放等级 **number** default 0 - maxZoom: 最大聚合缩放等级 **number** default 16 [聚合图使用案例](/zh/examples/point/cluster/cluster/) ## 方法 ### setData(data, options?) 更新数据 更新 source 数据,会触发图层重新渲染。 - `data` 数据,同 source 初始化参数 - `options` 配置项,同 source 初始化参数 ```javascript const source = new Source(data, { parser: { type: 'json', x: 'lng', y: 'lat' } }); // 更新数据 source.setData(newData); ``` ### getFeatureById(id: number) 根据 ID 获取要素 根据 featureID 获取 feature 要素。 - `id` featureId,L7 内部编码的唯一要素 ID ```tsx const source = layer.getSource(); const feature = source.getFeatureById(1); ``` ### getFeatureId(field: string, value: any) 根据属性获取要素 ID 根据属性的 key、value 获取要素 L7 编码 featureId,确保该属性的 value 是唯一值,如存在多个返回第一个。 - `field` 属性字段 - `value` 对应的值 ```tsx const source = layer.getSource(); const featureId = source.getFeatureId('name', '张三'); ``` ### updateFeaturePropertiesById(id, properties) 更新要素属性 根据 ID 更新 source 的属性数据,会触发重新渲染。 - `id` featureId,L7 内部编码的唯一要素 ID - `properties` 需要更新属性数据,进行 merge 操作 ```tsx const source = layer.getSource(); layer.on('click', (e) => { source.updateFeaturePropertiesById(e.featureId, { name: Math.random() * 10, }); }); ``` ### getClusters(zoom: number) 获取聚合数据 聚合图使用,获取指定缩放等级下的聚合数据。 - `zoom` 缩放等级 ```javascript const clusters = source.getClusters(scene.getZoom()); ``` ### getClustersLeaves(cluster_id) 获取聚合节点原始数据 聚合图使用,获取聚合节点的原始数据。 - `id` 聚合节点的 cluster_id ```javascript layer.on('click', (e) => { console.log(source.getClustersLeaves(e.feature.cluster_id)); }); ``` ### updateClusterData(zoom: number) 更新聚合数据 更新聚合数据,在地图缩放后需要调用以刷新聚合结果。 - `zoom` 当前缩放等级 ```javascript scene.on('zoomchange', () => { source.updateClusterData(scene.getZoom()); }); ``` ### getSourceCfg() 获取 source 配置 获取 source 的初始化配置项。 ```javascript const cfg = source.getSourceCfg(); ``` ### getParserType() 获取解析器类型 获取当前 source 使用的数据解析器类型。 ```javascript const parserType = source.getParserType(); // 如 'geojson', 'json', 'csv', 'mvt' 等 ``` ### destroy() 销毁 source 销毁 source,释放相关资源。 ```javascript source.destroy(); ``` ### create(data, cfg?) 异步工厂方法 `Source.create` 是异步工厂方法,内部 `await` source 初始化(parse + cluster 初始化 + transforms)完成后返回。相比 `new Source(data, cfg)` 的 fire-and-forget 初始化,`create` 返回的实例 `data` 已就绪,可直接读取,消除 `source.data` 可能为 `undefined` 的竞态。 - `data` 数据,同 source 初始化参数 - `cfg` 配置项,同 source 初始化参数 - 返回 `Promise` ```javascript const source = await Source.create(data, { parser: { type: 'json', x: 'lng', y: 'lat' } }); // 此时 source.data 已解析完成,无 undefined 竞态 ``` ### createSource(data, cfg?, registry?) 同步工厂 `createSource` 与 `new Source` 行为等价的同步工厂函数,返回 source 实例(初始化仍为 fire-and-forget)。第三个可选参数 `registry` 可注入自定义 `ParserRegistry` 实例,按需子集注册 parser / transform 或做测试隔离。 - `data` 数据,同 source 初始化参数 - `cfg` 配置项,同 source 初始化参数 - `registry`(可选)自定义 parser / transform 注册表,默认使用内置 `defaultRegistry` ```javascript import { createSource } from '@antv/l7-source'; const source = createSource(data, { parser: { type: 'geojson' } }); ``` ### ready 只读属性 `source.ready` 是一个 `Promise`,resolve 时 source 初始化完成(`inited === true` 且数据已解析)。可在消费侧 `await source.ready` 消除 `source.data` 竞态。 ```javascript const source = new Source(data); await source.ready; // source.data 已就绪 ``` ### stats() 获取数据快照 返回 source 当前数据的只读快照,便于调试与大小监控。不影响 source 内部状态。 返回 `ISourceStats` 对象: - `rows: number` 已解析数据行数(`data.dataArray.length`) - `bbox: BBox` 数据范围 `[minLng, minLat, maxLng, maxLat]` - `parserType: string` 当前解析器类型(如 `'geojson'`、`'mvt'`) - `tileCount: number` 已加载瓦片数(非瓦片源或未触发视口更新时为 `0`) - `isTile: boolean` 是否为瓦片数据源 - `cluster: boolean` 是否开启聚合 - `dataVersion: number` 数据 generation(见下) ```javascript const stats = source.stats(); console.log(stats.rows, stats.parserType, stats.tileCount); ``` ### dataVersion 数据版本号 `dataVersion` 是单调递增的数据 generation 计数器,每次「数据可能变化」的操作 `+1`: - `setData`(全量数据替换)后 `+1` - `updateFeaturePropertiesById`(原地属性变更)后 `+1` - `updateClusterData`(zoom 驱动的聚合视图重算,原始数据未变)**不** bump - 构造期首次解析为 generation `0` 可用于判断数据是否已变化、避免重复处理。 ```javascript const v1 = source.dataVersion; source.setData(newData); const v2 = source.dataVersion; // v2 === v1 + 1 ``` ## Source 更新 如果数据发生改变,可以需要更新数据。 可以通过调用 `layer` 的 `setData` 方法实现数据的更新。 具体见 [Layer](/zh/api/base_layer/base/#setdata) ```javascript layer.setData(data); ``` ## 瓦片 source 属性 ### tileset 瓦片数据集,可以获取当前视野内的瓦片信息, 瓦片状态 ```ts const source = layer1.getSource(); const tileSet = source.tileset; ``` #### 属性 ##### isLoaded 瓦片是否加载完成 ##### currentTiles 当前瓦片对象 ##### currentZoom 当前瓦片层级;这里的曾经和map 的缩放层级不相等 #### 事件 ##### tiles-load-start 地图拖动,需要加载新的瓦片时触发 ```ts tileSet.on('tiles-load-start', () => { console.log('tile start'); }); ``` ##### tiles-load-finished 所有需要加载的瓦片资源加载完成后触发 ```ts tileSet.on('tiles-load-finished', () => { console.log('tile finished'); }); ``` ## 瓦片 source 方法 ### reloadAllTile 重新加载瓦片,会重新请求数据,适用与动态瓦片场景,如瓦片数据发生了更新,或者瓦片Join 的数据发生了更新 ```ts pure source.reloadAllTile(); ``` ### reloadTilebyId 重新加载特定瓦片的 参数 - z 缩放等级 - x 瓦片 x 坐标 - y 瓦片 y 坐标 ```ts pure source.reloadTileById(z, x, y); ``` ### reloadTileByExtent 根据经纬度范围更新瓦片 参数 - extent: 经纬范围 [minLng, minLat, maxLng, maxLat] - zoom: 缩放等级 ### reloadTileByLnglat 根据经纬度更新瓦片,经纬度坐标转换成瓦片坐标更新 - lng 经度 - lat 纬度 - zoom 缩放等级 ```tsx pure source.reloadTileByLnglat(112, 30, 10); ``` ### 数据类型 #### JSON [JSON 数据格式解析](/zh/api/source/json) #### csv [CSV 数据格式解析](/zh/api/source/csv) 栅格数据类型 #### image [Image 数据格式解析](/zh/api/source/image) ## 事件 Source 继承自 EventEmitter,支持 `on`/`off`/`once`/`emit` 等事件方法。 ### update 数据更新事件,在以下情况触发: - source 初始化完成后(`type: 'inited'`) - 调用 `setData` 或 `updateFeaturePropertiesById` 后(`type: 'update'`) ```javascript const source = layer.getSource(); source.on('update', (e) => { if (e.type === 'inited') { console.log('source 初始化完成'); } else if (e.type === 'update') { console.log('source 数据已更新'); } }); ``` ### error 数据初始化或更新失败事件。当 `setData` 触发的 re-parse / cluster 初始化 / transform 执行失败时触发,payload 为错误对象。使用 `setData` 时建议监听 `error` 事件以感知失败(旧版本失败会静默 hang,现为显式 surfacing)。 ```javascript const source = layer.getSource(); source.on('error', (err) => { console.error('source 数据更新失败', err); }); source.setData(newData); ``` > 注:`new Source(data, cfg)` 构造期 init 失败仍为 fire-and-forget(未捕获 rejection,保留旧行为)。若需感知构造期失败,使用 `await Source.create(...)` 或 `await source.ready`(失败时 reject)。 #### GeoJsonVT 瓦片 - Canonical page: https://l7.antv.antgroup.com/zh/api/tile/geojsonvt_tile_layer/ - Markdown source: https://l7.antv.antgroup.com/zh/api/tile/geojsonvt_tile_layer.md - Description: GeoJsonVT 瓦片 --- title: "GeoJsonVT 瓦片" description: "GeoJsonVT 瓦片" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/tile/geojsonvt_tile_layer/" --- `L7` 矢量瓦片除了可以时候后端提供的瓦片服务之外,同时提供了 `geojson-vt` 瓦片切分方案,使得前端在没有后端支持的情况下也能使用矢量瓦片。 ### 矢量瓦片 - GeoJsonVT ```javascript import { PolygonLayer } from '@antv/l7'; fetch('https://gw.alipayobjects.com/os/bmw-prod/2b7aae6e-5f40-437f-8047-100e9a0d2808.json') .then((d) => d.json()) .then((data) => { const source = new Source(data, { parser: { type: 'geojsonvt', maxZoom: 9 }, }); const polygon = new PolygonLayer({ featureId: 'COLOR' }).source(source).color('red'); }); ``` ### sourceLayer 在使用前端瓦片切分的时候我们不再需要为瓦片图层指定数据源。 ### source(GeoJsonData: string, option: IOption) 在使用前端瓦片切分的矢量瓦片时,`source` 方法接收的不在时数据服务的地址,而是标准的 `GeoJSON` 数据。 #### option 在使用前端瓦片切分的时候我们需要将 `source parser` 的类型设置为 `geojsonvt`。 ```js const source = new Source(data, { parser: { type: 'geojsonvt', maxZoom: 9, geojsonvtOptions: {}, }, }); ``` `geojsonOptions` 支持如下参数: | 参数 | 类型 | 默认值 | 描述 | | | -------------- | ----------- | -------- | -------------------------------------------------------------- | ------------------------------------------------------- | | maxZoom | `number` | `14` | max zoom to preserve detail on | | indexMaxZoom | `number` | `5` | max zoom in the tile index | | indexMaxPoints | `number` | `100000` | max number of points per tile in the tile index | | tolerance | `number` | `3` | simplification tolerance (higher means simpler) | | extent | `number` | `4096` | tile extent | | buffer | `number` | `64` | tile buffer on each side | | lineMetrics | `boolean` | `false` | whether to calculate line metrics | | promoteId | `string` | `null` | `null` | name of a feature property to be promoted to feature.id | | generateId | `boolean` | `true` | whether to generate feature ids. Cannot be used with promoteId | | debug | `0, 1 or 2` | `0` | logging level (0, 1 or 2) | #### Raster 栅格瓦片 - Canonical page: https://l7.antv.antgroup.com/zh/api/tile/raster_tile_layer/ - Markdown source: https://l7.antv.antgroup.com/zh/api/tile/raster_tile_layer.md - Description: Raster 栅格瓦片 --- title: "Raster 栅格瓦片" description: "Raster 栅格瓦片" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/tile/raster_tile_layer/" --- `L7` 的栅格图层支持加载 `TMS`、`WMS`、`WMTS` 等多种格式的图片瓦片,同时也支持 `Tiff`、`Lerc` 等多种格式的数据栅格瓦片。 | 分类 | Layer | parserType | dataType | 描述 | | -------- | ------------- | ------------ | ------------- | ---------------- | | 栅格瓦片 | `RasterLayer` | `rasterTile` | `image`、`/` | 图片栅格 | | 栅格瓦片 | `RasterLayer` | `rasterTile` | `arraybuffer` | 数据栅格 | | 栅格瓦片 | `RasterLayer` | `rasterTile` | `rgb` | 彩色遥感影像栅格 | 🌟 目前只支持 3857 坐标系 ### source(url: string, option: IOption) 矢量瓦片的数据源需要传入矢量数据的瓦片服务以及对应的配置参数。 #### url 数据服务的路径处理支持单服务和多服务的写法,还支持同时请求多文件。 - 单服务器 向一台服务器请求瓦片数据。 - 多服务器 向多台服务器请求同一份服务的瓦片数据。 - 使用大括号的写法请求设置多服务器,如 `{1-3}`、`{a-c}`。 - 请求多文件 同时请求多份瓦片服务的瓦片数据。 - 使用数组的方式设置多服务。 - 目前请求多文件的格式只有栅格瓦片支持。 ```js import { Source } from '@antv/l7' // 单服务器 const source = new Source('http://webst01.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}', {...}) // 多服务器 const source = new Source('http://webst0{1-4}.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}', {...}) // 请求多文件 const urls = [ 'https://ganos.oss-cn-hangzhou.aliyuncs.com/m2/l7/tiff_jx/{z}/{x}/{y}.tiff', 'https://ganos.oss-cn-hangzhou.aliyuncs.com/m2/l7/tiff_jx/{z}/{x}/{y}.tiff', ] const urls = [ { url: 'https://ganos.oss-cn-hangzhou.aliyuncs.com/m2/l7/tiff_jx/{z}/{x}/{y}.tiff', bands: [0] }, { url: 'https://ganos.oss-cn-hangzhou.aliyuncs.com/m2/l7/tiff_jx/{z}/{x}/{y}.tiff' }, ... ] const tileSource = new Source(urls, {...}); ``` #### source option 通过配置 `parser` 中的参数,我们可以指定不同的瓦片类型以及瓦片服务的参数。 ```js const source = new Source(url, { parser: {...} }) ``` | 参数 | 类型 | 默认值 | 描述 | | -------------- | ---------------------------------- | ------------------------------------------ | -------------------- | | type | `string` | / | 描述不同类型的瓦片 | | tileSize | `number` | `256` | 请求的瓦片尺寸 | | minZoom | `number` | `0` | 请求瓦片的最小层级 | | maxZoom | `number` | `Infinity` | 请求瓦片的最大层级 | | zoomOffset | `number` | `0` | 请求瓦片层级的偏移量 | | extent | `[number, number, number, number]` | `[-Infinity,-Infinity,Infinity,Infinity,]` | 请求瓦片的边界 | | updateStrategy | `UpdateTileStrategy` | `replace` | 瓦片的替换策略 | ```js type UpdateTileStrategy = 'realtime' | 'overlap' | 'replace'; ``` 关于不同的栅格瓦片使用不同的 `parser` 参数。 | 瓦片类型 | type | dataType | 描述 | | ----------- | ------------ | ------------- | ---------------- | | TMS | `rasterTile` | `image` | 图片栅格 | | WMS | `rasterTile` | `image` | 图片栅格 | | WMTS | `rasterTile` | `image` | 图片栅格 | | arraybuffer | `rasterTile` | `arraybuffer` | 数据栅格,单通道 | | rgb | `rasterRgb` | `arraybuffer` | 数据栅格,多通道 | 🌟 `WMTS` 格式的瓦片有额外的参数。 | 参数 | 类型 | 值 | 描述 | | ------------- | -------------- | --- | ------------ | | `wmtsOptions` | `IWmtsOptions` | `/` | 设置请求参数 | `IWmtsOptions` 的参数用于拼接 `url`。 ```js interface IWmtsOptions { layer: string; version?: string; style?: string; format: string; service?: string; tileMatrixset: string; } ``` #### parser 参数 ##### type: string 用于指定瓦片服务的解析方式,值为 `rasterTile` 和 `mvt`。
`rasterTile` 用于栅格瓦片的解析,`mvt` 用于矢量瓦片的解析。 ##### dataType: string 使用 `dataType` 区分图片栅格和数据栅格,值为 `image` 和 `arraybuffer`,默认为 `image`。 ```javascript // 设置图片栅格 layer.source({ 'http://webst01.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}', { parser: { type: 'rasterTile', dataType: 'image', ... } } }) // 设置数据栅格 layer.source({ 'http://webst01.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}', { parser: { type: 'rasterTile', dataType: 'arraybuffer', ... } } }) ``` ##### minZoom/maxZoom: number 设置瓦片数据的请求层级。当地图的缩放层级 `zoom` 小于 `minZoom` 后,或 `zoom` 大于 `maxZoom` 后将不再请求新的瓦片。
`minZoom` 的默认值为 `-Infinity`。
`maxZoom` 的默认值为 `Infinity`。 ##### tileSize: number 设置的值是瓦片服务返回的瓦片大小。
`tileSize` 的默认值为 256。
ps: 该值在生产瓦片的时候确定,我们设置的 `tileSize` 需要和瓦片服务返回的保持一致。 ##### extent: [number, number, number, number] 设置请求瓦片数据的边界, 格式是 `[minLng, maxLat, maxLng, minLat]`,只会请求范围内的瓦片数据。 ##### zoomOffset: number 设置的值用于改变请求的瓦片数据的层级,通常在移动端可以请求更高一级的瓦片以获取更好的清晰度。 `zoomOffset` 的默认值为 0 ##### format: IRasterFormat _IFormat_ **必选** `format` 方法用于从传入的栅格文件二进制数据中提取波段数据。 - 第一个参数是栅格文件二进制数据。 - 第二个参数是第一个参数指定的栅格文件中应该提取的波段,方法参数是我们通过 `source` 参数传递的 `data` 数值。 - `format` 是一个 `async` 方法。 ```js interface IRasterData { rasterData: HTMLImageElement | Uint8Array | ImageBitmap | null | undefined; width: number; height: number; } type IRasterFormat = ( data: ArrayBuffer, bands: number[], ) => Promise; const source = new Source(data, { parser: { format: async (data, bands) => { ... return { rasterData: bandData, width: 256; height: 256; } } } }) ``` ## style - 单通道 绘制结果由是单一的数值控制,如灰度图,数值对应的颜色可以通过表示配置 `rampColors` 色带控制。 ```js layer.style({ opacity: 0.5, }); ``` ### options | style | 类型 | 描述 | 默认值 | | ----------- | ------------------ | ------------------------------------------- | ------------- | | opacity | `number` | 图形的透明度 | `1` | | clampLow | `boolean` | 设置为 `true`,低于 `domain` 的数据将不显示 | `false` | | clampHigh | `boolean` | 设置为 `true`,高于 `domain` 的数据将不显示 | `false` | | domain | `[number, number]` | 数据映射区间 | `[ 0, 8000 ]` | | noDataValue | `number` | 不会显示的值 | `-9999999` | | rampColors | `IRampColors` | 值域映射颜色的色带 | `/` | ### rampColors 颜色色带 - type 类型 支持 `linear','quantize','custom','cat' - colors  颜色数组 - positions 数据分段区间,可选,quantize 不需要设置 position,position 为原始数据值 ⚠️ 2.13 新增特性 #### cat 枚举类型色带 枚举类型色带只支持 0 -255 的整数类型,positions 用来设置枚举 ```tsx { type:'cat', colors:['#e41a1c','#377eb8','#4daf4a','#984ea3','#ff7f00'], positions:[1,20,101,102,200], } ``` #### quantize 等间距分类色带 等间距只根据数据的区间 domain 进行均匀分段,如 domain [0,10000],如果分 5 段,每段间距 2000。 等间距不需要设置 positions,只需要设置colors,根据colors 的长度设置分段数 ```tsx rampColors: { type:'quantize', colors: ['#f0f9e8','#bae4bc','#7bccc4','#43a2ca','#0868ac'] } ``` #### linear 线性连续色带 linear 为现有连续类型的加强版,positions 支持设置源数据,不需要转换成 0-1 ```tsx rampColors: { type:'linear', colors: ['#f0f9e8','#bae4bc','#7bccc4','#43a2ca','#0868ac'], positions [0,200,1000,4000,8000] } ⚠️ 兼容 2.13.0 之前版本,未设置type 时,position 值域为 0-1。 ``` #### custom 自定义分段色带 自定义分段色带区别等间距色带,用户自定义分段间隔。 自定义 positions 的长度需要比 colors 的长度多1个,同时poisitions ```tsx rampColors: { type:'custom', colors: ['#f0f9e8','#bae4bc','#7bccc4','#43a2ca','#0868ac'], positions: [0,200,1000,4000,8000,10000] } ``` #### Vector 矢量瓦片 - Canonical page: https://l7.antv.antgroup.com/zh/api/tile/vector_tile_layer/ - Markdown source: https://l7.antv.antgroup.com/zh/api/tile/vector_tile_layer.md - Description: Vector 矢量瓦片 --- title: "Vector 矢量瓦片" description: "Vector 矢量瓦片" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/tile/vector_tile_layer/" --- ### 简介 `L7` 的矢量瓦片图层复用了普通图层的数据可视化能力,支持对图层的样式进行数据映射。目前矢量瓦片支持了点、线、面、掩模等图层 | 分类 | Layer | parserType | 描述 | | -------- | ---------------- | ----------------------------------- | ----------------------------------------- | | 矢量瓦片 | `PointLayer` | parser of PointLayer、`geojsonvt` | 矢量点图层 | | 矢量瓦片 | `LineLayer` | parser of LineLayer、`geojsonvt` | 矢量线图层 | | 矢量瓦片 | `PolygonLayer` | parser of PolygonLayer、`geojsonvt` | 矢量几何体图层 | | 矢量瓦片 | `MaskLayer` | parser of MaskLayer、`geojsonvt` | 矢量掩模图层 | | 矢量瓦片 | `TileDebugLayer` | `/` | `TileDebugLayer` 不需要执行 `source` 方法 | 瓦片图层其他配置项和基础图层 PointLayer、Linelayer、PolygonLayer 保持一致 ### options #### sourceLayer _string_ **required** 只有矢量图层生效,用于设置矢量图层的数据源。 🌟 一般矢量服务返回的数据中存在多个图层的数据,我们需要从中进行选取。 ```javascript const layer = new PointLayer({ sourceLayer: 'city', }); ``` #### featureId _string_ **optional** _default:_ 自动数字编号 只有矢量图层生效,用于指定矢量图层的编码 `id`。 🌟 编码 `id` 用于在图层高亮时使用。 ```javascript const layer = new PointLayer({ featureId: 'id', }); ``` ### source(url: string, option: IOption) 矢量瓦片的数据源需要传入矢量数据的瓦片服务以及对应的配置参数。 #### url 数据服务的路径支持单服务和多服务的写法。 - 单服务器 向一台服务器请求瓦片数据。 - 多服务器 向多台服务器请求同一份服务的瓦片数据。 - 使用大括号的写法请求设置多服务器,如 `{1-3}`、`{a-c}`。 ```js // 单服务器 const source = new Source('http://webst01.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}', {...}) // 多服务器 const source = new Source('http://webst0{1-4}.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}', {...}) ``` #### source option 关于配置参数我们需要关系的是里面 `parser` 字段对应的参数。 ```js const source = new Source(url, { parser: {...} }) ``` | 参数 | 类型 | 默认值 | 描述 | | -------------- | ---------------------------------- | ------------------------------------------ | -------------------- | | type | `string` | / | 固定值为 `mvt` | | tileSize | `number` | `256` | 请求的瓦片尺寸 | | minZoom | `number` | `0` | 请求瓦片的最小层级 | | maxZoom | `number` | `Infinity` | 请求瓦片的最大层级 | | zoomOffset | `number` | `0` | 请求瓦片层级的偏移量 | | extent | `[number, number, number, number]` | `[-Infinity,-Infinity,Infinity,Infinity,]` | 请求瓦片的边界 | | updateStrategy | `UpdateTileStrategy` | `replace` | 瓦片的替换策略 | ```js type UpdateTileStrategy = 'realtime' | 'overlap' | 'replace'; ``` 🌟 矢量瓦片推荐复用 Source ```js const vectorSource = new Source( 'https://ganos.oss-cn-hangzhou.aliyuncs.com/m2/rs_l7/{z}/{x}/{y}.pbf', { parser: { type: 'mvt', maxZoom: 9, extent: [-180, -85.051129, 179, 85.051129], }, }, ); // 复用 layer1.source(vectorSource); layer2.source(vectorSource); ``` #### 图层基类 BaseLayer - Canonical page: https://l7.antv.antgroup.com/zh/api/base_layer/base/ - Markdown source: https://l7.antv.antgroup.com/zh/api/base_layer/base.md - Description: 图层基类 BaseLayer --- title: "图层基类 BaseLayer" description: "图层基类 BaseLayer" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/base_layer/base/" --- ## 简介 L7 Layer 接口设计遵循图形语法,所有图层都继承于基类(baseLayer)。 语法示例 ```javascript const layer = new BaseLayer(option) // option - 传入构造函数的参数对象,提供 layer 的初始状态 .source(...) // 传入图层需要的数据以及相关的解析器 .filter() // 数据过滤方法 .shape(...) // 为图层指定具体的形状,如:circle/triangle 等 .color(...) // 指定图层的颜色配置 .texture(...) // 指定图层引用的纹理 .size(...) // 设置图层元素的大小 .animate(...) // 设置图层元素的动画模式 .active(...) // 指定图层元素是否支持划过选中 .select(...) // 指定图层元素是否支持点击选中 .style(...); // 指定图层自定义样式的配置 scene.addLayer(layer); ``` ## options ### name _string_ **optional** _default:_ 自动数字编号 设置图层名称,可根据 name 获取 layer ```javascript scene.getLayerByName(name); ``` ### visible _bool_ **optional** _default:_ true 图层是否可见 ### zIndex _int_ **optional** _default:_ 0 图层绘制顺序,数值大绘制在上层,可以控制图层绘制的上下层级 L7 采用队列渲染的机制,所有的图层在内部保存在一个数组中,每一帧的渲染会将图层数组按照 zIndex 的值进行排序,然后遍历数组,将符合条件的图层渲染到场景中 ### minZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最小缩放等级 ### maxZoom _number_ **optional** _default:_ Mapbox (0-24) 高德 (2-19) 图层显示最大缩放等级 ### autoFit _bool_ **optional** _default:_ false layer 初始化完成之后,地图是否自动缩放到图层范围 ### pickingBuffer _bool_ **optional** _default:_ 0 图层拾取缓存机制,如 1px 宽度的线鼠标很难拾取(点击)到, 通过设置该参数可扩大拾取的范围(放大图层对象的尺寸) ### blend _string_ **optional** _default:_ 'normal' 图层元素混合效果 - normal 正常效果 默认 发生遮挡的时候,只会显示前面的图层的颜色 - additive 叠加模式 发生遮挡的时候,显示前后图层颜色的叠加 - subtractive 相减模式 发生遮挡的时候,显示前后图层颜色的相减 - max 最大值 发生遮挡的时候,显示图层颜色 rgb 的最大值 ### enablePropagation _boolean_ **optional** _default:_ 'false' 图层事件,默认只响应最上层图层,设置为true 将允许事件透传 ⚠️ mask、maskfence 不推荐使用,一下配置 2.14.x 之后版本生效 模板图层:用做模板的图层,PointLayer、LineLayer、PolygonLayer 都可以作为模板 掩模图层:被模板切割的图层 ### enableRelativeCoordinates 图层使用相对坐标系,缩放等级大于 20,室内场景 ### maskLayers 掩模图层生效 _array Layer_ **optional** _default:_ [] ### enableMask 掩模图层生效 是否开启掩模,默认开启 maskLayers 不为空时生效 _bool_ **optional** _default:_ true ### maskInside 掩模图层生效 _boolean_ **optional** _default:_ true 用来描述当前图层的内容与掩模边界显示。 - `true` 在掩模内部显示 - `false` 在掩模外部显示 ### maskOpetation 掩模方式 模板图层生效 _枚举_ **optional** _default:_ and maskLayers 为多个时失效,需要在模板图层设置 - or 交集 - and 并集 使用示例 ```ts const polygonLayer = new Polygon(); const rasterLayer = new Raster({ // 栅格图层使用polygon 掩模 maskLayers: [polygonLayer], enableMask: true, maskInside: true, }); ``` ## 数据方法 ### source 数据 设置图层数据以及解析配置 `source(data, config)`。 - data { geojson | json | csv } - config   可选   数据源配置项 - parser 数据解析,默认是解析层 geojson - transforms [transform,transform ]  数据处理转换可设置多个 `parser` 和  `transforms` [见 source 文档](/zh/api/source/source)。 ```javascript layer.source(data, { parser: { type: 'csv', x: 'lng', y: 'lat', }, transforms: [ { type: 'map', callback: function (item) { const [x, y] = item.coordinates; item.lat = item.lat * 1; item.lng = item.lng * 1; item.v = item.v * 1; item.coordinates = [x * 1, y * 1]; return item; }, }, { type: 'hexagon', size: 6000, field: 'v', method: 'sum', }, ], }); ``` ### cluster 我们在使用 `cluster` 配置聚合图之后就可以使用一些聚合方法来获取对应参数。 #### getClusters(zoom: number): IFeatureCollection 获取指定缩放等级的聚合数据 - `zoom` 缩放等级 #### getClustersLeaves(id: string): IFeatureCollection 根据 `id` 获取聚合节点的数据,每个聚合节点会有一个唯一 `ID`。 - `id` 聚合节点的 `id` ```ts const source = layer.getSource(); source.getClustersLeaves(id); layer.on('click', (e) => { console.log(source.getClustersLeaves(e.feature.cluster_id)); }); ``` ## scale 数据度量 Scale 度量是将地图数据值(数字、日期、类别等数据)转成视觉值(颜色、大小、形状)。尺度 Scale 是数据可视化的基本组成部分,因为它们决定了视觉编码的性质。 L7 目前支持连续、离散、枚举类型数据的Scale,并支持位置、形状、大小和颜色编码的映射。 在使用 L7 过程中,默认情况下不需要进行 Scale 的配置,因为 L7 会根据数据类型对 scale 推断,推断过程如下: 查看用户是否设置了 Scale,如果没有: 判断字段的第一条数据的字段类型,如果数据中不存在对应的字段: 认为是常量为固定值 如果是数字则为 'linear'; 如果是字符串类型 'cat'; ### scale [Scale 详细介绍](https://mp.weixin.qq.com/s/QyD1_ypu0PDwMxEz45v6Jg) 参数: (field: string, scaleOptions: IscaleOptions) - `field` 指定 source 中传入的数据中用于映射的字段名 - `scaleOptions` 列定义配置,对象类型 - type scale 类型 - unknown 未匹配颜色 可选 默认透明 - domain 值域 可选 ```javascript interface IscaleOptions { type: ScaleTypeName; domain?: any[]; ... } layer.color('id', ['#f00', '#ff0']) .size('mag', [1, 80]) .scale('mag', { type: 'linear', domain: [ 1, 50] }); ``` #### 类型 Range 和 domain 是 Scale 中非常重要的两个参数 domain: 地图数据值的定义区间 range:视觉值的区间 不同Scale 的差异在于 domain->range 的转换方法的不同 - domain: 地图数据值的定义区间 - range:视觉值的区间定义 | 数据类 | 度量类型 | | --------- | ------------------------------------- | | 连续 | linear、log、pow | | 连续分类 | quantize quantile,threshold,diverging | | 分类 枚举 | cat | #### Cat Cat 指枚举类型,用于展示分类数据,比如农作物种植区分布图,水稻、玉米、大豆等不同类别需要映射为不同的颜色。 ```js // 三种作物会分别转成对应的颜色 // domain = ['corn','rice', 'soybean']; // range = ['red','white','blue']; const data = [ { lng: 120, lat: 30, t: 'corn' }, { lng: 121, lat: 30, t: 'rice' }, { lng: 122, lat: 30, t: 'soybean' }, ]; layer.source(data, { parser: { type: 'type', x: 'lng', y: 'lat', }, }); layer.scale('t', { type: 'cat' }); layer.color('t', ['red', 'white', 'blue']); ``` #### identify 数据值和映射值相同 比如数据中value 字段记录了每个要素的颜色,数值既为要映射的结果值s ``` // 设置为 identify layer.scale('value', { type: 'identify' }); // 或者 layer.scale('value'); // L7 能够自动推断为 identify ``` #### linear 线性是连续数据的映射方法,数据和视觉值是通过线性方法换算的。如数据值 1-100 线性映射到红到蓝的线下渐变色每个数字对应一个颜色 #### quantize 相等间隔会将属性值的范围划分为若干个大小相等的子范围。相等间隔最适用于常见的数据范围,如百分比和温度。这种方法强调的是某个属性值相对于其他值的量 #### quantile 每个类都含有相等数量的要素。分位数分类非常适用于呈线性分布的数据。分位数为每个类分配数量相等的数据值。不存在空类,也不存在值过多或过少的类。 由于使用“分位数”分类将要素以同等数量分组到每个类中,因此得到的地图往往具有误导性。可能会将相似的要素置于相邻的类中,或将值差异较大的要素置于相同类中。可通过增加类的数量将这种失真降至最低。 #### threshold 他允许将域的任意子集(非统一段)映射到范围内的离散值。输入域仍然是连续的,并根据提供给域属性的一组阈值划分为多个切片。 range 属性必须有 N+1 个元素,其中 N 是域中提供的阈值边界数 手动设置间隔 Manual interval 手动设置分级分类区间,某些数据会有相应的业界标准,或者需要进行某种特殊的显示。如空气质量数据有严格数据分段标准 ``` -1 => "red" 0 => "white" 0.5 => "white" 1.0 => "blue" 1000 => "blue ``` #### diverging 离散分类通常与两种相反的色调一起使用,以显示从负值到中心到正值的变化。这些类型的地图显示了彼此相关的值的大小。 ### getScale(scaleName:string) 根据视觉通道名称获取 scale 实例,调用之前确保 layer 已经初始化完成 ```ts const scale = layer.getScale('color'); const color = scale(1); // 将数值转换成颜色 ``` 更多是方法 scale 示例使用 ## 视觉编码方法 可视化编码是将数据转换为可视形式的过程,L7 目前支持形状,大小,颜色 3 种视觉通道,你可以指定数据字段,为不同要素设置不同的图形属性。 案例 ### filter 数据过滤方法,支持回调函数,将数据映射为true | false, 结果为true 时可见 ```ts pointLayer.filter('type', (type) => { // 回调函数 if (type === 'a') { return false; } return true; }); ``` ### size 将数据值映射到图形的大小上的方法,size 方法具体的参数使用可以查看对应图层的详细文档 ```javascript pointLayer.size(10); // 常量 pointLayer.size('type'); // 使用字段映射到大小 pointLayer.size('type', [0, 10]); // 使用字段映射到大小,并指定最大值和最小值 pointLayer.size('type', (type) => { // 回调函数 if (type === 'a') { return 10; } return 5; }); ``` #### size(value) 传入数字常量,如  `pointLayer.size(20)` #### size(field) 根据 field 字段的值映射大小,使用默认的`最大值 max:10`  和`最小值 min: 1`。 #### size(field, callback) 使用回调函数控制图形大小。 - `callback`: function 回调函数。 ```javascript pointLayer.size('age', (value) => { if (value === 1) { return 5; } return 10; }); ``` ### color 将数据值映射到图形的颜色上的方法。 ```javascript layer.color('red'); // 常量颜色 layer.color('type'); // 对 type 字段进行映射,使用内置的颜色 layer.color('type', ['red', 'blue']); // 指定颜色 layer.color('type', (type) => { // 通过回调函数 if (type === 'a') { return 'red'; } return 'blue'; }); layer.color('type*value', (type, value) => { //多个参数,通过回调函数 if (type === 'a' && value > 100) { return 'red'; } return 'blue'; }); ``` #### color(value) 参数:`value` :string 只支持接收一个参数,value 可以是: - 映射至颜色属性的数据源字段名,如果数据源中不存在这个字段名的话,则按照常量进行解析,这个时候会使用 L7 默认提供的颜色。 - 也可以直接指定某一个具体的颜色值 color,如 '#fff', 'white','rgba(255,0,0,0.5)' ,rgb(255,0,1) 等。 如果数据为映射到颜色,默认为透明色不显示,如果需要设置该颜色,需要在scale 中设置 示例 ```javascript layer.color('name'); // 映射数据字段 layer.color('white'); // 指定颜色 ``` #### color(field, colors) 参数: - `field`: stringfield 为映射至颜色属性的数据源字段名,也支持指定多个参数。 - `colors`: string | array | function colors 的参数有以下情况:  如果为空,即未指定颜色的数组,那么使用内置的全局的颜色;如果需要指定颜色,则需要以数组格式传入,那么分类的颜色按照数组中的颜色确定。 ```javascript layer.scale('name',{ type:'quantile' unknown:'#ccc' // 设置无效颜色 }) layer.color('name'); // 使用identity layer.color('name', ['red', 'blue']); // 使用传入的指定颜色 ``` - colors 如果是回调函数,则该回调函数的参数为对应字段的数值,具体使用如下,当 color 映射为多个字段时,参数按照字段声明的顺序传入: ```javascript layer.color('gender', (value) => { if (value === 1) { return 'red'; } return 'blue'; }); layer.color('gender*age', (gender, age) => { if (age === 20 && gender == ' 男') { return 'red'; } return 'blue'; }); ``` ### shape 通常一种图层可以有多种表现形式,shape 方法用于指定图层具体的表现形式,以 PointLayer 的 shape 为例: ```javascript shape('circle'); // 圆形 shape('triangle'); // 三角形 shape('cylinder'); // 圆柱 ``` 案例 **shape(shape)** 参数 `shape` string - 只支持接收一个参数,指定几何图像对象绘制的形状。下表列出了不同的 图层 几何图形对象支持的 shape 形状 | layer 类型 | shape 类型 | 备注 | | ---------- | -------------------------------------------------------------------------------------- | ---- | | point | 2d:point,circle, square, triangle,hexagon,image,text 3d:circle,triangle,hexagon,square | | | line | line,arc, arc3d, greatcircle | | | polygon | fill,line, extrude | | **shape(field, shapes)** - shape 根据字段指定行形状,比如根据字段指定 PointLayer/imageLayer 的 icon 类型 ```javascript scene.addImage( '00', 'https://gw.alipayobjects.com/zos/basement_prod/604b5e7f-309e-40db-b95b-4fac746c5153.svg', ); scene.addImage( '01', 'https://gw.alipayobjects.com/zos/basement_prod/30580bc9-506f-4438-8c1a-744e082054ec.svg', ); scene.addImage( '02', 'https://gw.alipayobjects.com/zos/basement_prod/7aa1f460-9f9f-499f-afdf-13424aa26bbf.svg', ); const imageLayer = new PointLayer() .source(data, { parser: { type: 'json', x: 'longitude', y: 'latitude', }, }) .shape('name', ['00', '01', '02']) .size(20); scene.addLayer(imageLayer); ``` 案例 [在线案例](/zh/examples/point/image/image/) **shape(field, callback)** - shape 也支持回调函数的写法 ```javascript .shape('key', value => { if(value > 10) { return 'circle'; } else { return 'triangle'; } } ``` ### rotate 将数据值映射到图形的旋转角度上的方法,用于控制点图层图标/图形的旋转。 ```javascript layer.rotate(45); // 常量,所有元素旋转 45 度 layer.rotate('angle'); // 字段映射 layer.rotate('angle', [0, 360]); // 字段映射到角度范围 layer.rotate('angle', (angle) => { return angle * (Math.PI / 180); // 回调函数 }); ``` ### label 为图层设置标注(文字标签),将数据字段映射为标注内容显示在图层元素旁边。主要在特定图层类型(如 PointLayer 的文字标注)中生效。 ```javascript layer.label('name'); // 以 name 字段的值作为标注文本 layer.label('name', (name) => `${name}市`); // 回调函数处理标注文本 ``` ### style style 方法通常用于描述图层具体的样式,大多数图层会支持一些比较通用的属性, 如 opacity 属性,同时每个图层也会有仅限本图层支持的属性,如只有 CityBuildingLayer 支持的 windowColor 属性,每个图层具体要如何配置属性请查看每个图层的详细文档。 - opacity 设置透明度 大部分图层都支持 - stroke 线填充颜色 仅点图层支持 - strokeWidth 线的宽度 仅点图层支持 ```javascript layer.style({ opacity: 0.8, stroke: 'white', }); ``` - 样式数据映射🌟
在正常情况下,style 的参数会作用到一个图层上的所有图形,如一个 PointLayer 中有十个点,我们设置 opacity = 0.5, 这样十个点的透明度都是 0.5。
而在特殊情况下,我们可能需要为每个点分别设置一个透明度,这时候按照原来的方式直接设置 style 方法的 opacity 的值就无法满足需求了,为此我们需要提供特殊的赋值方式。
通常我们会根据传入图层的数据为图层的每个图形设置单独的值,因此我们称之为“样式数据映射”。
我们支持几种设置 style 中的参数从 source 数据中动态取值的写法。 ```javascript // 根据数据中的 v 字段的值设置点图层各个点的透明度 const data = [ { lng: 120, lat: 30, v: 0.5 }, ... ] const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat' } }) .shape('circle') .color('#f00') .size({ // 第一种写法 根据字段从 data 中直接取值 opacity: 'v'// opacity = 0.5 }); scene.addLayer(layer); ``` [在线案例](/zh/examples/point/text/style-map/) 从 `L7 2.5` 开始,各图层样式将逐步支持样式数据映射,目前支持样式数据映射的 `style` 参数如下: | layer 类型/shape | 支持的样式字段 | 备注 | | ---------------------- | ---------------------------------------------------- | --------------------------------- | | pointLayer/fill | opacity、strokeOpacity、strokeWidth、stroke、offsets | shape circle、triangle... | | pointLayer/image | opacity、offsets | offsets 经纬度偏移 | | pointLayer/normal | opacity、offsets | | | pointLayer/text | opacity、strokeWidth、stroke、textOffset | textOffset 相对文字画布位置的偏移 | | pointLayer/extrude | opacity | | | polygonLayer/fill | opacity | | | polygonLayer/extrude | opacity | | | lineLayer/line | opacity | | | lineLayer/arc | opacity、thetaOffset | thetaOffset 弧线的弯曲弧度 | | lineLayer/arc3d | opacity | | | lineLayer/great_circle | opacity | | 案例 [在线案例](/zh/examples/point/scatter/scatter-style-map/) ### texture 目前只在线图层上支持了纹理方法 - texture 方法支持传入由 scene.addImage 方法添加的全局 icon 贴图资源 ```javascript // 首先在全局加载图片资源 scene.addImage( 'plane', 'https://gw.alipayobjects.com/zos/bmw-prod/0ca1668e-38c2-4010-8568-b57cb33839b9.svg', ); const layer = new LineLayer({ blend: 'normal', }) .source(data, { parser: { type: 'json', x: 'lng1', y: 'lat1', x1: 'lng2', y1: 'lat2', }, }) .size(25) .shape('arc') .texture('plane') // 为图层绑定纹理 .color('#8C1EB2') .style({ lineTexture: true, // 开启线的贴图功能 iconStep: 30, // 设置贴图纹理的间距 textureBlend: 'replace', // 设置纹理混合方式,默认值为 normal,可选值有 normal/replace 两种 }); ``` 案例 [在线案例](/zh/examples/line/animate/plane-animate2/) ## 图层更新方法 如果已经添加了图层,需要修改图层显示样式可以再次调用图形映射方法,然后调用 `scene.render()`更新渲染即可 ### scale 更新 重新调用scale 方法 ```tsx layer.scale('value', { type: 'quantile', }); scene.render(); ``` ### 数据映射 重新调用 color/size/filter/shape等方法 ```javascript layer.color('blue'); layer.size(10); scene.render(); ``` ### layer.style ```javascript layer.style({ opacity: 1, }); scene.render(); ``` ### setData(data, option?: {}) 更新 Source 数据 参数: - data 数据 - option 默认和初始配置项一致,如果数据格式相同可不设置 调用 setData 方法会自动更新图层渲染 ```javascript layer.setData(data); ``` ### setBlend(type: string) 设置图层叠加方法 参数: - type blend 类型 normal | additive | subtractive | max ## 图层控制方法 ### show() 图层显示 ```javascript layer.show(); ``` ### hide() 图层隐藏 ```javascript layer.hide(); ``` ### isVisible(): boolean 图层是否可见 ```javascript layer.isVisible(); ``` ### setIndex(zIndex: int) 设置图层绘制顺序 ```javascript layer.setIndex(1); ``` ### fitBounds() 缩放到图层范围 ```javascript layer.fitBounds(); ``` ### setMinZoom(zoom: number) 设置图层最小缩放等级 ```javascript layer.setMinZoom(zoom); ``` ### setMaxZoom(zoom: number) 设置图层最大缩放等级 参数 - zoom {number} ```javascript layer.setMaxZoom(zoom); ``` ### getMinZoom(): number 获取图层最小缩放等级 ```javascript const minZoom = layer.getMinZoom(); ``` ### getMaxZoom(): number 获取图层最大缩放等级 ```javascript const maxZoom = layer.getMaxZoom(); ``` ### destroy() 销毁图层,释放相关资源。场景调用 `removeLayer` 时会自动销毁图层,一般不需要手动调用。 ```javascript layer.destroy(); ``` ## 图层交互方法 ### active(activeOption | boolean) - 开启或者关闭 mousehover 元素高亮效果 - `activeOption` - `color`: 高亮颜色 - `mix`: 可选参数,默认为 0,表示高亮颜色是指定纯色,最大有效值是1,表示高亮色全部是底色 ```javascript activeOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.active(true); // 开启 Active 自定义高亮颜色 layer.active({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.active(false); ``` ### setActive(featureId: int) 根据元素 ID 设置指定元素 hover 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setActive(featureId); ``` ### select(selectOption | boolean) - 开启或者关闭 mouseclick 元素选中高亮效果 - selectOption - `color`: 选中高亮颜色 - `mix`: 可选参数,默认为 0,表示选中高亮颜色是指定纯色,最大有效值是1,表示选中高亮色全部是底色 ```javascript selectOption: { color: '#f00'; mix: 0.6; } ``` ```javascript // 开启 Active 使用默认高亮颜色 layer.select(true); // 开启 Active 自定义高亮颜色 layer.select({ color: 'red', mix: 0.6, }); // 关闭高亮效果 layer.select(false); ``` ### setSelect(featureId: int) 根据元素 ID 设置指定元素 click 选中 高亮 🌟 指定元素高亮不等于图层高亮,一个图层包含多个元素,一般传入 source 的数据数组中有多少单条数据,一个图层就有多少元素 ```javascript layer.setSelect(featureId); ``` ### setAutoFit(autoFit: boolean) 让用户可以主动设置图层的 autoFit 参数
🌟 设置完该方法后会在图层发生更新的时候生效,如在 setData 之后触发 ```javascript // 使用方法 layer.setAutoFit(true); // 内部实现 public setAutoFit(autoFit: boolean): ILayer { this.updateLayerConfig({ autoFit, }); return this; } ``` ### getScale(attr: string) 支持单独获取某个图形经过 scale 计算后的值, 满足用户获取图层某些 feature 值的需求。 - attr scale 的属性值 ```javascript const data = [ { lng: 120, lat: 30, name: 'n1' }, { lng: 120, lat: 30, name: 'n2' }, ]; const layer = new PointLayer() .source(data, { parser: { x: 'lng', y: 'lat', type: 'json', }, }) .shape('circle') .color('name', ['#f00', '#ff0']) .size('name', [20, 40]); scene.addLayer(layer); // 此时在 scene 上绘制两个点 // 一个颜色为黄色,大小为 40 的点,对应 name 为 n1 // 一个颜色为红色,大小为 20 的点,对应 name 为 n2 const colorScale = layer.getScale('color'); // 获取 color 方法产生的 scale const color1 = colorScale('n1'); // '#ff0' const color1 = colorScale('n2'); // '#f00' const sizeScale = layer.getScale('size'); // 获取 size 方法产生的 scale const size1 = sizeScale('n1'); // 40 const size2 = sizeScale('n2'); // 20 ``` ### getLegendItems(type: string) 不推荐使用,将废弃, 获取图例配置 - type 图例类型 - index 可选 默认 ```javascript layer.getLegendItems('color'); layer.getLegendItems('size'); ``` ### getLegend(type: string) getLegendItems方法的替代方法 该方法需要 返回值 - type 图例类型 - field 映射字段 - items 图例项 ```javascript layer.getLegend('color'); layer.getLegend('size'); ``` 注:rasterayer 只支持 color 类型 ## 图层掩模方法 ### addMask 添加 Mask 图层 ```ts const polygonLayer = new Polygon(); layer.addMask(polygonLayer); scene.render(); ``` ### removeMask ```ts const polygonLayer = new Polygon(); layer.removeMask(polygonLayer); scene.render(); ``` ### disableMask ```ts layer.disableMask(); scene.render(); ``` ### enableMask ```ts layer.enableMask(); scene.render(); ``` ## 鼠标事件 鼠标事件回调参数 target ```javascript layer.on(eventName, (target) => console.log(target)); ``` - x: number 鼠标  在地图位置 x 坐标 - y: number 鼠标  在地图位置 y 坐标 - type: string 鼠标事件类型 - lngLat: 经度度对象 {lng:number, lat: number }; 鼠标所在位置经纬度 - feature: any; 数据选中的地理要素信息 - featureId: number | null; 数据选中的地理要素的 ID ### click 点击事件 ```javascript layer.on('click', (e) => console.log(e)); ``` ### dblclick 双击 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mousemove 鼠标移动事件 ```javascript layer.on('mousemove', (e) => console.log(e)); ``` ### mouseout 鼠标移除 ```javascript layer.on('mouseout', (e) => console.log(e)); ``` ### mouseup 鼠标抬起 ```javascript layer.on('mouseup', (e) => console.log(e)); ``` ### mousedown 鼠标按下 ```javascript layer.on('mousedown', (e) => console.log(e)); ``` ### contextmenu 鼠标右键 ```javascript layer.on('contextmenu', (e) => console.log(e)); ``` ### dblclick 双击拾取元素 ```javascript layer.on('dblclick', (e) => console.log(e)); ``` ### mouseenter 鼠标进入图层要素时触发 ```javascript layer.on('mouseenter', (e) => console.log(e)); ``` ### unclick 点击未拾取到元素 ```javascript layer.on('unclick', (e) => console.log(e)); ``` ### unmousemove 鼠标移动未拾取到元素 ```javascript layer.on('unmousemove', (e) => console.log(e)); ``` ### unmouseup 鼠标抬起未拾取到元素 ```javascript layer.on('unmouseup', (e) => console.log(e)); ``` ### unmousedown 鼠标按下未拾取到元素 ```javascript layer.on('unmousedown', (e) => console.log(e)); ``` ### uncontextmenu 鼠标右键位拾取到元素 ```javascript layer.on('uncontextmenu', (e) => console.log(e)); ``` ### unpick 所有鼠标事件未拾取到 ```javascript layer.on('unpick', (e) => console.log(e)); ``` ### touchstart 移动端事件 touchstart ```javascript layer.on('touchstart', (e) => console.log(e)); ``` ### touchend 移动端事件 touchend ```javascript layer.on('touchend', (e) => console.log(e)); ``` 使用示例 ```javascript layer.on('click', (ev) => {}); // 鼠标左键点击图层事件 layer.on('mouseenter', (ev) => {}); // 鼠标进入图层要素 layer.on('mousemove', (ev) => {}); // 鼠标在图层上移动时触发 layer.on('mouseout', (ev) => {}); // 鼠标移出图层要素时触发 layer.on('mouseup', (ev) => {}); // 鼠标在图层上单击抬起时触发 layer.on('mousedown', (ev) => {}); // 鼠标在图层上单击按下时触发 layer.on('contextmenu', (ev) => {}); // 图层要素点击右键菜单 // 鼠标在图层外的事件 layer.on('unclick', (ev) => {}); // 图层外点击 layer.on('unmousemove', (ev) => {}); // 图层外移动 layer.on('unmouseup', (ev) => {}); // 图层外鼠标抬起 layer.on('unmousedown', (ev) => {}); // 图层外单击按下时触发 layer.on('uncontextmenu', (ev) => {}); // 图层外点击右键 layer.on('unpick', (ev) => {}); // 图层外的操作的所有事件 ``` ## 图层事件 ### inited 参数 option - target 当前 layer - type 事件类型 图层初始化完成后触发 ```javascript layer.on('inited', (option) => {}); ``` ### add 图层添加到 scene 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('add', (type) => console.log(type)); ``` ### remove 图层移除时触发 参数 option - target 当前 layer - type 事件类型 ```javascript layer.on('remove', (type) => console.log(type)); ``` ### legend 数据映射更新,图例发生变化,主要 color、size ### `legend:color` 数据映射更新,图例 color 颜色改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:color', (ev) => console.log(ev)); ``` ### `legend:size` 数据映射更新,图例 size 大小改变 参数 option: - type 图例类型 - field 映射字段 - items 图例项 ```js layer.on('legend:size', (ev) => console.log(ev)); ``` ## 图层框选 ### boxSelect 参数 option - box [x1: number, y1: number, x2: number, y2: number] 相较于 - cb (...args: any[]) => void 传入的回调方法,返回框选内部的 feature ```javascript layer.boxSelect(box, cb); // (x1, y1), (x2, y2) 框选的方框左上角和右下角相对于地图左上角的像素坐标 // cb 是传入的回调函数,回调函数返回的参数是选中的 feature 对象数组,对象的字段和用户传入的数据相关 ``` #### 控件 - Canonical page: https://l7.antv.antgroup.com/zh/api/component/control/ - Markdown source: https://l7.antv.antgroup.com/zh/api/component/control.md - Description: 控件 --- title: "控件" description: "控件" language: "zh" canonical: "https://l7.antv.antgroup.com/zh/api/component/control/" --- 地图控件指的是悬停在地图四周,可以对地图以及图层等元素进行**信息呈现**或**交互**的组件。 ![](https://gw.alipayobjects.com/mdn/rms_816329/afts/img/A*zgFeTocc-_oAAAAAAAAAAAAAARQnAQ) ## 使用 ```ts import { Scene, Zoom } from '@antv/l7'; const scene = new Scene({ // ... }); scene.on('loaded', () => { // 实例化 Zoom 控件,可以在构造器中传入控件的配置 const zoom = new Zoom({ position: 'leftbottom', className: 'my-test-class', }); // 将实例化的控件添加至 L7 中 scene.addControl(zoom); }); ``` ## 更新配置 在控件实例化之后,如果需要更新配置,可以调用控件实例的 `setOptions` 方法,同时传入需要更新的配置对象即可。 ```ts const zoom = new Zoom({ position: 'leftbottom', }); const onPositionChange = () => { // 通过 setOptions 传入需要更新的配置对象 zoom.setOptions({ position: 'topright', }); }; ``` ## 插槽 当前 L7 中的控件支持插入到地图的**左上、左下、右上、右下、上、左、下、右**八个位置插槽或者用户自定义的 `DOM` 中,并且在同一地图插槽中,多个控件之间支持**横向**和**纵向**排列。 在初始化所有的控件类时,可以传入 `position` 参数来设置控件对应的插槽以及排列方式。 ![](https://gw.alipayobjects.com/mdn/rms_816329/afts/img/A*BfG1TI231ysAAAAAAAAAAAAAARQnAQ) ## 配置 | 名称 | 说明 | 类型 | | --------- | ----------------------------------------------------------------------------------------- | --------------------- | | position | 控件被添加到地图中的位置以及排列方式,详情可见 [控件插槽](/zh/api/component/control#插槽) | [Position](#position) | | className | 自定义样式名 | `string` | | style | 自定义样式 | `string` | ### Position ```ts export type Position = | 'topleft' // ↖ 左上角,纵向排列 | 'lefttop' // ↖ 左上角,横向排列 | 'topright' // ↗ 右上角,纵向排列 | 'righttop' // ↗ 右上角,横向排列 | 'bottomleft' // ↙ 左下角,纵向排列 | 'leftbottom' // ↙ 左下角,横向排列 | 'bottomright' // ↘ 右下角,纵向排列 | 'rightbottom' // ↘ 右下角,横向排列 | 'topcenter' // ↑ 上方中央,横向排列 | 'bottomcenter' // ↓ 下方中间,横向排列 | 'leftcenter' // ← 左边中间,纵向排列 | 'rightcenter' // → 右边中间,纵向排列 | Element; // 传入 DOM 作为当前控件的容器 ``` ## 方法 | 名称 | 说明 | 类型 | | ------------ | --------------------------------------------- | -------------------------------------- | | setOptions | 更新配置,参数需要参考对应组件的[配置](#配置) | `(newOption: Partial