基础模块

目的和范围

本文档介绍了 Turf.js 中的三个核心基础模块：@turf/helpers、@turf/meta 和 @turf/invariant。这些模块为库中所有其他模块提供基本构建块。它们处理 GeoJSON 对象创建、遍历 GeoJSON 结构、输入验证和单位转换。

有关这些基础模块如何融入更广泛的模块分类的信息，请参阅模块分类。有关依赖层次结构以及基础模块如何支持更高级操作的详细信息，请参阅依赖层次。

概述

基础层由三个包构成，形成了所有 Turf.js 操作的基础：

包	主要目的	使用频率	依赖
`@turf/helpers`	GeoJSON 工厂函数和单位转换	所有模块使用	无
`@turf/meta`	用于遍历 GeoJSON 结构的迭代工具	50+ 个模块使用	`@turf/helpers`
`@turf/invariant`	输入验证和数据提取	70+ 个模块使用	`@turf/helpers`

100%

图：基础模块依赖

@turf/helpers

@turf/helpers 模块提供用于创建 GeoJSON 对象和单位转换的工具函数。此模块不依赖其他 Turf 包，并作为所有 GeoJSON 操作的基础。

GeoJSON 工厂函数

该模块导出用于构建有效 GeoJSON Feature 和 Geometry 对象的函数：

100%

图：GeoJSON 工厂函数

函数	输入	输出	位置
`point()`	`Position, properties?, options?`	`Feature<Point>`	packages/turf-helpers/index.ts254-277
`lineString()`	`Position[], properties?, options?`	`Feature<LineString>`	packages/turf-helpers/index.ts405-418
`polygon()`	`Position[][], properties?, options?`	`Feature<Polygon>`	packages/turf-helpers/index.ts327-355
`feature()`	`Geometry, properties?, options?`	`Feature`	packages/turf-helpers/index.ts175-193
`featureCollection()`	`Feature[], options?`	`FeatureCollection`	packages/turf-helpers/index.ts474-490
`geometry()`	`type, coordinates`	`Geometry`	packages/turf-helpers/index.ts210-237

单位转换系统

该模块提供基于球形地球计算的综合单位转换系统：

100%

图：单位转换架构

关键转换函数：

函数	目的	位置
`radiansToLength()`	将弧度转换为距离单位	packages/turf-helpers/index.ts648-657
`lengthToRadians()`	将距离转换为弧度	packages/turf-helpers/index.ts669-678
`lengthToDegrees()`	将距离转换为度数	packages/turf-helpers/index.ts690-692
`convertLength()`	在长度单位之间转换	packages/turf-helpers/index.ts766-775
`convertArea()`	在面积单位之间转换	packages/turf-helpers/index.ts786-809

earthRadius 常量（6,371,008.8 米）代表地球的平均半径，并被 Turf.js 中所有将地球建模为球体的距离计算使用。

类型定义

该模块导出在整个 Turf.js 中使用的 TypeScript 类型：

100%

图：Helper 类型系统

@turf/meta

@turf/meta 模块提供用于遍历和处理 GeoJSON 结构的迭代工具。它实现了针对地理空间数据优化的函数式编程模式（forEach、reduce）。

迭代函数家族

该模块将迭代函数组织成六组，基于它们遍历的内容：

100%

图：Meta 迭代函数家族

坐标迭代

坐标迭代函数遍历任何 GeoJSON 对象中的所有坐标位置：

100%

图：coordEach() 遍历逻辑

coordEach() 函数通过避免临时数组分配来进行性能优化。它使用嵌套循环和条件逻辑来处理所有 GeoJSON 几何类型，而无需规范化输入结构。

关键实现细节：

通过跳过空几何体来处理它们 packages/turf-meta/index.js38-39
支持 excludeWrapCoord 参数以跳过 LinearRings 的闭合坐标 packages/turf-meta/index.js92-96
提供五个回调参数以进行精确的位置跟踪 packages/turf-meta/index.js4-12
递归处理 GeometryCollection packages/turf-meta/index.js176-183

线段迭代

线段迭代函数处理 2 顶点线段，这对于线操作是基础：

100%

图：线操作的线段迭代

segmentEach() 函数内部使用 coordEach() 生成表示连续坐标对的 2 顶点 LineString 特征。这种抽象简化了基于线的几何操作。

几何和特征迭代

该模块提供对几何体和特征的迭代，可访问属性和元数据：

函数	遍历	回调参数	位置
`geomEach()`	几何体	`currentGeometry, featureIndex, featureProperties, featureBBox, featureId`	packages/turf-meta/index.js514-630
`featureEach()`	特征	`currentFeature, featureIndex`	packages/turf-meta/index.js395-403
`propEach()`	属性	`currentProperties, featureIndex`	packages/turf-meta/index.js297-309
`flattenEach()`	展平的特征	`currentFeature, featureIndex, multiFeatureIndex`	packages/turf-meta/index.js738-790

flattenEach() 函数将多几何体分解为单个特征，将 MultiPoint 转换为多个 Point 特征，MultiLineString 转换为多个 LineString 特征等。

