📌 学习目标
- 掌握显示和样式化富文本标签的实现方法
- 理解相关API的使用
- 能够独立完成类似功能开发
🎯 核心概念
显示和样式化富文本标签。
💻 完 整 代 码
代码示例
<!DOCTYPEhtml><htmllang="en"><head><title>Display and style rich text labels</title><metaproperty="og:description"content="使用 format 表达式以英文和当地语言显示国家标签。"/><metaproperty="og:created"content="2023-06-27"/><metacharset='utf-8'><metaname="viewport"content="width=device-width, initial-scale=1"><linkrel='stylesheet'href='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css'/><scriptsrc='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 --><divid="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');constmap=newmaplibregl.Map({container:'map',// 容器IDstyle:'https://tiles.openfreemap.org/styles/bright',// 样式URLcenter:[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 官方文档
[下一课预告]：将继续学习地图图层的基础知识