# @file-viewer/renderer-geo 中文文档

规范地址：https://npmcn.com/package/%40file-viewer/renderer-geo/

版本：3\.3\.3
npm 元数据更新时间：2026-10-31T11:16:25.563Z
中文译文更新时间：2026-11-14T17:42:25.837Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40file-viewer/renderer-geo
原文对照：https://npmcn.com/package/%40file-viewer/renderer-geo/?lang=original
项目主页：https://doc.file-viewer.app/guide/on-demand-renderers
源码仓库：https://github.com/flyfish-dev/file-viewer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：621 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-06-23T06:25:59.409Z
- 最新版本发布：2026-10-31T11:16:25.183Z
- 近 30 天下载量：34950（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 57 个）

## 中文简介

用于文件查看器的独立地理空间渲染器插件,有GeoJSON,KML,GPX,SHP解析,CRS正常化,MapLibre重叠渲染,SVG倒置等功能,以及离线方便的懒惰加载.

## 安装

```sh
npm install @file-viewer/renderer-geo
```

也可以使用：`pnpm add @file-viewer/renderer-geo`、`yarn add @file-viewer/renderer-geo`、`bun add @file-viewer/renderer-geo`

## README

# @file-viewer/renderer-geo

[English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/geo/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/geo/README.zh-CN.md)

Flyfish File Viewer 的独立地理数据 renderer 包。它负责 GeoJSON、KML、GPX 和 Shapefile 的浏览器端预览，并让 `@tmcw/togeojson`、`shpjs`、`maplibre-gl`、`proj4` 只在命中地理数据格式时加载。

## 使用

```ts
import { geoRenderer } from '@file-viewer/renderer-geo'

const options = {
  builtinRenderers: 'none',
  renderers: [geoRenderer],
}
```

也可以通过全量 preset 自动装配：

```ts
import { allRenderers } from '@file-viewer/preset-all'

const options = {
  builtinRenderers: 'none',
  renderers: allRenderers,
}
```

## 能力

-   GeoJSON 直接读取 `FeatureCollection`、`Feature` 或单个 geometry。
-   KML / GPX 只在命中格式时按需加载 `@tmcw/togeojson`，转换为统一 GeoJSON 管线。
-   SHP / Shapefile 只在命中格式时按需加载 `shpjs`，支持常见 ZIP 或二进制 Shapefile 数据转 GeoJSON。
-   默认使用离线 MapLibre 空底图渲染点、线、面叠加层，支持平移、缩放和适配范围；显式配置后可叠加公网、内网或离线自托管瓦片底图。
-   支持 GeoJSON `crs` 元数据、`options.geo.projection` 显式坐标系、Web Mercator 自动推断，以及 `EPSG:4326`、`EPSG:3857`、`EPSG:4490`、`GCJ02`、`BD09` 和 proj4 字符串转换到 WGS84。
-   WebGL 或 MapLibre 初始化失败时自动回退 SVG 矢量预览，适合内网部署和附件快速审阅。
-   卸载时清理 DOM 资源，和 core 的生命周期、导出 HTML、缩放能力保持一致。

## 坐标系选项

```ts
const options = {
  renderers: [geoRenderer],
  geo: {
    projection: 'EPSG:3857',
    inferProjection: true,
    fitPadding: 48,
  },
}
```

标准 GeoJSON 默认按 WGS84 读取。如果业务导出没有写 `crs`，但坐标是 Web Mercator，默认会自动推断；GCJ-02 / BD-09 这类非 EPSG 坐标建议通过 `options.geo.projection` 显式声明。

## 底图和瓦片选项

Geo renderer 默认不访问公网。需要真实底图时，可以选择公开 MapLibre style、自托管 style，或简单 raster XYZ/TMS 瓦片模板：

```ts
const options = {
  renderers: [geoRenderer],
  geo: {
    // 国际化开源底图，适合 demo 或轻量在线场景；生产建议按需自托管或镜像到内网/国内 CDN。
    basemap: 'openfreemap-liberty',
  },
}
```

```ts
const options = {
  renderers: [geoRenderer],
  geo: {
    // 最简单的 raster 瓦片入口，可指向公网、内网网关、对象存储或本地静态目录。
    tileUrl: '/tiles/world/{z}/{x}/{y}.png',
  },
}
```

```ts
const options = {
  renderers: [geoRenderer],
  geo: {
    basemap: {
      type: 'vector-style',
      label: 'Intranet OpenMapTiles',
      styleUrl: '/maps/styles/liberty/style.json',
    },
  },
}
```

天地图需要使用在天地图控制台为部署域名申请的 token。内置 preset 会同时加载对应的底图和中文注记图层：

```ts
const options = {
  renderers: [geoRenderer],
  geo: {
    basemap: 'tianditu-vector', // 也支持 tianditu-imagery / tianditu-terrain
    tiandituToken: import.meta.env.VITE_TIANDITU_TOKEN,
  },
}
```

需要隐藏注记时可使用对象形式：`basemap: { type: 'tianditu', token, mapStyle: 'imagery', labels: false }`。组件不会内置、保存或代理 token；未提供 token 时会安全回退到离线空底图。

内置 preset 包含 `openfreemap-liberty`、`openfreemap-bright`、`openfreemap-positron`、`openfreemap-dark`、`openfreemap-fiord`、显式 opt-in 的 `osm-raster`，以及需要调用方 token 的 `tianditu-vector`、`tianditu-imagery`、`tianditu-terrain`。`osm-raster` 只建议用于 demo 或低频访问，生产环境请遵守 OpenStreetMap 官方 tile policy，配置可替换 URL、缓存和正确 attribution。中国大陆也可以把 OpenFreeMap / OpenMapTiles 栈自托管到内网或国内 CDN，再通过 `styleUrl` 或 `tileUrl` 接入。

## 迁移说明

`@file-viewer/core` 已不再内置 geo renderer，也不会默认安装 `@tmcw/togeojson` 和 `shpjs`。需要 GeoJSON / KML / GPX / SHP 预览时，请显式安装本包，或直接使用 `@file-viewer/preset-all` 聚合能力。

## 常见问题

### @file-viewer/renderer-geo 是什么？

用于文件查看器的独立地理空间渲染器插件,有GeoJSON,KML,GPX,SHP解析,CRS正常化,MapLibre重叠渲染,SVG倒置等功能,以及离线方便的懒惰加载\.

### 如何安装 @file-viewer/renderer-geo？

在项目目录运行 npm install @file-viewer/renderer-geo，或使用 pnpm add / yarn add / bun add。

### @file-viewer/renderer-geo 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @file-viewer/renderer-geo 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @file-viewer/renderer-geo 可以商用吗？

@file-viewer/renderer-geo 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @file-viewer/renderer-geo 的下载量有多少？

根据 npm 官方下载统计，@file-viewer/renderer-geo 在 2026/10/15 – 2026/11/13 这 30 天内被下载 34,950 次，日均约 1,165 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @file-viewer/renderer-geo 还在维护吗？

最新版本 3\.3\.3 发布于 2026/10/31（14 天前）；至今共发布 57 个版本，其中过去 12 个月发布了 57 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。