# @americana/maplibre-shield-generator 中文文档 规范地址：https://npmcn.com/package/%40americana/maplibre-shield-generator/ 版本：0\.1\.1 npm 元数据更新时间：2025-07-23T23:18:58.218Z 中文译文更新时间：2026-11-06T01:20:20.818Z 软件包许可：CC0-1\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40americana/maplibre-shield-generator 原文对照：https://npmcn.com/package/%40americana/maplibre-shield-generator/?lang=original 项目主页：https://github.com/osm-americana/openstreetmap-americana#readme 源码仓库：https://github.com/osm-americana/openstreetmap-americana ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.5 MB，58 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：4 个 - 首次发布：2023-03-26T01:39:10.265Z - 最新版本发布：2025-07-23T23:18:57.980Z - 近 30 天下载量：7253（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：29（近 12 个月 0 个） ## 中文简介 生成地图libre-gl-js地图的高速公路盾牌 ## 安装 ```sh npm install @americana/maplibre-shield-generator ``` 也可以使用：`pnpm add @americana/maplibre-shield-generator`、`yarn add @americana/maplibre-shield-generator`、`bun add @americana/maplibre-shield-generator` ## README # 美国盾牌设计师 Americana 盾牌制造器是一个图书库,旨在绘制公路盾牌 [映射- gl- js](https://github.com/maplibre/maplibre-gl-js) 矢量平面图 . ![Pictoral highway shields](https://wiki.openstreetmap.org/w/images/6/6d/Rendered_shields_americana.png) ## 盾牌渲染工作流程 铸造盾牌需要下列通配: 1 1. **在矢量牌片中编码屏蔽信息**首先,你的地砖必须包含信息 告诉盾牌制造者要画什么盾牌。 在 OpenMapTiles 中, 屏蔽信息在 [`transportation_name`](https://openmaptiles.org/schema/#transportation_name) 有一系列属性的矢量平面 `route_1`, (中文(简体) ), `route_2`等 (中文(简体) ). 每个属性都包含一个文本字符串,包含决定要显示的图形所需的全部信息,包括如果屏蔽被编号的话的数字路由号. 然而,这个库允许您指定盾牌信息是如何被编码的,在编码盾牌数据时可以将多个字段的数据相接. 2. **以样式层显示屏蔽信息**。接下来,必须使用 [图像](https://maplibre.org/maplibre-gl-js-docs/style-spec/expressions/#types-image) 在包含路由信息的结构字符串中。 例如,您可以将95号州际公路编码为命名的图像 `shield|US:I=95`。通常,图像表达式是用来指向在图示工作表中预先指定的图示的,但是在这种情况下,我们指的是一个不存在的图示,叫做: `shield|US:I=95`这将触发 `styleimagemissing` 事件允许盾牌渲染器在苍蝇上创建所需的图形。 作为如何编码屏蔽信息的例子,参见OSM Americana's [`highway_shield`](https://github.com/osm-americana/openstreetmap-americana/blob/main/src/layer/highway_shield.js) 样式层. 3. **定义描述路由信息如何被编码的解析器**。路径定义有三个部分: 1. 这个 `network` 字符串,它定义了具有共同屏蔽形状、图形和颜色的网络 2. 这个 `ref` 字符串,它定义了应该绘制在屏蔽图形上方的文本序列 3. 这个 `name` 字符串,它定义了一个名称,与参考文献分开,用于确定要绘制的图形 ```typescript let routeParser = { //format is `shield|${network}=${ref}|${name}` parse: (id: string) => { let id_parts = id.split("|"); let network_ref = id_parts[1].split("="); return { network: network_ref[0], ref: network_ref[1], name: id_parts[2], }; }, format: (network: string, ref: string, name: string) => `shield|${network}=${ref}|${name}`, }; ``` 4. **(可选) 创建可定义将处理哪些盾牌的上游**。例如,如果您样式中的所有图示标识都需要从字符串开始 `shield|`这看起来像: ```typescript let shieldPredicate = (imageID: string) => imageID.startsWith("shield"); ``` 如果所有未处理的图像ID都是盾牌,此步骤可以跳过. 此外,您可以指定要处理的网络 。 下面的例子忽略了所有 `nwn`, (中文(简体) ), `lwn`, (中文(简体) ), `ncn`等网络值 : ```typescript let networkPredicate = (network: string) => !/^[lrni][chimpw]n$/.test(network); ``` 5. **创建屏蔽定义和艺术品**。盾牌定义用JSON文件表示,并附有一套包含用于盾牌的任何光栅艺术图案。 它可以作为对象生成,也可以作为由URL访问的JSON文件主机. 下一节介绍如何创建这一定义. 6. **将屏蔽生成器连接到映射- gl- js 映射**。通过 JSON 盾牌定义的 URL ,或者在 javascript 代码中创建对象。 每种方法有两种不同的类别. ```typescript new URLShieldRenderer("shields.json", routeParser) .filterImageID(shieldPredicate) .filterNetwork(networkPredicate) .renderOnMaplibreGL(map); ``` ```typescript new ShieldRenderer(shields, routeParser) .filterImageID(shieldPredicate) .filterNetwork(networkPredicate) .renderOnMaplibreGL(map); ``` ## 盾牌定义 屏蔽定义的目的是定义您想要显示的每个网络/ref/名称组合要绘制的图形和文字. 这可以在javascript中作为对象创建,也可以作为HTTP-accessable JSON文件创建. 这一说明采用下列公约: - A 类 **网络** 是一个带有一条 _通用图形显示_. 每条路线的外观可能有所不同,例如路由编号不同,或下文所述的特例定义. 网络值在概念上对应 OpenStreetMap [网络标签](https://wiki.openstreetmap.org/wiki/Key:network)。 。 。 . - A 类 **参考** 包含要绘制在盾牌艺术品上的案文。 对应值在概念中对应 OpenStreetMap [参考标记](https://wiki.openstreetmap.org/wiki/Key:ref)。 。 。 . 结构如下: ```json { "options": { "bannerHeight": 9, "bannerPadding": 1, "bannerTextColor": "black", "bannerTextHaloColor": "white", "shieldFont": "'Noto Sans Condensed', sans-serif-condensed, 'Arial Narrow', sans-serif", "shieldSize": 20 }, "default": { ...definition }, "network_1": { ...definition }, "network_2": { ...definition }, "network_3": { ...definition } } ``` 选项块包含适用于所有屏蔽绘图的全球参数: - **`bannerHeight`**: 每个文本横幅的高度 - **`bannerPadding`**: 在每个横幅之间铺设 - **`bannerTextColor`**: 在屏蔽上方绘制文本横幅的颜色 - **`bannerTextHaloColor`**: 颜色以绘制文本横幅的大纲 - **`shieldFont`**: 命令用于屏蔽文字和横幅的字体列表. 此工程默认使用 Noto Sans Condensed, 主机为可下载的网页字体 [另一个仓库](https://github.com/osm-americana/web-fonts)。 。 。 . - **`shieldSize`**: 1x像素中用于盾牌的"标准"尺寸. 但是,有些盾牌可能存在分歧,例如,所画出取出钻石盾牌的尺寸稍大一些,以便与平面相近. 您应该为每个网络创建一个定义项 。 条目密钥必须匹配编码 `network` 价值准确。 "默认"网络定义了在没有特定网络定义的情况下应该绘制什么. 网络可包含以下参数的任何组合: ```json { "textColor": "black", "textHaloColor": "white", "padding": { "left": 3, "right": 3, "top": 3, "bottom": 3 }, "spriteBlank": ["name_of_image_2", "name_of_image_3", "name_of_image_4"], "noref": { "spriteBlank": "name_of_image_noref" } "shapeBlank": { "drawFunc": "pentagon", "params": { "pointUp": false, "yOffset": 5, "sideAngle": 0, "fillColor": "white", "strokeColor": "black", "radius1": 2, "radius2": 2 } }, "banners": ["ALT"], "bannerMap": { "ThisNetwork:Truck": ["TRK"], "ThisNetwork:Truck:Bypass": ["TRK", "BYP"] }, "bannerTextColor": "#000", "bannerTextHaloColor": "#FFF", "textLayout": { "constraintFunc": "roundedRect", "options": { "radius": 2 } }, "colorLighten": "#006747", "overrideByRef": { "REF": { "spriteBlank": "special_case_image", "textColor": "#003f87", "colorLighten": "#003f87" } }, "refsByName": { "Audubon Parkway": "AU" }, "overrideByName": { "Merritt Parkway": { "spriteBlank": "shield_us_ct_parkway_merritt" } } } ``` ### 盾牌财产说明 - **`textColor`**: 确定绘制颜色 `ref` 在盾牌上. - **`textHaloColor`**颜色来画一个击倒光环 `ref` 语句. - **`padding`**: 围绕 `ref`,可以将文本挤入盾牌内较小的空间. - **`spriteBlank`**:在图示工作表中指定要用作屏蔽背景的图像名称。 如果对不同的宽度有多个选项,这可以是单个字符串,也可以是数组字符串. - 若为 `spriteBlank` 是一系列字符串,它们必须从最窄到最宽的顺序,文件名必须被连续的整数范围所后缀,代表每个图标中要显示的最佳字符数. - **`noref`**: 指定在无时应用的替代属性 `ref` 提供。 这使得您可以使用一个数字路由的图形,和一个单独的非数字路由的图形。 支助 **`spriteBlank`**, (中文(简体) ), **`colorLighten`**,以及 **`colorDarken`**。 。 。 . - **`shapeBlank`**:指定盾牌应被绘制为共同的形状(矩形,椭圆形,五角形等),并指定颜色和尺寸. 见 [绘制的盾形](https://npmcn.com/package/%40americana/maplibre-shield-generator/#readme-defining-drawn-shield-shapes) 可选绘图选项. - **`banners`**:指定在屏蔽上方绘制一个或多个短文本字符串(最多4个字符). 这被指定为数组,文本将按从上到下顺序绘制。 下面是旗下盾牌上最多有三条旗子的例子: ![Bannered routes near Downington, PA](https://wiki.openstreetmap.org/w/images/f/f8/Downington_bannered_routes_Americana.png) - **`bannerMap`**:网络到屏风阵列的地图,列出应该具有相同风格但有指定横幅的网络. - **`bannerTextColor`**:指定横幅文字的颜色. - **`bannerTextHaloColor`**:指定旗下击倒光环的颜色. - **`textLayout`**: 具体说明应如何将文本刻入盾牌的加法界限。 文本将按此限制允许的最大大小绘制 。 见 [文本布局函数](https://npmcn.com/package/%40americana/maplibre-shield-generator/#readme-text-layout-functions) 用于文本布局选项. - **`colorLighten`**: 指定盾牌艺术品应被指定的颜色所淡出(多出). 这意味着黑色区域会以这种颜色被重新染色,而白色区域保持不变. 阿尔法值将保持不变. - **`colorDarken`**: 指定盾牌艺术品被指定的颜色所暗化. 这意味着白色区域会以这种颜色再作颜色,而黑色区域则保持不变. 阿尔法值将保持不变. - **`overrideByRef`**:指定特定 `ref` 内 `network` 应具有不同于网络中其他路径的屏蔽属性,每个特例一个条目 `ref`。支持的选项是: **`spriteBlank`**, (中文(简体) ), **`textColor`**,以及 **`colorLighten`**。 。 。 . - **`refsByName`**: 指定 a `name` 与指定的密钥一起应视为 `ref` 带有指定值. - **`ref`**: 指定该网络中的所有盾牌应同指定的盾牌一起绘制 `ref` 数值. - **`overrideByName`**:具体说明该特定 `name` 应使用特定的 **`spriteBlank`** 这不同于其他网络. ### 处理特殊案件网络 盾牌规格允许处理特例. 例如,在OSM Americana,我们想为美国制造特殊盾牌 [肯塔基州公园道系统](https://en.wikipedia.org/wiki/List_of_parkways_and_named_highways_in_Kentucky)这个网络使用了一套特别丑陋的盾牌 看起来像这样 ![Western Kentucky Parkway shield](https://upload.wikimedia.org/wikipedia/en/d/db/Western_Kentucky_Parkway_fair_use.svg) 美国队想画出一系列盾牌,这些盾牌使用双字母代码来代表每个公园道,这样它就会像这样: ![Kentucky parkways](https://wiki.openstreetmap.org/w/images/d/da/Kentucky_parkway_Americana.png) 然而,这两个字母代码实际上并没有用作盾牌上的路由编号,所以不宜在"盾牌"上加上 `ref=*` 标记在 OpenStreetMap 中。 相反,团队使用 `refsByName` 属性,然后定义每个指定路由网的双字母代码如下: ```json "US:KY:Parkway": { "spriteBlank":"shield_us_ky_parkway", "textColor":"#003f87", "padding": { "left":2, "right":2, "top":2, "bottom":6 }, "refsByName": { "Audubon Parkway":"AU", "Bluegrass Parkway":"BG", "Bluegrass Pkwy":"BG", "Cumberland Parkway":"LN", "Cumberland Pkwy":"LN", "Hal Rogers Parkway":"HR", "Hal Rogers Pkwy":"HR", "Mountain Parkway":"MP", "Mountain Pkwy":"MP", "Purchase Parkway":"JC", "Purchase Pkwy":"JC", "Western Kentucky Parkway":"WK", "Western Kentucky Pkwy":"WK" } }, ``` 另一个特例是当一个网络中选择的路线需要采用不同的样式. 譬如说, [格鲁吉亚国道520](https://en.wikipedia.org/wiki/Georgia_State_Route_520) 以绿色盾牌签署,而乔治亚州高速公路的默认颜色为黑色. 以下盾牌组装显示与格鲁吉亚国道两种风格的相交点和相通点: ![Georgia Route 520](https://upload.wikimedia.org/wikipedia/commons/4/4f/GA_green_route_concurrency.png) 这种效果可以通过在路由定义中将文字和图示颜色压倒如下来实现. 对于多个特例裁判,增加多个条目. ```json "US:GA": { "spriteBlank": ["shield_us_ga_2", "shield_us_ga_3"], "textColor": "black", "overrideByRef": { "520": { "textColor": "#006747", "colorLighten": "#006747" } } } ``` 在这个例子中 `shield_us_ga_...` 斯匹克空白代表了乔治亚州国道盾牌的狭长而宽的版本,并被用白色填充的颜色为黑色. 其结果如下: ![Georgia State Route 520 Concurrency](https://wiki.openstreetmap.org/w/images/0/0b/Columbs_georgia_concurrency.png) 最后,最后一个特例是当 _名称_ 网络中的路由需要与网络中的其他路由不同的屏蔽. 例如,康涅狄格州的Merrit Parkway在OSM被标记为 `network=US:CT:Parkway` + 键 `name=Merritt Parkway`。康涅狄格州还有另外两条公园通道 标记相同。 然而,只有梅里特公园道有盾牌. 因此,我们可以界定 `US:CT:Parkway` 作为空定义,但命名的路由除外 `Merritt Parkway`数字 : ```json "US:CT:Parkway": { "overrideByName" : { "Merritt Parkway": { "spriteBlank": "shield_us_ct_parkway_merritt", }, } } ``` 以下片段显示了梅里特公园道(与CT-15同时进行)结束和威尔伯十字公园道(名称但无盾牌)开始的结果: ![Merritt Parkway Shield](https://wiki.openstreetmap.org/w/images/3/37/Ct_parkway_shield.png) ### 文本布局函数 根据具体规定,案文被置于盾牌上 `textLayout` 数值。 文本将被绘制、测量和扩展,直到它被打入文本布局限制的边缘。 例如,一个 `ellipse` 约束会填充一个像这样的外加式盾牌, 由中央取出并扩展到椭圆: ![Ellipse constraint](https://upload.wikimedia.org/wikipedia/commons/7/72/Ellipse_constraint.png) 并不是所有的限制都由中心指定。 例如 `southHalfEllipse` 限制将从盾牌上方扩大如下: ![South half-ellipse constraint](https://upload.wikimedia.org/wikipedia/commons/6/62/South_half-ellipse_constraint.png) 得到支持的案文限制如下: - `diamond` - `ellipse` - `rect` - `roundedRect` - `southHalfEllipse` - `triangleDown` ### 定义已绘制的盾形 若为 `shapeBlank` 中,盾将绘制为形状。 需要用绘图函数指定 , `drawFunc` (单位:千美元) `params` 屏蔽描述如何绘制形状。 绘图功能如下: | | `drawFunc` | | --- | --- | | ![](https://upload.wikimedia.org/wikipedia/commons/c/cf/Diamond_highway_shield_shape.svg) | `diamond` | | ![](https://upload.wikimedia.org/wikipedia/commons/3/30/Black_and_white_circle_shape_as_used_in_highway_shields.svg) | `ellipse` | | ![](https://upload.wikimedia.org/wikipedia/commons/7/75/Escutcheon_highway_shield_shape.svg) | `escutcheon` | | ![](https://upload.wikimedia.org/wikipedia/commons/f/f8/Fishhead_highway_shield_shape.svg) | `fishhead` | | ![](https://upload.wikimedia.org/wikipedia/commons/6/61/Hexagon_highway_shield_shape.svg) | `hexagonVertical` | | ![](https://upload.wikimedia.org/wikipedia/commons/2/25/Horizontal_hexagon_shape.svg) | `hexagonHorizontal` | | ![](https://upload.wikimedia.org/wikipedia/commons/f/f8/Octagon_shield_shape.svg) | `octagonVertical` | | ![](https://upload.wikimedia.org/wikipedia/commons/f/ff/Pentagon_shield_shape.svg)![](https://upload.wikimedia.org/wikipedia/commons/b/b0/Black_and_white_home_plate_shape_as_used_in_highway_shields.svg) | `pentagon` | | ![](https://upload.wikimedia.org/wikipedia/commons/archive/1/17/20230326013156%21Pill_shape.svg) | `pill` | | ![](https://upload.wikimedia.org/wikipedia/commons/3/30/Black_and_white_circle_shape_as_used_in_highway_shields.svg)![](https://upload.wikimedia.org/wikipedia/commons/archive/a/a1/20230326013519%21Rounded_rectangle_shape.svg) | `roundedRectangle` | | ![](https://upload.wikimedia.org/wikipedia/commons/a/ad/Black_and_white_downward_trapezoid_as_used_in_highway_shields.svg)![](https://upload.wikimedia.org/wikipedia/commons/5/56/Black_and_white_upward_trapezoid_as_used_in_highway_shields.svg) | `trapezoid` | | ![](https://upload.wikimedia.org/wikipedia/commons/a/ad/Downward_triangle_highway_shield_shape.svg) | `triangle` | 以下内容: `params` 可指定选项: - `sideAngle` - 表示边边缘偏离垂直的角度(以度为单位)。 适用于 `trapezoid`, (中文(简体) ), `pentagon`, (中文(简体) ), `hexagonHorizontal`, (中文(简体) ), `octagonVertical`。 。 。 . - `fill` - 指定内部填充颜色. - `yOffset` - 表示高度(以像素计),其中下端和/或上端边缘偏离了水平。 适用于 `escutcheon`, (中文(简体) ), `pentagon`, (中文(简体) ), `hexagonVertical`, (中文(简体) ), `octagonVertical`。 。 。 . - `outline` - 指定大纲颜色. - `outlineWidth` - 指定大纲的宽度. - `pointUp` - 适用于若干形状类型,并具体说明尖面是否上升. - `radius` - 指定圆半径,以像素表示,用于角. - `radius1` - 五角形正边角半径(默认为2) - `radius2` - 五角形平面的角半径(默认为0) - `shortSideUp` - 为 `trapezoid` 指定短边是上还是下. ### 自定义屏蔽图形 除了股票绘图功能,还可以指定自定义绘图功能. `paDot` 财务报告和审定财务报表 `branson` 作为例子列入,用于提供 [阿列根尼县皮带系统](https://en.wikipedia.org/wiki/Allegheny_County_belt_system) 还有布兰森,密苏里州彩色路线系统 见文件 `src/custom_shields.mjs` 举个例子说明如何做到这一点. ## 文档 见 [TypeDoc 生成文档](https://americanamap.org/shield-docs/index.html) 详细API信息. ## 常见问题 ### @americana/maplibre-shield-generator 是什么？ 生成地图libre-gl-js地图的高速公路盾牌 ### 如何安装 @americana/maplibre-shield-generator？ 在项目目录运行 npm install @americana/maplibre-shield-generator，或使用 pnpm add / yarn add / bun add。 ### @americana/maplibre-shield-generator 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/americana\_\_maplibre-shield-generator 是否存在。 ### @americana/maplibre-shield-generator 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @americana/maplibre-shield-generator 可以商用吗？ @americana/maplibre-shield-generator 使用 CC0-1\.0 许可。作者放弃著作权，可不受限制地使用。以上为概括，不构成法律意见，请以许可原文为准。 ### @americana/maplibre-shield-generator 的下载量有多少？ 根据 npm 官方下载统计，@americana/maplibre-shield-generator 在 2026/10/06 – 2026/11/04 这 30 天内被下载 7,253 次，日均约 242 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @americana/maplibre-shield-generator 还在维护吗？ 最新版本 0\.1\.1 发布于 2025/07/24（1\.3 年前）；至今共发布 29 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/03/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。