字体与图标库

字体库与图标库为地图样式提供中文字体和自定义图标。同一套字体与图标同时用于两种渲染方式：服务端出图（SLD 样式）与浏览器端的 MapLibre 渲染。

字体库

能做什么

• 在控制台「制图资源 → 字体库」查看平台字体、输入任意文字预览效果。
• 为 MapLibre 提供字形：样式里写平台的字形地址和字体名即可显示中文标注。
• 为服务端出图提供字体：SLD 里写字体的字族名即可。
• 缺字自动回退：字体缺某个字时，自动用平台预装的字体补上（中文 Noto Sans SC、拉丁文 Noto Sans、阿拉伯文 Noto Sans Arabic），标注不会整体消失，也不会显示成方框。MapLibre 的字形与服务端出图都会回退。

权限

字体是平台级资源，所有工作空间共用：

• 所有登录用户可以查看字体列表、详情与预览。
• 上传、编辑、停用与删除仅限管理员。在线系统中如需新字体，请联系平台管理员。
• 预装字体只读，可以停用，不能删除。

字形按字体名公开。 MapLibre 取字形的地址不需要登录，知道字体名的人都能取到字形（不含字体文件本身）。请不要上传保密或未获授权的字体，字体的授权由上传者负责。

上传规则（管理员）

在字体库点「上传字体」，选择 .ttf、.otf、.ttc 文件或 .zip 包（可多选；不能直接拖入文件夹，请先打成 zip）。选好后先预览：逐项列出字体名、字族、风格、覆盖范围与状态（新增 / 替换 / 跳过 / 拒绝）；确认后点「登记」才写入。

• 重名处理：字体名已存在时可选「跳过同名字体」（默认）、「覆盖同名字体」或「自动改名」（加数字后缀）。
• 字体名取自字体文件内部的名称，上传后不能改；不能含 , / ? # % \ ; 等字符。
• 限制：单个字体文件不超过 64 MB；一次上传合计不超过 200 MB；zip 最多 200 个条目、解压后不超过 256 MB；同一时间只处理一个上传。
• 会被拒绝的字体：既不含基本拉丁字母，也不含常用汉字和阿拉伯字母的；无法解析或试渲染不出内容的。
• 可变字体只使用默认字重。例如某些可变版本的中文字体默认是最细的 Thin，登记后得到的是 Thin，不能当常规体使用。
• 新登记的字体许可记为「未知」，请在详情中改成真实的许可与来源。

在 MapLibre 样式中引用

{
  "version": 8,
  "glyphs": "https://map-demo.geobridge.cn/geobridge-mapserver/fonts/{fontstack}/{range}.pbf",
  "layers": [
    {
      "id": "poi-label",
      "type": "symbol",
      "source": "geobridge",
      "source-layer": "poi",
      "layout": { "text-field": ["get", "name"], "text-font": ["Noto Sans SC Regular"] }
    }
  ]
}

• text-font 写字体栈名称（字体详情里「复制 text-font」），必须与名称完全一致，区分大小写和空格。可以写多个，逐字取第一个含该字的字体；粗体用名称带 Bold 的字体。
• 平台的全部字体栈名称可以从 https://map-demo.geobridge.cn/geobridge-mapserver/fonts.json 查到。
• 只支持基本多文种平面（U+0000–U+FFFF）的字符，部分生僻字没有字形。
• 写了平台中没有的字体名时，该名称被忽略，由回退字体出字。

在 SLD 中引用

<TextSymbolizer>
  <Label><ogc:PropertyName>name</ogc:PropertyName></Label>
  <Font>
    <CssParameter name="font-family">Noto Sans SC</CssParameter>
    <CssParameter name="font-size">12</CssParameter>
    <CssParameter name="font-weight">bold</CssParameter>
  </Font>
</TextSymbolizer>

• font-family 写 SLD 字族名（字体详情里「复制字族名」），如 Noto Sans SC，区分大小写。不要写字体栈名称（Noto Sans SC Regular 在 SLD 中找不到）；粗体、斜体用 font-weight、font-style 表达。
• 服务端出图时，平台在每个标注的字体后面自动追加回退字体：标注里出现所写字体没有的文字（如阿拉伯文）时，这些字符改用回退字体绘制。阿拉伯文、希伯来文等从右到左的文字会按正确的方向排列，并做字母连写。

从右到左的文字（阿拉伯文、希伯来文）

• 服务端出图（地图服务的切片与导出、WMS 等）：不需要额外设置。

• MapLibre 矢量瓦片：浏览器端还需要加载 MapLibre 的 RTL 插件，才能正确排列方向和连写。平台的控制台预览与地图编辑器已经自动加载；在自己的页面里，请在建图前加一行：

  // 插件文件取自 npm 包 @mapbox/mapbox-gl-rtl-text 的 dist/mapbox-gl-rtl-text.js，放到自己的站点上；地址须为绝对地址
  maplibregl.setRTLTextPlugin(new URL('/libs/mapbox-gl-rtl-text.js', location.href).href, true)

  第二个参数 true 表示按需加载：地图上出现从右到左的文字时才下载插件。

生效时间

变更	MapLibre 字形	服务端出图
上传或启用字体	立即	无需重启，很快生效
停用或删除字体	立即	平台重启后才失效
覆盖同名字体	立即	建议重启后再确认

