百度地图JSAPI THREE Icon 组件完使用指南

原创

用户11921230

发布于 2025-12-10 11:35:55

1500

文章被收录于专栏：JSAPI THREEJSAPI THREE

百度地图JSAPI THREE Icon 组件使用指南

在三维地图可视化场景中，图标（Icon）是最常用的元素之一。MapVThree 提供了功能强大的 Icon 组件，支持多种配置方式和渲染效果。本文将深入介绍 Icon 组件的使用方法，帮助开发者快速掌握其核心功能。

一、Icon 组件基础

1.1 创建 Icon 实例

Icon 组件通过 mapvthree.Icon 类创建，需要传入配置对象。基础配置包括图标尺寸、图片路径等：

const icon = engine.add(
    new mapvthree.Icon({
        width: 100,      // 图标宽度（像素）
        height: 100,     // 图标高度（像素）
        mapSrc: 'path/to/icon.png',  // 图标图片路径
        flat: true,      // 是否贴地显示
        offset: [0, 0],  // 偏移量 [x, y]
    })
);

1.2 绑定数据源

Icon 组件通过数据源（DataSource）来管理要渲染的点位数据。MapVThree 支持 GeoJSON 格式的数据源：

const dataSource = mapvthree.GeoJSONDataSource.fromGeoJSON([
    {
        type: 'Feature',
        geometry: {
            type: 'Point',
            coordinates: [116.4256, 39.9166, 0],  // [经度, 纬度, 高度]
        },
        properties: {
            icon: 'https://example.com/icon.png',
            color: 'yellow',
            size: 50,
        },
    }
]);

// 定义属性字段
dataSource.defineAttribute('color')
          .defineAttribute('size')
          .defineAttribute('icon');

// 绑定数据源
icon.dataSource = dataSource;

在 properties 中定义的属性可以在数据源中为每个点位单独配置，实现个性化的图标显示。

二、核心配置选项

2.1 显示模式：flat 与 3D

flat 参数控制图标的显示模式：

flat: true：图标贴地显示，始终垂直于地面
flat: false：图标在 3D 空间中显示，可以设置高度

// 贴地显示
const flatIcon = engine.add(
    new mapvthree.Icon({
        flat: true,
        mapSrc: 'icon.png',
    })
);

// 3D 空间显示
const icon3D = engine.add(
    new mapvthree.Icon({
        flat: false,
        mapSrc: 'icon.png',
    })
);

2.2 图标旋转

Icon 组件支持多种旋转方式：

const icon = engine.add(
    new mapvthree.Icon({
        rotateZ: Math.PI,           // 全局旋转角度（弧度）
        vertexRotateZs: true,       // 允许每个顶点独立旋转
    })
);

当 vertexRotateZs 为 true 时，可以在数据源的 properties 中为每个点位设置 rotateZ 属性，实现不同图标的独立旋转。

2.3 颜色与样式

Icon 组件支持全局颜色设置和顶点颜色：

// 全局颜色
const icon = engine.add(
    new mapvthree.Icon({
        color: 'red',              // 全局颜色
        vertexColors: true,        // 启用顶点颜色（允许每个点位独立设置颜色）
    })
);

启用 vertexColors 后，可以在数据源的 properties 中为每个点位设置 color 属性。

2.4 偏移量设置

offset 参数用于调整图标的位置偏移：

const icon = engine.add(
    new mapvthree.Icon({
        offset: [0, -30],  // [x偏移, y偏移]，单位：像素
    })
);

三、顶点图标功能

顶点图标（vertexIcons）允许每个点位使用不同的图标图片。启用此功能后，需要在数据源的 properties 中为每个点位指定 icon 属性：

const icon = engine.add(
    new mapvthree.Icon({
        width: 100,
        height: 100,
        vertexIcons: true,  // 启用顶点图标
        mapSrc: 'default-icon.png',  // 默认图标（当点位未指定时使用）
    })
);

const dataSource = mapvthree.GeoJSONDataSource.fromGeoJSON([
    {
        type: 'Feature',
        geometry: {
            type: 'Point',
            coordinates: [116.4252, 39.9162, 21],
        },
        properties: {
            icon: 'custom-icon.png',  // 该点位使用自定义图标
            color: 'red',
            size: 30,
        },
    }
]);

