# @12-apps/routing 中文文档

规范地址：https://npmcn.com/package/%4012-apps/routing/

版本：1\.5\.1
npm 元数据更新时间：2026-11-07T06:15:48.223Z
中文译文更新时间：2026-11-07T06:16:59.004Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%4012-apps/routing
原文对照：https://npmcn.com/package/%4012-apps/routing/?lang=original
项目主页：https://github.com/12-apps/shared-packages#readme
源码仓库：https://github.com/12-apps/shared-packages

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

- 包体积（解压后）：127 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，maplibre-gl \>=5\.0\.0，@12-apps/wiring \>=1\.17\.0
- 首次发布：2026-10-07T08:23:42.945Z
- 最新版本发布：2026-11-07T06:15:47.856Z
- 近 30 天下载量：31232（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

路由通过订购的站点列表,由主机配置选择的路由服务(openrouteservice,OSRM,Google Routes,或您自己的适配器),在无人回答时使用直线回落,外加用于网页主机的MapLibre路由图d

## 安装

```sh
npm install @12-apps/routing
```

也可以使用：`pnpm add @12-apps/routing`、`yarn add @12-apps/routing`、`bun add @12-apps/routing`

## README

# @ 12- 应用程序/ 路由

道路路线通过订购的站点清单和绘制它们的地图.

-   **线路服务为配置.** 一个主机列出其提供者 想要,顺序:开路服务,OSRM,Google Routes,或自己的适配器. 计划者保留第一个答案.
-   **总是有一条路.** 当每个供应商都失败时, 出局或不是 配置后, 答案是点之间有正分, 有标记 `fallback: true`它有距离,没有持续时间,因为一个时间计算 由直线 将是一个发明.
-   **地图画的是什么.** `RouteMap` (地图Libre GL, OpenFreeMap 由 默认)使标记、位置、编号的站点、被破解的计划行和 一条坚固的行走线 它一无所获,每个字和颜色都来了 从东道.

## 服务器

```ts
import { createApiRouting, openRouteServiceProvider, osrmProvider } from "@12-apps/routing/server";

const routing = createApiRouting({
  providers: [
    openRouteServiceProvider({ apiKey: secrets.ROUTING_ORS_API_KEY }),
    osrmProvider({ baseUrl: secrets.ROUTING_OSRM_URL }),
  ],
  timeoutMs: 6_000,
  authorize: (actor) => actor.canPlanRoutes,
});

// In-process (a job that saves a trip's route):
const route = await routing.planRoute({ origin: shop, stops: [a, b], returnTo: shop });
// route.geometry, route.legs[i].durationS (null on fallback), route.provider, route.fallback

// Or mount `routing.routes` (one POST /route) behind your own router.
```

计划者保留它给出的停止命令; 排序停止是宿主的 任务。 它从不给供货商惹麻烦 它会扔 `RouteRequestError` 仅限 对于无法被路由的请求( 超过两点, 或无效) 点或 0,0),对于列出两次的提供者.

### 添加提供者

执行 `RoutingProvider`数字 :

```ts
const myProvider: RoutingProvider = {
  name: "my-service",
  async route(request, { fetch, signal }) {
    // …call the service with `fetch` and `signal`…
    return { ok: true, geometry, legs }; // or { ok: false, kind: "http", status }
  },
};
```

入为宿主名相. 没有什么变化.

### 谷歌路线

Google 的地图平台术语不允许其路由内容在 非谷歌地图。 不列出 `googleRoutesProvider` 如果你画与 `RouteMap` 在 OpenFreeMap 或其他任何非 Google 基图之上 .

## 网页

```tsx
import { createWebRouting, ROUTE_MAP_COPY } from "@12-apps/routing/react";

const { RouteMap } = createWebRouting({
  copy: ROUTE_MAP_COPY["pt-BR"],
  theme: { planned, travelled, done, next, pending, ink, paper, place, control, controlBorder },
});

<RouteMap
  height={480}
  markers={couriers.map((c) => ({ id: c.id, position: c.point, text: c.initials, ariaLabel: c.label, color: c.color, onSelect: () => select(c.id) }))}
  places={[{ id: "shop", position: shop, label: "Loja" }]}
  stops={stops}
  planned={route?.geometry}
  travelled={fixes}
  fitKey={tenantSlug}
/>;
```

