最小可載入的 QGIS 外掛
要有哪些檔案
Processing 腳本適合「輸入→計算→輸出」的工具,但有些需求它做不到:要在地圖上拖拉畫框、要一個常駐在側邊的面板、要在選單裡放一組按鈕。這時就要寫外掛。
第一次寫外掛最常卡在:
- 檔案放進資料夾了,外掛管理員 Plugin Manager 裡卻找不到。
- 找得到,但勾選啟用時跳出一長串 Python 錯誤。
- 停用外掛後選單項目還留著,再啟用就出現兩個。
這些都跟外掛的最小結構與載入流程有關。
不需要地理資料,只需要一個文字編輯器。開始前先確認外掛資料夾的位置:
-
設定 Settings ▸ 使用者設定檔 User Profiles ▸ 開啟使用中的設定檔資料夾 Open Active Profile Folder。
-
在開啟的資料夾裡找到
python/plugins/(沒有就自己建立),每個外掛是其中一個子資料夾。
操作步驟(QGIS 4)
Section titled “操作步驟(QGIS 4)”-
在
python/plugins/底下建立資料夾layer_counter。資料夾名稱只用英文字母、數字、底線、連字號,不要以數字開頭,也不要用中文。 -
建立
metadata.txt(UTF-8 編碼):; 測試狀態:未在 QGIS 4 實機執行[general]name=Layer CounterqgisMinimumVersion=3.40qgisMaximumVersion=4.99description=Show the feature count of the active layer.about=A minimal example plugin. Click the toolbar button to see how many features the active vector layer has.version=0.1.0author=Your Nameemail=you@example.comrepository=https://example.com/your/repositoryrepository、email先填自己的;這裡的網址只是佔位,發布前一定要換成真的公開程式庫。 -
建立
__init__.py。QGIS 載入外掛時只呼叫這個檔案裡的classFactory():# 測試狀態:未在 QGIS 4 實機執行def classFactory(iface):from .plugin import LayerCounterPluginreturn LayerCounterPlugin(iface) -
建立
plugin.py:# 測試狀態:未在 QGIS 4 實機執行try: # Qt6/QGIS 4:QAction 在 QtGuifrom qgis.PyQt.QtGui import QActionexcept ImportError: # Qt5/QGIS 3from qgis.PyQt.QtWidgets import QActionfrom qgis.core import Qgis, QgsVectorLayerMENU = '&Layer Counter'class LayerCounterPlugin:def __init__(self, iface):self.iface = ifaceself.action = Nonedef initGui(self):self.action = QAction('計算圖徵數', self.iface.mainWindow())self.action.triggered.connect(self.run)self.iface.addToolBarIcon(self.action)self.iface.addPluginToMenu(MENU, self.action)def unload(self):if self.action is not None:self.iface.removePluginMenu(MENU, self.action)self.iface.removeToolBarIcon(self.action)self.action = Nonedef run(self):layer = self.iface.activeLayer()if not isinstance(layer, QgsVectorLayer):self.iface.messageBar().pushMessage('Layer Counter', '請先在圖層面板選一個向量圖層',level=Qgis.MessageLevel.Warning, duration=5)returnself.iface.messageBar().pushMessage('Layer Counter', '{}:{} 筆圖徵'.format(layer.name(), layer.featureCount()),level=Qgis.MessageLevel.Info, duration=5) -
放一份
LICENSE(純文字、沒有副檔名)。只在自己電腦用可以先不放,要發布到官方外掛庫就是必要檔案,見 05 發布到官方外掛庫。 -
重新啟動 QGIS,開 外掛 Plugins ▸ 管理與安裝外掛 Manage and Install Plugins ▸ 已安裝 Installed,找到 Layer Counter 並勾選啟用。工具列會多一個按鈕(沒有圖示時顯示文字),外掛 Plugins 選單會多一個 Layer Counter 子選單。
-
修改程式後不必每次重開 QGIS:從外掛管理員安裝 Plugin Reloader,選擇要重新載入的外掛,一鍵重載。
QGIS 啟動 └─ 掃描 python/plugins/ 下每個子資料夾 └─ 讀 metadata.txt:版本範圍不符 → 不列入或標示不相容 使用者啟用外掛 └─ import 資料夾(執行 __init__.py) └─ classFactory(iface) → 外掛物件 └─ initGui():建立選單、工具列、面板 使用者停用外掛或關閉 QGIS └─ unload():移除 initGui() 建立的所有東西initGui() 與 unload() 必須成對:initGui() 加了什麼,unload() 就要移除什麼。沒移除的選單項目會在重新啟用時重複出現;沒中斷的訊號連線會讓已停用的外掛繼續被呼叫。
metadata.txt 必填欄位
Section titled “metadata.txt 必填欄位”依 PyQGIS 開發者手冊(3.44 版),必填欄位是 name、qgisMinimumVersion、description、about、version、author、email、repository。常用選填欄位有 qgisMaximumVersion、changelog、experimental、deprecated、tags、homepage、tracker、icon、category、plugin_dependencies、server、hasProcessingProvider。category 可填 Raster、Vector、Database、Mesh、Web。
qgisMaximumVersion 在跨大版本時特別重要:沒寫時,相容範圍只到最低版本那個大版本的結尾。所以 qgisMinimumVersion=3.40 又沒寫最高版本的外掛,QGIS 4 不會載入。要同時支援 3 與 4,就要明寫 qgisMaximumVersion=4.99,並且程式本身要真的能在 Qt6 下執行,見 04 外掛遷移到 QGIS 4/Qt6。
為什麼 import 放在 classFactory 裡
Section titled “為什麼 import 放在 classFactory 裡”__init__.py 在 QGIS 掃描外掛時就可能被讀取。把 from .plugin import … 放在 classFactory() 函式裡,外掛主程式只有在啟用時才載入,啟動比較快,主程式有錯也不會影響其他外掛的掃描。
Plugin Builder 與手寫
Section titled “Plugin Builder 與手寫”Plugin Builder 是產生外掛範本的外掛,會一次建好對話框、資源檔、翻譯與測試的骨架。依官方外掛庫頁面(2026-11 查詢):Plugin Builder 3 最新版的相容範圍到 QGIS 3.99,並標示 QGIS 3 分支進入維護模式;QGIS 4 用的是另一個項目 Plugin Builder 4,最低版本 4.0。
本單元選擇手寫,因為三個檔案就能看清外掛的最小結構;Plugin Builder 產生的範本檔案多,第一次看容易分不清哪些是必要的。需要對話框與翻譯時再改用 Plugin Builder,並記得它產生的 ui_*.py、resources.py 這類檔案發布時不要打包進去。
外掛和 Processing 提供者可以並存
Section titled “外掛和 Processing 提供者可以並存”外掛可以在 initGui() 裡向 Processing 註冊自己的提供者(provider),把演算法放進工具箱,同時保留自己的面板與地圖工具。這是坡地、地質類外掛常見的架構,06 讀一支真實外掛 會看到實例。官方發布指引也建議分析類外掛考慮做成 Processing 的子外掛。
| 症狀 | 原因 | 解法 |
|---|---|---|
| 外掛管理員找不到外掛 | 資料夾放錯層(多包了一層),或放到別的設定檔 | 確認結構是 python/plugins/layer_counter/metadata.txt;用選單開啟使用中的設定檔資料夾 |
| 顯示外掛不相容 | qgisMinimumVersion/qgisMaximumVersion 範圍不含目前版本 |
調整版本範圍;跨 QGIS 3 與 4 要寫 qgisMaximumVersion=4.99 |
啟用時出現 ImportError: cannot import name 'QAction' |
QGIS 4(Qt6)的 QAction 移到 QtGui |
用範例的 try/except 兩段 import |
| 停用再啟用後選單項目重複 | unload() 沒移除選單或工具列按鈕 |
unload() 逐一對應 initGui() 加入的項目 |
| 中文訊息變成亂碼 | 檔案不是 UTF-8 存檔 | 所有 .py 與 metadata.txt 一律存成 UTF-8 |
本單元目前沒有對應影片。
- 照步驟做出 Layer Counter,啟用、停用、再啟用三次。
- 檢查方式:外掛 Plugins 選單裡始終只有一個 Layer Counter 項目,工具列只有一個按鈕。
- 把
qgisMaximumVersion那一行刪掉,在 QGIS 4 重開外掛管理員。- 檢查方式:說得出外掛為什麼被標示不相容或不載入,並改回來。
- 在
run()裡加上「選取圖徵數」:用layer.selectedFeatureCount()。- 檢查方式:在地圖上選取幾筆圖徵後按按鈕,訊息列顯示的數字與狀態列一致。
- PyQGIS Developer Cookbook:Structuring Python Plugins:必要檔案、metadata 欄位表、
initGui()/unload()範例(撰寫時對應 QGIS 3.44) - Plugin Builder 3、Plugin Builder 4(官方外掛庫頁面)
- Plugin Reloader
- Migrate your plugin to QGIS 4(官方外掛庫):版本範圍規則