Skip to content

开始插件开发

Jump to bottom
Fu Zhen edited this page Dec 29, 2017 · 16 revisions

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

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

目录

  1. 准备工作
  2. 创建项目
  3. 安装依赖
  4. 编写代码
  5. 构建打包
  6. 测试
  7. 发布到github
  8. 发布到npm
  9. 持续集成(CI)
  10. 通知我们
  11. 示例项目

准备工作

创建项目

  • 命名. 插件名字以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.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';

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
$ gulp tdd

发布到github

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

git init
git add .
git commit

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

git remote add origin [email protected]:{USERNAME}/maptalks.myplugin.git
git 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插件吗? 你可以把它克隆下来实际体验一下上述内容.

Usage

Plugin Develop

使用

插件开发

其他

Clone this wiki locally