安装

NPM

核心库

npm i maptalks

import { Map, TileLayer } from "maptalks";

如果你要使用完整的webgl功能,你需要包maptalks-gl

npm i maptalks-gl

import { Map, TileLayer ,VectorTileLayer,GroupGLLayer,...} from "maptalks-gl";

这里解释下：
maptalks-gl 是一个包含了maptalks核心库的webgl版本,里面提供大量的webgl方面的功能，比如矢量切片，倾斜摄影，地形等，所以你需要完整的webgl功能时需要安装maptalks-gl

如果你不介意包体积的大小，一股脑的使用maptalks-gl即可

WARNING

maptalks-gl里已经自动集成了maptalks包了,是不需要自己主动去安装maptalks包的的

CDN

如果你喜欢以CDN的方式使用的话：

核心库

html

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/maptalks/dist/maptalks.css"
/>
<!-- 仅仅引入核心库 -->
<script
    type="text/javascript"
    src="https://cdn.jsdelivr.net/npm/maptalks/dist/maptalks.min.js"
></script>

<!-- 其他插件脚本 -->

webgl版本包

html

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/maptalks/dist/maptalks.css"
/>
<!-- 引入完成的功能包括webgl -->
<script
    type="text/javascript"
    src="https://cdn.jsdelivr.net/npm/maptalks-gl/dist/maptalks-gl.min.js"
></script>
<!-- 其他插件脚本 -->

WARNING

众所周知的原因，用国外的CDN是不可靠的，所以使用时请注意网络原因带来的风险，条件允许的情况下可以自建CDN,或者把脚本下载放到自己的项目里

手动下载相关脚本
或者利用npm，然后去node_modules里手动拷贝相关脚本资源

生产环境注意

生产环境里一定要记住要锁版本，体现在：

用cdn要记得带上版本号
npm 的方式记得锁住版本号

以免：

新版本可能出现bug,或者出现不兼容的情况
多人协作项目，如果不锁住npm version,可能导致不同的用户电脑上安装不同的版本包，导致出现bug和不兼容情况

WARNING

生产环境里一定要记住要锁版本

大家容易犯的错误

大家很容易从核心库maptalks里去引入maptalks-gl或者其他插件里的类，这是错误的，具体代码表现在

//注意 maptalks包里没有VectorTileLayer
import { VectorTileLayer,GroupGLLayer,... } from "maptalks";

import * as maptalks from "maptalks";
//注意 maptalks包里没有VectorTileLayer
const vt = new maptalks.VectorTileLayer("vt0", {
    urlTemplate: "https://tiles.maptalks.com/test/{z}/{x}/{y}.mvt",
});

DANGER

这些是错误的代码,这里做示范作用

ESM的方式正确用法

从每个包里到处自己的变量即可,这个是标准的也是最佳的EMS的使用方式

import {
    Map,
    GroupGLLayer,
    VectorTileLayer,
    GLTFMarker,
    GLTFLayer,
    PolygonLayer,
} from "maptalks-gl";
import { ThreeLayer, BaseObject } from "maptalks.three";

const map = new Map("map", {
    center: [0, 0],
    zoom: 2,
});
const vtLayer = new VectorTileLayer("vt", {
    urlTemplate: "http://tile.maptalks.com/test/planet-single/{z}/{x}/{y}.mvt",
});

const groupLayer = new GroupGLLayer("group", [vtLayer]).addTo(map);

const gltfLayer = new GLTFLayer("gltflayer");
groupLayer.addLayer(gltfLayer);

const polygonLayer = new PolygonLayer("polygonlayer");
groupLayer.addLayer(polygonLayer);
//other layers

如果你喜欢ESM的方式，就使用这个方式就行

同学的疑问?

有的同学会问:我从官方的例子看代码明明是这样写的啊？ ❓ ❓ ❓ ❓ ❓

const map = new maptalks.Map("map", {
    center: [-74.01, 40.71],
    zoom: 16,
});

const vtLayer = new maptalks.VectorTileLayer("vt", {
    urlTemplate: "http://tile.maptalks.com/test/planet-single/{z}/{x}/{y}.mvt",
    style: "/resources/styles/maptalks-common/style.json",
});