dataSource.defineAttribute('icon')
          .defineAttribute('color')
          .defineAttribute('size');

icon.dataSource = dataSource;

四、动画效果

Icon 组件支持跳跃动画效果，让图标更加生动：

const icon = engine.add(
    new mapvthree.Icon({
        jumpHeight: 30,    // 跳跃高度（像素）
        jumpSpeed: 1,      // 跳跃速度
        animationJump: true,  // 启用动画（可选）
    })
);

跳跃动画会让图标在垂直方向上周期性上下移动，适合用于突出显示重要点位。

五、事件处理

Icon 组件支持交互事件，最常用的是点击事件：

engine.event.bind(icon, 'click', (e) => {
    console.log('图标被点击', e);
    // e 对象包含点击的图标信息
});

通过事件绑定，可以实现图标的交互功能，如显示详情、跳转页面等。

六、完整示例

下面是一个综合示例，展示了 Icon 组件的多种用法：

// 创建引擎
const engine = new mapvthree.Engine(container, {
    map: {
        is3DControl: true,
    },
    rendering: {
        enableAnimationLoop: true,
    },
});

// 示例1：基础贴地图标
const flatIcon = engine.add(
    new mapvthree.Icon({
        width: 100,
        height: 100,
        flat: true,
        mapSrc: 'default-marker.png',
        offset: [0, 0],
        color: 'red',
        rotateZ: Math.PI,
        vertexRotateZs: true,
    })
);

const dataSource1 = mapvthree.GeoJSONDataSource.fromGeoJSON([
    {
        type: 'Feature',
        geometry: {
            type: 'Point',
            coordinates: [116.4256, 39.9166, 0],
        },
        properties: {
            icon: 'custom-marker.png',
            color: 'yellow',
            size: 50,
            rotateZ: Math.PI / 2,
        },
    }
]);

dataSource1.defineAttribute('color')
           .defineAttribute('size')
           .defineAttribute('icon')
           .defineAttribute('rotateZ');

flatIcon.dataSource = dataSource1;

// 示例2：3D 空间图标（带动画）
const icon3D = engine.add(
    new mapvthree.Icon({
        width: 100,
        height: 100,
        flat: false,
        mapSrc: 'default-marker.png',
        vertexColors: true,
        jumpHeight: 30,
        jumpSpeed: 1,
    })
);

const dataSource2 = mapvthree.GeoJSONDataSource.fromGeoJSON([
    {
        type: 'Feature',
        geometry: {
            type: 'Point',
            coordinates: [116.425, 39.916, 21],
        },
        properties: {
            icon: 'custom-icon-1.png',
            color: 'red',
            size: 30,
        },
    },
    {
        type: 'Feature',
        geometry: {
            type: 'Point',
            coordinates: [116.4256, 39.9166, 21],
        },
        properties: {
            icon: 'custom-icon-2.png',
            color: 'yellow',
            size: 50,
        },
    }
]);

dataSource2.defineAttribute('color').defineAttribute('icon');
icon3D.dataSource = dataSource2;

// 示例3：顶点图标
const vertexIcon = engine.add(
    new mapvthree.Icon({
        width: 100,
        height: 100,
        vertexIcons: true,
        flat: false,
        mapSrc: 'default-marker.png',
        offset: [0, -30],
    })
);

const dataSource3 = mapvthree.GeoJSONDataSource.fromGeoJSON([
    {
        type: 'Feature',
        geometry: {
            type: 'Point',
            coordinates: [116.4252, 39.9162, 21],
        },
        properties: {
            icon: 'special-marker.png',
            color: 'red',
            size: 30,
        },
    }
]);

dataSource3.defineAttribute('color')
            .defineAttribute('size')
            .defineAttribute('icon');

vertexIcon.dataSource = dataSource3;

// 绑定事件
engine.event.bind(flatIcon, 'click', (e) => {
    console.log('贴地图标被点击', e);
});

engine.event.bind(icon3D, 'click', (e) => {
    console.log('3D图标被点击', e);
});