目录

MapPolyline

Use Cases

This section describes how to draw a MapPolyline on a map, and set the segment colors, enable gradient, and draw the texture for the MapPolyline.

A MapPolyline is mainly used to display various navigation routes such as walking, driving, and cycling routes. It can also record and display users' workout trajectories and historical routes. It is also widely used in scenarios such as region boundary marking, distance measurement, utility network layout, and activity route visualization.

Starting from 5.0.3(15), the function of drawing the texture for the MapPolyline is supported. Starting from 26.0.0, the function of adding text to the MapPolyline is supported.

API Description

The MapPolyline adding function is mainly provided by MapPolylineOptions, addPolyline, and MapPolyline. For more information about the APIs, please refer to API Reference.

API Description
MapPolylineOptions MapPolyline parameters.
addPolyline(options: mapCommon.MapPolylineOptions): Promise<MapPolyline> Adds a MapPolyline on a map.
MapPolyline MapPolyline. This API supports updating and querying MapPolyline attributes.

Development Procedure

[h2]Adding a MapPolyline

  1. Import required modules.

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

  2. Add a MapPolyline. Create initialization parameters in the callback method, and create a MapPolyline.

    @Entry
@Component
struct MapPolylineDemo {
  // ...
  private mapOptions?: mapCommon.MapOptions;
  private mapController?: map.MapComponentController;
  private callback?: AsyncCallback<map.MapComponentController>;
  private mapPolyline?: map.MapPolyline;

  aboutToAppear(): void {
    // Map initialization parameters.
    this.mapOptions = {
      position: {
        target: {
          latitude: 31.98,
          longitude: 118.78
        },
        zoom: 14
      }
    };
    this.callback = async (err, mapController) => {
      if (!err) {
        this.mapController = mapController;

        // MapPolyline initialization parameters.
        let polylineOption: mapCommon.MapPolylineOptions = {
          points: [
            { longitude: 118.78, latitude: 31.975 },
            { longitude: 118.78, latitude: 31.982 },
            { longitude: 118.79, latitude: 31.985 }
          ],
          clickable: true,
          startCap: mapCommon.CapStyle.BUTT,
          endCap: mapCommon.CapStyle.BUTT,
          geodesic: false,
          jointType: mapCommon.JointType.BEVEL,
          visible: true,
          width: 10,
          zIndex: 10,
          gradient: false
        }
        // Create a MapPolyline.
        try {
          this.mapPolyline = await this.mapController.addPolyline(polylineOption);
        } catch (e) {
          console.error(`Failed to create the mapPolyline. Code: ${e.code}; message: ${e.message}`);
        }
      } else {
        console.error(`Failed to initialize the map. Code: ${err.code}; message: ${err.message}`);
      }
    };
  }

  build() {
    // ...
      Stack() {
        Column() {
          MapComponent({ mapOptions: this.mapOptions, mapCallback: this.callback });
        }.width('100%')
      }.height('100%')

      // ...
  }
}

[h2]Setting the Colors of MapPolyline Segments

Method 1: During MapPolyline creation, set the color values of the MapPolyline segments through the colors attribute in MapPolylineOptions.

let polylineOption: mapCommon.MapPolylineOptions = {
  points: [
    { longitude: 118.78, latitude: 31.975 },
    { longitude: 118.78, latitude: 31.982 },
    { longitude: 118.79, latitude: 31.985 }
  ],
  clickable: true,
  startCap: mapCommon.CapStyle.BUTT,
  endCap: mapCommon.CapStyle.BUTT,
  geodesic: false,
  jointType: mapCommon.JointType.BEVEL,
  visible: true,
  width: 10,
  zIndex: 10,
  // Set the color.
  colors: [0xffffff00, 0xff000000],
  gradient: false
};

Method 2: Call the setColors() method of MapPolyline.

let colors = [0xffffff00, 0xff000000];
this.mapPolyline.setColors(colors);

