render2dpro 文档

简介

1. render2dpro 是 render3dpro 的二维版本，采用 OpenLayers 的 ol.layer.Vector + ol.style.Style 渲染方式，实现 GeoJSON 在二维地图中的渲染与可视化。
2. 与 render3dpro 保持完全一致的链式 API，同一套业务代码只需把 Cesium/viewer 换成 ol/map，即可从三维场景切换到二维地图。
3. 除了需要传入 OpenLayers 的 ol、map 对象外，无任何第三方依赖，以极致的轻量化为目标。
4. 封装与使用方式参考了阿里 AntV L7 的链式调用与传参方式。

与 render3dpro 的差异

| 对比项 | render3dpro（三维） | render2dpro（二维） | | --- | --- | --- | | 底层地图 | Cesium | OpenLayers | | 构造参数 | { Cesium, viewer } | { ol, map } | | 渲染对象 | Cesium.PrimitiveCollection | ol.layer.Vector | | 命中检测 | scene.pick | map.forEachFeatureAtPixel | | 弹窗 | 自绘 DIV + clock.onTick 定位 | ol.Overlay | | 定位 | camera.flyTo(Rectangle) | view.fit(extent) | | renderedPrimitiveCollection | PrimitiveCollection | ol.layer.Vector（属性名保持一致） |

二维下退化的形态：fill3D / polygon3D 退化为面，circle3D 退化为圆形面，box3D 退化为方形面。

二维下的空实现方法（保留方法签名以保证链式调用不中断，调用时仅在控制台提示一次）： bottomHeight、extrudedHeight、updateExtrudedHeight、updateX、updateY、updateZ、updateXYZRotationScale。

安装与引入

ol 需要传入 OpenLayers 完整包（ol.js）暴露的全局 ol 对象：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/ol.css" />
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/ol.js"></script>

也可以在构建工具中自行组装 ol 命名空间对象后传入，需要包含以下成员：

import Feature from "ol/Feature.js";
import Overlay from "ol/Overlay.js";
import VectorLayer from "ol/layer/Vector.js";
import VectorSource from "ol/source/Vector.js";
import { Style, Fill, Stroke, Circle } from "ol/style.js";
import GeoJSON from "ol/format/GeoJSON.js";
import * as proj from "ol/proj.js";
import * as extent from "ol/extent.js";

const ol = {
  Feature,
  Overlay,
  layer: { Vector: VectorLayer },
  source: { Vector: VectorSource },
  style: { Style, Fill, Stroke, Circle },
  format: { GeoJSON },
  proj,
  extent,
};

缺少成员时会在控制台明确列出缺失项，并跳过渲染而不抛异常。

语法示例

const layer = new PrimitiveGeoJsonLayer(option) // option - 传入 ol、map 等初始参数
.source(...)    // 传入图层需要的数据以及相关的解析器
.filter(...)    // 数据过滤方法
.shape(...)     // 为图层指定具体的形状、填充方式，如：fill、line、circle、box 等
.color(...)     // 指定图层的颜色配置
.texture(...)   // 指定图层引用的纹理（暂不支持）
.size(...)      // 设置图层元素的大小
.animate(...)   // 设置图层元素的动画模式（暂不支持）
.active(...)    // 指定图层元素是否支持划过选中
.select(...)    // 指定图层元素是否支持点击选中
.doubleClick(...) // 双击事件
.style(...)     // 指定图层自定义样式的配置
.render()       // 指定图层执行渲染并添加到地图中
.ready()        // 异步方法 调用此方法可以确定数据渲染是否全部完成
.show(...)      // 控制图层显隐
.visible(...)   // 控制图层显隐
.popupByMouse(...)      // 设置图层的浮窗行为的显示、触发方式
.popupByFixed(...)      // 设置图层的固定浮窗
.closePopupFixedLayers() // 关闭图层的浮窗
.locate(...)    // 设置图层定位
.flyTo(...)     // 等同于 locate
.zoomTo(...)    // 等同于 locate
.destroy()      // 图层销毁、移除
.remove()       // 等同于 destroy
.clear()        // 等同于 destroy
.close()        // 等同于 destroy

