# @geolonia/embed 中文文档

规范地址：https://npmcn.com/package/%40geolonia/embed/

版本：6\.0\.1
npm 元数据更新时间：2026-11-12T00:17:31.203Z
中文译文更新时间：2026-11-16T04:36:26.451Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40geolonia/embed
原文对照：https://npmcn.com/package/%40geolonia/embed/?lang=original
项目主页：https://github.com/geolonia/embed#readme
源码仓库：https://github.com/geolonia/embed

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

- 包体积（解压后）：5.7 MB，71 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2019-12-13T10:11:09.516Z
- 最新版本发布：2026-11-12T00:17:30.796Z
- 近 30 天下载量：3477（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：146（近 12 个月 12 个）

## 中文简介

Geolonia 嵌入了JS API

## 安装

```sh
npm install @geolonia/embed
```

也可以使用：`pnpm add @geolonia/embed`、`yarn add @geolonia/embed`、`bun add @geolonia/embed`

## README

# @geolonia/内嵌

[![build](https://github.com/geolonia/embed/actions/workflows/build.yml/badge.svg)](https://github.com/geolonia/embed/actions/workflows/build.yml)

JS为Geolonia服务安装了API.

## 特征

-   webGL 向量映射
-   简单配置
-   地图懒于渲染

## 实例

[https://geolonia.github.io/embed/ 互联网档案馆的存檔,存档日期2013-12-21](https://geolonia.github.io/embed/)

## 使用量

指定 `.geolonia` 分类.

```html
<!DOCTYPE html>
<html>
  <body>
    <div class="geolonia" ...></div>
    <script src="https://cdn.geolonia.com/embed/v5/embed?geolonia-api-key=YOUR-API-KEY"></script>
  </body>
</html>
```

或者说

```html
<!DOCTYPE html>
<html>
  <body>
    <div class="geolonia" data-key="YOUR-API-KEY" ...></div>
    <script src="https://cdn.geolonia.com/embed/v5/embed"></script>
  </body>
</html>
```

### 使用 npm(用于React, Next.js, Astro, Fresh等)

对于现代网络框架,使用 `@geolonia/embed/core` 方案使用的切入点.

```shell
npm install @geolonia/embed
```

```typescript
import { GeoloniaMap, keyring } from "@geolonia/embed/core";

keyring.setApiKey("YOUR-API-KEY");

const map = new GeoloniaMap({
  container: "#map",
  style: "geolonia/gsi",
  center: [139.7671, 35.6812],
  zoom: 14,
});
```

不同于默认 `@geolonia/embed` 进入点, `/core` 已经 **没有** 自动扫描 DOM 或设置 `window.geolonia`这使得在安全部门改革环境中使用安全,避免了在React、Preact和Vue等框架中出现双重初始化问题。 (它只是导入时的副作用是注册被捆绑的 MapLibre 工人,它被跳出浏览器外. )

### 内容安全政策

`@geolonia/embed` 因此MapLibre工人被嵌入到捆绑中 从一个开始 `blob:` URL (中文(简体) ). 如果您的页面设置了内容安全政策, 请 `blob:` 作为工人来源:

```
Content-Security-Policy: worker-src blob:;
```

### 使用没有 API 密钥的外部样式

您可以使用外部样式. json URLs 没有Geolonia API 键. 这在下列情况下是有用的:

-   使用 OpenStreetMap 日本等开源平板服务器
-   自我接待自己的瓷砖和风格
-   在没有 API 密钥依赖的情况下分发地图

**说明:** Geolonia API 密钥仅在使用 Geolonia 的主机样式和瓷砖时需要.

```html
<!DOCTYPE html>
<html>
  <body>
    <!-- Using OpenStreetMap Japan tiles (no API key needed) -->
    <!-- Note: tile.openstreetmap.jp is for non-commercial use only -->
    <div
      class="geolonia"
      data-lat="35.6812"
      data-lng="139.7671"
      data-zoom="14"
      data-style="https://tile.openstreetmap.jp/styles/osm-bright/style.json"
    ></div>
    <script src="https://cdn.geolonia.com/embed/v5/embed"></script>
  </body>
</html>
```

您也可以使用npm/unpkg/jsDelivr进行自办或CDN的发售:

```html
<!-- Using npm CDN (unpkg) -->
<script src="https://unpkg.com/@geolonia/embed@latest/dist/embed.js"></script>

<!-- Using jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@geolonia/embed@latest/dist/embed.js"></script>
```

#### 数据样式属性

这个 `data-style` 属性接受 :

-   **Geolonia 样式名称**数字 : `geolonia/basic`, (中文(简体) ), `geolonia/gsi` (需要 API 密钥)
-   **完整 URL 语句**数字 : `https://example.com/style.json`
-   **相对路径**数字 : `./custom-style.json`, (中文(简体) ), `/styles/my-style.json`
-   **文件结束于.json**: 自动解析为绝对 URL

#### 数据长属性

这个 `data-lang` 属性控制地图标签的语言 :

-   `ja` ——日本标签
-   `en` (或任何其他非日文价值)-英文标签
-   `auto` ——遵循浏览器语言(`navigator.languages`(中文(简体) )
-   **删除** - 与 `auto` (遵循浏览器语言)

仅 `ja` 编号 : `ja-jp` 解决日语问题; 所有其他价值解决英语问题.

**重要内容:** 当两个 `data-lang` 也没有 `lang` 时,语言遵循浏览器设置。 在非日文浏览器上,它会装入英文样式(`en.json`) (中文(简体) ). 明确设定以强制使用语言:

```html
<div class="geolonia" data-lang="ja" ...></div>
```

使用 JavaScript API 时 (`new GeoloniaMap({...})`,通过 `lang` 选项中,而不是 `data-lang` 属性 :

```ts
const map = new GeoloniaMap({ container: "#map", lang: "ja" });
```

可以在 [https://geolonia.github.io/embed/ 互联网档案馆的存檔,存档日期2013-12-21](https://geolonia.github.io/embed/)。 。 。 .

# 捐款

## 发展

### 所需资源

-   节点.js >= 22.22.2 (按 `jsdom` 30个; `.tool-versions` 标出最新的22.x)

### 如何建设

这个项目使用 [小时](https://pnpm.io/)。该版本被固定在两个地方,必须保留 同步编辑: `packageManager` 领域 `package.json` (使用时间: [核心软件包](https://nodejs.org/api/corepack.html) 由 `pnpm/action-setup` )和 `.tool-versions` (使用时间: [资产f](https://asdf-vm.com/) 财务报告和审定财务报表 [爱](https://mise.jdx.dev/)) (中文(简体) ). `pnpm-workspace.yaml` 套装 `pmOnFail: ignore`,所以pnpm本身不会纠正不匹配 `build` 工作流程比较了两个指针,如果有分歧则失败.

```shell
$ git clone git@github.com:geolonia/embed.git
$ cd embed
$ pnpm install
$ pnpm start # run dev server
$ pnpm test # run tests
$ pnpm run e2e # run e2e tests (run `pnpm run build` first to include the production-bundle test)
$ pnpm run build # build production bundle
```

那你可以看见了 `http://localhost:3000/`。 。 。 .

## 依赖性更新

依附关系由Dependabot更新,配置于 `.github/dependabot.yml`。小和补丁 更新以一个分组式的每周公关到达。 目前主要版本的更新被忽略——有一个 但任何版本的安全更新信息都到齐了, 主要包括,因为 `ignore` 打开 `version-update:semver-major` 只有范围版本更新.

`pnpm-workspace.yaml` 套装 `pmOnFail: ignore`,该线是负载的:没有它pnpm 12 写入 `pnpm-lock.yaml` 作为两个YAML文档,GitHub的依赖图解读器只读取 第一个(只持有 pnpm 本身),没有 npm 软件包到达图形——所以没有 视星等警报上升 见 `pnpm-workspace.yaml` 财务报告和审定财务报表 [函数核心 # 15904](https://github.com/dependabot/dependabot-core/issues/15904)保留 lockfile 单个 YAML 文档 .

亲手检查:

```shell
$ pnpm audit            # vulnerabilities
$ pnpm outdated         # available updates
$ pnpm why maplibre-gl  # who pulls a package in
```

## 运行组合分析器

```shell
$ pnpm run analyze
```

## 快照测试

### 准备

```shell
$ cp .envrc.sample .envrc
$ vi .envrc
$ pnpm run build
$ docker build . -t geolonia/embed
```

## 常见问题

### @geolonia/embed 是什么？

Geolonia 嵌入了JS API

### 如何安装 @geolonia/embed？

在项目目录运行 npm install @geolonia/embed，或使用 pnpm add / yarn add / bun add。

### @geolonia/embed 支持 TypeScript 吗？

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

### @geolonia/embed 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @geolonia/embed 可以商用吗？

@geolonia/embed 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @geolonia/embed 的下载量有多少？

根据 npm 官方下载统计，@geolonia/embed 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,477 次，日均约 116 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @geolonia/embed 还在维护吗？

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