@turf/invariant

@turf/invariant 模块提供输入验证和数据提取工具。它确保 GeoJSON 输入符合预期格式，并使用适当的错误处理提取特定组件。

数据提取函数

100%

图：Invariant 数据提取函数

类型验证函数

该模块提供三个验证函数，如果输入不符合期望，则抛出错误：

100%

图：类型验证流程

函数	目的	在以下情况抛出	位置
`geojsonType()`	验证 GeoJSON 类型匹配预期	类型不匹配	packages/turf-invariant/README.md53-67
`featureOf()`	验证 Feature 几何类型	几何类型不匹配	packages/turf-invariant/README.md69-84
`collectionOf()`	验证集合中的所有特征	任何特征类型不匹配	packages/turf-invariant/README.md86-99

这些验证函数在整个 Turf.js 中使用，以便在将不正确的几何类型传递给函数时提供清晰的错误消息。

常用使用模式

getGeom() 函数是最常使用的 invariant 工具之一：

100%

图：getGeom() 使用模式

来自 @turf/boolean-overlap 的示例：

const geom1 = getGeom(feature1);
const geom2 = getGeom(feature2);

这种模式允许函数接受 Feature 或 Geometry 对象作为输入，在需要时自动提取几何体组件。

模块间依赖

三个基础模块具有清晰的依赖层次：

100%

图：基础模块依赖

依赖详情

@turf/helpers packages/turf-helpers/package.json70-73：

"dependencies": {
  "@types/geojson": "^7946.0.10",
  "tslib": "^2.8.1"
}

@turf/meta packages/turf-meta/package.json84-87：

"dependencies": {
  "@turf/helpers": "workspace:*",
  "@types/geojson": "^7946.0.10"
}

从 helpers 导入：packages/turf-meta/index.js1

@turf/invariant packages/turf-invariant/package.json67-71：

"dependencies": {
  "@turf/helpers": "workspace:*",
  "@types/geojson": "^7946.0.10",
  "tslib": "^2.8.1"
}

构建配置

所有三个基础模块都使用仓库根目录中定义的相同构建配置：

100%

图：基础模块构建流程

每个模块的 package.json 都指定了 ES modules 和 CommonJS 的双重导出：

"exports": {
  ".": {
    "import": {
      "types": "./dist/esm/index.d.ts",
      "default": "./dist/esm/index.js"
    },
    "require": {
      "types": "./dist/cjs/index.d.cts",
      "default": "./dist/cjs/index.cjs"
    }
  }
}

这允许消费者根据其环境使用任一模块系统。

使用示例

创建和处理 GeoJSON

结合所有三个基础模块的典型工作流：

100%

图：典型基础模块使用流程

来自 @turf/boolean-overlap packages/turf-boolean-overlap/index.ts1-94 的示例：

使用 @turf/invariant 的 getGeom() 提取几何体
使用 @turf/meta 的 segmentEach() 遍历线段
使用几何计算比较线段

迭代模式

坐标处理的常见模式：

模式	使用的函数	用例
转换所有坐标	`coordEach()`	应用投影、四舍五入精度
聚合坐标	`coordReduce()`	计算边界、收集唯一坐标
处理线段	`segmentEach()`	查找相交、测量角度
分离多几何体	`flattenEach()`	独立处理每个组件

性能考虑

基础模块经过大量优化，因为它们被每个其他模块调用：

@turf/helpers 优化

直接对象创建，无中间结构 packages/turf-helpers/index.ts254-277
最小验证（仅类型检查）以提高性能
可重用的工厂模式

@turf/meta 优化

在迭代期间避免创建临时数组 packages/turf-meta/index.js55-66
直接坐标访问，无需规范化
支持提前返回的短路求值 packages/turf-meta/index.js110-111

@turf/invariant 优化

轻量级类型检查
直接属性访问
最小对象分配

基础模块 ​

目的和范围 ​

概述 ​

@turf/helpers ​

GeoJSON 工厂函数 ​

单位转换系统 ​

类型定义 ​

@turf/meta ​

迭代函数家族 ​

坐标迭代 ​

线段迭代 ​

几何和特征迭代 ​

@turf/invariant ​

数据提取函数 ​

类型验证函数 ​

常用使用模式 ​

模块间依赖 ​

依赖详情 ​

构建配置 ​

使用示例 ​

创建和处理 GeoJSON ​

迭代模式 ​

性能考虑 ​

@turf/helpers 优化 ​

@turf/meta 优化 ​

@turf/invariant 优化 ​

基础模块

目的和范围

概述

@turf/helpers

GeoJSON 工厂函数

单位转换系统

类型定义

@turf/meta

迭代函数家族

坐标迭代

线段迭代

几何和特征迭代

@turf/invariant

数据提取函数

类型验证函数

常用使用模式

模块间依赖

依赖详情

构建配置

使用示例

创建和处理 GeoJSON

迭代模式

性能考虑

@turf/helpers 优化

@turf/meta 优化

@turf/invariant 优化