maptalks插件开发

Maptalks 是一个基于 WebGL 的轻量级、可定制、跨平台的地图应用开发框架。要开发 Maptalks 插件，你需要遵循以下步骤：

1. 创建插件项目

2. 编写插件代码

3. 配置 package.json

4. 安装依赖并运行项目

现在，你可以在浏览器中查看你的插件效果了。如果一切正常，你可以继续完善你的插件功能。

开始插件开发

包括如何创建一个maptalks插件项目, 并把它发布到github和npm上与社区共享.

项目结构基于插件脚手架maptalks-plugin项目, 你也可以采用自己熟悉的项目结构.

本文内容包括如何创建一个maptalks插件项目, 并把它发布到github和npm上与社区共享.

本文中的项目结构基于插件脚手架maptalks-plugin项目, 你也可以采用自己熟悉的项目结构.

目录

准备工作

创建项目

安装依赖

编写代码

构建打包

测试

自动测试

浏览器端测试

发布到github

发布到npm

持续集成(CI)

通知我们

示例项目

准备工作

安装node.js (>= 6.x)

安装浏览器(推荐Google Chrome)

创建项目

命名. 插件名字以maptalks.为前缀, 加上你选择的插件名字, 例如maptalks.myplugin

下载项目脚手架, 并解压, 目录结构如下:

    |-- .babelrc            # babel配置文件    |-- .gitignore    |-- gulpfile.js         # gulp脚本程序    |-- index.js            # 源代码主程序文件    |-- package.json        # package.json 项目元数据    |-- dist                # 可执行js文件发布目录

将解压后的目录改为你的插件的名字, 例如maptalks.myplugin

编辑package.json, 改写以下相关属性, 其具体含义请查阅npm官方文档

name

version

description

license

repository

main

author

contributors

安装依赖

在项目目录下运行npm install, 安装所需的依赖.

编写代码

根目录中的index.js是必须的, 用来声明插件的公开方法(public API).

如果你的插件比较简单, 你可以将源码全部写在index.js中, 例如

// index.jsimport * as maptalks from "maptalks";export default class MyLayer extends maptalks.Layer {    ...}class MyLayerRenderer extends maptalks.renderer.CanvasRenderer {    ...}MyLayer.registerRenderer("canvas", MyLayerRenderer);

如果插件逻辑很复杂, 你可以将源代码组织在别的目录中(例如src), 并在index.js中引用并声明要公开的类或方法, 例如

// index.jsexport { default as MyLayer } from "./src/MyLayer";export { default as MyGeometry } from "./src/MyGeometry";

Lint检查

在编写代码时, 推荐使用ESLint来做代码检查, 目前流行编辑器, 如VSCode, 都对ESLint有完善的支持.

推荐使用maptalks的eslint规则.

构建打包

代码编写完毕后, 可以运行gulp来打包生成可执行js文件或其他的构建任务. 工程脚手架中默认采用babel和rollup编译打包, 并采用uglify压缩.

脚手架工程提供了gulpfile.js, 用来运行自动化任务, gulp是一个流行的自动化脚本程序.

我们在gulpfile中预制的任务如下:

编译生成ES5可执行js文件

$ gulp build

脚手架工程中默认采用babel和rollup作为编译打包工具, 在dist目录中会生成maptalks.myplugin.js可执行文件

压缩代码生成maptalks.myplugin.min.js, 并生成gzip文件maptalks.myplugin.min.js.gz

$ gulp minify

监听源代码文件并自动编译生成

$ gulp watch

测试

一个好的插件, 完善的测试是必不可少的.

maptalks.js和官方插件采用了mocha和karma作为测试程序框架. mocha和karma的具体配置与运行方法, 请参考相关教程. 当然你也可以选择其他测试框架.

脚手架工程中的maptalks-build-helpers默认添加了对karma的支持, 提供了TestHelper用来操作karma.

这里有一些测试相关的最佳实践:

测试代码一般放在"./test"目录下

在package.json的scripts中添加test命令来运行测试, 这样可以用npm test运行测试

gulpfile中预制了两个与测试相关的脚本任务

启动karma, 运行一次自动测试

$ gulp test

启动karma, 监听源代码并自动重复测试, 特别适合测试驱动开发.

$ gulp tdd

发布到github

如果你已经完成了插件, 并准备与全世界分享你的杰作, 现在可以开始你的第一次提交

git initgit add .git commit

然后去github上创建一个名为maptalks.myplugin的项目, 然后在命令行中添加github远程库地址并推送:

git remote add origin git@github.com:{USERNAME}/maptalks.myplugin.gitgit push -u origin master

Bingo! 快把你的github项目地址发送给你的好友们吧.

发布到npm

当你觉得到时候了, 可以正式发布你的插件的第一个版本时, 你可以通过以下步骤发布新版本:

npm version 0.1.0

一般我们采用语义化版本号来管理版本

然后推送到github上

git push origin master v0.1.0

推荐把dist中的执行文件打包为maptalks.myplugin-0.1.0.zip文件, 并将文件上传到github的releases中, 并在releases中说明版本改动, 方便用户下载和使用.

最后将插件发布到npm上, 这样其他人就能通过npm install maptalks.myplugin --save命令来安装你的插件了.

npm publish

持续集成(CI)

成功的开源软件一般都会采用CI服务对项目进行持续集成, 例如travis-ci, CircleCI, appveyor等, 他们对开源软件一般是免费的, 你可以阅读相关文章作进一步的了解.

通知我们

最后如果你愿意与大家分享你的作品, 请向我们提交你的插件信息, 我们会在官网插件栏目中展示并宣传你的项目.

示例项目

还记得之前提到过的maptalks.isects插件吗? 你可以把它克隆下来实际体验一下上述内容.

文章连接：https://github.com/maptalks/maptalks.js/wiki/%E5%BC%80%E5%A7%8B%E6%8F%92%E4%BB%B6%E5%BC%80%E5%8F%91