const threeLayer = new maptalks.ThreeLayer("t");

和你说的不一样，你给我解释解释呢？
这因为maptalks的例子是是以传统的script标签引入的umd包, 表现在maptalks和其插件导出的命名空间都是maptalks,如果你是jquery时代的老程序员应该立马就懂

html

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/maptalks/dist/maptalks.css"
/>
<!-- 引入完成的功能包括webgl -->
<script
    type="text/javascript"
    src="https://cdn.jsdelivr.net/npm/maptalks-gl/dist/maptalks-gl.min.js"
></script>

<script src="
https://cdn.jsdelivr.net/npm/maptalks.routeplayer@1.0.0-rc.2/dist/maptalks.routeplayer.min.js
"></script>

<script src="
https://cdn.jsdelivr.net/npm/maptalks.three@0.38.3/dist/maptalks.three.min.js
"></script>

<!-- 其他插件脚本 -->

maptalks相关的插件打包时导出的也是maptalks命名空间和核心库的maptalks进行了合并了，大意代码如下

const maptalks = Object.assign({}, maptalksCore, maptalksGL);

DANGER

这个只是个大意的代码，不是实际的命名空间合并代码,这里只是用来解释为什么你能从maptalks命名空间下拿到插件里的变量

更多详情参阅 rollup extend config

maptalks的插件导出的命名空间一般都是maptalks,当在html页面里直接使用umd脚本时，会自动和核心库的命名空间合并的

比如three插件,导出的 BaseObject,ThreeLayer等会自动挂载到maptalks命名空间如果你希望以ESM的方式使用：

import { BaseObject, ThreeLayer } from "maptalks.three";

如果你犯这种错误，说明你关于模块化，ESM,UMD包等概念不清楚，需要自己去系统的学习这些名词和其具体的含义, 因为这个前端基础的知识，不属于maptalks范畴的知识，这里就不做详细介绍了

常用的插件集合

插件	描述	仓库地址	作者
maptalks.three	threejs插件包	github	maptalks
maptalks.snap	绘制编辑吸附包	github	maptalks
maptalks.esri	arcgis服务加载插件包	github	maptalks
maptalks.mapboxgl	mapbox底图插件包	github	maptalks
maptalks.routeplayer	轨迹播放插件	github	maptalks
maptalks.tileclusterlayer	点的瓦片聚合包	github	deyihu
maptalks.modelcontrol	模型拖拽缩放插件包	github	deyihu
maptalks.mapsync	地图视角同步控件	github	deyihu
maptalks.tiflayer	加载tif文件	github	deyihu
maptalks.heatlayer	热区图插件	github	deyihu
maptalks.query	maptalks 图层数据查询插件	github	deyihu
maptalks.tileclip	maptalks 瓦片剪裁工具	github	deyihu

TIP

这些包的umd包导出的命名空间都是maptalks,会和核心库自动合并的,以three插件为例, 导出的ThreeLayer会自动挂载到window.maptalks下
如果你是以ESM的方式使用，那就是

import { Map } from "maptalks";
import { ThreeLayer } from "maptalks.three";
import { HeatLayer } from "maptalks.heatlayer";
// .....

传统的script标签引入

向我这样的老的同学可能喜欢在页面直接引入对应的umd包

html

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/maptalks/dist/maptalks.css"
/>
<!-- 引入完成的功能包括webgl -->
<script
    type="text/javascript"
    src="https://cdn.jsdelivr.net/npm/maptalks-gl/dist/maptalks-gl.js"
></script>

<script src="
https://cdn.jsdelivr.net/npm/maptalks.routeplayer@1.0.0-rc.2/dist/maptalks.routeplayer.min.js
"></script>

<!-- 其他插件脚本,如果需要 -->

的方法引入，也是可以的，尤其是强GIS项目，反正每个页面都用到地图，打包显得没有任何意义(个人见解)

这些公共的类库又不改其代码，每次都打包浪费时间和资源
打包应该仅限于自己的业务代码，而不是这些我们根本不会去动其源码的第三方库

不打包html页面直接写

在html页面的script标签里直接写代码即可，maptalks-study的例子都是这么干的，之所以这么干是因为例子都比较简单，直接写直接调试，省去打包等繁杂的流程

