【HarmonyOS 6.0】Map Kit：用自定义组件灵活构建地图Marker图标

文章目录

• [1 -> 概述](#1 -> 概述)
• [2 -> Marker自定义图标的功能演进](#2 -> Marker自定义图标的功能演进)
• [3 -> 核心概念与基础用法](#3 -> 核心概念与基础用法)
• • [3.1 -> iconBuilder属性](#3.1 -> iconBuilder属性)
  • [3.2 -> @Builder装饰器与组件定义](#3.2 -> @Builder装饰器与组件定义)
  • [3.3 -> 动态数据的实时刷新](#3.3 -> 动态数据的实时刷新)
  • [3.4 -> 完整的Marker集成示例](#3.4 -> 完整的Marker集成示例)
• [4 -> 进阶用法：ComponentSnapshot快照生成PixelMap](#4 -> 进阶用法：ComponentSnapshot快照生成PixelMap)
• • [4.1 -> ComponentSnapshot简介](#4.1 -> ComponentSnapshot简介)
  • [4.2 -> 将自定义组件转为PixelMap并设置为Marker图标](#4.2 -> 将自定义组件转为PixelMap并设置为Marker图标)
  • [4.3 -> ComponentSnapshot的方案演进](#4.3 -> ComponentSnapshot的方案演进)
• [5 -> 适用场景与最佳实践](#5 -> 适用场景与最佳实践)
• • [5.1 -> 适合使用iconBuilder的场景](#5.1 -> 适合使用iconBuilder的场景)
  • [5.2 -> 性能考量与注意事项](#5.2 -> 性能考量与注意事项)
• [6 -> 总结](#6 -> 总结)

---

1 -> 概述

在移动端地图开发中，Marker（地图标记）是最基础也最核心的视觉元素之一。传统的Marker图标多以静态图片的形式呈现------开发者在MarkerOptions中传入一张图片资源，地图引擎将其渲染到指定经纬度上。这种方式简单直接，覆盖了绝大多数通用场景，但当业务需求超出静态图片的承载能力时，局限性便开始显现。

想象这样一个场景：你需要在地图上展示一组实时变价的商品，每个Marker上需要显示最新的价格数字；或者你需要为某个热门餐厅添加一个带有排队人数动态标签的Marker；又或者你的设计师希望Marker的样式能够跟随应用的深色/浅色模式自动切换。这些需求在传统方案下并非不能实现，但实现路径往往曲折------要么需要在服务端预先生成大量不同内容的图标图片，要么需要在客户端动态合成图片再转换为PixelMap设置到Marker上，代码复杂度高且性能开销大。

HarmonyOS 6.0.0(20)版本的Map Kit引入了一个关键特性：支持通过自定义组件（@Builder修饰的函数）直接生成Marker图标 。该特性通过MarkerOptions中新增的iconBuilder属性，允许开发者使用ArkUI的声明式语法来定义Marker的外观。这意味着Marker不再只能是静态图片，而是可以变成一个真正"活的"UI组件------文本可以随数据动态更新，样式可以响应状态变化，甚至还可以包含交互逻辑。

本文主要内容

本文将围绕该特性的技术背景、使用方法和实际应用展开，希望能够帮助开发者全面理解并灵活运用这项能力：

• 回顾Marker自定义图标的发展历程，分析自定义组件方案相比传统图片方案的优势
• 详细讲解自定义组件实现Marker图标的核心概念与基础用法
• 通过完整代码示例展示如何构建动态内容更新的Marker，并结合ComponentSnapshot实现组件快照生成PixelMap的进阶用法
• 总结该特性的适用场景与最佳实践

需要说明的是，本文示例基于HarmonyOS 6.0.0(20)及以上版本，开发环境需使用DevEco Studio 5.0.0及以上版本，并确保项目已正确集成@kit.MapKit模块。

2 -> Marker自定义图标的功能演进

在深入探讨新的自定义组件特性之前，先回顾一下Map Kit中Marker图标自定义能力的演进过程，这有助于我们更好地理解新特性的价值所在。

阶段一：传统静态图片方案

在早期的Map Kit版本中，自定义Marker图标的标准做法是在MarkerOptions中通过icon属性传入图片资源。该属性支持两种类型：一是Resource类型，指向resources/rawfile或resources/base/media目录下的本地图片文件；二是image.PixelMap类型，可由网络图片下载后转换得到。代码示例如下：

let markerOptions: mapCommon.MarkerOptions = {
    position: { latitude: 31.9844, longitude: 118.7663 },
    icon: 'test.png'  // 指向rawfile中的图片
};
let marker = await mapController.addMarker(markerOptions);

这种方案的优势在于简单稳定，执行效率高，适用于大多数常规场景。但问题也同样明显：Marker图标是"静态"的，一旦创建便无法动态改变其内部的文字、颜色等视觉属性，除非重新创建一个新的Marker。当业务需要Marker内容实时变化时，这种方案会显得力不从心。

阶段二：PixelMap合成方案

面对动态内容的需求，开发者们探索出了一种变通方案：利用ArkUI的ComponentSnapshot模块，将自定义的ArkUI组件截图为PixelMap，然后将该PixelMap作为Marker的图标。大致思路如下：

1. 使用@Builder定义一个包含动态内容的UI组件
2. 创建一个隐藏的节点，将组件渲染到该节点上
3. 调用ComponentSnapshot.get()方法对组件进行截图，生成PixelMap
4. 将PixelMap作为MarkerOptions.icon传入

这种做法在当时很大程度上解决了动态内容Marker的需求，各路开发者社区中也有不少相关讨论和实现。然而，它本质上是一种绕过官方API限制的"曲线救国"方案，存在几个明显的问题：流程繁琐，截图操作本身存在异步延迟；每次内容更新都需要重新截图并刷新Marker；截图生成的PixelMap分辨率问题可能导致图标在不同屏幕密度下显示效果不一致。

阶段三：自定义组件原生支持（6.0.0(20)版本）

在HarmonyOS 6.0.0(20)版本中，Map Kit正式引入了对自定义组件的原生支持。开发者可以直接在MarkerOptions中设置iconBuilder属性，传入一个由@Builder修饰的函数，Map Kit内部会自动处理组件的渲染和与地图的融合。这一改进从根本上解决了上述所有问题：

• 真正的声明式：直接使用ArkUI组件定义Marker外观，符合HarmonyOS整体的开发范式
• 动态内容实时响应 ：组件内的@State等状态变量变化时，Marker图标自动刷新，无需手动干预
• 无需截图转换：消除了截图方案带来的异步延迟和性能开销
• 完全兼容现有生态 ：MarkerOptions中的其他属性（位置、锚点、碰撞规则等）均与iconBuilder兼容

至此，Map Kit的Marker自定义能力完成了一次质的飞跃。

版本说明

• 5.1.1(19)：支持控制Marker文字显隐功能
• 6.0.0(20)：支持自定义组件实现Marker图标功能
• 6.1.1(24)：支持监听Marker长按事件

本文的核心功能需要HarmonyOS 6.0.0(20)及以上版本。

3 -> 核心概念与基础用法

3.1 -> iconBuilder属性

iconBuilder是mapCommon.MarkerOptions接口中新增的一个属性，其类型为() => void，接收一个无参数的箭头函数，该函数的返回值应当是由@Builder修饰器标记的自定义组件构建函数。Map Kit在渲染Marker时，会自动调用该函数来生成和更新Marker图标所使用的UI组件。

与传统icon属性使用图片资源相比，iconBuilder允许开发者使用完整的ArkUI组件体系来构建图标。这意味着你可以使用Text、Image、Stack、Column、Row等任意ArkUI内置组件，也可以嵌套自定义的@Component和@Builder组件。

基本数据类型对比

// 传统方式：使用静态图片
let markerOptionsStatic: mapCommon.MarkerOptions = {
    position: { latitude: 32.12075, longitude: 118.788765 },
    icon: $r('app.media.marker_icon')  // 或 'test.png'
};

// 新方式：使用自定义组件
let markerOptionsDynamic: mapCommon.MarkerOptions = {
    position: { latitude: 32.12075, longitude: 118.788765 },
    iconBuilder: () => {
        this.markerIconBuilder();  // 调用自定义Builder函数
    }
};

需要特别注意的是，icon和iconBuilder是互斥的属性------在同一个MarkerOptions对象中，如果同时设置了icon和iconBuilder，Map Kit的行为是未定义的，开发时应避免这种情况。

3.2 -> @Builder装饰器与组件定义

在ArkUI中，@Builder装饰器用于声明一个自定义的UI构建函数，可以包含任意复杂的UI布局和逻辑。自定义组件实现Marker图标的核心就是使用@Builder定义一个函数，该函数返回Marker图标所需要的UI结构。

基础的自定义图标组件

@Builder
markerIconBuilder() {
    Stack({ alignContent: Alignment.Center }) {
        // 外层气泡背景
        Column() {
            Image($r('app.media.marker_bubble'))
                .width(40)
                .height(40)
        }
        // 中心图标
        Image($r('app.media.marker_center_icon'))
            .width(24)
            .height(24)
    }
    .width(50)
    .height(50)
}

这里使用了Stack布局将两个Image组件叠加，形成自定义的Marker气泡效果。Stack的alignContent参数设置为Alignment.Center，确保内部组件在容器中居中排列。对Marker图标组件设置明确的宽高尺寸是非常重要的------如果组件没有明确尺寸，渲染结果可能会出现偏移或裁剪问题。

3.3 -> 动态数据的实时刷新

iconBuilder方案最强大的地方在于，Marker图标组件中可以使用@State装饰的状态变量。当这些状态变量发生变化时，图标会自动重新渲染，整个过程无需任何额外代码。

动态价格标签示例

@Component
struct DynamicPriceMarker {
    @State price: number = 0;
    private updateTimer?: number;

    aboutToAppear(): void {
        // 模拟实时价格变化（每秒更新一次）
        this.updateTimer = setInterval(() => {
            // 随机生成 10~100 之间的价格
            this.price = Math.floor(Math.random() * 90 + 10);
        }, 1000);
    }

    aboutToDisappear(): void {
        if (this.updateTimer) {
            clearInterval(this.updateTimer);
        }
    }

    @Builder
    markerIconBuilder() {
        Stack() {
            // 背景圆角矩形
            Column() {
                Text(`¥${this.price.toFixed(2)}`)
                    .fontSize(14)
                    .fontColor(Color.White)
                    .fontWeight(FontWeight.Bold)
            }
            .width(60)
            .height(28)
            .borderRadius(14)
            .backgroundColor('#FF4D4F')
            .justifyContent(FlexAlign.Center)

            // 底部小三角指示器
            Path()
                .width(10)
                .height(8)
                .commands('M5,8 L0,0 L10,0 Z')
                .fill('#FF4D4F')
                .margin({ top: 28 })
        }
        .width(60)
        .height(36)
    }

    build() {
        // 此组件仅用于展示Builder，实际使用时无需build
    }
}

在这个示例中，价格数据每秒自动更新一次，而更新后地图上Marker的价格显示也会实时变化。这种实时数据刷新的能力，正是iconBuilder方案相比传统icon静态图片方案的最大优势所在。

3.4 -> 完整的Marker集成示例

以下是一个完整的示例，展示如何在地图初始化时添加使用自定义组件的Marker。

import { map, mapCommon, MapComponent } from '@kit.MapKit';
import { AsyncCallback } from '@kit.BasicServicesKit';

@Entry
@Component
struct CustomMarkerDemo {
    private mapOption?: mapCommon.MapOptions;
    private mapController?: map.MapComponentController;
    private callback?: AsyncCallback;
    private marker?: map.Marker;
    @State dynamicPrice: number = 99;

    aboutToAppear(): void {
        // 配置地图初始化参数
        this.mapOption = {
            position: {
                target: {
                    latitude: 32.120750,
                    longitude: 118.788765
                },
                zoom: 14
            },
            scaleControlsEnabled: true
        };

        // 地图初始化回调，在地图加载完成后创建Marker
        this.callback = async (err, mapController) => {
            if (!err) {
                this.mapController = mapController;

                // 构造MarkerOptions，通过iconBuilder指定自定义组件
                let markerOptions: mapCommon.MarkerOptions = {
                    position: {
                        latitude: 32.120750,
                        longitude: 118.788765
                    },
                    // 核心：通过iconBuilder关联自定义图标组件
                    iconBuilder: () => {
                        this.customMarkerBuilder();
                    },
                    clickable: true,
                    draggable: false,
                    zIndex: 10,
                    anchorU: 0.5,  // 水平锚点（0.5表示图标水平居中）
                    anchorV: 1.0    // 垂直锚点（1.0表示图标底部与经纬度点对齐）
                };

                this.marker = await this.mapController?.addMarker(markerOptions);
            } else {
                console.error(`地图初始化失败, code: ${err.code}, message: ${err.message}`);
            }
        };
    }

    @Builder
    customMarkerBuilder() {
        Stack({ alignContent: Alignment.Center }) {
            // Marker主背景
            Column() {
                Row() {
                    Image($r('app.media.location_icon'))
                        .width(16)
                        .height(16)
                        .margin({ right: 4 })
                    Text('当前位置')
                        .fontSize(12)
                        .fontColor('#FFFFFF')
                }
                .justifyContent(FlexAlign.Center)

                Text(`¥${this.dynamicPrice}`)
                    .fontSize(18)
                    .fontWeight(FontWeight.Bold)
                    .fontColor('#FFD700')
                    .margin({ top: 2 })
            }
            .width(80)
            .height(44)
            .borderRadius(8)
            .backgroundColor('#1A73E8')
            .justifyContent(FlexAlign.Center)

            // 指示小三角（底部尖端）
            Path()
                .width(12)
                .height(8)
                .commands('M6,8 L0,0 L12,0 Z')
                .fill('#1A73E8')
                .margin({ top: 44 })
        }
        .width(80)
        .height(52)
    }

    // 模拟动态价格变化
    private startPriceSimulation(): void {
        setInterval(() => {
            // 价格在50~150之间随机变化
            this.dynamicPrice = Math.floor(Math.random() * 100 + 50);
        }, 2000);
    }

    build() {
        Stack() {
            Column() {
                MapComponent({
                    mapOptions: this.mapOption,
                    mapCallback: this.callback
                })
                .width('100%')
                .height('100%')
            }
            .width('100%')
        }
        .height('100%')
        .onAppear(() => {
            this.startPriceSimulation();
        })
    }
}

代码要点说明

1. 锚点设置（anchorU/anchorV） ：anchorU和anchorV是两个非常重要的属性，它们定义了图标上的哪个点与地图上的经纬度坐标点对齐。anchorU控制水平方向，anchorV控制垂直方向，取值范围均为0到1。一般默认约定是锚点位于图标底部中心，即{ anchorU: 0.5, anchorV: 1.0 }，这样图标的"尖端"会准确对应经纬度位置。

2. zIndex：控制Marker的图层堆叠顺序，数值越大的Marker会显示在上层。当多个Marker位置接近时，zIndex高的会覆盖低的。

3. clickable/draggable ：clickable决定用户是否可以点击该Marker并触发事件；draggable决定用户是否可以拖拽移动Marker位置。这两个属性可根据业务场景按需开启。

4 -> 进阶用法：ComponentSnapshot快照生成PixelMap

尽管iconBuilder已经能够满足绝大多数动态Marker的需求，但某些特殊场景下，开发者仍可能需要获取Marker图标组件对应的PixelMap格式数据。例如：需要将Marker图标保存为图片以便分享、需要将图标用于通知栏展示、或者需要将图标数据传递给其他模块使用。

在这种情况下，ComponentSnapshot模块提供了将ArkUI组件渲染为PixelMap的能力。下面介绍如何结合使用ComponentSnapshot与Map Kit的icon属性。

技术说明 ：对于HarmonyOS 6.0.0(20)及以上版本，iconBuilder已是官方推荐的动态Marker实现方式。需要获取PixelMap的场景实际上并不常见，以下内容供有特殊需求的开发者参考。

4.1 -> ComponentSnapshot简介

ComponentSnapshot是鸿蒙ArkUI框架中用于对UI组件进行快照处理的模块。它可以将一个由@Builder定义的组件渲染为PixelMap格式的像素图，开发者可以进一步将该像素图用于图像处理、保存、分享等操作。

4.2 -> 将自定义组件转为PixelMap并设置为Marker图标

以下示例演示了如何将自定义的优惠券样式组件转换为PixelMap，然后通过icon属性将其设置为Marker图标：

import { image } from '@kit.ImageKit';
import { componentSnapshot } from '@kit.ArkUI';

@Entry
@Component
struct SnapshotMarkerDemo {
    private mapController?: map.MapComponentController;
    private marker?: map.Marker;
    @State couponCode: string = 'SAVE20';
    @State discountRate: string = '8折';

    @Builder
    couponMarkerTemplate() {
        Column() {
            Text(this.discountRate)
                .fontSize(16)
                .fontWeight(FontWeight.Bold)
                .fontColor('#E53935')
            Text(this.couponCode)
                .fontSize(10)
                .fontColor('#757575')
                .margin({ top: 2 })
        }
        .width(60)
        .height(50)
        .borderRadius(8)
        .backgroundColor('#FFFFFF')
        .border({ width: 1, color: '#E53935', radius: 8 })
        .justifyContent(FlexAlign.Center)
    }

    // 将Builder组件转换为PixelMap
    private async getBuilderPixelMap(builder: () => void): Promise<image.PixelMap> {
        try {
            const pixelMap = await componentSnapshot.get(builder);
            return pixelMap;
        } catch (error) {
            console.error(`截图失败: ${error}`);
            throw error;
        }
    }

    // 将PixelMap设置为Marker图标
    private async addCouponMarker(): Promise<void> {
        if (!this.mapController) return;

        // 1. 将Builder组件转为PixelMap
        const pixelMap = await this.getBuilderPixelMap(() => this.couponMarkerTemplate());

        // 2. 使用PixelMap构造MarkerOptions
        let markerOptions: mapCommon.MarkerOptions = {
            position: {
                latitude: 32.120750,
                longitude: 118.788765
            },
            icon: pixelMap,  // 将PixelMap作为图标资源
            clickable: true
        };

        // 3. 添加Marker到地图
        this.marker = await this.mapController.addMarker(markerOptions);
    }

    // 动态更新优惠券信息并刷新Marker
    async refreshCouponMarker(newCode: string, newRate: string): Promise<void> {
        if (!this.marker) return;

        // 更新状态变量
        this.couponCode = newCode;
        this.discountRate = newRate;

        // 等待下一帧，确保UI已完成更新
        await new Promise(resolve => setTimeout(resolve, 50));

        // 重新截图并更新Marker图标
        const newPixelMap = await this.getBuilderPixelMap(() => this.couponMarkerTemplate());
        this.marker.setIcon(newPixelMap);
    }

    build() {
        Column() {
            Button('添加优惠券标记')
                .onClick(() => this.addCouponMarker())
            MapComponent({
                // ... 地图配置
            })
        }
    }
}

方案特点与注意事项

• 优势：可以在任何需要PixelMap的场景下复用这套逻辑，灵活性高
• 限制：截图操作是一个异步过程，需要额外处理加载状态；频繁截图会带来一定的性能开销，不适合高频更新的场景
• 建议：对于高频更新场景，应优先使用iconBuilder方案；仅在确实需要PixelMap对象时才使用快照方案

4.3 -> ComponentSnapshot的方案演进

在HarmonyOS 6.0.0(20)版本之前，想要在Map Kit中实现动态Marker内容，唯一可行的方法就是使用ComponentSnapshot配合PixelMap的变通方案。当时甚至有开发者在地图相关的FAQ中咨询"marker是否支持传入自定义view"，得到的答复也是"鸿蒙上也支持将view转成pixelMap的"。

iconBuilder的出现标志着Map Kit对这一需求做出了官方原生支持，替代了此前社区中的各种"曲线救国"方案。对于新项目和新功能开发，应直接使用iconBuilder方案；对于仍在使用截图方案的老代码，可以考虑在有足够测试覆盖的前提下逐步迁移。

另外需要了解的一个性能事实是：使用默认图标的Marker数量限制为5000个，但如果使用自定义图标，可添加的Marker数量会减少，因为自定义图标需要占用额外的内存资源。实际项目中应根据设备内存和业务需求合理规划Marker数量。

5 -> 适用场景与最佳实践

5.1 -> 适合使用iconBuilder的场景

• 实时数据展示：Marker上需要显示实时变化的数据，如车辆速度、设备温度、股票价格、排队人数等动态信息。
• 用户相关个性化内容：不同用户看到的Marker内容不同，例如显示用户姓名首字母、距离目的地剩余时间、个性化优惠信息等。
• 复杂视觉样式：Marker样式包含多图层叠加、渐变、圆角、阴影等复杂视觉效果，使用ArkUI实现比合成位图更为高效可控。
• 主题自适应 ：Marker样式需要跟随系统的深色/浅色模式自动切换，@Builder组件可以响应系统主题变化而自动刷新。

5.2 -> 性能考量与注意事项

• 组件尺寸明确 ：为Marker图标组件显式设置width和height是必须的，这有助于Map Kit准确计算布局和点击区域。
• 状态变量作用域 ：iconBuilder中的组件可以访问外层组件的@State变量，但需要注意这些变量的生命周期。当外层组件销毁时，与之关联的Marker图标也会随之消失。
• 避免过度复杂布局：Marker图标通常尺寸较小，过于复杂的组件嵌套会增加渲染开销。建议保持简洁，深度控制在2-3层内。
• 锚点位置校准 ：anchorU和anchorV的配置直接影响Marker图标与经纬度点的对齐关系。不同类型图标可能需要调整不同的锚点值才能达到预期的视觉对齐效果。

6 -> 总结

对比维度	传统icon静态图片方案	ComponentSnapshot截图方案	iconBuilder方案
支持动态内容更新	❌ 不支持	✅ 支持（需手动刷新）	✅ 原生支持
实现复杂度	低	高	低
性能开销	极低	中（截图开销）	低
与ArkUI开发范式契合度	低	中	高
官方推荐程度	一般（用于静态图标）	不推荐（6.0+）	强烈推荐

HarmonyOS Map Kit在6.0.0(20)版本中引入的自定义组件Marker图标支持，从功能设计的角度补齐了声明式地图开发的一个重要拼图。在此之前，开发者想要在地图上实现动态内容的标记点，不得不在服务端预生成大量图片，或者在前端通过截图等变通手段完成。iconBuilder的出现让这一切回归到了"声明式UI"的本质------数据驱动视图，视图自动刷新。

从更宏观的视角来看，这项特性体现了华为在HarmonyOS生态中推动"一次开发，多端部署"理念的延续。开发者可以使用同一套ArkTS和ArkUI的技能栈来构建应用的各个部分，包括地图上那些看似不起眼的小小标记点。

---

感谢各位大佬支持！！！
互三啦！！！