• 浏览器会缓存字形 1 天、字体列表 5 分钟。
• 字体变更不会让已缓存的瓦片失效：需要旧区域立刻使用新字体时，请清除相关服务的瓦片缓存或重新切片。

图标库

能做什么

• 在控制台「制图资源 → 图标库」新建图标集，上传 SVG / PNG 图标、zip 包或整个文件夹，图标按目录自动分组。
• 服务端出图：SLD 的 <ExternalGraphic> 引用图标地址，SVG 图标可以着色。
• MapLibre：每个图标集自动提供雪碧图，样式里写 icon-image: "<图标集>:<图标名>"。
• 平台内置只读的 maki 图标集（Maki 8.2.0，CC0 许可）。
• 替换、改名或删除图标后立即生效，不需要重新发布服务。

概念与权限

• 图标集代码：平台内唯一，格式为 2–40 个小写字母、数字或连字符（如 hk-poi），是图标地址与雪碧图的命名空间，创建后不能修改。maki、default 与以 geobridge 开头的代码保留不可用。
• 图标名：小写字母、数字与连字符，最长 100 个字符，集内唯一。每个图标集最多 2000 个图标。
• 权限按图标集所在的工作空间：读权限可以查看；写权限可以新建、上传、替换、改名、移动分组；管理权限可以删除。设为「公共图标集」（所有人可见）仅限管理员。

图标地址按代码公开。 图标与雪碧图的地址不需要登录，知道图标集代码和图标名的人都能读取。「可见」只影响控制台列表，不是访问控制，请不要放保密图标。

上传规则

在图标集详情点「上传」，可以拖放或选择 .svg、.png、.zip 文件，或选择文件夹。与字体一样先预览再「登记」，重名时可选跳过、覆盖或自动改名（加 -2、-3 后缀）。

• 图标名由文件名转换：转小写，空格、下划线、点号改为 -，去掉其他字符。文件名含中文等非 ASCII 字符时，图标名为 icon- 加 8 位哈希，原文件名作为标题保存并可搜索。想要可读的图标名，请把文件名改成英文或拼音。
• 分组取 zip 内的目录，最多 3 级；所有图标都在同一个顶层目录下时，这一层不算分组。
• 大小：单个图标不超过 512 KB；SVG、PNG 宽高不超过 1024 像素（较大的 SVG 会等比缩小到 1024）。zip 最多 2000 个条目、解压后不超过 50 MB；一次上传合计不超过 60 MB。
• 安全清洗：含脚本、事件属性、外部引用等内容的 SVG 会被拒绝；PNG 会重新编码并去掉元数据。被拒绝的只是单个文件，其余照常登记。

在 SLD 中引用

<ExternalGraphic>
  <OnlineResource xlink:type="simple" xlink:href="https://map-demo.geobridge.cn/geobridge-mapserver/icons/hk-poi/bus-stop.svg?fill=%23FFFFFF"/>
  <Format>image/svg+xml</Format>
</ExternalGraphic>

• 地址为 https://map-demo.geobridge.cn/geobridge-mapserver/icons/<图标集>/<图标名>.svg 或 .png，扩展名必须与图标实际格式一致，<Format> 写 image/svg+xml 或 image/png。
• fill、stroke 参数（写作 %23RRGGBB）为 SVG 着色，PNG 忽略；两个参数同时写时，XML 里的 & 要写成 &。
• Size 为目标高度（像素），SVG 最大 512。不写时用图标自身尺寸，大图标会画得很大，建议总是写 Size。
• 平台按地址路径识别图标，与主机名无关，同一份 SLD 可以在不同环境间复用。图标不存在时退回默认符号，不会让整张图出错。

在 MapLibre 中引用

{
  "sprite": [
    { "id": "default", "url": "https://example.com/tiles/sprite" },
    { "id": "hk-poi", "url": "https://map-demo.geobridge.cn/geobridge-mapserver/sprites/hk-poi/sprite" }
  ],
  "layers": [
    {
      "id": "poi",
      "type": "symbol",
      "source": "geobridge",
      "source-layer": "poi",
      "layout": { "icon-image": "hk-poi:bus-stop", "icon-size": 1.2 }
    }
  ]
}

• 用多雪碧图写法：平台图标集的条目 id 就是图标集代码，icon-image 写 图标集:图标名；default 条目中的图标仍用不带前缀的名称。
• 地图方案可以在「底图方案」的方案菜单「图标集…」中勾选图标集，保存时自动写好 sprite，不改动样式中原有的雪碧图条目。
• 雪碧图中单个图标最大 64 像素，并提供 2 倍图；图标集很大（约 960 个以上的大图标）时，2 倍图会退回 1 倍图，高分屏上略糊。
• 雪碧图保持图标原色，不支持着色。

生效时间

• 上传、改名、移动分组、删除后立即生效，不需要重启或重新发布。
• 浏览器缓存用户图标与雪碧图 300 秒，内置图标 1 天。
• 地图编辑器会缓存雪碧图：上传或修改图标后请刷新编辑器页面。
• 已缓存的瓦片不会自动更新：需要旧区域立刻显示新图标时，请清除相关服务的瓦片缓存或重新切片。
• 图标改名或删除后，样式中的旧引用不会自动更新，出图时退回默认符号。