折线
==

#### 场景介绍

本章节将向您介绍如何在地图上绘制折线、设置折线分段颜色、设置折线可渐变、绘制纹理。

折线主要用于展示步行、驾车、骑行等各类导航路线，同时可记录并呈现用户的运动轨迹及历史行程信息。此外，在区域边界标注、距离测量、管网线路布局以及活动路径可视化等场景中也有广泛应用。

5.0.3(15)开始，支持折线绘制纹理功能；26.0.0开始，支持折线添加文字。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/fc/v3/U55KJdFfSo2nggTPEVJQaA/zh-cn_image_0000002594829256.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073626Z&HW-CC-Expire=86400&HW-CC-Sign=0334EF8055C3869E5947693A828B351D711EE1C9FC5383899D1F1756311AD266 "点击放大")

#### 接口说明

添加折线功能主要由[MapPolylineOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#mappolylineoptions)、[addPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mapcomponentcontroller#addpolyline)和[MapPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline)提供，更多接口及使用方法请参见[接口文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline)。

| 接口名 | 描述 |
| :-- | :-- |
| [MapPolylineOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#mappolylineoptions) | 折线参数。 |
| [addPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mapcomponentcontroller#addpolyline)(options: [mapCommon.MapPolylineOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#mappolylineoptions)): Promise<[MapPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline)\> | 在地图上添加一条折线。 |
| [MapPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline) | 折线，支持更新和查询相关属性。 |

#### 开发步骤

#### \[h2\]添加折线

1.  导入相关模块。
    
    import { MapComponent, mapCommon, map } from '@kit.MapKit';
    import { AsyncCallback } from '@kit.BasicServicesKit';
    
2.  添加折线，在callback方法中创建初始化参数并新建[MapPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline)。
    
    @Entry
    @Component
    struct MapPolylineDemo {
      // ...
      private mapOptions?: mapCommon.MapOptions;
      private mapController?: map.MapComponentController;
      private callback?: AsyncCallback<map.MapComponentController>;
      private mapPolyline?: map.MapPolyline;
    
      aboutToAppear(): void {
        // 地图初始化参数
        this.mapOptions = {
          position: {
            target: {
              latitude: 31.98,
              longitude: 118.78
            },
            zoom: 14
          }
        };
        this.callback = async (err, mapController) => {
          if (!err) {
            this.mapController = mapController;
    
            // polyline初始化参数
            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
            }
            // 创建polyline
            try {
              this.mapPolyline = await this.mapController.addPolyline(polylineOption);
            } catch (e) {
              console.error(\`Failed to create the mapPolyline, code is：${e.code}, message is ${e.message}\`);
            }
          } else {
            console.error(\`Failed to initialize the map, code is：${err.code}, message is ${err.message}\`);
          }
        };
      }
    
      build() {
        // ...
          Stack() {
            Column() {
              MapComponent({ mapOptions: this.mapOptions, mapCallback: this.callback });
            }.width('100%')
          }.height('100%')
    
          // ...
      }
    }
    
    ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ee/v3/my9xhdcNTreKzmPFt4SX-w/zh-cn_image_0000002625188703.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073626Z&HW-CC-Expire=86400&HW-CC-Sign=E7FE7424FA7C941B4FEF9E442D3E57F3529629A966ED8A482CEFD4D403BB2005 "点击放大")
    

#### \[h2\]设置折线分段颜色

方法一：新建折线时在[MapPolylineOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#mappolylineoptions)的colors属性中设置折线分段颜色值。

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\],
  gradient: false
};

方法二：调用[MapPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline)的[setColors](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline#setcolors)()方法。

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

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/86/v3/JIrPXOfWSkKUu7iBoNaE6w/zh-cn_image_0000002625108847.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073626Z&HW-CC-Expire=86400&HW-CC-Sign=6DA22631BACB9A5A433F8C5BFC8323DDF2133C13ABC057624F3E304BF4612C9B "点击放大")

#### \[h2\]设置折线可渐变

方法一：[MapPolylineOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#mappolylineoptions)的gradient属性设置为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\],
  // 设置颜色折线可渐变
  gradient: true
};

方法二：调用[MapPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline)的[setGradient](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline#setgradient)()方法。

this.mapPolyline.setGradient(true);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8c/v3/Exn5FWnmRICNBLuOb82lkw/zh-cn_image_0000002594669330.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073626Z&HW-CC-Expire=86400&HW-CC-Sign=84CF93CD123C77E359E96F32AA35091D65E24536BA3A48AC9A0273EEF9A4BF4F "点击放大")

#### \[h2\]绘制纹理

方法一：新建折线时在[MapPolylineOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#mappolylineoptions)的customTexture属性设置折线纹理。

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,
  // 图标需存放在resources/rawfile目录下
  customTexture: 'icon/naviline\_arrow.png'
}

方法二：调用[MapPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline)的[setCustomTexture](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline#setcustomtexture)方法。

await this.mapPolyline.setCustomTexture('icon/naviline\_arrow.png');

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/76/v3/ldVNJf_RQ1CaCubxDKiR0Q/zh-cn_image_0000002594829258.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073626Z&HW-CC-Expire=86400&HW-CC-Sign=E0082C9B871B7C5D97711A5DBD26AF599DC8A1957463213CFCFB4B25C6EF3E96 "点击放大")

#### \[h2\]折线设置分段纹理

新建折线时利用在[MapPolylineOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-common#mappolylineoptions)的customTextures和customTextureIndexes属性设置折线分段纹理。

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

// ...
// 数组存放图片内容
let customTextures: (ResourceStr | image.PixelMap)\[\] = \[\];
// 图标存放在resources/rawfile，'icon/img.png'参数值传入rawfile文件夹下的相对路径
customTextures.push('icon/img.png');
customTextures.push('icon/img\_1.png');
let cusIndexNumber: number\[\] = \[\];
// cusIndexNumber数组长度与折线点数量必须相同，数组元素内容与customTextures下标相对应，图片从数组第二个元素开始选择
cusIndexNumber.push(0, 0, 1);
// polyline初始化参数
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,
  // 图标需存放在resources/rawfile目录下
  customTextures: customTextures,
  customTextureIndexes: cusIndexNumber
};
let mapPolyline = await this.mapController.addPolyline(polylineOption);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a7/v3/fUlsZp2TR0OprzEfXLdqQA/zh-cn_image_0000002625188705.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073626Z&HW-CC-Expire=86400&HW-CC-Sign=77AAA54EFEA8B20ADAA95B71743B66B82743F6556E0110CAE7BE6398C6B64F28 "点击放大")

#### \[h2\]折线添加文字

新建折线后可调用[MapPolyline](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline)的[addLineText](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline#addlinetext)方法给折线添加文字，通过[removeLineText](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/map-map-mappolyline#removelinetext)方法可删除折线文字。

// 添加折线文字
let textLine: mapCommon.LineText = {
  lineNames: \['第一段文字', '第二段文字'\],
  lineNameIndexes: \[0, 1, 1, 2\],
  nameOnRight: false,
  color: 0xFF000000,
  fontSize: 15,
  strokeColor: 0xFFFFFFFF,
  fontStyle: 0
};
this.mapPolyline.addLineText(textLine);

// 删除折线文字
this.mapPolyline.removeLineText();

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d9/v3/i73ppAFgQLi4fXLGxE8Fyg/zh-cn_image_0000002625108849.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073626Z&HW-CC-Expire=86400&HW-CC-Sign=7F22700D5E1D84A82CBA8E3D56D769E6426AC0DD40C3B09B6B63D3C497CD485A "点击放大")