使用示例

import { PrimitiveGeoJsonLayer, PopupShowByEventTypes } from "render2dpro";

const map = new ol.Map({
  target: "map",
  layers: [new ol.layer.Tile({ source: new ol.source.OSM() })],
  view: new ol.View({
    center: ol.proj.fromLonLat([121.47, 31.23]),
    zoom: 9,
  }),
});

const polygonLayer = new PrimitiveGeoJsonLayer({
  ol: ol,
  map: map,
})
  .source(geojsonData)
  .shape("polygon")
  .color("weight", [
    "rgba(1, 117, 152,0.8)",
    "rgba(28, 189, 216,0.8)",
    "rgba(95, 249, 240,0.8)",
  ])
  .style({ opacity: 0.6 })
  .active(true, "rgba(255,0,0,1)")
  .select(true, "rgba(24,144,255,1)", (res) => {
    console.log(res.renderPrimitiveID, res.geojson);
  })
  .popupByMouse(PopupShowByEventTypes.MouseOver, (item) => {
    const container = document.createElement("div");
    container.innerText = item.name;
    return [container];
  })
  .render()
  .locate();

await polygonLayer.ready();

详情

source

设置图层数据，仅支持 GeoJSON 数据格式，支持传入 FeatureCollection 或 Feature。 数据坐标按 EPSG:4326（经纬度）处理，渲染时自动转换到地图视图的投影。

layer.source(data);

render

数据渲染的执行方法，用于将数据渲染到二维地图中。

layer.render();

ready

数据是否渲染完成的判断方法，异步方法，通过 renderReady 判断是否全部渲染结束。

await layer.ready();
console.log("是否全部渲染结束", layer.renderReady);

locate / flyTo / zoomTo

定位到图层范围。

layer.locate();                                        // 定位到当前显示的所有图斑
layer.locate((properties) => properties["name"] === "黄浦区"); // 基于 properties 定位
layer.locate("name", (value) => value === "黄浦区");    // 基于字段值定位

filter

数据过滤方法，返回 true 时可见。二维下通过将要素样式设为全透明来实现隐藏。

layer.filter((properties) => properties["weight"] >= 70);
layer.filter("weight", (value) => value >= 70);

shape

指定图层表现形式：fill/polygon（面）、line（线）、circle（圆形面）、box（正方形面）、point（点）。 fill3D/polygon3D/circle3D/box3D 在二维下分别退化为对应的二维形态。 注意： 必须在 render() 之前调用。

layer.shape("circle");

color

将数据值映射到图形的颜色，支持 5 种传参形式（与 render3dpro 完全一致）。

layer.color("rgba(1, 117, 152, 0.5)");        // 常量颜色
layer.color("c");                              // 取 properties 中的字段值作为颜色
layer.color("weight", ["#f00", "#0f0", "#00f"]); // 自然断裂法分段渲染
layer.color("name", (value) => { /* 返回颜色或 [面色, 线色] */ });
layer.color((properties) => { /* 返回颜色或 [面色, 线色] */ });

style

设置图层的通用整体样式。

layer.style({
  lineColor: "rgba(255,20,255,1)",
  stroke: "rgba(255,20,255,1)",
  lineWidth: 2,
  fillColor: "rgba(0,255,0,0.1)",
  opacity: 0.5,
});

size

当 shape 为 circle、box、point 时设置半径（单位：米）。数组第一个值为高度（二维下无效），第二个值为宽度。

layer.size([0, 2000]);
layer.size("weight", (value) => [0, value * 10]);

active

是否支持鼠标滑过高亮及高亮颜色。

layer.active(true, "rgba(255,0,0,1)");

select

