xieziyu / ngx-amap

angular 2+ component for AMap (Gaode map)

ngx-amap

• 在线演示
• 模块文档
• CHANGELOG

ngx-amap 是为在Angular(ver >= 2.x)项目中便捷、高效地使用高德地图Javascript API而构建的组件集合

目录

1. 最新进度
2. 安装
3. 使用
4. 配置
5. 加载插件
6. 加载UI库
7. 指令和服务
8. 本地演示

最新进度

2020.02.06: v3.0.0

• NEW:

  • 支持 AMapUI 库，可通过 AmapUILoaderService 服务加载使用，部分 UI 组件也封装成了指令，如：ui-awesome-marker
  • 提供加载插件服务：AmapPluginLoaderService，部分常用插件已封装成了指令，如：amap-tool-bar

• BREAKING CHANGES:

  • 重写了整体的封装架构，不再使用 Promise 封装，全部使用 Observable
  • @Output 事件命名统一调整为: 包含na前缀
  • 不再提供 Getter 和 Setter 的 Wrapper，建议直接调用 amap 原生对象的方法
  • 移除 amap 相关的类型定义，引入 @types/amap-js-api

安装

npm install -S ngx-amap
npm install -D @types/amap-js-api
# 地图插件类型定义可按需安装：
npm install -D @types/amap-js-api-tool-bar
npm install -D @types/amap-js-api-heatmap
npm install -D @types/amap-js-api-autocomplete
npm install -D @types/amap-js-api-place-search
npm install -D @types/amap-js-api-driving
npm install -D @types/amap-js-api-transfer
# ...

使用

1. import NgxAmapModule

   • Example:

     import { NgxAmapModule } from 'ngx-amap';
     
     @NgModule({
       imports: [
         ...,
         NgxAmapModule.forRoot({
           apiKey: '你申请的key'
         })
       ],
       ...
     })
     export class AppModule { }

2. 使用 ngx-amap 组件时必须给定高度.

   • 简单示例:

     • html:

     <ngx-amap class="demo-map"></ngx-amap>

     • css:

     .demo-map {
       height: 400px;
     }

3. 可以配合使用其他指令和组件。例如 amap-marker 可以在地图中画覆盖物：点标记。

   • 简单示例:

     • html:

     <ngx-amap class="demo-map" [center]="[116.397428, 39.90923]">
       <amap-marker [position]="[116.397428, 39.90923]" (markerClick)="onMarkerClick($event)"></amap-marker>
     </ngx-amap>

4. 加入地图控件的方法也很简单，例如：amap-tool-bar

   • 简单示例:

     • html:

     <ngx-amap class="demo-map">
       <amap-tool-bar></amap-tool-bar>
     </ngx-amap>

5. 由于采用了懒加载高德 JS 库，所以如果需要直接使用全局 AMap 对象的方法，需要等加载完成后使用。

   • 可以在组件 <ngx-amap> (naReady) 事件之后使用 AMap
   • 也可以使用 AMapLoaderService 的 load 方法

   import { AMapLoaderService } from  'ngx-amap';
   
   @Component({
     ...
   })
   export class MyComponent implements OnInit {
     constructor(private loader: AMapLoaderService) {}
   
     ngOnInit() {
       this.loader.load().subscribe(() => {
         // 高德 JS SDK 加载完毕
         const dis = AMap.GeometryUtil.distance([123, 456], [123, 456]);
         console.log(dis: ${dis});
       })
     }
   }

更多用法和事件，请参看演示和文档。

配置

我们可以通过NgxAmapModule的forRoot()方法设置ngx-amap。它可以接受以下参数传入：

{
  apiKey: string;   // 高德地图的开发者license key
  apiVersion?: string;  // [可选], api 版本, 默认是 '1.4.15'
  uiVersion?: string;   // [可选], ui 库版本, 默认是 '1.0.11'
  protocol?: 'http' | 'https'; // [可选], api 路径协议类型
  debug?: boolean; // [可选], 是否开启调试模式
  debugTags?: string; // [可选], 开启调试的 TAG, '*' 为全部
}

加载插件

部分常用插件如: AMap.ToolBar 已封装成指令，可直接使用。

插件可通过服务：AmapPluginLoaderService 加载后使用。若插件需要 mapObject，可配合 ngx-amap 的 (naReady) 事件一起使用。

查看示例

加载UI库

部分常用 UI 库如: AMapUI.SimpleMarker 已封装成指令，可直接使用。

UI 库可通过服务：AmapUILoaderService 加载后使用。若 UI 需要使用 mapObject，可配合 ngx-amap 的 (naReady) 事件一起使用。

查看示例

指令和服务

NGX-AMAP	类型	高德地图	类	演示示例
ngx-amap	Component	地图	AMap.Map	demo
amap-text	Component	覆盖物：文本标记	AMap.Text	demo
amap-info-window	Component	信息窗体	AMap.InfoWindow	demo
amap-marker	Directive	覆盖物：点标记	AMap.Marker	demo
amap-polyline	Directive	覆盖物：折线	AMap.Polyline	demo
amap-polygon	Directive	覆盖物：多边线	AMap.Polygon	demo
amap-bezier-curve	Directive	覆盖物：贝塞尔曲线	AMap.BezierCurve	demo
amap-ellipse	Directive	覆盖物：椭圆	AMap.Ellipse	demo
amap-circle	Directive	覆盖物：圆	AMap.Circle	demo
amap-circle-marker	Directive	覆盖物：圆点标记	AMap.CircleMarker	demo
amap-rectangle	Directive	覆盖物：矩形	AMap.Rectangle	demo
amap-tool-bar	Directive	工具条插件	AMap.ToolBar	demo
amap-marker-clusterer	Directive	点聚合插件	AMap.MarkerClusterer	demo
amap-heatmap	Directive	图层：热力图	AMap.Heatmap	demo
ui-simple-marker	Directive	UI 简单标记	AMapUI.SimpleMarker	demo
ui-awesome-marker	Directive	UI 字体图标标注	AMapUI.AwesomeMarker	demo
AmapPluginLoaderService	Service	插件加载	AMap.plugin	demo
AmapUILoaderService	Service	UI 库加载服务	AMapUI.loadUI	demo
AmapAutocompleteService	Service	关键字提示服务	AMap.Autocomplete	demo

本地演示

1. clone 当前 repo 到本地
2. 修改 src/app/app.module.ts 以使用自己的的高德API key
3. 启动demo，浏览器打开: localhost:8080

npm install
npm run demo
# or
yarn
yarn demo