MaplatCore

关于MaplatCore

mapplatcore是mapplat历史地图/图解地图的核心库 查看器。它用非线性但同胚的方式变换每个映射的坐标 投影，因此地图可以与GPS和精确地图协作 扭曲原始地图图像。在此基础上构建的终端用户查看器是 Maplat;数据创作工具是 MaplatEditor.

mapplatcore是在Apache许可证2.0下开源的（从0.13.2版本开始）。

阅读本文档的日语版本

关键特性

• 具有非线性但同胚的历史地图/图解地图查看器API 坐标变换
• GPS /精确地图协作，不扭曲原始地图图像
• 可插入的基础地图（基于openlayers；可选Mapbox GL JS / mapplibre GL JS） 对于矢量贴图)
• 事件驱动的POI /线/层管理
• 开源（Apache 2.0从0.13.2版开始）——Maplat生态系统的一部分

快速入门

当前版本: 1.2.0． 这个街区是唯一一个 这个存储库携带一个发布版本（ADR-0012）；外面的一切都是 针对1.0版本编写的。 npm: @maplat/core

安装

# pnpm (recommended)
pnpm add @maplat/core

# npm
npm install @maplat/core

最小的使用

import { MaplatApp } from '@maplat/core';
import 'ol/ol.css'; // REQUIRED: OpenLayers CSS

const option = {
  startFrom: 'gsi',
};

MaplatApp.createObject(option).then((app) => {
  console.log('Maplat initialized', app);
});

CDN (jsDelivr)

要在浏览器中直接使用而不需要绑定器，你必须加载OpenLayers 加载mapplatcore之前。

<!-- OpenLayers -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10/ol.css">
<script src="https://cdn.jsdelivr.net/npm/ol@10/dist/ol.js"></script>

<!-- MaplatCore -->
<script src="https://cdn.jsdelivr.net/npm/@maplat/[email protected]/dist/maplat_core.umd.js"></script>

<div id="map_div"></div>
<script>
  var option = {
    startFrom: 'gsi',
    div: 'map_div',
  };
  MaplatApp.createObject(option).then(function (app) {
    console.log('Maplat initialized', app);
  });
</script>

注意：请确保使用最新的兼容版本。

POI规格(setting.pois）

这个 pois 地图/应用设置的字段接受几种历史形式。所有 现有表单继续工作不变（向后兼容）。一个新的 层 裁判(包装) 添加表单是为了让应用重写每层的表示 （hide / title / icon / selectedIcon)，而不编辑图层 FeatureCollection。

覆盖语义:

• 只有四个覆盖键被尊重。未知的键是 掉在地上 console.warn （无投掷，向前兼容）。
• hide: true （布尔值仅为true）集合 cluster.hide = true. hide:false / 非布尔值被忽略（保留数据端值）。
• title （非空字符串，或非空本地化对象）映射到 cluster.name.
• icon / selectedIcon （非空字符串）映射到 cluster.icon / cluster.selectedIcon.
• 覆盖 赢了 FeatureCollection.properties 同名同姓。
• 内部群集密钥(pois / id / namespaceID / __nextId)不可能 从包装器覆盖（它们不是覆盖键）。
• 输入对象是 不突变.

看到 src/normalize_pois.ts （isPoiLayerRef， PoiLayerRef)。 程序化的表面。

