MapLibre GL JS第54课：用本地字体样式化标签

原创于 2026-06-17 09:05:12 发布 · 234 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#javascript #Maplibre GL JS #Mapbox #GIS #地图

MapLibre GL JS教程专栏收录该内容

56 篇文章

订阅专栏

📌 学习目标

掌握用本地字体样式化标签的实现方法
理解相关API的使用
能够独立完成类似功能开发

🎯 核心概念

将本地字体应用到样式的文本标签。

💻 完整代码

代码示例

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Style labels with local fonts</title>
    <meta property="og:description" content="将本地字体应用到样式的文本标签。此选项适用于您不需要每个用户都看到完全相同的字体，或者如果您避免依赖第三方内容交付网络（CDN）。为了最大兼容性，text-font属性应包含多个平台上找到的常见字体。">
    <meta property="og:created" content="2025-10-31" />
    <meta charset='utf-8'>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel='stylesheet' href='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css'>
    <script src='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js'></script>
    <style>
        body { margin: 0; padding: 0; }
        html, body, #map { height: 100%; }
    </style>
</head>
<body>
<div id="map"></div>
<script>
    const map = new maplibregl.Map({
        container: 'map',
        zoom: 9,
        center: [137.9150899566626, 36.25956997955441],
        style: {
            "version": 8,
            "sources": {
                "satellite": {
                    "type": "raster",
                    "tiles": [
                        "https://tiles.maps.eox.at/wmts/1.0.0/s2cloudless-2020_3857/default/g/{z}/{y}/{x}.jpg"
                    ],
                    "tileSize": 256
                },
                "places": {
                    "type": "geojson",
                    "data": {
                        "type": "FeatureCollection",
                        "features": [
                            {
                                "type": "Feature",
                                "properties": {
                                    "name": "安曇野市"
                                },
                                "geometry": {
                                    "type": "Point",
                                    "coordinates": [137.9054972, 36.3044083]
                                }
                            },
                            {
                                "type": "Feature",
                                "properties": {
                                    "name": "松本市"
                                },
                                "geometry": {
                                    "type": "Point",
                                    "coordinates": [137.9687141, 36.2382047]
                                }
                            }
                        ]
                    }
                }
            },
            "layers": [
                {
                    "id": "satellite",
                    "type": "raster",
                    "source": "satellite"
                },
                {
                    "id": "places",
                    "type": "symbol",
                    "source": "places",
                    "layout": {
                        "text-font": ["Hiragino Mincho ProN", "Noto Serif CJK JP", "MS Mincho"],
                        "text-size": 24,
                        "text-field": ["get", "name"]
                    },
                    "paint": {
                        "text-color": "white"
                    }
                }
            ]
        }
    });
</script>
</body>
</html>

🔍 代码解析

1. 初始化地图

使用 new maplibregl.Map() 创建地图实例，配置卫星影像底图和GeoJSON点数据源，展示日本松本市和安曇野市的位置标签。

2. 关键配置项

text-font: 指定本地字体数组 ["Hiragino Mincho ProN", "Noto Serif CJK JP", "MS Mincho"]，按优先级排列
text-field: 使用表达式获取地名属性
text-color: 设置为白色，确保在卫星底图上清晰可见

⚙️ 参数说明

参数	类型	必填	说明
text-font	array	是	本地字体名称数组，按优先级顺序排列
text-size	number	是	标签字体大小（像素）
text-field	expression	是	定义标签显示内容的表达式
text-color	string	否	标签颜色，默认黑色

🎨 效果说明

在这里插入图片描述

运行代码后，地图显示日本松本市区域的卫星影像底图，在两个标记点上显示日文地名标签（安曇野市、松本市）。字体使用用户系统中可用的日文字体，实现本地化显示效果。

💡 常见问题

Q1: 本地字体不显示怎么办？
A: 本地字体依赖用户系统中已安装的字体，检查以下几点：

确认字体名称拼写正确
在text-font数组中提供多个备选字体
检查用户系统是否安装了指定字体

Q2: 如何确保跨平台兼容性？
A: 在text-font数组中包含各平台常见字体：

macOS: Hiragino系列
Windows: MS系列
Linux/Android: Noto系列

Q3: 中文标签显示为方框怎么办？
A: 添加中文字体到text-font数组：

"text-font": ["PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC"]

📝 练习任务

基础练习：添加中文地名标签，配置中文字体回退链
进阶挑战：创建支持多语言标签的图层，根据语言属性选择不同字体
拓展思考：如何检测用户系统可用字体并动态选择最佳字体？
综合实践：为不同地区创建字体配置文件，实现本地化显示

🌟 最佳实践

字体回退链: 在text-font数组中按优先级排列多个平台的常见字体
避免CDN依赖: 使用本地字体无需依赖第三方CDN，提高加载速度
多语言支持: 根据标签语言属性动态选择合适字体
字体测试: 在不同操作系统和设备上测试字体显示效果
性能优化: 本地字体无需网络请求，减少加载时间和带宽消耗

🔗 延伸阅读

Map API文档
MapLibre GL JS 官方文档
[下一课预告]：将继续学习地图图层的基础知识