@geolonia/embed

中文文档
6.0.1发布于 2026/11/12MITTypeScriptCommonJS构建来源已验证近 30 天下载 3477

Geolonia 嵌入了JS API

中文使用文档
文档目录13 节
  1. 特征
  2. 实例
  3. 使用量
  4. 使用 npm(用于React, Next.js, Astro, Fresh等)
  5. 内容安全政策
  6. 使用没有 API 密钥的外部样式
  7. 发展
  8. 所需资源
  9. 如何建设
  10. 依赖性更新
  11. 运行组合分析器
  12. 快照测试
  13. 准备

@geolonia/内嵌

build

JS为Geolonia服务安装了API.

特征

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

实例

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

使用量

指定 .geolonia 分类.

<!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>

或者说

<!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 方案使用的切入点.

npm install @geolonia/embed
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 的主机样式和瓷砖时需要.

<!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的发售:

<!-- 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) (中文(简体) ). 明确设定以强制使用语言:

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

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

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

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

捐款

发展

所需资源

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

如何建设

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

$ git clone [email protected]: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保留 lockfile 单个 YAML 文档 .

亲手检查:

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

运行组合分析器

$ pnpm run analyze

快照测试

准备

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

版本与发布记录

@geolonia/embed 共发布 146 个版本,首次发布于 2019/12/13;过去 12 个月发布了 12 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
6.0.1latest2026/11/124 天前
6.0.02026/11/114 天前
6.0.0-pre.6next2026/10/3017 天前
6.0.0-pre.52026/10/151 个月前
6.0.0-pre.42026/10/051 个月前
6.0.0-pre.32026/08/073 个月前

关于 @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 和提交记录判断。