开始插件开发

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

为简单易懂, 本文中各步骤均基于插件脚手架maptalks-plugin项目, 如果你已经熟悉项目结构, 也可以定制自己的构建流程.

准备工作

• 安装node.js (>= 6.x)
• 安装浏览器(推荐Google Chrome)

创建项目

• 命名. 插件名字以maptalks.为前缀, 加上你选择的插件名字, 例如maptalks.myplugin
• 下载项目脚手架, 并解压, 目录结构如下:

    |-- .babelrc            # babel配置文件
    |-- .editorconfig
    |-- .eslintrc           # eslint配置
    |-- .gitignore
    |-- .npmignore
    |-- gulpfile.js         # gulp脚本程序
    |-- index.js            # 源代码主程序文件
    |-- karma.config.js     # karma配置文件
    |-- LICENSE             # LICENSE
    |-- package.json        # package.json 项目元数据
    |-- README.md       
    |-- dist                # 可执行js文件发布目录
    |-- test                # 测试程序目录
        |-- .eslintrc       # 测试程序eslint配置
        |-- test.js         # 测试程序

• 将解压后的目录改为你的插件的名字, 例如maptalks.myplugin
• 编辑package.json, 改写以下相关属性, 其具体含义和更多详情, 请查阅npm官方文档
  • name
  • version
  • description
  • license
  • repository
  • main
  • author
  • contributors

安装依赖

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

编写代码

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

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

// index.js
import * 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.js
export { default as MyLayer } from './src/MyLayer';
export { default as MyGeometry } from './src/MyGeometry';

自动构建(gulp脚本)

gulp是一个流行的自动化脚本程序, 可在gulpfile.js中创建各种自动化构建任务.

我们在脚手架中预制的任务如下:

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

$ gulp watch

• 运行一次自动测试

$ gulp test

• 重复运行自动化测试, 并监听源代码并自动重复测试

$ gulp tdd

• 编译生成可执行js文件, 调用uglify压缩混淆生成maptalks.myplugin.min.js, 并调用gzip生成maptalks.myplugin.min.js.gz

$ gulp minify

测试

自动测试

我们在脚手架中选择了mocha作为测试框架, 并选用karma作为Test Runner.

当然你也可以选择其他你喜欢的测试框架, 但还是推荐采用mocha + karma, 以和maptalks.js核心库以及其他插件项目保持一致.

按照惯例, 测试代码应放在'./test'目录下, 测试代码编写完后, 可以运行npm test来运行测试. 默认会采用Google Chrome作为测试浏览器, 你可以修改karma.config.js来选择其他浏览器运行测试.

npm test会先调用eslint做代码检查, 之后会调用gulp test运行测试代码. 所以你也可以单独运行gulp test来跳过eslint检查.

你还可以选择用gulp tdd来运行测试, 与gulp test不同的是, tdd在测试结束后, 不会退出测试, 而是会继续监听文件修改, 当源代码或测试代码有改动时, 会重新运行测试. tdd特别适合测试驱动开发.

浏览器端测试

如果你需要在浏览器端测试你的代码, 需要先把代码编译打包(脚手架中采用babel和rollup作为编译打包工具).

要编译打包源代码, 只需运行gulp build, 之后会在dist目录下生成maptalks.myplugin.js文件, 你可以在浏览器中引用此文件来在浏览器端测试你的代码逻辑.

<script type="text/javascript">../dist/maptalks.myplugin.js</script>

发布到github

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

git init
git add .
git commit

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

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

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

发布版本

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

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插件吗? 你可以把它克隆下来实际体验一下上述内容.

通知我们

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