html

<script>
    const map = new maptalks.Map("map", {
        center: [116.45266161, 39.86656647],
        zoom: 8,
        baseLayer: new maptalks.TileLayer("base", {
            urlTemplate:
                "https://webrd01.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z}",
            subdomains: ["a", "b", "c", "d"],
            // attribution: "&copy; <a href='http://osm.org'>OpenStreetMap</a> contributors, &copy; <a href='https://carto.com/'>CARTO</a>",
        }),
    });
    const baseLayer = map.getBaseLayer();
    const layer = new maptalks.VectorLayer("layer").addTo(map);
    const point = new maptalks.Marker(map.getCenter()).addTo(layer);

    var params = {
        baseLayer: true,
        layer: true,
    };
    var gui = new lil.GUI({ width: 250 });
    gui.add(params, "baseLayer")
        .name("底图控制")
        .onChange(function () {
            if (params.baseLayer) {
                map.setBaseLayer(baseLayer);
            } else {
                map.removeBaseLayer();
            }
        });
    gui.add(params, "layer")
        .name("业务图层控制")
        .onChange(function () {
            if (params.layer) {
                map.addLayer(layer);
            } else {
                map.removeLayer(layer);
            }
        });
</script>

用ESM的方式并打包

可以的，目前市面上的打包工具都提供了了 externals功能的

下面我们来演示个例子，例子里包含了引入maptalks的一些插件了

安装 maptalks-gl

npm i maptalks-gl

html页面引入相关脚本呢

html

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/maptalks/dist/maptalks.css"
/>
<!-- 引入完成的功能包括webgl -->
<script
    type="text/javascript"
    src="https://cdn.jsdelivr.net/npm/maptalks-gl/dist/maptalks-gl.min.js"
></script>
<script src="
https://cdn.jsdelivr.net/npm/three@0.138.0/build/three.min.js
"></script>
<script src="
https://cdn.jsdelivr.net/npm/maptalks.three@0.38.3/dist/maptalks.three.min.js
"></script>

配置打包工具的externals

webpack(一般是自己搭建的脚手架/React/Angular等)

//weppack.config.js

externals: {

    "maptalks-gl": "maptalks",
    "maptalks": "maptalks",
    'three': 'THREE',
    'maptalks.three': 'maptalks',
    //....
}

vue-cli

//vue.config.js

configureWebpack: {
    externals: {
        "maptalks-gl": "maptalks",
        "maptalks": "maptalks",
        'three': 'THREE',
        'maptalks.three': 'maptalks'
            //....
    },
}

vitejs

//vite.config.js

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { viteExternalsPlugin } from "vite-plugin-externals";

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [
        vue(),
        viteExternalsPlugin({
            "maptalks-gl": "maptalks",
            maptalks: "maptalks",
            three: "THREE",
            "maptalks.three": "maptalks",
            //....
        }),
    ],
});

这样在业务代码里我们既可以愉快的写

import { Map, TileLayer, GroupGLLayer } from "maptalks-gl";
import * as THREE from "three";
import { ThreeLayer, BaseObject } from "maptalks.three";
import { HeatLayer } from "maptalks.heatlayer";

const map = new Map("map", {
    //   ...
});

// ....

也可以不去打包maptalks的生态包了，项目打包时间将大大缩短了

maptalks-vite-externals 例子工程

CNPM上找不到最新版本的问题

有的同学会将NPM的源指向阿里的npmmirror.com,由于npmmirror.com从npm仓库同步会存在一定的延迟，所有有时你可能不能安装到最新的版本，需要你去npmmirror.com上去手动同步下就可以了

安装 ​

NPM ​

CDN ​

生产环境注意 ​

大家容易犯的错误 ​

ESM的方式正确用法 ​

同学的疑问? ​

常用的插件集合 ​

传统的script标签引入 ​

不打包html页面直接写 ​

用ESM的方式并打包 ​

CNPM上找不到最新版本的问题 ​

安装

NPM

CDN

生产环境注意

大家容易犯的错误

ESM的方式正确用法

同学的疑问?

常用的插件集合

传统的script标签引入

不打包html页面直接写

用ESM的方式并打包

CNPM上找不到最新版本的问题