mapbox-style-quality

Mapbox 样式质量技能

此技能提供专业指导，帮助你借助验证、无障碍和优化工具确保 Mapbox 样式质量。

何时使用质量工具

上线前检查清单

将任何 Mapbox 样式部署到生产环境之前：

1. 验证所有表达式——在运行时之前捕获语法错误
2. 检查颜色对比度——确保文本易于阅读（符合 WCAG）
3. 验证 GeoJSON 数据源——确保数据完整性
4. 优化样式——减小文件体积并提升性能
5. 比较版本——了解发生了哪些变化
6. 移除空图层——删除没有可见绘制属性的图层，作为最终清理步骤
7. 简化冗余布尔表达式——清理包含不必要布尔逻辑的筛选条件（例如，["all", expr] → expr，["any", false, expr] → expr）

开发期间

添加 GeoJSON 数据时：

• 使用外部 GeoJSON 作为数据源前，务必先用 validate_geojson_tool 验证

编写表达式时：

• 编写表达式时使用 validate_expression_tool 进行验证
• 尽早捕获类型不匹配问题（例如，对数字使用字符串运算符）
• 确认运算符在你的 Mapbox GL JS 版本中可用
• 使用预期的数据类型测试表达式

设置文本／标签样式时：

• 使用 check_color_contrast_tool 检查前景色与背景色的对比度
• 力求至少达到 WCAG AA 标准（普通文本为 4.5:1，大号文本为 3:1）
• 使用 AAA 标准（普通文本为 7:1），以提升无障碍性
• 考虑不同的背景场景（地图瓦片、叠加层）

提交更改前

比较样式版本：

• 使用 compare_styles_tool 生成差异报告
• 检查所有图层更改、数据源修改和表达式更新
• 了解更改的影响
• 在提交消息中记录重大更改

部署前

优化样式：

• 运行 optimize_style_tool 以减小文件体积
• 移除引用已删除图层的未使用数据源
• 删除属性完全相同的重复图层
• 简化筛选条件中的冗余布尔表达式（例如，将 ["all", expr] 简化为 expr，删除恒真条件）
• 移除空图层（没有可见绘制属性的图层），作为最终清理步骤

验证最佳实践

GeoJSON 验证

以下情况务必进行验证：

• 加载用户上传的 GeoJSON
• 从外部 API 获取 GeoJSON
• 处理来自第三方来源的 GeoJSON
• 在不同数据格式之间进行转换

常见 GeoJSON 错误：

• 坐标范围无效（经度 > 180 或 < -180）
• 多边形环未闭合（首尾坐标必须一致）
• 坐标顺序错误（应为 [经度, 纬度]，而非 [纬度, 经度]）
• 缺少必需属性（type、coordinates、geometry）
• 几何类型或嵌套无效

示例工作流：

1. Receive GeoJSON data
2. Validate with validate_geojson_tool
3. If valid: Add as source to style
4. If invalid: Fix errors, re-validate

表达式验证

应验证以下表达式：

• 筛选条件（图层上的 filter 属性）
• 数据驱动样式（paint 和 layout 属性）
• 要素状态表达式
• 动态属性计算

常见表达式错误：

• 类型不匹配（对数字使用字符串运算符）
• 运算符名称无效或语法错误
• 运算符参数数量错误
• 嵌套表达式错误
• 使用你的 GL JS 版本中不可用的运算符

预防策略：

• 编写表达式时就进行验证，而不是等到运行时
• 使用有代表性的数据测试表达式
• 使用类型检查（expectedType 参数）
• 在上下文中进行验证（图层、筛选条件、paint、layout）

无障碍验证

WCAG 级别：

• AA（最低要求）：普通文本为 4.5:1，大号文本为 3:1
• AAA（增强要求）：普通文本为 7:1，大号文本为 4.5:1

文本大小类别：

• 普通：< 18pt 或 < 14pt 粗体
• 大号：≥ 18pt 或 ≥ 14pt 粗体

需要检查的常见场景：

• 地图瓦片上的文本标签
• 带背景色的 POI 标签
• 带文本的自定义标记
• 地图上的 UI 覆盖层
• 图例文本和符号
• 归属信息文本

测试策略：

• 在浅色和深色地图瓦片上都进行测试
• 考虑覆盖层背景（弹出窗口、模态框）
• 在不同光照条件下测试（移动设备户外使用）
• 验证不同缩放级别下的对比度

质量工作流示例

基本质量检查

1. Validate expressions in style
2. Check color contrast for text layers
3. Optimize if needed

完整的上线前工作流

1. Validate all GeoJSON sources
2. Validate all expressions (filters, paint, layout)
3. Check color contrast for all text layers
4. Compare with previous production version
5. Optimize style
6. Test optimized style
7. Deploy

故障排查工作流

1. Compare working vs. broken style
2. Identify differences
3. Validate suspicious expressions
4. Check GeoJSON data if source-related
5. Verify color contrast if visibility issue

常见问题与解决方案

运行时表达式错误

问题： 地图在运行时抛出表达式错误
解决方案： 在开发过程中使用 validate_expression_tool 验证表达式
预防措施： 将表达式验证添加到提交前钩子或 CI/CD 中

文本可读性差

问题： 地图上的文本标签难以阅读
解决方案： 使用 check_color_contrast_tool 检查对比度，调整颜色以符合 WCAG AA
预防措施： 在浅色和深色背景上测试文本，并在不同缩放级别下检查

样式文件过大

问题： 样式加载或传输耗时过长
解决方案： 运行 optimize_style_tool 去除冗余并简化样式
预防措施： 在开发过程中定期优化，并立即移除未使用的数据源

GeoJSON 数据源无效

问题： GeoJSON 数据源无法加载或渲染
解决方案： 使用 validate_geojson_tool 验证，修复坐标问题并确认结构正确
预防措施： 将所有外部 GeoJSON 添加到样式之前先进行验证

样式意外更改

问题： 样式发生了更改，但不清楚修改内容
解决方案： 使用 compare_styles_tool 生成差异报告
预防措施： 对所有重大更改进行前后对比，并记录修改内容

工具速查表

工具	使用时机	输出
validate_geojson_tool	添加 GeoJSON 数据源	有效/无效 + 错误列表
validate_expression_tool	编写表达式	有效/无效 + 错误列表
check_color_contrast_tool	设置文本标签样式	通过/未通过 + WCAG 级别
compare_styles_tool	审查更改	包含路径的差异报告
optimize_style_tool	部署前	优化后的样式 + 节省量

参考文件

如需特定主题的详细指导，请加载相关参考文件：

• references/optimization.md — 优化类型、策略、建议顺序和维护最佳实践
• references/comparison.md — 样式比较工作流、ignoreMetadata 的用法和重构工作流
• references/ci-integration.md — Git 提交前钩子、CI/CD 流水线步骤和代码审查清单

加载说明： 用户需要某个主题的深入指导时，请阅读相应的参考文件。

其他资源

• Mapbox 样式规范
• WCAG 2.1 指南
• GeoJSON 规范（RFC 7946）
• Mapbox 表达式参考