是否支持鼠标点击高亮及回调。回调参数包含 renderPrimitiveID 和 geojson。

layer.select(true, "rgba(255,0,255,1)", (res) => {
  console.log(res.renderPrimitiveID, res.geojson);
});

doubleClick

地图双击事件，返回选中的要素及点击的坐标位置等信息。

layer.doubleClick((res) => {
  const { clickID, methods, picks, positions } = res;
});

popupByMouse

根据鼠标行为展示弹窗。支持 MouseOver（滑过）、MouseClick（点击）、NotShow（不显示）。

layer.popupByMouse(PopupShowByEventTypes.MouseOver, (properties) => {
  const container = document.createElement("div");
  container.innerText = properties["name"];
  return [container];
});
layer.popupByMouse(PopupShowByEventTypes.MouseClick, "name", (value) => value);

popupByFixed

固定弹窗。支持 AfterRendered（渲染后立即显示）、RightNow（立即显示）、NotShow（关闭）。 数据量超过 200 条时会随机抽取 200 条显示（由 randomRenderPopup 控制）。

layer.popupByFixed(PopupShowByEventTypes.AfterRendered, (properties) => {
  /* 返回文字或 DOM 数组 */
});
layer.popupByFixed(PopupShowByEventTypes.NotShow); // 隐藏

show / visible / hidden

控制图层与弹窗的显隐。

layer.show(true);        // 弹窗跟随图层
layer.show(true, false); // 图层显示、弹窗隐藏
layer.hidden();

destroy / remove / clear / close

销毁图层，移除地图图层、弹窗与已注册的地图事件。

layer.destroy();

示例

examples 目录下为可直接运行的示例，与 render3dpro 的示例一一对应、同名同编号（需通过 VSCode 的 Live Server 插件打开）：

• indexExamples.html — 示例集锦，左侧列表可切换全部示例（推荐入口）
• 00 render2dpro 介绍.html / indexCN.html — 中文 API 文档
• indexEN.html — 英文 API 文档

| 编号 | 示例 | 编号 | 示例 | | --- | --- | --- | --- | | 01 | 渲染(source+render+ready+locate) | 14 | 弹窗 1~4(popupByFixed) | | 02 | 定位 1~3(locate) | 15 | 弹窗(closePopupFixedLayers) | | 03 | 过滤 1~2(filter) | 16 | 显示隐藏控制(show) | | 04 | 形态 1~4(shape) | 17 | 销毁关闭移除图层(destroy) | | 05 | 颜色 1~4(color) | 18 | 点数据渲染 | | 06 | 样式 1(style) | 19 | 线数据渲染 | | 07 | 尺寸大小 1~3(size) | 20 | 面数据渲染 | | 08 | 鼠标滑过(active) | 21 | 面数据边线渲染 | | 09 | 鼠标点击(select) | 22 | 面数据中心点渲染 | | 10 | 离地高度 1~3(bottomHeight)※ | 23 | 面数据中心点圆柱渲染※ | | 11 | 拉伸高度 1~3(extrudedHeight)※ | 24 | 面数据立体渲染※ | | 12 | 动态拉伸高度(updateExtrudedHeight)※ | 25 | 分类渲染动态分类 | | 13 | 弹窗 1~2(popupByMouse) | 26 | 鼠标点击浦东新区行政区划下钻 | | | | 27 | 利用弹窗实现异形渲染五角星 | | | | 28 | 双击回调事件(doubleClick) |

※ 标记的示例涉及三维专有能力（离地高度、拉伸高度、立体/圆柱形态）。为与 render3dpro 保持示例编号与 API 一致，这些示例仍然保留，二维下相关方法为空实现、立体形态退化为对应的二维形态， 示例中已用注释说明，页面本身可正常渲染运行。

测试

npm test              # 运行 smoketest.mjs 冒烟测试
node buildExamples.js # 重新生成 examples 下的示例（01~28）