MapLibre GL JS第52课：显示和样式化富文本标签

最新推荐文章于 2026-06-16 20:43:31 发布

原创最新推荐文章于 2026-06-16 20:43:31 发布 · 272 阅读

5 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#javascript #GeoAI #GIS #Map #Mapbox

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

56 篇文章

订阅专栏

📌 学习目标

掌握显示和样式化富文本标签的实现方法
理解相关API的使用
能够独立完成类似功能开发

🎯 核心概念

显示和样式化富文本标签。

💻 完整代码

代码示例

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Display and style rich text labels</title>
    <meta property="og:description" content="使用 format 表达式以英文和当地语言显示国家标签。" />
    <meta property="og:created" content="2023-06-27" />
    <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>
<!-- The lang attribute is read from the map container if present, otherwise from the HTML document -->
<div id="map" lang="zh-HK"></div>
<script>
    maplibregl.setRTLTextPlugin(
        'https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.3.0/dist/mapbox-gl-rtl-text.js'
    );

    const map = new maplibregl.Map({
        container: 'map', // 容器ID
        style: 'https://tiles.openfreemap.org/styles/bright', // 样式URL
        center: [17.49, 40.01], // 初始位置 [经度, 纬度]
        zoom: 4 // 初始缩放级别
    });

    map.on('load', () => {
        map.setLayoutProperty('label_country', 'text-field', [
            'format',
            ['get', 'name_en'],
            {'font-scale': 1.2},
            '\n',
            {},
            ['get', 'name'],
            {
                'font-scale': 0.8,
                'text-font': [
                    'literal',
                    ['Noto Sans Regular']
                ]
            }
        ]);
    });
</script>
</body>
</html>

🔍 代码解析

初始化地图

使用 new maplibregl.Map() 创建地图实例，配置基本参数。本示例的核心特色是展示如何使用 format 表达式创建富文本标签，同时显示英文和当地语言名称。

加载 RTL 插件

maplibregl.setRTLTextPlugin(
    'https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.3.0/dist/mapbox-gl-rtl-text.js'
);

关键配置项

container: 地图容器的 DOM 元素 ID
style: 使用 OpenStreetMap 亮色样式 https://tiles.openfreemap.org/styles/bright
center: 地图初始中心点 [17.49, 40.01]（巴尔干半岛区域）
zoom: 初始缩放级别为 4，显示区域级别视图

format 表达式配置

map.setLayoutProperty('label_country', 'text-field', [
    'format',
    ['get', 'name_en'],      // 第一部分：英文名称
    {'font-scale': 1.2},     // 英文名称样式：放大1.2倍
    '\n',                    // 换行符
    {},                      // 换行符不需要样式
    ['get', 'name'],         // 第二部分：当地语言名称
    {
        'font-scale': 0.8,   // 当地语言样式：缩小0.8倍
        'text-font': ['literal', ['Noto Sans Regular']]
    }
]);

⚙️ 参数说明

参数	类型	必填	默认值	说明
container	string	是	-	地图容器元素的 ID
style	string/object	是	-	地图样式 URL 或内联样式对象
center	[number, number]	否	`[0, 0]`	初始中心点坐标
zoom	number	否	`0`	初始缩放级别

format 表达式

参数	类型	说明
text	expression	要显示的文本内容
options	object	文本样式选项

文本样式选项

属性	类型	说明
font-scale	number	字体缩放比例
text-font	array	字体名称数组
text-color	string	文本颜色
text-halo-color	string	文本光晕颜色
text-halo-width	number	文本光晕宽度

🎨 效果说明

在这里插入图片描述

运行代码后，地图上的国家标签会以双行富文本形式显示：

第一行: 英文名称（放大1.2倍）
第二行: 当地语言名称（缩小0.8倍，使用 Noto Sans 字体）
示例: 国家标签显示为 “Italy” 在上方，意大利文 “Italia” 在下方

视觉效果:

英文名称更大更突出
当地语言名称作为补充信息
支持 RTL（从右到左）语言（如阿拉伯语、希伯来语）

💡 常见问题

Q1: format 表达式是什么？
A: format 表达式允许创建富文本标签，支持多行文本和不同样式的组合。每个文本片段都可以有独立的样式设置。

Q2: 为什么需要 RTL 插件？
A: RTL（Right-to-Left）插件支持从右到左书写的语言，如阿拉伯语、希伯来语等，确保这些语言正确显示。

Q3: 如何添加更多文本样式？
A: 在 format 表达式中添加更多的文本和样式对象对：

['format',
    ['get', 'name'], {'font-scale': 1.2},
    '\n', {},
    ['get', 'capital'], {'font-scale': 0.8, 'text-color': '#888'}
]

Q4: 可以使用哪些字体？
A: 可以使用样式中定义的字体或通过 text-font 属性指定字体。建议使用支持多语言的字体如 Noto Sans。

📝 练习任务

基础练习：修改字体大小比例，调整中英文名称的显示效果
进阶挑战：添加第三行文本显示国家首都
拓展思考：如何根据国家属性动态改变文本颜色？

🌟 最佳实践

字体选择: 使用支持多语言的字体（如 Noto Sans）确保各种语言正确显示
样式层次: 主文本使用较大字体，辅助信息使用较小字体
RTL 支持: 加载 RTL 插件支持从右到左的语言
性能考虑: 避免过多的文本样式组合，影响渲染性能
可读性: 确保文本颜色与背景有足够对比度
语言属性: 使用 lang 属性帮助浏览器正确处理文本方向

🔗 延伸阅读

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