# @maplat/ui 中文文档
规范地址：https://npmcn.com/package/%40maplat/ui/
版本：1\.2\.0
npm 元数据更新时间：2026-11-01T18:25:59.776Z
中文译文更新时间：2026-11-01T19:51:34.446Z
软件包许可：Apache-2\.0
本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40maplat/ui
原文对照：https://npmcn.com/package/%40maplat/ui/?lang=original
项目主页：https://github.com/code4history/Maplat/wiki
源码仓库：https://github.com/code4history/Maplat
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：7.2 MB，113 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：16 个
- peer 依赖：ol ^9\.0\.0 \|\| ^10\.0\.0，mapbox-gl ^2\.0\.0 \|\| ^3\.0\.0，maplibre-gl ^5\.0\.0 \|\| ^6\.0\.0
- 首次发布：2019-09-15T23:09:56.336Z
- 最新版本发布：2026-11-01T18:25:59.405Z
- 已发布版本数：52（近 12 个月 21 个）
## 中文简介
Maplat是一个很酷的历史地图/插图地图查看器。 它可以用非线性但同纯投影变换每个地图坐标，使地图可以与GPS/精确地图协作，而不会扭曲原始地图。
## 安装
```sh
npm install @maplat/ui
```
也可以使用：`pnpm add @maplat/ui`、`yarn add @maplat/ui`、`bun add @maplat/ui`
## README
# Maplat
[](https://github.com/code4history/Maplat/actions/workflows/ci.yml) [](https://npmcn.com/package/%40maplat/ui/LICENSE)
## 关于Maplat
Maplat是一个很酷的历史地图/插图地图查看器。 它可以用非线性但同胚的方式变换每个映射的坐标 投影，它可以让地图与GPS和精确地图协作，而不需要 扭曲原始地图图像。 配套的数据编辑器作为另一个项目提供， [MaplatEditor](https://github.com/code4history/MaplatEditor/). 该项目获得特等奖/教育效果奖/参观奖 国土资源部地质活动竞赛2018优秀奖； 基础设施、交通和旅游。
Maplat是在Apache许可证2.0下开源的（从0.12.2版本开始）。
**[阅读本文档的日语版本](https://npmcn.com/package/%40maplat/ui/README.ja.md)**
## 关键特性
- 具有非线性但同胚坐标变换的历史地图/图解地图查看器
- GPS /精确地图协作，不扭曲原始地图图像
- 可插入的基础地图（基于openlayers；矢量贴图可选Mapbox GL JS / mapplibre GL JS）
- PWA-ready应用程序shell （manifest、Service Worker、share、URL state）
- 查看器UI支持11种语言：英语、日语、德语、西班牙语、 法语、印尼语、韩语、泰语、越南语、中文（简体）和 中文(繁体)
- 开源（Apache 2.0从0.12.2版本开始），带有配套的桌面编辑器（MaplatEditor）
## 快速入门
> **当前版本: `1.2.0`**． 这个街区是唯一一个 这个存储库携带一个发布版本（ADR-0012）；外面的一切都是 针对1.0版本编写的。 npm: [`@maplat/ui`](https://www.npmjs.com/package/@maplat/ui) [](https://www.npmjs.com/package/@maplat/ui)
### 安装
```bash
# pnpm (recommended)
pnpm add @maplat/ui
# npm
npm install @maplat/ui
```
### 最小的使用
```typescript
import { MaplatUi } from '@maplat/ui';
import '@maplat/ui/dist/maplat_ui.css'; // Import styles
const option = {
appid: 'myMark',
// ...
};
MaplatUi.createObject(option).then(app => {
// Application initialized
});
```
### CDN (jsDelivr)
要在浏览器中直接使用而不需要绑定器，你必须加载OpenLayers 加载mapplat UI之前。Maplat Core是捆绑的，所以你不需要加载它 分开。
```html
```
_注意：请确保使用最新的兼容版本。_
### POI规格(`setting.pois`）
mapplat UI传递 `pois` 一个应用程序/地图设置的字段直接到 `MaplatApp.createObject`，所以这里接受MaplatCore接受的所有表单 不变。指向POI数据的常用方法有：
- **URL字符串** - - - - - - `"pois/landmarks.geojson"`，初始化时获取
- **Map-embedded POI** -内联 `FeatureCollection` 直接写在 设置
- **Layer ref （wrapper）** - - - - - - `{ layer: , hide?, title?, icon?, selectedIcon? }`，它引用一个层并只覆盖它的 此应用程序的演示文稿，而无需编辑引用的文件
可接受表单的完整列表、重写优先级和用于的规则 未知密钥在mapplatcore中记录一次；看到 [POI规格(`setting.pois`）](https://github.com/code4history/MaplatCore#poi-specification-settingpois) 在mapplatcore README中。
### 生命周期
- 看到 [文档/ ui-core-lifecycle.md](https://npmcn.com/package/%40maplat/ui/docs/ui-core-lifecycle.md) 生命周期阶段和uihook。
### API参考
- **API签名** (release-dependent):明白了 [`docs/api/`](https://npmcn.com/package/%40maplat/ui/docs/api/)
- **概念性指南** （release-independent）：参见 [Wiki api参考](https://github.com/code4history/Maplat/wiki/API-Reference)
### 开发
#### 设置
克隆存储库并安装依赖项。
```bash
git clone https://github.com/code4history/Maplat.git
cd Maplat
pnpm install
```
#### 开发服务器
使用热重新加载启动开发服务器。
```bash
pnpm dev
```
访问 `http://localhost:5173/` 在浏览器中。
#### 构建
```bash
pnpm build # Build npm package (dist/)
pnpm build:demo # Build demo application (dist-demo/)
```
#### 测试
```bash
pnpm test # Run tests (Vitest)
pnpm typecheck # Run type checks (TypeScript)
pnpm lint # Run linter and formatter (ESLint/Prettier)
```
## 先决条件
> 源自 `engines` 场 `package.json` (adr - 0012: release-dependent)。
- Node.js: v20或v22（通过GitHub Actions进行LTS测试）
- 规划: `>=9.0.0` (要求; `package.json` 实施规划)
## 同行依赖性
mapplat UI依赖于以下库作为对等依赖项。你必须 手动安装。
- **OpenLayers (`ol`）** - - - - - - `^9.0.0 || ^10.0.0` (Maplat的对等依赖 `@maplat/ui` 和MaplatCore `@maplat/core`）
```bash
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`
## 生态系统
Maplat是Maplat生态系统的一部分 [历史代码](https://github.com/code4history). 查看完整的生态系统地图（8个存储库+产品/企业网站）：
📖 **生态系统图** - - - - - - _(该图目前保存在一个私人规划中 库;下面的姊妹存储库表是公共替代品)_
### 妹妹存储库
| 存储库 | 许可证 | npm | 角色 |
| --- | --- | --- | --- |
| [Maplat](https://github.com/code4history/Maplat) | Apache 2.0 | `@maplat/ui` | 主要查看器 |
| [MaplatCore](https://github.com/code4history/MaplatCore) | Apache 2.0 | `@maplat/core` | 核心库 |
| [MaplatTin](https://github.com/code4history/MaplatTin) | Apache 2.0 | `@maplat/tin` | 锡转换 |
| [MaplatTransform](https://github.com/code4history/MaplatTransform) | Apache 2.0 | `@maplat/transform` | 坐标变换 |
| [MaplatEditor](https://github.com/code4history/MaplatEditor) | Apache 2.0 | \- - - - - - | 数据创作工具（桌面） |
| [楚辞](https://github.com/code4history/Chuci) | 麻省理工学院 | `@c4h/chuci` | 多媒体滑动器和查看器Web组件 |
| [屈原](https://github.com/code4history/Quyuan) | 麻省理工学院 | `@c4h/quyuan` | GeoJSON模板引擎+多媒体浏览器Web组件 |
| [Weiwudi](https://github.com/code4history/Weiwudi) | 麻省理工学院 | `@c4h/weiwudi` | Service Worker用于tile缓存 |
> mapplateditor是用于创建地图和poi的数据创作工具 上面的观众渲染。Maplat生态系统是端到端的： 作者与mapplateditor，服务于任何查看器库。
## 链接
| 观众 | 链接 | 目的 |
| --- | --- | --- |
| 项目信息/功能/案例 | [https://www.maplat.jp/en/](https://www.maplat.jp/en/) | 产品网站 |
| 赞助商/业务查询 | [https://www.nayuta-inc.co.jp/en/](https://www.nayuta-inc.co.jp/en/) | 公司网站（Nayuta, Inc.） |
> ADR-0013: apache许可的存储库（这个）链接到两个站点。 麻省理工学院授权的姊妹reppos （Weiwudi / Quyuan / chui）没有Nayuta链接。
## 许可证
Apache License 2.0 -参见 [许可证](https://npmcn.com/package/%40maplat/ui/LICENSE).
```
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.12.2之前的版本在 Maplat有限许可1.1。license恢复到Apache 2.0需要 1.0.0-rc1版本生效。早期版本可在npmjs.com上获得 保持在原始的有限许可条款下。
## 贡献者
这个项目的存在要感谢所有做出贡献的人。 [](https://github.com/code4history/Maplat/graphs/contributors)
## 赞助商
支持Maplat [](https://www.locazing.com/) [](https://www.thedesignium.com/) [](https://www.browserstack.com/) [](https://zender.co.jp/) [](https://www.webimpact.co.jp/)
感谢我们所有的支持者！🙏\[[成为支持者](https://opencollective.com/maplat#backer)］ [](https://opencollective.com/maplat#backers)
通过成为赞助者来支持这个项目。您的标志将显示在这里与链接到您的网站。［[成为赞助商](https://opencollective.com/maplat#sponsor)］
## 常见问题
### @maplat/ui 是什么？
Maplat是一个很酷的历史地图/插图地图查看器。 它可以用非线性但同纯投影变换每个地图坐标，使地图可以与GPS/精确地图协作，而不会扭曲原始地图。
### 如何安装 @maplat/ui？
在项目目录运行 npm install @maplat/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ol（^9\.0\.0 \|\| ^10\.0\.0）、mapbox-gl（^2\.0\.0 \|\| ^3\.0\.0）、maplibre-gl（^5\.0\.0 \|\| ^6\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @maplat/ui 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @maplat/ui 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @maplat/ui 可以商用吗？
@maplat/ui 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。
### @maplat/ui 还在维护吗？
最新版本 1\.2\.0 发布于 2026/11/02（1 天前）；至今共发布 52 个版本，其中过去 12 个月发布了 21 个；首次发布于 2019/09/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。