Point 类

Point 类用于在地图上添加和管理点要素，支持普通点、聚合点、DOM 点、高性能闪烁点和 Vue 组件点。

构造函数

constructor(map: Map)

• map: OpenLayers 地图实例。

接口定义

PointOptions

继承自 BaseOptions, StyleOptions, TextOptions。

属性名	类型	说明
textKey	string	数据中用于显示文本的字段键名
img	string	图标图片的 URL
scale	number	图标缩放比例
iconColor	string	图标颜色（用于改变图标色调）
circleColor	string	圆点填充颜色。未设置 img 时生效，与 circleRadius 搭配绘制纯色圆点
circleRadius	number	圆点半径（像素），默认 6。仅在未设置 img 时生效
layerName	string	图层名称（基础配置中可选；公开 add 图层入口使用 *LayerOptions 要求必填）
zIndex	number	图层层级
visible	boolean	是否可见
style	Style | Style[] | ((feature: FeatureLike) => Style | Style[])	自定义样式函数

ClusterOptions

继承自 PointOptions。

属性名	类型	说明
distance	number	聚合距离（像素），默认为 20
minDistance	number	最小聚合距离

PointLayerOptions / ClusterPointLayerOptions / PulsePointLayerOptions

公开点图层入口使用的配置类型，分别继承自 PointOptions、ClusterOptions、PulsePointOptions，并把 layerName 收紧为必填。

interface PointLayerOptions extends PointOptions {
  layerName: string
}

interface ClusterPointLayerOptions extends ClusterOptions {
  layerName: string
}

interface PulsePointLayerOptions extends PulsePointOptions {
  layerName: string
}

PulsePointOptions

继承自 PointOptions，因此与 addPoint 一致支持 img、scale、iconColor、textKey、textVisible 等参数。

属性名	类型	说明
levelKey	string	点位等级字段，默认 lev
icon	PulsePointIconOptions	不使用 img 时的矢量圆点兜底配置
pulse.enabled	boolean	是否启用闪烁圈，默认 true
pulse.duration	number	单轮动画时长，默认 2400ms
pulse.radius	[number, number]	闪烁圈半径范围，默认 [8, 26]
pulse.colorMap	Record<string | number, string>	按等级配置闪烁圈填充色
pulse.strokeColorMap	Record<string | number, string>	按等级配置闪烁圈描边色
pulse.strokeWidth	number	闪烁圈描边宽度，默认 0
pulse.frameCount	number	动画分帧缓存数量，默认 24

PulsePointLayerHandle

属性名	类型	说明
layer	VectorLayer<VectorSource>	创建的闪烁点图层
source	VectorSource	图层数据源
start	() => void	开始闪烁动画
stop	() => void	停止闪烁动画
setVisible	(visible: boolean) => void	控制图层显隐
updateData	(data: PointData[]) => void	更新点位数据
remove	() => void	停止动画并移除图层

PointData

属性名	类型	说明
lgtd	number	经度
lttd	number	纬度
[key: string]	any	其他业务数据字段

PointJSONInput

点 API 统一输入类型。addPoint / addClusterPoint / addPulsePointLayer 均接受以下任意形态：

type PointJSONInput =
  | PointData[]                                    // 传统数组
  | MapJSONData                                    // GeoJSON FeatureCollection
  | FeatureData                                    // 单个 GeoJSON Feature
  | { type: 'Point'; coordinates: number[] }       // 裸 Point geometry
  | { type: 'MultiPoint'; coordinates: number[][] } // 裸 MultiPoint geometry

标准化规则：

• FeatureCollection 中只提取 Point / MultiPoint 类型的 Feature，其他 geometry 类型被跳过。
• MultiPoint 会被拆分为多个独立的 PointData。
• GeoJSON Feature 的 properties 会被保留，与 lgtd / lttd 合并。
• 创建 OpenLayers Feature 时，业务字段会平铺到 Feature 顶层，可通过 feature.get('name') 或 feature.getProperties().name 读取；rawData 仅保留兼容旧代码，不推荐新代码继续依赖。
• 坐标含 NaN、Infinity 或缺失的点会被过滤。
• 不支持 lng/lat、longitude/latitude、x/y 等字段别名。

本优化借鉴 mapshaper 对地理数据输入的统一处理思路，但仅提供轻量点数据标准化能力，不包含拓扑简化、dissolve、clip/erase 等 GIS 编辑功能。

VueTemplatePointOptions

属性名	类型	说明
Template	any	Vue 组件模板
lgtd	number	经度
lttd	number	纬度
props	any	传递给组件的 props
styleType	'default' | 'custom'	样式类型
positioning	string	定位方式，如 'bottom-center'
stopEvent	boolean	是否阻止事件冒泡
visible	boolean	是否可见
className	string	自定义类名
zIndex	number	层级

方法

addPoint

添加普通点图层。支持 PointJSONInput 任意形态（PointData[]、GeoJSON FeatureCollection、Feature、裸 geometry）。

addPoint(pointData: PointJSONInput, options: PointLayerOptions): LayerHandle<VectorLayer<VectorSource>> | null

• pointData: 点位数据，支持 PointData[] 或标准 GeoJSON 点数据。
• options: 配置选项。
• 返回值: { layer, remove(), setVisible() } 形态的统一句柄；如果数据无效返回 null。

addClusterPoint

添加聚合点图层。支持 PointJSONInput 任意形态。

