本仓库现已新增 Vue 3 组件库 @rawhugh/ol-ext-vue，面向 TypeScript、Vite、Element Plus 和 OpenLayers 10.10.0。提供弹窗、测距测面、图层管理、矢量编辑、PNG/JPEG/PDF 导出，以及原 ol-ext 模块的 Vue 适配入口。
Vue 接入请先阅读 组件库使用文档，并查看 实施计划、源码覆盖矩阵 和 验证记录。下文保留原 JavaScript 核心的功能介绍与分类。
# 在仓库根目录执行
npm run vue:install
npm run vue:dev
# 打开 http://127.0.0.1:5178生成可在其他项目中安装的包：
npm run vue:build
npm run vue:pack
# 产物：vue/artifacts/rawhugh-ol-ext-vue-0.1.0.tgzVue 组件库独立位于 vue/，保留原 src/ 和 HTML 示例。五项业务组件提供默认可关闭的操作界面与严格类型；其他原扩展以生命周期组件及工具模块形式接入，详细兼容性与验证范围见组件库文档。
面向 OpenLayers 的地图功能扩展库，提供图层管理、绘制编辑、搜索定位、弹窗、专题样式、动画、滤镜、空间计算和地图输出等组件。
本仓库基于 Jean-Marc Viglino 的 ol-ext 项目。它是围绕 OpenLayers 组织的 JavaScript 组件库，可按模块引入，也提供供普通网页使用的构建产物。
本说明按当前源码和构建配置整理：package.json 中的版本为 4.0.39，OpenLayers 对等依赖声明为 ol >= 5.3.0。该声明不表示每个扩展都适用于所有 OpenLayers 版本，具体模块还需结合源码及示例确认。
在线示例 · 在线 API 文档 · 更新记录 · 贡献指南
在你的应用项目中安装 OpenLayers 和 ol-ext：
npm install ol ol-ext下面的示例创建地图，并添加支持图层排序和透明度调节的图层管理器。JavaScript 需要交给支持 ES 模块和 CSS 导入的应用构建工具处理。
<div id="map" style="width: 100%; height: 480px;"></div>import 'ol/ol.css'
import 'ol-ext/dist/ol-ext.css'
import Map from 'ol/Map.js'
import View from 'ol/View.js'
import TileLayer from 'ol/layer/Tile.js'
import OSM from 'ol/source/OSM.js'
import LayerSwitcher from 'ol-ext/control/LayerSwitcher.js'
const map = new Map({
target: 'map',
layers: [
new TileLayer({
title: 'OpenStreetMap 底图',
source: new OSM(),
}),
],
view: new View({
center: [0, 0],
zoom: 2,
}),
})
map.addControl(new LayerSwitcher({
collapsed: false,
reordering: true,
show_progress: true,
}))注意引入路径的区别：发布到 npm 的组件路径为 ol-ext/control/LayerSwitcher.js，仓库中的对应源码为 src/control/LayerSwitcher.js。发布脚本会将 src/ 下的模块复制到包根目录。
TypeScript 类型声明由独立项目 types-ol-ext 维护，原项目提供的安装方式如下；使用时需核对声明与组件版本：
npm install --save-dev @types/ol-ext@npm:@siedlerchr/types-ol-ext仓库的 dist/ 提供全局脚本和样式。先加载与你的应用匹配的 OpenLayers 全局构建，再加载 dist/ol-ext.css 和 dist/ol-ext.js（或各自的 .min 版本），之后通过 ol.control.LayerSwitcher 等命名空间使用组件。
可从 图层管理示例 查看完整 HTML 引入顺序。部分扩展需要额外脚本或字体文件，详见后文的依赖说明。旧的 openlayers-ext npm 包在原 README 中已标记为弃用。
ol-ext/
├── vue/ # Vue 3 组件库、演示、测试、打包和接入文档
├── src/ # ES 模块源码及组件样式
│ ├── control/ # 地图控件：按钮、图层管理、搜索、打印等
│ ├── interaction/ # 输入交互：绘制、修改、吸附、选择、撤销等
│ ├── layer/ # 图层扩展：聚合动画、地理影像、3D 绘制等
│ ├── source/ # 数据源：服务加载、分箱统计、插值、等值面等
│ ├── overlay/ # 地理位置关联的弹窗、标记及动画覆盖物
│ ├── style/ # 要素样式：图表、字体符号、纹理、流线等
│ ├── legend/ # 图例内容模型、图例项和图片图例
│ ├── featureanimation/ # 要素动画基类及具体动画
│ ├── filter/ # 地图/图层绘制滤镜、遮罩与裁剪
│ ├── geom/ # 几何运算、简化、编码和路径计算
│ ├── format/ # GeoJSONX、GeoJSONP、GeoRSS 数据格式
│ ├── render/ # 样条、网格、绘制排序和瞬时绘制效果
│ ├── map/ # PerspectiveMap 透视地图
│ ├── particule/ # 粒子模型：云、雨、雪、鸟等（目录原名）
│ ├── util/ # DOM、Ajax、颜色、Canvas、Worker 等基础工具
│ │ ├── input/ # 颜色、数值、开关、列表等输入组件
│ │ └── SVGFilter/ # 边缘检测、纸张效果等 SVG 滤镜
│ └── utils/ # iframe 通信、跨窗口同步等附加工具
├── examples/ # 按功能组织的 HTML 示例及演示数据
├── dist/ # 合并、压缩后的 JavaScript/CSS 与 extra 脚本
├── doc/ # JSDoc 配置、说明及生成的 API 页面
├── img/ # 项目介绍图片
├── .github/workflows/ # GitHub Actions 包发布配置
├── index.html # 示例站点首页
├── gulpfile.cjs # npm 脚本实际使用的 Gulp 构建入口
├── gulpfile.js # 仓库保留的另一份 Gulp 文件
├── package.json # 包信息、依赖及开发命令
├── DEVELOPING.md # 原开发说明
├── CONTRIBUTING.md # 贡献约定
└── CHANGELOG.md # 版本变更记录
lib/ 是运行独立文件构建任务后生成的目录，不是当前源码入口。util/ 与 utils/ 也不是同一个目录：前者主要供组件内部复用，后者含附加集成脚本，其中部分仍带有模块化重写的 TODO。
代码以 OpenLayers 的对象体系为基础，通过继承、组件组合、事件监听和部分原型扩展实现功能：
| 扩展方式 | 代码中的实现 | 使用入口 |
|---|---|---|
| 控件继承与组合 | LayerSwitcher 继承 ol/control/Control；EditBar 组合按钮、开关与编辑交互 |
map.addControl(control) |
| 地图事件交互 | Transform 基于 Pointer 交互处理拖拽，并用辅助矢量层绘制操作手柄；UndoRedo 监听数据源及编辑事件维护历史 |
map.addInteraction(interaction) |
| 数据源与图层分工 | 数据源负责加载、组织或计算要素，图层负责显示；例如 HexBin 生成统计单元，AnimatedCluster 处理聚合变化动画 |
构造数据源并传入图层 |
| 样式与覆盖物 | Chart、FontSymbol 等生成要素符号；Popup、Tooltip 等显示与地图位置关联的内容 |
设置图层/要素样式，或 map.addOverlay(overlay) |
| 渲染扩展 | 滤镜在渲染事件中处理 Canvas；动画基类管理要素动画过程；粒子由 AnimatedCanvas 更新和绘制 |
使用具体滤镜、动画或覆盖物 |
| 原型补充 | filter/Base.js 添加图层的 addFilter 等方法；FeatureAnimation.js 添加 animateFeature；source/Vector.js 补充清空前后事件 |
需先导入注册这些方法的模块 |
因此，按需导入时除了组件本身，也要注意模块的初始化副作用和依赖。普通网页构建通过 gulpfile.cjs 将 ol_control_* 等变量名转换为 ol.control.*，移除模块导入导出后按顺序合并；ES 模块与全局脚本采用不同的加载方式。
以下按使用目的分类，列出主要组件和实现能力。表中的名称与源码文件名对应，目录链接可继续查看同类组件；这是一份功能导航，完整参数和事件请查看源码注释或 API 文档。
源码入口：src/control/、src/legend/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 图层管理 | LayerSwitcher、LayerSwitcherImage、LayerPopup、LayerShop |
显隐切换、透明度调节、图层排序、图像式图层选择及图层操作界面 |
| 工具栏与按钮 | Bar、Button、TextButton、Toggle、EditBar |
按钮组合、嵌套工具栏、交互启停和矢量编辑工具栏 |
| 视图导航 | Overview、Globe、GeoBookmark、MapZone、Permalink |
鹰眼/球形概览、位置书签、区域跳转和视图链接保存 |
| 地图辅助信息 | Scale、Compass、CenterPosition、Target、Graticule、GridReference |
比例尺、指北针、中心坐标、中心标靶、经纬网及索引网格 |
| 信息反馈 | Dialog、Notification、Overlay、Status、Gauge、ProgressBar、Disable |
对话框、通知、面板、状态/数值展示、瓦片加载进度及地图操作屏蔽 |
| 要素列表与筛选 | FeatureList、Select、SelectCondition、SelectCheck、SelectPopup、SelectFulltext、SelectMulti |
要素列表、属性条件筛选、文本筛选和多条件组合 |
| 图例 | control/Legend、legend/Legend、legend/Item、legend/Image |
展示符号图例、要素样式图例和图片图例 |
源码入口：src/control/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 自定义及本地搜索 | Search、SearchJSON、SearchFeature |
搜索控件基类、JSON 服务适配和本地要素搜索 |
| 地名与地址搜索 | SearchNominatim、SearchPhoton、SearchBAN、SearchGeoportail、SearchWikipedia |
对接对应地理编码、地址或百科服务，展示搜索结果并定位 |
| 坐标与地块搜索 | SearchCoordinates、SearchGPS、SearchDFCI、SearchGeoportailParcelle |
坐标输入定位、法国 DFCI 网格定位和地籍地块搜索 |
| 设备定位 | GeolocationButton、GeolocationBar |
控制设备定位与定位绘制流程，可结合 GeolocationDraw 使用 |
| 路线与可达范围 | RoutingGeoportail、IsochroneGeoportail |
调用 Geoportail 服务进行路线及等时/等距可达范围查询 |
| 服务图层接入 | WMSCapabilities、WMTSCapabilities |
读取服务能力信息，选择并添加服务图层 |
源码入口：src/interaction/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 绘制 | DrawRegular、DrawHole、GeolocationDraw |
绘制规则图形、为多边形挖洞、按设备定位绘制 |
| 修改与变换 | Modify、ModifyFeature、Transform、Offset |
修改顶点、平移、旋转、缩放、拉伸及几何偏移 |
| 分割与吸附 | Split、Splitter、SnapGuides、SnapLayerPixel |
主动分割、编辑时自动分割线、辅助线吸附和图层像素吸附 |
| 编辑历史与属性 | UndoRedo、CopyPaste、Delete、FillAttribute |
撤销/重做、复制粘贴、删除和属性填充；撤销可组织操作块及注册自定义操作 |
| 选择与反馈 | Hover、SelectCluster、DragOverlay |
悬停反馈、聚合要素选择及覆盖物拖动 |
| 文件与焦点 | DropFile、CurrentMap、FocusMap |
拖放文件加载、自定义接收区域和地图键盘焦点管理 |
| 触屏操作 | DrawTouch、ModifyTouch、LongTouch、TouchCompass、TouchCursor 及其绘制/修改/选择子类 |
中心或偏移光标操作、触屏顶点编辑、长按和触屏方向控制 |
源码入口：src/source/、src/layer/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 服务数据加载 | Geoportail、TileWFS、Overpass、DBPedia、WikiCommons、GeoRSS |
Geoportail 瓦片、按瓦片范围加载 WFS、OSM 查询、知识/图片数据和 GeoRSS 订阅加载 |
| 地理配准影像 | source/GeoImage、layer/GeoImage |
将图片按地理位置、比例和旋转等参数放置到地图上 |
| 分箱统计 | BinBase、GridBin、HexBin、FeatureBin、InseeBin |
按规则网格、六边形、指定面要素或法国 INSEE 网格收集要素 |
| 插值与等值面 | IDW、Delaunay、Contour |
反距离加权插值、Delaunay 三角剖分、从规则网格数值生成等值面；Contour 依赖 d3-contour |
| 专用网格与昼夜 | DFCI、DayNight |
法国 DFCI 网格及指定时间的昼夜区域 |
| 聚合与图层辅助 | AnimatedCluster、GetPreview、SketchOverlay |
聚合变化动画、图层预览图获取及编辑草图辅助层 |
| 3D 与外部渲染 | Render3D、Vector3D、Maplibre |
矢量高度/立体表现和 MapLibre GL 图层集成；接入时需核对渲染器依赖与版本 |
源码入口：src/style/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 统计图表 | Chart |
在要素位置绘制饼图、立体饼图、环形图和柱状图 |
| 字体与照片符号 | FontSymbol、FontAwesomeDef、FontAwesome5Def、FontMakiDef、FontMaki2Def、Photo |
字体图标注册与绘制、照片标记 |
| 图案与阴影 | FillPattern、StrokePattern、Shadow |
图案填充、图案描边和点符号阴影 |
| 线与文字 | FlowLine、SetTextPath |
可变颜色/宽度的线条表现及沿线文字 |
| 剖面与默认样式 | Profile、defaultStyle、geoportailStyle |
地图上的剖面样式、默认样式及 Geoportail 要素样式辅助 |
源码入口：src/overlay/、src/control/、src/interaction/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 弹窗与标记 | Popup、PopupFeature、FixedPopup、Fixed、Placemark、Tooltip |
地理位置弹窗、要素属性模板、固定覆盖物、标记和跟随提示 |
| 卷帘对比 | control/Swipe、control/SwipeMap |
图层或地图画面卷帘 |
| 局部查看 | overlay/Magnify、interaction/Clip、ClipMap、Blob、Flashlight |
放大镜、圆形/不规则局部裁剪和手电筒效果 |
| 多地图联动 | interaction/Synchronize |
同步多个地图的视图操作 |
源码入口：src/featureanimation/、src/particule/、src/map/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 要素动画 | FeatureAnimation、Fade、Zoom、Bounce、Drop、Slide、Throw、Shake、Blink、Teleport |
渐变、缩放、弹跳、下落、滑入、抛出、抖动、闪烁及传送效果 |
| 沿线运动与即时强调 | featureanimation/Path、render/Pulse、render/AnimExtent、render/Markup |
沿路径播放动画、强调点位/范围、绘制临时标记 |
| 粒子与指针特效 | overlay/AnimatedCanvas、particule/Cloud、Rain、RainDrop、Snow、Bird、interaction/Ripple、TinkerBell |
覆盖在地图上的云雨雪等粒子，以及波纹、指针光效 |
| 时间与叙事 | control/Timeline、Imageline、Storymap |
时间轴、图片时间线及随内容滚动导航的故事地图 |
| 透视展示 | map/PerspectiveMap |
地图透视显示与对应的坐标/像素处理 |
源码入口：src/filter/、src/util/SVGFilter/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 区域控制 | Mask、Crop、Clip |
根据要素或裁剪区域控制显示范围 |
| 颜色与混合 | Colorize、Composite、CSS、CanvasFilter、SVGFilter |
着色、混合模式、Canvas/CSS/SVG 滤镜处理 |
| 艺术化表现 | Texture、TextureImage、Paper、Fold、PencilSketch、Pointillism、Halftone、Lego |
纹理、纸张、折叠、铅笔、点描、半色调及积木效果 |
| 边缘检测 | util/SVGFilter/Sobel、Prewitt、Roberts、Laplacian |
使用不同算子构建边缘检测滤镜 |
| 图像处理数据源 | source/OilPainting |
通过图像处理生成油画效果 |
源码入口：src/geom/、src/format/、src/render/、src/util/、src/utils/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 几何运算 | GeomUtils、ConvexHull、LineStringSplitAt、Scribble |
距离与相交等辅助计算、凸包、按点切分线及手绘填充线生成 |
| 简化与平滑 | Simplificator、visvalingam、render/Cspline |
几何简化、Visvalingam–Whyatt 简化及样条平滑 |
| 路径与球面计算 | Dijkstra、geom/sphere |
线网络最短路径计算（含 A* 优化）、方位角、大圆路径和目的点等球面计算 |
| 编码与高程辅助 | geohash、DFCI、GPAltiCode |
Geohash 编解码、法国 DFCI 编码和 Geoportail 高程数据辅助 |
| 数据格式 | GeoJSONX、GeoJSONP、GeoRSS |
GeoJSON 扩展格式读写、Polyline 编码几何读写及 GeoRSS 解析 |
| 网格与排序 | render/HexGrid、InseeGrid、Ordering |
六边形/INSEE 网格计算和矢量绘制顺序辅助 |
| 通用工具 | Ajax、element、color、Worker、TextStreamReader、imagesLoader、matrix3D |
请求、DOM、颜色转换、Worker 包装、分块逐行读取文本、BIL-32 图像加载及矩阵计算 |
| 输入组件 | util/input/Color、Slider、Range、Switch、Checkbox、Radio、List、Collection 等 |
颜色、数值、开关和集合编辑界面 |
| 附加集成脚本 | utils/IFrameAPI、MapIFrameAPI、WSynchro、Exif2Geojson、ExportMap |
iframe 通信、跨窗口同步、照片 EXIF 位置转换及地图导出辅助；部分为待整理的旧脚本 |
源码入口：src/control/。
| 类型 | 主要组件 | 已实现的功能 |
|---|---|---|
| 图像与打印 | Print、PrintDialog、PrintDialog2x |
地图画布图像输出、纸张/方向/比例等打印设置和双地图打印界面 |
| 输出装饰 | CanvasBase、CanvasTitle、CanvasScaleLine、CanvasAttribution |
将标题、比例尺和来源信息绘制到画布，便于随图导出 |
| 视频录制 | VideoRecorder |
录制地图画布视频，依赖浏览器媒体能力 |
| 高程剖面 | Profile |
根据包含高程的几何坐标绘制剖面，并与地图位置关联 |
启动本地服务后，从首页进入示例；也可以将下列仓库路径接在 http://localhost:8181/ 后访问。GitHub 文件链接用于查看代码，不会直接运行 HTML。
| 想实现的功能 | 示例入口 |
|---|---|
| 图层管理 | 图层切换器 |
| 完整编辑工具栏 | 编辑工具栏 |
| 旋转、缩放与平移 | 要素变换 |
| 撤销与重做 | 编辑历史 |
| 地址搜索 | Nominatim 搜索 |
| 六边形聚合统计 | 六边形分箱 |
| 栅格数值等值面 | Contour 数据源 |
| 地图统计图表 | 图表样式 |
| 要素属性弹窗 | 要素弹窗 |
| 沿线动画 | 路径动画 |
| 故事地图 | 滚动叙事 |
| 地图卷帘 | 卷帘对比 |
| 地图打印 | 打印对话框 |
| 移动端绘制 | 触屏光标绘制 |
在仓库根目录执行：
npm install
npm run build
npm start然后在浏览器打开 本地示例站点。npm start 启动静态服务并监听源码变化，触发重新构建；它不会自动打开浏览器。示例中的在线底图、CDN 和外部 API 仍需要网络连接。
| 命令 | 当前配置中的行为 |
|---|---|
npm run build |
使用 gulpfile.cjs 执行
7D75
默认任务，生成 JavaScript、额外脚本和 CSS |
npm start |
执行 serve，在 8181 端口提供示例，并监听源码修改 |
npm run build -- lib |
执行 lib 任务，为脚本中列出的目录生成独立 JS/CSS；该任务没有覆盖全部源码子目录 |
npm run doc |
从构建后的 dist/ol-ext.js 和文档说明生成 doc/doc-pages/；需额外安装 gulp-jsdoc3 |
npm run lint |
对 src/ 执行 ESLint 自动修复；脚本会吞掉失败退出码，退出码不能用于证明检查全部通过 |
如需生成 API 文档，可先安装文档工具，再构建并生成文档：
npm install --no-save gulp-jsdoc3
npm run build
npm run doc当前 test 脚本内容为 npm test npmtest.js，会再次调用自身；仓库中也未找到该 npmtest.js 文件。因此不能把 npm test 当作可用的自动化测试入口。修改组件时应构建产物，并用对应示例验证实际行为。
dist/ol-ext.js、dist/ol-ext.min.js：全局 JavaScript 构建。dist/ol-ext.css、dist/ol-ext.min.css：组件样式合集。dist/extra/：字体符号定义、附加工具等独立脚本，不全部包含在主构建中。src/<类型>/<名称>.js：组件源码入口；组件样式通常放在同目录的.css文件中。- 新组件遵循现有命名规则，例如
ol_control_MyControl对应src/control/MyControl.js，便于构建脚本转换命名空间。既有工具模块也包含命名导出及原型扩展，阅读时以文件实际导出为准。 prepack/postpack会在打包前后复制和清理包根目录中的模块文件；开发组件时优先修改src/，再重新生成分发文件。
- 外部服务组件：搜索、路线、WFS、Geoportail、Overpass 等模块封装的是服务接入逻辑；端点、密钥、配额、跨域和服务可用性需按实际部署配置。
- 等值面：
source/Contour接收规则网格{ x, y, z }，需要提供d3.contours工厂或对应的全局 D3 对象；它不替你完成坐标投影转换。 - MapLibre：
layer/Maplibre.js依赖外部渲染器，源码使用maplibre-gl.js导入及渲染器内部方法；接入应用时需适配模块解析并验证版本兼容性。 - 图标与 PDF：字体符号需要对应字体及定义文件；
PrintDialog的 PDF 功能需要额外提供 jsPDF。utils/下的 EXIF 等辅助脚本也有独立依赖。 - 浏览器与渲染方式：Canvas 滤镜、图像导出和视频录制受浏览器、渲染器及跨域图像条件影响。不能仅凭 OpenLayers 的最低版本声明推断所有效果都可用。
- 旧代码状态：部分文件保留兼容逻辑、TODO 或未测试标记，例如
source/Mapillary.js明确标注未测试。选用这些模块前应结合示例和实际服务验证。
贡献代码前请阅读 贡献指南 和 开发说明。开发命令以当前 package.json 与 gulpfile.cjs 为准。
本仓库相关改动可在 RAWHugh/ol-ext 中协作；通用组件的问题与上游功能建议可参考 上游 Issue。报告问题时附上 OpenLayers/ol-ext 版本、浏览器、最小复现代码及涉及的示例。
ol-ext 原作者为 Jean-Marc Viglino，感谢原项目及所有贡献者。
仓库保留 CeCILL-B 许可证说明 和 BSD 3-Clause 许可证，package.json 的许可证字段为 BSD-3-Clause；具体授权内容以许可证文件为准。部分源码、地图服务、字体、图像和第三方 API 另有各自的许可及署名要求。