Leaflet插件开发指南

PLUGIN-GUIDE.md

# Leaflet Plugin Authoring Guide

#枫叶插件权威指南

One of the greatest things about Leaflet is its powerful plugin ecosystem.

关于Leaflet最强大的一点就是它强大的插件生态系统。

The [Leaflet plugins page](http://leafletjs.com/plugins.html) lists dozens of awesome plugins, and more are being added every week.

Leaflet插件页面（http://leafletjs.com/plugins.html）列出了几十种很棒的插件，每周都会添加新的。

This guide lists a number of best practices for publishing a Leaflet plugin that meets the quality standards of Leaflet itself.

该指南列出了发布满足Leaflet质量标准的Leaflet插件的几个最强实践。

Contents目录

1. [Presentation](#presentation)

- [Repository](#repository)

- [Name](#name)

- [Demo](#demo)

- [Readme](#readme)

- [License](#license)

2. [Code](#code)

- [File Structure](#file-structure)

- [Code Conventions](#code-conventions)

- [Plugin API](#plugin-api)

3. [Publishing on NPM](#publishing-on-npm)

4. [Module Loaders](#module-loaders)

5. [Adding to the plugins list](#adding-to-the-plugins-list)

1.【演示文稿】（#演示文稿）
-[存储库]（#存储库）
-[姓名]（#姓名）
-[演示]（#演示）
-[自述]（#自述）
-[许可证]（#许可证）
2.[代码]（#代码）
-[文件结构]（#文件结构）
-[代码约定]（#代码约定）
-[插件API]（#插件API）
3.【NPM发布】（#NPM发布）
4.[模块加载器]（#模块加载器）
5.[添加到插件列表]（#添加到插件列表）

## Presentation

##演示文稿

### Repository

###存储库

The best place to put your Leaflet plugin is a separate [GitHub](http://github.com) repository.

放置Leaflet插件最好的地方就是一个单独的Github仓库。

If you create a collection of plugins for different uses,如果你为不同的用途创建了好几个插件，

don't put them in one repo —最好不要把它们都放在一个Github仓库里，

it's usually easier to work with small, self-contained plugins in individual repositories.因为单独的仓库工作起来更方便。

### Name姓名

Most existing plugins follow the convention of naming plugins (and repos) like this: `Leaflet.MyPluginName`.

You can use other forms (e.g. "leaflet-my-plugin-name"),

just make sure to include the word "Leaflet" in the name so that it's obvious that it's a Leaflet plugin.

大多数现有的插件都遵循这样命名插件（和repos）的惯例：`传单.MyPluginName`.
您可以使用其他形式（例如“传单我的插件名”），
只需确保在名称中包含“传单”一词，以便很明显它是一个传单插件。

### Demo

The most essential thing to do when publishing a plugin is to include a demo that showcases what the plugin does —

it's usually the first thing people will look for.

发布插件时最重要的事情是包含一个demo展示插件的功能&mdash；
这通常是人们首先要找的。

The easiest way to put up a demo is using [GitHub Pages](http://pages.github.com/).

而发布demo好的方式是通过Github Pages。

A good [starting point](https://help.github.com/articles/creating-project-pages-manually) is creating a `gh-pages` branch in your repo and adding an `index.html` page to it —

after pushing, it'll be published as `http://<user>.github.io/<repo>`.

### Readme

The next thing you need to have is a [good `README.md`](https://github.com/noffle/art-of-readme) in the root of the repo (or a link to a website with a similar content).

At a minimum it should contain the following items:

- name of the plugin

- a simple, concise description of what it does

- requirements

- Leaflet version

- other external dependencies (if any)

- browser / device compatibility

- links to demos

- instructions for including the plugin

- simple usage code example

- API reference (methods, options, events)

### License

Every open source repository should include a license.

If you don't know what open source license to choose for your code,

[MIT License](http://opensource.org/licenses/MIT) and [BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause) are both good choices.

You can either put it in the repo as a `LICENSE` file or just link to the license from the Readme.

## Code

### File Structure

Keep the file structure clean and simple,

don't pile up lots of files in one place —

make it easy for a new person to find their way in your repo.

A barebones repo for a simple plugin would look like this:

```

my-plugin.js

README.md

```

An example of a more sophisticated plugin file structure:

```

/src - JS source files

/dist - minified plugin JS, CSS, images

/spec - test files

/lib - any external libraries/plugins if necessary

/examples - HTML examples of plugin usage

README.md

LICENSE

package.json

```

### Code Conventions

Everyone's tastes are different, but it's important to be consistent with whatever conventions you choose for your plugin.

For a good starting point, check out [Airbnb JavaScript Guide](https://github.com/airbnb/javascript).

Leaflet follows pretty much the same conventions

except for using smart tabs (hard tabs for indentation, spaces for alignment)

and putting a space after the `function` keyword.

### Plugin API

Never expose global variables in your plugin.

If you have a new class, put it directly in the `L` namespace (`L.MyPlugin`).

If you inherit one of the existing classes, make it a sub-property (`L.TileLayer.Banana`).

Every class should have a factory function in camelCase, e.g. (`L.tileLayer.banana`).

If you want to add new methods to existing Leaflet classes, you can do it like this: `L.Marker.include({myPlugin: …})`.

Function, method, property and factory names should be in `camelCase`.

Class names should be in `CapitalizedCamelCase`.

If you have a lot of arguments in your function, consider accepting an options object instead

(putting default values where possible so that users don't need to specify all of them):

```js

// bad

marker.myPlugin('bla', 'foo', null, {}, 5, 0);

// good

marker.myPlugin('bla', {

optionOne: 'foo',

optionThree: 5

});

```

And most importantly, keep it simple. Leaflet is all about *simplicity*.

## Publishing on NPM

NPM (Node Packaged Modules) is a package manager and code repository for JavaScript. Publishing your module on NPM allows other developers to quickly find and install your plugin as well as any other plugins it depends on.

NPM has an excellent [developers guide](https://docs.npmjs.com/using-npm/developers.html) to help you through the process.

When you publish your plugin you should add a dependency on `leaflet` to your `package.json` file. This will automatically install Leaflet when your package is installed.

Here is an example of a `package.json` file for a Leaflet plugin.

```json

{

"name": "my-leaflet-plugin",

"version": "1.0.0",

"description": "A simple leaflet plugin.",

"main": "my-plugin.js",

"author": "You",

"license": "IST",

"peerDependencies": {

"leaflet": "^1.0.0"

}

```

If possible, do not commit your minified files (e.g. `dist`) to a repo; this can

lead to confusion when trying to debug the wrong file. Instead, use `npm` to

trigger a build/minification just before publishing your package with a

[`prepublish` script](https://docs.npmjs.com/misc/scripts#common-uses), for example:

```json

{

"name": "my-leaflet-plugin",

...

"scripts": {

"prepublish": "grunt build"

}

```

You can then use the [`.gitignore`](https://help.github.com/articles/ignoring-files/)

file to make sure the minified files are not versioned, and an

[empty `.npmignore`](https://docs.npmjs.com/misc/developers#keeping-files-out-of-your-package)

to ensure that they are published to NPM.

## Module Loaders

Module loaders such as [RequireJS](http://requirejs.org/) and [Browserify](http://browserify.org/) implement module systems like AMD (Asynchronous Module Definition) and CommonJS to allow developers to modularize and load their code.

You can add support for AMD/CommonJS loaders to your Leaflet plugin by following this pattern based on the [Universal Module Definition](https://github.com/umdjs/umd/blob/master/templates/returnExportsGlobal.js)

```js

(function (factory, window) {

// define an AMD module that relies on 'leaflet'

if (typeof define === 'function' && define.amd) {

define(['leaflet'], factory);

// define a Common JS module that relies on 'leaflet'

} else if (typeof exports === 'object') {

module.exports = factory(require('leaflet'));

}

// attach your plugin to the global 'L' variable

if (typeof window !== 'undefined' && window.L) {

window.L.YourPlugin = factory(L);

}

}(function (L) {

var MyLeafletPlugin = {};

// implement your plugin

// return your plugin when you are done

return MyLeafletPlugin;

}, window));

```

Now your plugin is available as an AMD and CommonJS module and can be used in module loaders like Browserify and RequireJS.

## Adding to the plugins list

Once your plugin is published, it is a good idea to add it to the [Leaflet plugins list](http://leafletjs.com/plugins.html). To do so:

* [Fork](https://help.github.com/articles/fork-a-repo/) the Leaflet repo.

* In the `docs/plugins.md` file, find the section your plugin should go in, and add a table row with information and links about your plugin.

* Commit the code to your fork.

* [Open a pull request](https://help.github.com/articles/creating-a-pull-request/) from your fork to Leaflet's original repo.

Once the pull request is done, a Leaflet maintainer will have a quick look at your

plugin and, if everything looks right, your plugin will appear in the list shortly thereafter.

Leaflet插件开发指南相关推荐

Hyperic HQ HQU 插件开发指南
推荐由Hyperic HQ 国内独家代理商北京铸锐数码科技有限公司提供.适用于Hyperic HQ开发人员,不但讲述了什么是HQU,如何开发Hyperic HQU插件还提供了示例.是Hyperic ...
BurpSuite插件开发指南之 Java 篇
Her0in · 2016/05/27 16:53 此文接着 <BurpSuite插件开发指南之 API 下篇> .在此篇中将会介绍如何使用Java 开发 BurpSuite 的插件,重点 ...
linux gret 文件内容,DataX插件开发指南.docx
Linux公社(LinuxlDC.com)于2006年9月25日注册并开通网站,Linux现在已经成为一种广受关注和支持的一种操作系统,IDC是互联网数据中心,LinuxlDC就是关于Linux的数 ...
奇舞周刊第 424 期：Sketch 插件开发指南
记得点击文章末尾的" 阅读原文 "查看哟~ 下面先一起看下本期周刊摘要吧~ 奇舞推荐 ■ ■ ■ Sketch 插件开发指南众所周知,Sketch 是 UED 设计工具,大多 ...
Qt Plugin插件开发指南（1）- 一般开发流程
Qt Plugin插件开发指南(1)- 一般开发流程 Date Author Version Note 2020.02.17 Dog Tao V1.0 整理后发表. 2020.12.10 Dog Ta ...
android 小插件开发,Android Gradle 插件开发指南
原标题:Android Gradle 插件开发指南 2018安卓巴士全球开发者论坛-成都站安卓巴士全球开发者论坛成都站即将开启! 作为Android开发者,你可能见过无数个apply plugin: ...
gstreamer插件开发指南(一)
翻译自:https://gstreamer.freedesktop.org/documentation/plugin-development/index.html 1 简介 GStreamer是一个非 ...
jQuery 插件开发指南
jQuery凭借其简洁的API,对DOM强大的操控性,易扩展性越来越受到web开发人员的喜爱,经常有人询问一些技巧,因此干脆写这么一篇文章给各位jQuery爱好者,算是抛砖引玉吧. 那么首先我们来简单 ...
illustrator插件开发指南pdf_Jenkins之pipeline开发工具
精华推荐:重磅发布 - 自动化框架基础指南pdf 新手写jenkins pipeline,最常见的是在jenkins里直接写,如下所示这种方式一般适用于初学者,用于了解pipeline. 这种方式对 ...

Leaflet插件开发指南

Leaflet插件开发指南相关推荐

最新文章

热门文章