## 地图样式与视觉规范（Map Style Guideline） > 目标：在使用百度地图 HarmonyOS SDK（`@bdmap/map` 等）时，统一标注点、路线、面、文本等地图元素的**视觉样式与锚点约定**，保证不同业务页面风格一致、信息层级清晰，可读性与美观兼顾。 > 本文为**样式规范文档**，与性能/交互规范配合使用： > - 性能与覆盖物分层规范：`performance-optimization.md` > - 地图 UI 交互与用户反馈规范：`ui-feedback.md` --- ## 1. 点标注（Marker）图标与锚点规范 ### 1.1 Located 枚举语义说明（重要） > **Agent 必读**：`SysEnum.Located` 的语义是描述**图标整体相对于坐标点的位置方向**，而非图标的哪条边对齐坐标。这与常见 UI 框架中 anchor/gravity 的含义**相反**，极易混淆，生成代码时务必参照本节。 百度地图 SDK 中 `SysEnum.Located` 的含义如下： | 枚举值 | 语义 | 图标与坐标点的位置关系 | 图标哪条边对齐坐标点 | |---|---|---|---| | `Located.TOP` | 图标位于坐标点**上方** | 图标在坐标点的上面 | 图标**底边中点**对齐坐标 | | `Located.BOTTOM` | 图标位于坐标点**下方** | 图标在坐标点的下面 | 图标**顶边中点**对齐坐标 | | `Located.CENTER` | 图标**中心**对齐坐标点 | 图标中心在坐标点上 | 图标**几何中心**对齐坐标 | | `Located.LEFT` | 图标位于坐标点**左侧** | 图标在坐标点的左边 | 图标**右边中点**对齐坐标 | | `Located.RIGHT` | 图标位于坐标点**右侧** | 图标在坐标点的右边 | 图标**左边中点**对齐坐标 | **图示说明**（`●` 表示地理坐标点）： ``` Located.TOP Located.CENTER Located.BOTTOM ╭──╮ ● ← 坐标点 │ │ ╭──╮ ╭──╮ │ │ │ ●│ ← 坐标点 │ │ ╰─┬╯ ╰──╯ ╰──╯ ● ← 坐标点 ``` **关键记忆口诀**：`Located` 的值表示”图标在坐标点的哪个方向”——`TOP` 表示图标在上、坐标在下，所以图标底边对齐坐标点。 ### 1.2 锚点通用约定 - **非圆形图标（带尖角/底边）** - **默认锚点：`SysEnum.Located.TOP`** - 图标整体在坐标点上方，底边中点对齐坐标，尖角/底边精准落在地理位置上。 - 适用场景：定位点、POI 标注、起终点标记、针状/水滴图标等。 - **圆形图标 / 正方形图标** - **默认锚点：`SysEnum.Located.CENTER`** - 图标中心与实际经纬度对齐。 - 适用场景：轨迹节点、兴趣点聚合圆点、状态指示点等。 - **带 PopView 的 Marker** - 当 Marker 需要在上方附加信息气泡（PopView）时，Marker 自身通常使用 `Located.BOTTOM`，使 Marker 图标在坐标点下方，PopView 通过 `setLocated(Located.TOP)` 显示在 Marker 上方。 - **其他特殊需求** - 若图标视觉重心明显上移（如带大图标 + 小尖角），可根据具体需求调整锚点，保证「视觉重心」落在真实经纬度附近；但必须在代码注释中**说明原因**。 - 对于需要「悬浮在地面上方」的图标（如气泡阴影、弹窗箭头），可以在 yOffset 方向上设置小于 0 的像素值（例如 `-20`），让图标稍微”抬起”。 ### 1.3 常见业务场景锚点示例 - **用户当前位置 / 定位点（非圆形水滴图标）** - 图标：水滴或针形图标，底部有尖角。 - 锚点：`SysEnum.Located.TOP` —— 图标在坐标上方，尖角（底边）指向真实位置。 - **兴趣点（POI）圆点** - 图标：纯色圆点 / 圆环。 - 锚点：`SysEnum.Located.CENTER` —— 圆心对应真实位置。 - **起点 / 终点 / 途经点（带底边的方形或图标卡片）** - 图标：下边缘为直线的矩形。 - 锚点：`SysEnum.Located.TOP` —— 图标在坐标上方，下边中点落在道路或位置上。 - **聚合点（Cluster）** - 图标：数字圆点或圆形徽章。 - 锚点：`SysEnum.Located.CENTER`，保证数字居中。 - **带信息气泡的 Marker** - Marker 锚点：`SysEnum.Located.BOTTOM`（图标在坐标下方）。 - PopView 锚点：`popView.setLocated(SysEnum.Located.TOP)`（气泡在 Marker 上方）。 --- ## 2. 路线与线条样式规范 ### 2.1 路线规划线（导航/路径） - **基础规则** - 默认使用**单纹理**线条表达路线（如纯色或渐变色纹理），保证清晰、简洁。 - 线宽：根据分辨率与缩放级别，一般在 **8-16px** 之间，需在实现中与 UI 设计统一。 - **拥堵 / 通畅状态表达（多纹理）** - 当需要表达「拥挤/畅通」等实时路况时，采用**多纹理**（Multi-Texture）线条： - 绿色：通畅 - 黄色：缓行 - 红色：拥堵 - 深红/紫色：严重拥堵 - 各纹理段之间应平滑过渡，避免频繁颜色跳变造成视觉噪音。 - **主路线 vs 备选路线** - 主路线： - 颜色：高饱和主色（如品牌蓝/绿色），不透明度 80%–100%。 - 线宽：略宽（如 12-16px），以突出主路线。 - 备选路线： - 颜色：同色系低饱和或灰色，透明度 40%–60%。 - 线宽：略细（如 8-12px）。 ### 2.2 轨迹线（历史轨迹 / 运动记录） - 颜色：与业务品牌色一致的中等饱和色，如蓝/绿。 - 线宽：比路线规划线略细，强调辅信息属性。 - 若需要方向感，可使用**箭头纹理**或在关键点增加小箭头 Marker。 ### 2.3 行政边界 / 功能区线条 - 省 / 市 / 区边界： - 颜色：低饱和灰色或浅色实线，透明度 30%–60%。 - 线宽：较细（如 4-6px），避免喧宾夺主。 - 业务相关区域边界（如配送范围、服务区域）： - 使用半透明填充色 + 清晰边线，详见「面与区域」部分。 --- ## 3. 面（Polygon/Region）与圆形区域样式 ### 3.1 半透明填充 + 清晰边线 - 所有面状区域应使用： - **填充色**：低饱和品牌色 + 较高透明度（例如 10%–30%）。 - **边线**：同色系略深颜色，透明度 60%–80%，线宽 4-6px。 - 目的： - 区域可被明显识别，但不遮挡地图底图细节。 ### 3.2 常见业务区域推荐样式 - **服务范围 / 配送区域** - 填充：品牌主色的浅色（如浅绿/浅蓝），透明度 15%–20%。 - 边线：主色深一档，线宽 4px。 - **风险区域 / 禁止进入区域** - 填充：红色或橙色，透明度 10%–15%。 - 边线：同色系深色虚线或实线，线宽 4-6px。 - 覆盖物 `zIndex` 应低于标注点和信息气泡，避免遮挡重要提示。 - **安全区域 / 推荐活动范围** - 填充：绿色/蓝色系浅色，透明度 10%–20%。 - 边线：不必过于抢眼，可与背景相融。 --- ## 4. 文本与标签（Label）样式 ### 4.1 文本层级与字号 - 文本字号应随缩放级别自动调整（若 SDK & 业务支持），但需保持： - **一级信息（地点名称、路线名称）**：字号较大，颜色对比度高。 - **二级信息（地址简要、距离/时长）**：中等字号，颜色略浅。 - **辅助信息（标签、分类）**：较小字号，灰色系。 ### 4.2 颜色与对比度 - 深色底图： - 主文本：浅色（如 #FFFFFF、#F5F5F5） - 辅助文本：浅灰（如 #CCCCCC） - 浅色底图： - 主文本：深色（如 #222222、#333333） - 辅助文本：中灰（如 #666666、#888888） - 必须确保**足够对比度**（建议对比度不低于 WCAG 标准 4.5:1），兼顾可读性与无障碍需求。 ### 4.3 标签与信息框（PopView/InfoWindow） - 信息框内： - 标题：使用较大字号 + 粗体。 - 副标题/地址：中等字号，单行或两行内展示，超长用省略号。 - 操作按钮（若有）：与全局按钮风格一致，避免在气泡内放过多操作。 - 信息框与 Marker 的组合需遵循： - Marker 锚点与信息框锚点协调，确保信息框三角箭头指向目标点。 - 承载信息框的透明 Marker `zIndex` 必须处于最高层级，避免被线/面遮挡。 --- ## 5. 颜色体系与主题适配 ### 5.1 基础颜色体系 - **品牌主色**：用于主路线、关键 Marker、高亮区域。 - **辅助色**：用于次级路线、备选路径、次要区域。 - **警告色**：用于拥堵、风险区域、错误提示。 - **中性色**：用于行政边界、背景线条、辅助文本。 ### 5.2 深色/浅色主题 - 浅色主题： - 底图偏浅，路线与标注可使用饱和度更高的颜色。 - 警告色需适当降低饱和度避免刺眼。 - 深色主题： - 路线与标注需使用高亮浅色或荧光色系。 - 文本需使用高对比度浅色，避免纯白大面积导致眩光。 --- ## 6. 不同缩放级别下的样式调整 - **低缩放级别（城市/全国视野）** - 仅展示关键信息：主路线、主要城市/地标、重要区域轮廓。 - 隐藏或合并普通 POI、细粒度轨迹点。 - **中缩放级别（区县/城区视野）** - 展示更多 POI 与区域信息； - 路线细节适度展示，但避免过多小折线导致视觉负担。 - **高缩放级别（街道/楼宇级）** - 展示详细 POI、建筑轮廓、轨迹节点等。 - 允许显示更多文本标签，但需避免碰撞： - 可开启 SDK 文本避让能力（如有）； - 业务侧避免在同一位置叠加多文本。 --- ## 7. 交互相关样式建议 - Marker 点击态： - 建议在选中状态下放大 10%–20%，或添加描边/光晕高亮； - 同时改变对应信息框或底部卡片样式，形成「联动」。 - 路线选中态： - 被选中的路线加粗或改变颜色，其他路线降低透明度。 - 区域 hover/点击态（若有）： - 填充色稍微加深或边线加粗，以提示用户当前操作目标。 --- ## 8. 与其他规范的关系 - **与性能规范的关系** - 颜色、线宽、透明度等样式设置不得通过频繁重建覆盖物的方式实现，应尽量在已有对象上更新属性，详见 `performance-optimization.md`。 - **与 zIndex 分层规范的关系** - 任何样式调整不得破坏既定的 zIndex 分层原则：面 < 线 < Marker < 信息框/临时标注。 - **与 UI 反馈规范的关系** - 样式变化（如选中态、错误态）需与交互反馈（Toast/Dialog/状态文本）保持一致的语义颜色和文案，详见 `ui-feedback.md`。 --- ## 9. 实施与落地建议 - 新增地图样式时： - 优先在此文档中补充规则，再在代码中实现； - 重要样式变化需评审通过后方可全局使用。 - 代码实现中： - 避免在页面内写死魔法值（如颜色、线宽、透明度），推荐集中定义样式常量或配置； - 对锚点、颜色等关键参数需添加中文注释，说明选择原因与业务含义。