Gcoord

English | 简体中文

gcoord（geographic coordinates）是一个轻量的 JavaScript 地理坐标转换库，用于在常见 Web 地图坐标系之间转换坐标。它可以帮助你统一来自 GPS、百度地图、高德地图、Google 中国地图以及其他地图服务商的坐标。

gcoord 支持转换坐标数组和 GeoJSON 对象，没有运行时依赖，可在 Node.js、现代浏览器和 React Native 中使用。浏览器全局构建 gzip 后约 3 KB。

更多背景信息可以阅读地理坐标系。

法律提示

在发布、展示、传播或以其他方式使用地图数据前，请务必遵守适用于你使用场景的法律法规。

（禁止）未经批准，在测绘活动中擅自采用国际坐标系统。

• 《中华人民共和国测绘法》第 40 条第 1 款

导航电子地图在公开出版、销售、传播、展示和使用前，必须进行空间位置技术处理。

• GB 20263-2006《导航电子地图安全处理技术基本要求》4.1

安装

通过 npm 安装：

npm install gcoord

或者直接在页面中通过 script 标签引入浏览器全局构建：

<script src="https://unpkg.com/[email protected]/dist/gcoord.global.prod.js"></script>

通过 script 标签引入时，请始终指定精确的包版本号。

引入

CommonJS：

const gcoord = require('gcoord');

ES Module：

import gcoord from 'gcoord';

浏览器全局变量：

window.gcoord.transform([116.403988, 39.914266], gcoord.WGS84, gcoord.BD09);

使用

例如，从手机 GPS 得到一个经纬度坐标后，如果需要将它展示在百度地图上，应当将坐标从 WGS-84 转换为 BD-09：

const result = gcoord.transform(
  [116.403988, 39.914266], // 坐标：[经度，纬度]
  gcoord.WGS84, // 源坐标系
  gcoord.BD09, // 目标坐标系
);

console.log(result); // [116.41661560068297, 39.92196580126834]

gcoord 也可以转换 GeoJSON 对象中的坐标。详细用法见 API。

API

transform(input, from, to)

将坐标从一个 CRS 转换到另一个 CRS。

参数

• input GeoJSON | string | Array<number>：GeoJSON 对象、GeoJSON 字符串或坐标数组。
• from CRS：源坐标系。
• to CRS：目标坐标系。

返回值

GeoJSON | Array<number>

示例

// 将 GCJ-02 坐标转换为 WGS-84 坐标。
const result = gcoord.transform([123, 45], gcoord.GCJ02, gcoord.WGS84);
console.log(result); // [122.99395597, 44.99804071]

// 转换 GeoJSON 对象中的坐标。
const geojson = {
  type: 'Point',
  coordinates: [123, 45],
};

gcoord.transform(geojson, gcoord.GCJ02, gcoord.WGS84);
console.log(geojson.coordinates); // [122.99395597, 44.99804071]

返回值类型与输入类型一致。注意：当输入为 GeoJSON 对象时，transform 会原地修改输入对象。

CRS

支持以下坐标系：

CRS	坐标格式	说明
gcoord.WGS84	[lng, lat]	WGS-84，GPS 设备获取的经纬度坐标。
gcoord.GCJ02	[lng, lat]	GCJ-02，高德地图、Google 中国地图、搜搜地图、阿里云地图和 MapABC 使用的经纬度坐标。
gcoord.BD09	[lng, lat]	BD-09，百度地图采用的经纬度坐标。
gcoord.BD09LL	[lng, lat]	BD-09 的别名。
gcoord.BD09MC	[x, y]	BD-09 米制坐标，百度地图采用的米制坐标，单位：米。
gcoord.BD09Meter	[x, y]	BD09MC 的别名。
gcoord.Baidu	[lng, lat]	BD-09 的别名。
gcoord.BMap	[lng, lat]	BD-09 的别名。
gcoord.AMap	[lng, lat]	GCJ-02 的别名。
gcoord.WebMercator	[x, y]	Web Mercator 投影，EPSG3857 的别名，单位：米。
gcoord.WGS1984	[lng, lat]	WGS-84 的别名。
gcoord.EPSG4326	[lng, lat]	WGS-84 的别名。
gcoord.EPSG3857	[x, y]	Web Mercator 投影，单位：米。
gcoord.EPSG900913	[x, y]	Web Mercator 的别名。

开发

npm ci
npm run lint
npm run typecheck
npm test
npm run build

项目使用 tsup 构建，使用 vitest 测试，发布产物会输出到 dist/。

支持更多坐标系？

gcoord 的目标是处理 Web 地图中的常见坐标系。目前支持的坐标系已经能满足大多数 Web 地图场景，同时可以保持包体积足够轻量。如果需要更专业的坐标系处理工具，可以使用 proj4js 等开源库。

许可证

MIT