跳到內容

最小可載入的 QGIS 外掛

要有哪些檔案

M10進階約 45 分鐘

草稿|步驟依 QGIS 3.x 手冊撰寫,尚未在 QGIS 4 實機驗證

Processing 腳本適合「輸入→計算→輸出」的工具,但有些需求它做不到:要在地圖上拖拉畫框、要一個常駐在側邊的面板、要在選單裡放一組按鈕。這時就要寫外掛。

第一次寫外掛最常卡在:

  • 檔案放進資料夾了,外掛管理員 Plugin Manager 裡卻找不到。
  • 找得到,但勾選啟用時跳出一長串 Python 錯誤。
  • 停用外掛後選單項目還留著,再啟用就出現兩個。

這些都跟外掛的最小結構與載入流程有關。

不需要地理資料,只需要一個文字編輯器。開始前先確認外掛資料夾的位置:

  1. 設定 Settings ▸ 使用者設定檔 User Profiles ▸ 開啟使用中的設定檔資料夾 Open Active Profile Folder。

  2. 在開啟的資料夾裡找到 python/plugins/(沒有就自己建立),每個外掛是其中一個子資料夾。

  1. 在 python/plugins/ 底下建立資料夾 layer_counter。資料夾名稱只用英文字母、數字、底線、連字號,不要以數字開頭,也不要用中文。

  2. 建立 metadata.txt(UTF-8 編碼):

    ; 測試狀態:未在 QGIS 4 實機執行
    [general]
    name=Layer Counter
    qgisMinimumVersion=3.40
    qgisMaximumVersion=4.99
    description=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.0
    author=Your Name
    email=you@example.com
    repository=https://example.com/your/repository

    repository、email 先填自己的;這裡的網址只是佔位,發布前一定要換成真的公開程式庫。

  3. 建立 __init__.py。QGIS 載入外掛時只呼叫這個檔案裡的 classFactory():

    # 測試狀態:未在 QGIS 4 實機執行
    def classFactory(iface):
    from .plugin import LayerCounterPlugin
    return LayerCounterPlugin(iface)
  4. 建立 plugin.py:

    # 測試狀態:未在 QGIS 4 實機執行
    try: # Qt6/QGIS 4:QAction 在 QtGui
    from qgis.PyQt.QtGui import QAction
    except ImportError: # Qt5/QGIS 3
    from qgis.PyQt.QtWidgets import QAction
    from qgis.core import Qgis, QgsVectorLayer
    MENU = '&Layer Counter'
    class LayerCounterPlugin:
    def __init__(self, iface):
    self.iface = iface
    self.action = None
    def 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 = None
    def run(self):
    layer = self.iface.activeLayer()
    if not isinstance(layer, QgsVectorLayer):
    self.iface.messageBar().pushMessage(
    'Layer Counter', '請先在圖層面板選一個向量圖層',
    level=Qgis.MessageLevel.Warning, duration=5)
    return
    self.iface.messageBar().pushMessage(
    'Layer Counter', '{}:{} 筆圖徵'.format(layer.name(), layer.featureCount()),
    level=Qgis.MessageLevel.Info, duration=5)
  5. 放一份 LICENSE(純文字、沒有副檔名)。只在自己電腦用可以先不放,要發布到官方外掛庫就是必要檔案,見 05 發布到官方外掛庫。

  6. 重新啟動 QGIS,開 外掛 Plugins ▸ 管理與安裝外掛 Manage and Install Plugins ▸ 已安裝 Installed,找到 Layer Counter 並勾選啟用。工具列會多一個按鈕(沒有圖示時顯示文字),外掛 Plugins 選單會多一個 Layer Counter 子選單。

  7. 修改程式後不必每次重開 QGIS:從外掛管理員安裝 Plugin Reloader,選擇要重新載入的外掛,一鍵重載。

QGIS 啟動
└─ 掃描 python/plugins/ 下每個子資料夾
└─ 讀 metadata.txt:版本範圍不符 → 不列入或標示不相容
使用者啟用外掛
└─ import 資料夾(執行 __init__.py)
└─ classFactory(iface) → 外掛物件
└─ initGui():建立選單、工具列、面板
使用者停用外掛或關閉 QGIS
└─ unload():移除 initGui() 建立的所有東西

initGui() 與 unload() 必須成對:initGui() 加了什麼,unload() 就要移除什麼。沒移除的選單項目會在重新啟用時重複出現;沒中斷的訊號連線會讓已停用的外掛繼續被呼叫。

依 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。

__init__.py 在 QGIS 掃描外掛時就可能被讀取。把 from .plugin import … 放在 classFactory() 函式裡,外掛主程式只有在啟用時才載入,啟動比較快,主程式有錯也不會影響其他外掛的掃描。

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

本單元目前沒有對應影片。

  1. 照步驟做出 Layer Counter,啟用、停用、再啟用三次。
    • 檢查方式:外掛 Plugins 選單裡始終只有一個 Layer Counter 項目,工具列只有一個按鈕。
  2. 把 qgisMaximumVersion 那一行刪掉,在 QGIS 4 重開外掛管理員。
    • 檢查方式:說得出外掛為什麼被標示不相容或不載入,並改回來。
  3. 在 run() 裡加上「選取圖徵數」:用 layer.selectedFeatureCount()。
    • 檢查方式:在地圖上選取幾筆圖徵後按按鈕,訊息列顯示的數字與狀態列一致。