拆一支台灣坡地外掛的原始碼
看外掛怎麼分層
前面幾個單元的範例都只有幾十行。真正在用的外掛動輒幾千行,第一次打開原始碼常不知道從哪裡讀起:哪個檔案是入口?計算寫在哪裡?為什麼同一個功能既有面板又有 Processing 工具?為什麼有一個檔案專門處理版本相容?
讀一支結構清楚的真實外掛,是學外掛架構最快的方式。本單元挑的是官方外掛庫上的 SWC Grid Slope(坵塊法坡度分析),它實作台灣《水土保持技術規範》的坵塊法坡度分析,題材與 M5 地質與坡地 直接相關(外掛的操作與坵塊法原理見 M5 該外掛的單元),而且同時支援 QGIS 3.22 到 4.99。本單元只看程式架構。
| 項目 | 內容 |
|---|---|
| 外掛 | SWC Grid Slope(坵塊法坡度分析),本單元閱讀的版本為 1.4.1 |
| 作者 | 黃敏郎(Min-Lang Huang),外掛庫維護者帳號 yoshihuang |
| 授權 | GNU GPL 第 2 版或任何更新版本(依外掛內 LICENSE 檔) |
| 外掛庫頁面 | plugins.qgis.org/plugins/swc_grid_slope |
| 原始碼庫 | github.com/yoshihuang/swc_grid_slope |
| metadata 版本範圍 | qgisMinimumVersion=3.22、qgisMaximumVersion=4.99 |
取得方式:在外掛庫頁面下載該版本的 zip,或到原始碼庫瀏覽。下載的 zip 放到一個新的空資料夾解壓再讀,只閱讀、不要用系統的 Python 直接執行裡面的檔案;要實際使用就從 QGIS 的外掛管理員安裝。
外掛 README 註明它是獨立開發的工具,不是主管機關(農業部農村發展及水土保持署)的官方產品,計算成果仍應由專業技師依規範檢核。
操作步驟(QGIS 4)
Section titled “操作步驟(QGIS 4)”-
先看檔案清單,猜每個檔案的角色。1.4.1 版的 Python 檔與大致行數:
檔案 行數 推測角色 __init__.py7 入口, classFactory()plugin.py57 外掛類別:選單、工具列、面板、註冊 Processing dock.py1014 右側面板介面 maptools.py380 地圖上畫框、平移、旋轉的互動工具 core.py1004 坡度計算核心 processing_provider.py158 Processing 提供者與演算法 layout.py、styles.py、save.py455、283、259 出圖版面、圖層樣式、存成 GeoPackage 專案 compat.py108 QGIS 3/4 版本相容 -
讀
metadata.txt。注意hasProcessingProvider=yes、category=Vector、changelog的寫法:每個版本一行,寫清楚改了什麼。1.2.4 版的 changelog 特別記錄了「為了通過 plugins.qgis.org 的安全與 Qt6 掃描」所做的修改,對照 05 發布到官方外掛庫 讀很有參考價值。 -
讀入口
__init__.py,跟 03 外掛骨架 的寫法相同,import 放在函式裡:# 節錄自 SWC Grid Slope 1.4.1 __init__.py(GPL-2.0-or-later)def classFactory(iface): # noqa: N802from .plugin import SwcGridSlopePluginreturn SwcGridSlopePlugin(iface) -
讀
plugin.py。重點有三:QAction用 try/except 兩段 import;initGui()先呼叫initProcessing()把演算法註冊進處理工具箱;面板(dock)在使用者第一次按按鈕時才建立。# 節錄自 SWC Grid Slope 1.4.1 plugin.py(GPL-2.0-or-later)try: # Qt6 / QGIS 4: QAction lives in QtGuifrom qgis.PyQt.QtGui import QActionexcept ImportError: # Qt5from qgis.PyQt.QtWidgets import QActionunload()依序關閉面板、移除選單與工具列、從 Processing 註冊表移除提供者,正好是initGui()的反向操作。 -
讀
core.py的開頭。檔頭說明寫著「不依賴任何 GUI 元件,可供 Processing 演算法共用」,坡度公式寫成一個小函式:# 節錄自 SWC Grid Slope 1.4.1 core.py(GPL-2.0-or-later)def slope_percent(n, dh, cell, pi=PI_314):"""S(%) = n·π·Δh / (8L) × 100"""if cell <= 0:return 0.0return n * pi * dh / (8.0 * cell) * 100.0這裡的
n是坵塊四邊與等高線的交點總數、dh是等高線間距、cell是坵塊邊長 L(10 或 25 公尺),PI_314是常數 3.14。外掛讓使用者選 π 用 3.14 或math.pi,README 說明預設 3.14 是為了與規範表列一致。 -
讀
processing_provider.py。它定義兩個類別:GridSlopeAlgorithm(繼承QgsProcessingAlgorithm)與GridSlopeProvider(繼承QgsProcessingProvider)。演算法的processAlgorithm()讀參數、檢查坐標系統,然後呼叫core.run_analysis(),計算本身完全交給core.py。對照 02 Processing 腳本 的結構看,會發現方法名稱與流程一模一樣。 -
最後讀
compat.py,看它怎麼讓同一份原始碼在 QGIS 3.22 到 4 都能跑(見下方「原理」)。
分層:介面、計算、Processing 各管各的
Section titled “分層:介面、計算、Processing 各管各的”plugin.py ──建立──▶ dock.py(面板)──呼叫──┐ │ maptools.py(畫框) │ │ ▼ └──註冊──▶ processing_provider.py ──呼叫──▶ core.py(純計算) │ layout.py/styles.py/save.py ◀── 計算結果這支外掛把「怎麼算」集中在 core.py,面板與 Processing 演算法都只是呼叫它的兩個入口。好處是:
- 面板上按「計算」與在工具箱、批次、模型裡執行,用的是同一份計算程式,結果一致。changelog 1.3.0 也特別說明自動搜尋與正式計算使用相同的交點計數方式。
- 計算核心不碰介面,要寫測試或改公式只需要看一個檔案。
- 面板延後建立(使用者按按鈕才建),QGIS 啟動時不必載入上千行的介面程式。
自己的外掛只要功能超過一個按鈕,就值得照這個方式拆:介面一層、計算一層、Processing 包一層。
用 Processing 提供者,而不只是腳本
Section titled “用 Processing 提供者,而不只是腳本”02 單元 的腳本放在使用者自己的 scripts 資料夾,換一台電腦就沒有。外掛透過 QgsProcessingProvider 註冊演算法,安裝外掛的人就自動在工具箱看到「坵塊法坡度分析」分組,也能用在批次與模型。metadata.txt 的 hasProcessingProvider=yes 就是告訴外掛庫與 QGIS 這支外掛有提供 Processing 演算法。
版本相容層的做法
Section titled “版本相容層的做法”外掛要支援 QGIS 3.22,可是 Qgis.ProcessingSourceType.VectorPolygon 這類全名列舉值在很舊的版本不存在;同時又要通過官方外掛庫的 Qt6 掃描,原始碼裡不能出現舊的未全名化寫法。compat.py 的解法是「先找新名稱,找不到再用字串查舊名稱」:
# 節錄自 SWC Grid Slope 1.4.1 processing_provider.py(GPL-2.0-or-later)_ST_TypeVectorPolygon = _modern_or_legacy( Qgis, "ProcessingSourceType.VectorPolygon", QgsProcessing, "TypeVectorPolygon")_modern_or_legacy() 用 getattr 依名稱逐段查找,舊名稱只以字串出現,所以掃描工具不會把它當成舊寫法。欄位型別也一樣,QGIS 3.38 以上用 QMetaType.Type,更舊的版本退回 QVariant。changelog 1.2.4 記錄了這次修改的目的:通過 plugins.qgis.org 的安全掃描(例如不再使用 try/except/pass,改為寫入 QGIS 訊息記錄)與 Qt6 掃描。
只需要支援 QGIS 3.40 以上與 QGIS 4 的新外掛,可以直接寫全名列舉值,不必做這層;要往前支援很舊的版本,才需要這種相容模組。
輸入檢查寫在演算法裡
Section titled “輸入檢查寫在演算法裡”processAlgorithm() 一開始就檢查:範圍圖層是經緯度坐標就丟出例外,提示改用公尺制投影坐標(例如 EPSG:3826);沒有圖徵、沒有等高線、方格範圍沒有完全包含計畫範圍,都直接中止並說明原因。坡度計算對坐標單位極度敏感,與其算出錯的數字,不如在第一步就擋下來。這是寫給別人用的工具最值得學的習慣。
| 症狀 | 原因 | 解法 |
|---|---|---|
| 讀到一半迷路,不知道某個函式從哪裡被呼叫 | 從最大的檔案(介面)開始讀 | 照「metadata → __init__ → plugin.py → 核心 → 介面」的順序;用編輯器的「尋找所有參考」追呼叫關係 |
| 引用他人程式碼後被要求下架或修改 | 引用大段程式、未標授權與出處,或把 GPL 程式碼放進不相容授權的專案 | 只節錄說明所需的片段,標明作者、版本、授權;改作並散布時,整個作品要遵守 GPL |
直接執行下載檔案裡的 .py 出錯或產生意外結果 |
外掛程式需要 QGIS 環境,且來源未經自己檢查 | 下載檔只閱讀;要使用就從外掛管理員安裝 |
| 照抄相容層後程式變得很難讀 | 新外掛其實不需要支援很舊的 QGIS | 先決定最低支援版本;3.40 以上可直接寫全名列舉值 |
huangyoshi 頻道有這支外掛的操作示範(本站 M5 也列為延伸影片),可以對照閱讀:先看外掛實際怎麼操作,再回來看程式怎麼實作。

- 在原始碼庫找出
GridSlopeAlgorithm.initAlgorithm()宣告了哪些輸入與輸出參數。- 檢查方式:列出的參數數目與名稱,和在 QGIS 處理工具箱打開該演算法時看到的輸入框一一對應。
- 用
slope_percent()的公式手算:交點數 n = 12、Δh = 1 公尺、L = 25 公尺、π = 3.14,S 是多少?- 檢查方式:答案應為 18.84%,與外掛 README 的範例一致。
- 畫出你自己外掛(或打算寫的外掛)的分層圖:哪些是介面、哪些是計算、哪些要包成 Processing 演算法。
- 檢查方式:計算層的函式不 import 任何
QtWidgets或iface。
- 檢查方式:計算層的函式不 import 任何
- SWC Grid Slope 外掛庫頁面:版本、相容範圍、標籤、changelog
- SWC Grid Slope 原始碼庫
- PyQGIS Developer Cookbook:Structuring Python Plugins
- PyQGIS Developer Cookbook:Releasing your plugin:「分析類外掛考慮做成 Processing 子外掛」的建議
- GNU General Public License v2.0