[h2]Enabling Gradient for a MapPolyline

Method 1: Set the gradient attribute of MapPolylineOptions to true.

let polylineOption: mapCommon.MapPolylineOptions = {
  points: [
    { longitude: 118.78, latitude: 31.975 },
    { longitude: 118.78, latitude: 31.982 },
    { longitude: 118.79, latitude: 31.985 }
  ],
  clickable: true,
  startCap: mapCommon.CapStyle.BUTT,
  endCap: mapCommon.CapStyle.BUTT,
  geodesic: false,
  jointType: mapCommon.JointType.BEVEL,
  visible: true,
  width: 10,
  zIndex: 10,
  colors: [0xffffff00, 0xff000000],
  // Enable gradient for the MapPolyline.
  gradient: true
};

Method 2: Call the setGradient() method of MapPolyline.

this.mapPolyline.setGradient(true);

[h2]Drawing Texture

Method 1: During MapPolyline creation, set the customTexture attribute of MapPolylineOptions.

let polylineOption: mapCommon.MapPolylineOptions = {
  points: [
    { latitude: 32.220750, longitude: 118.788765 },
    { latitude: 32.120750, longitude: 118.788765 },
    { latitude: 32.020750, longitude: 118.788765 },
    { latitude: 31.920750, longitude: 118.788765 },
    { latitude: 31.820750, longitude: 118.788765 }
  ],
  clickable: true,
  jointType: mapCommon.JointType.DEFAULT,
  width: 20,
  // The icon must be stored in the resources/rawfile directory.
  customTexture: 'icon/naviline_arrow.png'
}

Method 2: Call the setCustomTexture method of MapPolyline.

await this.mapPolyline.setCustomTexture('icon/naviline_arrow.png');

[h2]Setting Textures for Segments of a MapPolyline

You can set the MapPolyline segment textures through the customTextures and customTextureIndexes attributes of MapPolylineOptions during MapPolyline creation.

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

// ...
// Store images in an array.
let customTextures: (ResourceStr | image.PixelMap)[] = [];
// Icons are stored in resources/rawfile. The passed value icon/img.png indicates the relative path of the icon file within resources/rawfile.
customTextures.push('icon/img.png');
customTextures.push('icon/img_1.png');
let cusIndexNumber: number[] = [];
// The length of the cusIndexNumber array must be the same as the number of MapPolyline points. The array element content corresponds to the subscripts of customTextures. Images are stored from the second element in the array.
cusIndexNumber.push(0, 0, 1);
// MapPolyline initialization parameters.
let polylineOption: mapCommon.MapPolylineOptions = {
  points: [
    { longitude: 118.78, latitude: 31.975 },
    { longitude: 118.78, latitude: 31.982 },
    { longitude: 118.79, latitude: 31.985 }
  ],
  clickable: true,
  startCap: mapCommon.CapStyle.BUTT,
  endCap: mapCommon.CapStyle.BUTT,
  jointType: mapCommon.JointType.BEVEL,
  width: 30,
  // The icon must be stored in the resources/rawfile directory.
  customTextures: customTextures,
  customTextureIndexes: cusIndexNumber
};
let mapPolyline = await this.mapController.addPolyline(polylineOption);

[h2]Adding Text to a MapPolyline

After creating a MapPolyline object, you can call the addLineText method of MapPolyline to add text to the MapPolyline, and call the removeLineText method to remove the text from the MapPolyline.

// Add text to a MapPolyline.
let textLine: mapCommon.LineText = {
  lineNames: ['First text segment', 'Second text segment'],
  lineNameIndexes: [0, 1, 1, 2],
  nameOnRight: false,
  color: 0xFF000000,
  fontSize: 15,
  strokeColor: 0xFFFFFFFF,
  fontStyle: 0
};
this.mapPolyline.addLineText(textLine);
// ...

// Remove the text from the MapPolyline.
this.mapPolyline.removeLineText();