addClusterPoint(pointData: PointJSONInput, options: ClusterPointLayerOptions): LayerHandle<VectorLayer<VectorSource>> | null

• pointData: 点位数据，支持 PointData[] 或标准 GeoJSON 点数据。
• options: 聚合配置选项。
• 返回值: { layer, remove(), setVisible() } 形态的统一句柄。

addPointByUrl

从 URL 加载点位数据，支持 PointData[] 数组或 GeoJSON FeatureCollection。

addPointByUrl(url: string, options: PointLayerOptions): Promise<LayerHandle<VectorLayer<VectorSource>> | null>

addDomPoint

添加 DOM 元素点（Overlay）。

addDomPoint(twinkleList: TwinkleItem[], callback?: Function): {
  target: Overlay[],
  anchors: Overlay[],
  remove: () => void,
  setVisible: (visible: boolean) => void
}

• twinkleList: 包含经纬度和类名的数据列表。
• callback: 点击回调函数。
• 返回值: 控制对象，包含 target、anchors、remove 和 setVisible。

addPulsePointLayer

添加高性能闪烁点图层。支持 PointJSONInput 任意形态。

addPulsePointLayer(pointData: PointJSONInput, options: PulsePointLayerOptions): PulsePointLayerHandle | null

• pointData: 点位数据，支持 PointData[] 或标准 GeoJSON 点数据。
• options: 闪烁点配置选项，复用 addPoint 的图标、文本和图层参数习惯。
• 返回值: 控制对象，包含动画启停、显隐、数据更新和移除方法；如果数据无效返回 null。

addPulsePointLayerByUrl

从 URL 加载点位数据并添加高性能闪烁点图层。

addPulsePointLayerByUrl(url: string, options: PulsePointLayerOptions): Promise<PulsePointLayerHandle | null>

addVueTemplatePoint

添加 Vue 组件作为点位。

addVueTemplatePoint(pointDataList: PointData[], template: any, options?: VueTemplatePointOptions): {
  target: VueTemplatePointInstance[],
  setVisible: (visible: boolean) => void,
  setOneVisibleByProp: (propName: string, propValue: any, visible: boolean) => void,
  remove: () => void,
  getPoints: () => VueTemplatePointInstance[]
}

• pointDataList: 点位数据列表。
• template: Vue 组件。
• options: 配置选项。
• 返回值: 控制对象，包含 target、显示/隐藏、按属性显示/隐藏和移除方法。

使用示例

添加普通点

import { Point } from 'my-openlayers';

const point = new Point(map);
const data = [
  { lgtd: 116.40, lttd: 39.90, name: '北京' },
  { lgtd: 121.47, lttd: 31.23, name: '上海' }
];

point.addPoint(data, {
  layerName: 'cities',
  img: 'path/to/icon.png',
  textKey: 'name',
  scale: 0.8
});

添加聚合点

point.addClusterPoint(data, {
  layerName: 'clusters',
  distance: 40,
  img: 'path/to/cluster-icon.png'
});

添加高性能闪烁点

const pulseCtrl = point.addPulsePointLayer(data, {
  layerName: 'village-warning-pulse',
  levelKey: 'lev',
  textKey: 'name',
  img: '/icons/village.svg',
  scale: 0.8,
  textVisible: true,
  pulse: {
    duration: 2400,
    radius: [8, 28],
    colorMap: {
      0: 'rgba(255, 48, 54, 0.48)',
      1: 'rgba(255, 136, 0, 0.45)',
      2: 'rgba(253, 216, 46, 0.4)',
      3: 'rgba(6, 183, 253, 0.32)'
    }
  }
});

pulseCtrl?.stop();
pulseCtrl?.start();
pulseCtrl?.updateData(data);
pulseCtrl?.remove();

添加 Vue 组件点

import MyComponent from './MyComponent.vue';

const ctrl = point.addVueTemplatePoint(data, MyComponent, {
  positioning: 'bottom-center',
  props: { status: 'active' }
});

// 隐藏所有点
ctrl.setVisible(false);

使用 GeoJSON 数据添加点位

从 3.0 起，点 API 直接接受标准 GeoJSON 点数据，无需手动转换：

// 方式一：GeoJSON FeatureCollection
const fc = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', properties: { name: '北京' }, geometry: { type: 'Point', coordinates: [116.40, 39.90] } },
    { type: 'Feature', properties: { name: '上海' }, geometry: { type: 'Point', coordinates: [121.47, 31.23] } }
  ]
};
const handle = point.addPoint(fc, { layerName: 'cities', textKey: 'name' });
const firstFeature = handle?.layer.getSource()?.getFeatures()[0];
firstFeature?.get('name'); // '北京'
// firstFeature.get('rawData') 仅保留兼容旧代码，新代码优先读取顶层业务字段。

// 方式二：单个 Feature
const feature = { type: 'Feature', properties: { name: '杭州' }, geometry: { type: 'Point', coordinates: [120.15, 30.27] } };
point.addPoint(feature, { layerName: 'single-city' });

// 方式三：MultiPoint Feature（自动拆分为多个点）
const multiPoint = { type: 'Feature', properties: { region: '华东' }, geometry: { type: 'MultiPoint', coordinates: [[120, 30], [121, 31]] } };
point.addPoint(multiPoint, { layerName: 'region' });

// 闪烁点同样支持 GeoJSON 输入
const pulseHandle = point.addPulsePointLayer(fc, {
  layerName: 'villages',
  levelKey: 'lev',
  pulse: { enabled: true, radius: [8, 28] }
});