署名及授权(attr / dataAttr）

地图元数据将归属和许可作为两个独立的对：一个 为 地图图像 它本身，还有一个 数据 (控制点，poi， 以及其他衍生数据)。把它们分开很重要，因为扫描地图 在此基础上建立的地理参考数据通常来自不同的地区 版权持有者。

attr / dataAttr 接受一个本地化的对象，这样信用额度就可以有所不同 每个观众的语言； license / dataLicense 是普通字符串。它们不是 枚举-库存储并呈现给定的任何字符串。在 实践中使用了两个常规值：

• "ODbL" - ODbL（开放数据库许可证）
• "Custom" -自定义许可，实际条款写入 licenseNote / dataLicenseNote

捆绑的基础地图 src/source_ex.ts 展示两种惯例 声明为 attr: "©︎ OpenStreetMap contributors" 与 license: "Custom" 和 dataLicense: "ODbL"，而GSI基础图使用 "Custom" 两者都有 将条款拼出来 licenseNote.

在UI中选择这些值是创作工具的关注点（如mapplateditor）； mapplatcore只定义字段的含义并呈现结果。

从贴图缓存中排除映射(noCache）

当 MaplatApp 开始于 enableCache: true (一个 MaplatApp 选项), 每个贴图都注册到Service Worker的贴图缓存（weiwui）中。一幅地图 谁的背景 noCache: true 是 不 注册，所以它的瓷砖总是 从网络和 getMapCacheEnable(mapID) 返回 false 为它。 没有钥匙，还是有钥匙 noCache: false时，地图将像以前一样被缓存。

• 将其写成一个JSON布尔值。只有 true 排除地图；像这样的字符串 "true" 并没有被当作是真的。
• 它可以写在两个地方：地图主(maps/<mapID>.json)及 的元素 sources 在应用程序设置中。当两者都有app元素时 赢得(如。 noCache: false 在app中，元素被取消 noCache: true 在 掌握地图)。
• 作为字符串编写的源代码(捆绑的基本映射，例如 "osm" 或者 "gsi"） 不能携带 noCache． 把它写成对象形式： { "mapID": "osm", "noCache": true }.
• 已经缓存的磁贴不会通过设置来删除 noCache． 一次 Map被排除，它不再注册，所以 clearMapTileCacheAsync(mapID) 没有什么可以作为它的行动；使用命令清除缓存 clearMapTileCacheAsync(mapID) 之前 把 noCache 打开。

生命周期

• 看到 文档/ ui-core-lifecycle.md 的生命周期 phase和uihook(该文档位于mapplat查看器存储库中 生命周期与 @maplat/ui）。

API参考

• API签名 (release-dependent):明白了 docs/api/
• 概念性指南 （release-independent）：参见 Wiki api参考

开发

设置

克隆存储库并安装依赖项。

git clone https://github.com/code4history/MaplatCore.git
cd MaplatCore
pnpm install

开发服务器

使用热重新加载启动开发服务器。

pnpm dev

构建

pnpm build        # Build npm package (dist/)
pnpm build:demo   # Build demo application (dist-demo/)

测试

pnpm test         # Run unit tests (Vitest)
pnpm typecheck    # Run type checks (TypeScript)
pnpm lint         # Run linter and formatter (ESLint/Prettier)
pnpm run test:e2e # Run E2E tests (Playwright)

先决条件

Node.js遵循GitHub Actions test.yml 矩阵;PNPM遵循 engines 场 package.json (adr - 0012: release-dependent)。

• Node.js: v22或v24（通过GitHub Actions测试）
• 规划: >=9.0.0 (要求; package.json 实施规划)

同行依赖性

mapplatcore依赖于以下库作为对等依赖项。你必须 手动安装。

• OpenLayers (ol） - - - - - - ^9.0.0 || ^10.0.0 (必需的；对等依赖的 MaplatCore和Maplat @maplat/ui）

pnpm add ol

如果你使用矢量贴图，你可能还需要Mapbox GL JS或mapplibre GL JS：

• mapbox-gl： ^2.0.0 || ^3.0.0 (可选)
• maplibre-gl： ^5.0.0 || ^6.0.0 (可选)

生态系统

MaplatCore是Maplat生态系统的一部分 历史代码. 查看完整的生态系统地图（8个存储库+产品/企业网站）：

📖 生态系统图 - - - - - - (该图目前保存在一个私人规划中 库;下面的姊妹存储库表是公共替代品)

妹妹存储库

mapplateditor是用于创建地图和poi的数据创作工具 上面的观众渲染。Maplat生态系统是端到端的： 作者与mapplateditor，服务于任何查看器库。

链接

ADR-0013: apache许可的存储库（这个）链接到两个站点。 麻省理工学院授权的姊妹reppos （Weiwudi / Quyuan / chui）没有Nayuta链接。

许可证

Apache License 2.0 -参见 许可证.

Copyright 2019-2026 Kohei Otsuka, Code for History / Nayuta, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

专利的通知： Maplat坐标变换技术获得专利 日本（专利号：6684776）。

过去的版本： 0.13.2之前的版本在 Maplat有限许可1.1。license恢复到Apache 2.0需要 1.0.0-rc1版本生效。早期版本可在npmjs.com上获得 保持在原始的有限许可条款下。