Leaflet 外掛程式撰寫指南

← 返回部落格文章列表

由 Vladimir Agafonkin 於 2013 年 6 月 28 日發佈

Leaflet 最棒的功能之一是其強大的外掛程式生態系統。「Leaflet 外掛程式頁面」列出了數十個很棒的外掛程式，而且每週都有更多外掛程式加入。

本指南列出了發佈符合 Leaflet 本身品質標準的 Leaflet 外掛程式的一些最佳實踐方法。也可以在儲存庫中找到。

呈現方式

儲存庫

存放 Leaflet 外掛程式的最佳位置是一個獨立的 GitHub 儲存庫。如果您為不同的用途建立外掛程式集合，請不要將它們放在同一個儲存庫中 — 通常在個別的儲存庫中使用小而獨立的外掛程式會更容易。

展示

發佈外掛程式時，最重要的事情是包含一個展示外掛程式功能的展示 — 這通常是人們首先會尋找的東西。

建立展示的最簡單方法是使用 GitHub Pages。一個好的起點是在您的儲存庫中建立一個 gh-pages 分支，並在其中加入一個 index.html 頁面 — 推送後，它將發佈為 http://<使用者>.github.io/<儲存庫>。

Readme

您需要的下一個東西是儲存庫根目錄中一個描述性的 README.md （或連結到具有類似內容的網站）。它至少應包含以下項目

外掛程式的名稱
對其功能的簡潔描述
需求
- Leaflet 版本
- 其他外部依賴項（如果有的話）
- 瀏覽器/裝置相容性
連結到展示
包含外掛程式的說明
簡單的使用程式碼範例
API 參考（方法、選項、事件）

授權

每個開源儲存庫都應包含授權。如果您不知道該為您的程式碼選擇哪種開源授權，MIT 授權和 BSD 2-Clause 授權都是不錯的選擇。您可以將其作為 LICENSE 檔案放入儲存庫中，或僅從 Readme 連結到授權。

程式碼

檔案結構

保持檔案結構的乾淨和簡單，不要在一個地方堆積大量檔案 — 讓新人容易在您的儲存庫中找到方向。

一個簡單外掛程式的簡化儲存庫如下所示

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。