Leaflet 插件编写指南

← 返回博客文章列表

发布于 2013 年 6 月 28 日作者 Vladimir Agafonkin

Leaflet 最棒的一点就是它强大的插件生态系统。 Leaflet 插件页面上列出了数十个很棒的插件，而且每周都有新的插件加入。

本指南列出了发布符合 Leaflet 自身质量标准的 Leaflet 插件的一些最佳实践。也可在仓库中找到。

展示

仓库

将 Leaflet 插件放到一个单独的 GitHub 仓库是最合适的地方。如果你创建了一系列用于不同用途的插件，不要将它们放在一个仓库中 - 通常将小型、自包含的插件放在单独的仓库中更容易管理。

演示

发布插件时最重要的是包含一个展示插件功能的演示 - 通常是人们首先会寻找的内容。

使用 GitHub Pages 创建演示的最简单方法。一个很好的起点是在你的仓库中创建一个 gh-pages 分支，并在其中添加一个 index.html 页面 - 推送之后，它将被发布为 http://<user>.github.io/<repo>。

自述文件

接下来你需要的是在仓库根目录中添加一个描述性的 README.md（或指向包含类似内容的网站的链接）。至少应该包含以下内容

插件的名称
对插件功能的简单、简洁的描述
需求
- Leaflet 版本
- 其他外部依赖项（如果有）
- 浏览器/设备兼容性
指向演示的链接
包含插件的说明
简单的使用代码示例
API 参考（方法、选项、事件）

许可证

每个开源仓库都应该包含一个许可证。如果你不知道为你的代码选择哪个开源许可证， MIT 许可证和 BSD 2-Clause 许可证都是不错的选择。你可以将它作为 LICENSE 文件放在仓库中，也可以直接从自述文件中链接到许可证。

代码

文件结构

保持文件结构简洁明了，不要将大量文件堆放在一个地方 - 这样方便新人更容易找到他们需要的东西。

一个简单插件的简单仓库看起来像这样

my-plugin.js
README.md

一个更复杂的插件的文件结构示例

/src        JS source files
/dist       minified plugin JS, CSS, images
/spec       test files
/examples   HTML examples of plugin usage
README.md
LICENSE
package.json

代码规范

每个人的品味都不一样，但重要的是对你为插件选择的任何规范保持一致。

为了有一个好的起点，请查看 Airbnb JavaScript 指南。 Leaflet 遵循几乎相同的规范，除了使用智能制表符（用于缩进的硬制表符，用于对齐的空格）以及在 function 关键字后加一个空格。

插件 API

永远不要在插件中公开全局变量。
如果你有一个新类，请直接将其放在 L 命名空间中 (L.MyPlugin)。
如果你继承了现有类之一，请将其作为一个子属性 (L.TileLayer.Banana)。
如果你想为现有的 Leaflet 类添加新方法，你可以这样做： L.Marker.include({myPlugin: …})。

函数、方法和属性名称应该使用 camelCase。
类名应该使用 CapitalizedCamelCase。

如果你在函数中有很多参数，请考虑接受一个选项对象（尽可能设置默认值，这样用户就不必指定所有参数）

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

// good
marker.myPlugin('bla', {
	optionOne: 'foo',
	optionThree: 5
});

最重要的是，保持简单。 Leaflet 的核心是 *简洁*。

干杯！
Vladimir。