在使用Mapbox等地图库绘制GeoJSON多边形时，常因数据无效导致错误。本文将介绍如何利用Turf.js库中的BooleanValid函数，在绘图前高效校验多边形坐标的有效性，确保Geojson数据的合规性，从而避免运行时错误，提升应用稳定性。通过示例代码和注意事项，帮助开发者正确处理多边形数据。
GeoJSON多边形数据校验的必要性
在地理信息系统（gis）应用开发中，尤其是在使用mapbox gl js这类前端地图库进行图形绘制时，多边形（polygon）数据是常见的地理要素类型。然而，如果提供给地图库的geojson多边形数据不符合其规范，例如坐标格式错误、环未闭合、存在自相交等，便可能导致运行时错误，如常见的Error: input data is not a valid geojson Object.。为了避免这类问题，在将多边形数据传递给绘图api之前进行严格的有效性校验是至关重要的一步。
使用Turf.js进行多边形有效性校验
Turf.js是一个强大的地理空间分析库，它提供了一系列处理GeoJSON数据的函数。其中，@turf/boolean-valid模块提供了一个专门用于检查GeoJSON几何对象有效性的函数booleanValid。这个函数能够判断一个GeoJSON对象是否符合其类型规范，对于多边形而言，它会检查其坐标结构、环的闭合性以及是否存在自相交等问题。
安装Turf.js模块
首先，你需要通过npm或yarn安装@turf/boolean-valid模块：
npm install @turf/boolean-valid # 或者 yarn add @turf/boolean-valid
校验函数的使用
安装完成后，你可以在你的JavaScript/typescript代码中导入并使用booleanValid函数。该函数接收一个GeoJSON多边形对象作为参数，并返回一个布尔值：true表示多边形有效，false表示多边形无效。
import { booleanValid } from '@turf/boolean-valid'; import type { Polygon } from 'geojson'; // 引入GeoJSON Polygon类型定义 /** * 示例：一个有效的GeoJSON多边形 * 外环顺时针或逆时针均可，但通常建议外环逆时针（符合右手定则），内环顺时针。 * 环的第一个和最后一个坐标必须相同以形成闭合环。 */ const validPolygon: Polygon = { type: 'Polygon', coordinates: [ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0], // 闭合 ], ], }; /** * 示例：一个无效的GeoJSON多边形 * 1. 环未闭合：第一个和最后一个坐标不一致 * 2. 可能存在自相交（虽然此例中未直接展示，但booleanValid会检查） * 3. 坐标顺序错误等 */ const invalidPolygonUnclosed: Polygon = { type: 'Polygon', coordinates: [ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], // [100.0, 0.0] 缺失，导致环未闭合 ], ], }; const invalidPolygonSelfIntersection: Polygon = { type: 'Polygon', coordinates: [ [ [0, 0], [2, 2], [0, 2], [2, 0], [0, 0], // 自相交 ], ], }; // 执行校验 const isValid1 = booleanValid(validPolygon); console.log('Valid Polygon is valid:', isValid1); // 输出: Valid Polygon is valid: true const isValid2 = booleanValid(invalidPolygonUnclosed); console.log('Invalid (unclosed) Polygon is valid:', isValid2); // 输出: Invalid (unclosed) Polygon is valid: false const isValid3 = booleanValid(invalidPolygonSelfIntersection); console.log('Invalid (self-intersecting) Polygon is valid:', isValid3); // 输出: Invalid (self-intersecting) Polygon is valid: false // 在绘制前进行判断 function drawPolygonIfValid(map: any, polygon: Polygon) { if (booleanValid(polygon)) { console.log('多边形数据有效，可以进行绘制。'); // 假设 map.addSource 和 map.addLayer 是Mapbox GL JS的API // map.addSource('my-polygon', { // type: 'geojson', // data: polygon, // }); // map.addLayer({ // id: 'my-polygon-layer', // type: 'fill', // source: 'my-polygon', // paint: { // 'fill-color': '#088', // 'fill-opacity': 0.8, // }, // }); } else { console.error('错误：多边形数据无效，无法绘制。请检查坐标结构。', polygon); // 可以进一步处理，例如向用户显示错误消息 } } // 示例调用 (假设有一个map实例) // const myMap = new MapboxMap({ /* ... */ }); // drawPolygonIfValid(myMap, validPolygon); // drawPolygonIfValid(myMap, invalidPolygonUnclosed);
多边形有效性的常见规则
booleanValid函数会根据GeoJSON规范检查以下几个主要方面：
- 坐标结构： 多边形的coordinates属性是一个数组，其中包含一个或多个线性环（LinearRing）。第一个环是外部环，后续的环是内部环（孔洞）。每个线性环本身是一个坐标对的数组。
- 闭合性： 每个线性环（无论是外环还是内环）必须是闭合的，即其第一个坐标和最后一个坐标必须完全相同。
- 最小点数： 一个有效的线性环至少需要四个坐标点（三个顶点加上一个重复的闭合点）。
- 自相交： 对于简单的多边形，其边界不能自相交。如果存在自相交，booleanValid会返回false。
- 内外环关系： 内部环（孔洞）必须完全包含在外部环之内，并且内部环之间不能相互重叠或相交。
注意事项与最佳实践
- 数据源校验： 无论是用户输入、API获取还是文件导入的GeoJSON数据，都应在处理前进行有效性校验。
- 错误处理： 当booleanValid返回false时，应有相应的错误处理机制，例如向用户提示错误信息，或者记录日志以便后续调试。
- 性能考量： 对于包含大量顶点或复杂自相交的多边形，校验操作可能会消耗一定的计算资源。在处理大规模数据时，可以考虑在数据预处理阶段进行一次性校验。
- 与其他Turf.js模块结合： 如果需要修复无效的多边形（例如，移除自相交），Turf.js还提供了其他有用的模块，如@turf/clean-coords或@turf/union等，可以结合使用。
总结
通过在绘图前引入@turf/boolean-valid进行GeoJSON多边形数据校验，开发者可以有效预防因数据格式不规范导致的运行时错误，提升应用的健壮性和用户体验。这是一个简单而强大的工具，对于任何处理地理空间数据的应用都应作为标准实践。