-   `travelledParts` 将固态线绘制为相隔的下划线( 一条有 不能用直线来弥补的缺口;它胜过 `travelled`。 。 。 .
-   `maplibre-gl` 是可选的对等依赖:在网络主机中安装它. 它是第一次导入地图,所以没有地图的页面永远不会 下载它.
-   地图符合其内容一次,只有在 `fitKey` 变化或 适切控制按下键 。 一个数据刷新 永远不会移动一个地图 某人平板.
-   在屏幕上重叠的标记折叠成一个分组按钮. `onGroupSelect` 获得他们的id。如果没有回话,地图将放大.
-   `focus={{ key, points }}` 恰好符合这些点数(选定之行) 任何时候 `key` 变化——取景者选择,永不刷新. `focus={{ key, points, zoom: 16 }}` 以准确的边界为中心 缩放,在同一块地上 `insets` 一个圆形的圆形 积分可能落在框架之外;新的 `zoom` 在相同情况下 `key` 已经 无所事事:一个适合的垫子 孤独地指向几百米 控制清晰,在一张小地图上,它停在了街道上.
-   `insets={{ bottom: legendHeight }}` 告诉合适的主机本身 盖上盖子,所以装好后针 从不降落在传说或被子下.
-   对于一张小地图(一张牌): `placeLabels="at-point"` 绘制一个位置的标签 它的分量,而不是升起一针 `attribution="compact"` 折叠 基础映射信用为打开它的"i".
-   停下来 `emphasized: true` 上面画出银幕 披针; 其他停在他们下面.
-   标记的(或组的)标记——它的药丸和尾巴——除了停止之外的步骤 徽章和地标`tagPlacement="avoid"`,默认值). 接下来 画出、贴合、平板并缩放,保持其目前的一面,同时清晰; 否则它会按照上面的顺序 划出它的第一分线, 下方,右,左(除目前的一侧外,必须用 很少像素,所以一个颤抖的GPS固定 永远不会翻转它, 当每一边都是 被封锁了,最没有遮挡的 一站一站,一站一站 (信使抵达)不算数。 停止,地点和针点永远不会 移动;尾跟随侧面,元素被固定在原地,所以 键盘焦点存活. `tagPlacement="fixed"` 将每个标记保留在上方, 如 在释放之前.
-   **DOM 变化 :** 现在每个标记和组元素都携带 `data-tag-side="above|below|right|left"` (两种模式),所以一个主机的DOM 地图的快照会增加这个属性。 一个主机自己 `loadMapLibre` 伪造 需求 `Marker#setOffset` 用于移动标签.
-   `controls={{ placement: "top-left" }}` 将缩放并匹配列到 其他上角 当主机浮出铬覆盖上右上角时.
-   **一个可拖动的地方 :** `places={[{ id, position, label, draggable: { ariaLabel, onMove, onDrop } }]}` 将取景器拖动的地方变成一针(mouse或一指; MapLibre's 自己的标记拖曳) 或用箭头键的焦点和向后推移( 从缩放 15, 5 m), 50米以下; `stepMetres(zoom)` (原始内容存档于2017-03-25). overse. 主机拥有此位置 : `onMove` 报告每一个动作, `onDrop` 在那里,它和宿主 把位置转回去 元素被保存在移动之间,所以焦点保持. `disabled: true` 持之以去(一出出出出出出出所出出所出所出.
-   **圆和点 :** `circles={[{ id, center, radiusMetres, dashed? }]}` 在地上画出环( 固态和微小地填入) `theme.travelled`,或 冲入 `theme.ink`),当数组改变时重新绘制,所以主机可以 用被拖起的指针来移动中心 重新绘制它的活环;“ 适合所有” 包括 他们. `dots={[{ id, position, filled }]}` 在针下画出小点, 装入 `theme.ink` 或空虚。 既无图又无图层 .
-   **一个地方的颜色,鬼的地方和绳子:** `color` 一个地方充满它 可拖动接头( 上) `theme.travelled`),其标签(结束 `theme.place`或一个 鬼戒和标签(结束) `theme.ink`),例如与东道主的品牌颜色. `ghost: true` 绘制参考位置( 在 针曾是,或将会是) 被打碎的空心戒指 有安静的标签,从来没有 针. `tethers={[{ id, from, to, color? }]}` 在其中绘制稀疏的片段 `theme.ink` 与圆;"适"出出.
-   `copy={{ fitAll: "…" }}` 覆盖一个挂载的表面词; `controls={{ zoomWhenNarrow: true }}` 将缩放按钮保持在600px以下, 隐匿其中; `onZoomChange(zoom)` 报告一次缩放 准备好,每放大后.
-   `controls={{ fitAsText: true }}` 绘制合适的控件作为它的单词 (单位:千美元)`copy.fitAll`)取而代之为角格.
-   `controls={{ onZoomOut }}` 替换缩放控制( 主机) 留下一条街景,供它自己的更宽的地图使用;轮子和捏子仍会缩放.
-   `scaleBar={(metres) => "100 m"}` 绘制缩放栏左下:最长 在地图宽度的四分之一范围内 保持良好的距离(50米.50公里) 每个锅和放大。 一个主机假需求 `getZoom` 财务报告和审定财务报表 `getCenter`。 。 。 .
-   没有WebGL, 一个没有到达的库或样式 `readyTimeoutMs` (默认 15 s),显示 `copy.mapError` 与复试. 该地区 `data-state` 读取 `loading`, (中文(简体) ), `ready` 或者说 `error`。主持人的 `overlay` 实值 在错误显示时隐藏——错误面板带有自己的重试.

## 接线

`./manifest` 声明 `server: ["http"]` 财务报告和审定财务报表 `web: ["surface"]`。 。 。 . `http.create` 实值 `createApiRouting` 财务报告和审定财务报表 `surface.create` 实值 `createWebRouting`。 。 。 .

## 常见问题

### @12-apps/routing 是什么？

路由通过订购的站点列表,由主机配置选择的路由服务\(openrouteservice,OSRM,Google Routes,或您自己的适配器\),在无人回答时使用直线回落,外加用于网页主机的MapLibre路由图d

### 如何安装 @12-apps/routing？

在项目目录运行 npm install @12-apps/routing，或使用 pnpm add / yarn add / bun add。

### @12-apps/routing 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/12-apps\_\_routing 是否存在。

### @12-apps/routing 支持 ESM 还是 CommonJS？

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

### @12-apps/routing 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @12-apps/routing 可以商用吗？

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

### @12-apps/routing 的下载量有多少？

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

### @12-apps/routing 还在维护吗？

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