計器可視化組件)
先說明一下我這篇要講的東西。QML 開發(fā)里有個長期被吐槽的點自定義控件寫了幾十個復(fù)用全靠手敲代碼或者靠“復(fù)制粘貼再改 id”遇到主界面要拼一堆業(yè)務(wù)組件時效率極低。而 Qt Creator 設(shè)計器里那只“組件庫”面板默認只放 Qt Quick 自帶的基礎(chǔ)控件自己寫的那些漂亮的儀表盤、卡片、按鈕組根本拖不進去。這篇文章就是解決這個問題的。我會從 Qt 6.5 的模塊化機制講起再用 5 個步驟把你自己寫的 QML 自定義控件掛進 Qt Creator 設(shè)計器的組件庫變成鼠標拖一下就能用的“可視化插件”。整個過程不涉及太底層的 C 插件知識純 QML 工程也能走通適合 QML 新手、做前端界面的 Qt 開發(fā)者以及想把設(shè)計器真正用起來的團隊。1. 先搞清楚Qt Creator 設(shè)計器為什么不認識你的自定義控件很多人第一次在 Design Mode 里找自己的 QML 文件翻遍整個組件庫都看不到第一反應(yīng)是“是不是得寫 C 插件”其實不完全是。要搞明白這個問題得先知道設(shè)計器面板里那些控件是怎么“住”進組件庫的。1.1 設(shè)計器組件庫里的兩類“住客”Qt Creator 的 QML 設(shè)計器Design Mode左下角有個組件庫里面大致住著兩類東西。第一類是 QML 模塊里自帶的類型比如 QtQuick 里的 Rectangle、Text、ButtonQtQuick.Controls 里的各種控件。它們能出現(xiàn)在組件庫里是因為這些模塊本身在安裝 Qt 時就被聲明成了“可被設(shè)計器識別”內(nèi)部有對應(yīng)的元數(shù)據(jù)描述告訴設(shè)計器“我叫 Button我有哪些屬性我的圖標長什么樣”。第二類是項目里臨時加入的可視化類型。你打開一個 .qml 文件并切到 Design Mode 時設(shè)計器實際是在后臺解析這個文件把它當作一棵對象樹。如果你在一個 .qml 文件里定義了一個自定義類型的實例比如你自己寫的Card {}這個Card類型如果已經(jīng)在某個路徑或模塊里注冊過設(shè)計器也能解析出來。難點就在這個“注冊”上。Qt Creator 設(shè)計器默認不會去掃描你的整個硬盤找自定義 QML 文件。它只認兩樣?xùn)|西已安裝 Qt 自帶的 QML 模塊以及你手動告訴它的自定義組件路徑或 QML 模塊。所以你的控件不顯示不是它不存在而是設(shè)計器壓根不知道去哪里找它。1.2 從 .qml 到“可視化插件”的本質(zhì)類型注冊把自定義控件變成設(shè)計器可拖拽組件核心動作是類型注冊。Qt 6 里 QML 的模塊系統(tǒng)比 Qt 5 更嚴格以前可能把一個 .qml 文件放目錄里再寫個 qmldir 就勉強能 importQt 6 會檢查模塊名、版本、插件依賴還推薦用 CMake 的qt_add_qml_module來管理注冊。注冊之后QML 引擎和設(shè)計器才能回答三個問題這個類型叫什么名字它是在哪個模塊URI里定義的它有什么屬性、屬于什么分類設(shè)計器拿到這些信息后才會把類型顯示在組件庫面板里并且在你拖拽時生成對應(yīng)的對象代碼。那到底要不要寫 C看需求。純 QML 自定義控件走“模塊注冊 組件路徑”就能顯示想讓它出現(xiàn)在全局組件庫、帶自定義圖標、有更完善的屬性面板表現(xiàn)那才需要寫一點點 C 包裝插件。文章后面兩種情況都會講你按自己的工程復(fù)雜度選。1.3 Qt6.5 里模塊化帶來的變化Qt 6.5 之后QML 模塊和 CMake 的綁定更深了。用qt_add_qml_module創(chuàng)建模塊時CMake 會自動生成 qmldir、插件元數(shù)據(jù)模塊里的 QML 文件會被自動識別為可注冊的類型。這意味著只要你的自定義控件文件放在模塊目錄里并且QML_FILES列表包含它QML 引擎和設(shè)計器就都能通過模塊名找到它。但這里有個設(shè)計器特有的坑Qt Creator 的組件庫面板默認展示的是“從當前打開項目里能 import 到的類型”。所以即使你的模塊注冊了設(shè)計器能不能立刻看到還和模塊路徑、構(gòu)建目錄、你對組件庫路徑的配置有關(guān)。這就是文章第 3 部分 5 步實操要解決的核心問題。2. 寫控件前先立規(guī)矩能被設(shè)計器識別的 QML 文件長什么樣并不是你隨便寫一個 .qml 文件放在模塊目錄里設(shè)計器就會乖乖把它顯示成可拖拽組件。我一開始吃過不少虧控件寫得很花哨但拖進設(shè)計器要么白屏要么屬性面板一片空。后來總結(jié)出一套“設(shè)計器友好”的 QML 寫法先講清楚這幾個規(guī)矩后面實操才不會翻車。2.1 頂層類型別亂寫id 命名也講究設(shè)計器解析 QML 時最關(guān)心的其實是這個文件的根對象。比如你寫一個MyCard.qml根對象是Rectangle那設(shè)計器拖拽后生成的就是一個 Rectangle 實例如果你的根對象是Window或Item它也能處理但某些特殊根類型在設(shè)計器里的表現(xiàn)會受限。一句話建議自定義控件的根對象盡量用視覺可渲染的類型比如 Item、Rectangle、Control 或基于它們的自定義類型。盡量避免根對象直接是Window、ApplicationWindow這種帶窗口語義的類型設(shè)計器里拖一個窗口進去很尷尬而且 QML 設(shè)計器對 Window 的嵌套支持一直不好。id 命名雜亂無章也會讓生成的代碼難懂。例如控件內(nèi)部有個id: root設(shè)計器在生成對象樹時會參考它但不會完全依賴它。真正影響設(shè)計器的是屬性名和類型名id 主要是可讀性問題。我建議統(tǒng)一用小駝峰命名內(nèi)部 id 和導(dǎo)出的類型名區(qū)分開比如MyCard.qml內(nèi)部根對象id: root避免出現(xiàn)id: rect1、id: item23這種毫無語義的命名。2.2 用屬性暴露“可調(diào)項”設(shè)計器面板才能顯示參數(shù)設(shè)計器之所以能讓你在右側(cè)屬性面板里改顏色、改寬度、改文字靠的是去解析這個 QML 類型里可寫的property。所以自定義控件里那些你認為“用的時候可能要改的”東西都應(yīng)該寫成屬性而不是直接寫死在內(nèi)部。// MyCard.qml import QtQuick import QtQuick.Controls Item { id: root implicitWidth: 240 implicitHeight: 120 property string titleText: 標題 property string descText: 這里是描述內(nèi)容 property color cardColor: #FAFAFA property color titleColor: #333333 property int radius: 12 Rectangle { anchors.fill: parent color: root.cardColor radius: root.radius Column { anchors.centerIn: parent spacing: 6 Text { text: root.titleText font.pixelSize: 18 font.bold: true color: root.titleColor } Text { text: root.descText font.pixelSize: 13 color: #999999 } } } }像這樣的寫法拖進設(shè)計器后屬性面板會列出titleText、descText、cardColor、titleColor、radius這些可配置項使用者不用打開代碼就能把標題、背景色改了。2.3 該寫 alias 的地方要寫 alias但別嵌套太多層QML 中的property alias在設(shè)計器里同樣能被識別。比如一個自定義按鈕你希望別人能直接設(shè)text、onClicked而內(nèi)部實際是Button的屬性可以用別名透出來。// MyButton.qml import QtQuick import QtQuick.Controls Button { id: control property alias text: control.text property alias fontPixelSize: control.font.pixelSize }但有一點要提醒設(shè)計器解析嵌套層次過深的屬性別名時偶爾會卡頓或顯示不全。我遇到過把別名鏈寫到三四層深結(jié)果設(shè)計器屬性面板里能看到屬性名卻改不動值。盡量讓 alias 直連基礎(chǔ)控件的屬性不要 alias 了再 alias這不是硬性語法限制而是設(shè)計器工具鏈的穩(wěn)定性問題。2.4 能不用 JS 邏輯就不用能用綁定就用綁定設(shè)計器可以渲染 QML 里的綁定表達式但遇到復(fù)雜的 JavaScript 邏輯、for 循環(huán)、狀態(tài)機切換它的預(yù)覽和實際運行往往對不上。為了讓控件在設(shè)計器里表現(xiàn)得穩(wěn)定我把自定義控件分成兩層來寫外層組件目錄下的獨立 .qml 文件只做布局、樣式、屬性和簡單綁定這是設(shè)計器能看到的那層。內(nèi)層復(fù)雜邏輯放到業(yè)務(wù)代碼里或 C 中通過信號、屬性通知傳到外層。這種做法能保證控件“設(shè)計時可預(yù)覽”同時又不會因為設(shè)計器解析不了高級 JS 而白屏。你要做一個大而全的復(fù)雜控件建議也拆成“設(shè)計器殼子 運行時內(nèi)核”兩邊各得其所。3. 5 步實操把自己的 QML 控件注冊成可視化插件下面進入正題。我用的環(huán)境是 Qt 6.5.2 Qt Creator 11工程是 CMake 構(gòu)建。整個步驟不要求你寫 C純 QML 模塊就能跑通這是最常見的“把自定義控件變成可拖拽組件”路線。3.1 第一步把自定義控件整理成獨立模塊目錄先建一個目錄專門放你自己的控件。我這個例子里項目結(jié)構(gòu)是這樣MyProject/ ├── CMakeLists.txt ├── Main.qml └── components/ # 自定義控件模塊目錄 ├── CMakeLists.txt # 這個下面會講 ├── MyCard.qml ├── MyButton.qml └── MyProgressCard.qml關(guān)鍵點這些控件文件盡量放在同一目錄最好不要和其他業(yè)務(wù)頁面混在一起。因為qt_add_qml_module是以目錄為單位生成 QML 模塊的模塊名和路徑是綁定的。目錄一亂模塊結(jié)構(gòu)就亂了。3.2 第二步用qt_add_qml_module把模塊掛進工程在 Qt 6.5 的 CMake 工程里注冊自定義 QML 模塊的標準姿勢是qt_add_qml_module。這個函數(shù)會幫你生成模塊需要的 qmldir 文件、插件元數(shù)據(jù)并且把模塊名注冊到構(gòu)建系統(tǒng)里。我來寫一個最小可用的 CMake 配置cmake_minimum_required(VERSION 3.21) project(MyProject VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(Qt6 6.5 REQUIRED COMPONENTS Quick Qml) qt_standard_project_setup(REQUIRES 6.5) qt_add_executable(MyProject main.cpp Main.qml ) qt_add_qml_module(MyProject URI MyProject VERSION 1.0 QML_FILES Main.qml ) # 額外添加自定義控件模塊作為獨立模塊導(dǎo)入 qt_add_qml_module(mycomponents URI MyComponents VERSION 1.0 QML_FILES components/MyCard.qml components/MyButton.qml components/MyProgressCard.qml ) target_link_libraries(MyProject PRIVATE Qt6::Quick Qt6::Qml)這里核心是第二個qt_add_qml_module。我把控件目錄單獨做成了一個 URI 為MyComponents的 QML 模塊這樣你在 Main.qml 里只需要import MyComponents就能用MyCard、MyButton這些類型了。這一步做完編譯運行是沒問題的但這只是“運行時”可見。要讓設(shè)計器也看見還要繼續(xù)。3.3 第三步把模塊路徑告訴 Qt Creator 設(shè)計器這是純 QML 路線里最關(guān)鍵的一步。Qt Creator 設(shè)計器并不會自動去掃描你 CMake 里定義了哪些模塊它需要你告訴它“去哪些路徑下面找 QML 模塊”。打開 Qt Creator菜單欄選“工具” - “選項” - “QML/JS” - “自定義組件路徑”Custom Component Paths。點擊“添加”把包含 qmldir 文件的目錄路徑加進去。這里有個細節(jié)要特別注意要添加的是模塊的根路徑不是控件的具體目錄。也就是說如果你用 CMake 構(gòu)建生成的模塊元數(shù)據(jù)通常在構(gòu)建目錄下比如build/MyComponents你要添加的路徑應(yīng)該是這個包含 qmldir 的目錄如果是純手工目錄就添加components所在的上一層目錄然后里面按模塊名組織子目錄。更省事的做法直接添加你的components目錄然后確保目錄結(jié)構(gòu)是“模塊名/文件”的層次。因為 Qt Creator 支持在組件路徑面板中導(dǎo)入一個根路徑然后它自動搜索這個路徑下所有的子模塊。我項目里components這個根路徑一加MyComponents就出現(xiàn)在組件庫面板里了。3.4 第四步重新加載設(shè)計器找到控件并拖拽路徑配置好了之后記得做兩件事重新構(gòu)建工程確保新模塊的 qmldir 已經(jīng)生成。關(guān)閉當前 .qml 文件窗口重新打開讓設(shè)計器重新解析項目環(huán)境。然后切到 Design Mode左側(cè)組件庫面板最下面通常會出現(xiàn)新的分組分組名對應(yīng)模塊 URI。我這邊顯示的是MyComponents展開就是MyCard、MyButton、MyProgressCard三個控件。直接拖一個MyCard到畫布上設(shè)計器會生成類似這樣的代碼MyCard { id: myCard x: 120 y: 80 titleText: 標題 descText: 這里是描述內(nèi)容 }右側(cè)屬性面板里能改文字、顏色、圓角整個過程和拖 Qt Quick 自帶的 Button 沒什么區(qū)別。走到這一步你的“5 步可視化插件”已經(jīng)完成 80% 了。3.5 第五步進階——用 C 把控件注冊成真正的插件顯示全局組件純 QML 模塊的方式有個限制它依賴你把組件路徑配置好而且組件庫里的分組、圖標、分類都比較樸素。如果你想把控件做成一個真正的、帶圖標的“插件”讓它在任何項目里都能拖那需要用到 C 的 QML 插件機制。思路是這樣寫一個 C 類繼承QQmlExtensionPlugin。在自己的插件類里通過qmlRegisterType注冊 QML 類型。CMake 里用qt_add_qml_module配置PLUGIN_TARGET生成插件。把插件和 qmldir 一起放進 Qt 的 QML 模塊安裝目錄或通過 Qt Creator 的組件路徑指向插件所在目錄。第 2 步注冊的代碼大概是#include QQmlExtensionPlugin #include QQmlEngine class MyComponentsPlugin : public QQmlExtensionPlugin { Q_OBJECT Q_PLUGIN_METADATA(IID QQmlExtensionInterface_iid) public: void registerTypes(const char *uri) override { qmlRegisterType(QUrl(QStringLiteral(qrc:/qt/qml/MyComponents/MyCard.qml)), uri, 1, 0, MyCard); qmlRegisterType(QUrl(QStringLiteral(qrc:/qt/qml/MyComponents/MyButton.qml)), uri, 1, 0, MyButton); } };這里我實際上是用 URL 方式注冊了一個 QML 文件為類型這是 Qt 6 里常用的一種混合注冊方式控件實現(xiàn)仍是 QML插件只負責“告訴設(shè)計器這個類型存在”。這種注冊方式比純 qmldir 更正式一點組件庫面板里面顯示也更穩(wěn)定。寫完后工程里qt_add_qml_module的配置加一行PLUGIN_TARGET就行qt_add_qml_module(mycomponents URI MyComponents VERSION 1.0 PLUGIN_TARGET mycomponentsplugin QML_FILES components/MyCard.qml components/MyButton.qml components/MyProgressCard.qml )編譯生成的插件再配合組件路徑導(dǎo)入Qt Creator 會自動識別。這個方案比起純 QML 更接近“真正的可視化插件”但對工程組織要求更高新手建議先跑通純 QML 方案再把 C 加進來。3.6 完整 CMakeLists.txt 參考為了避免大家拼配置時漏這漏那我把剛才講的完整 CMakeLists.txt 貼一遍基于 Qt 6.5 驗證過cmake_minimum_required(VERSION 3.21) project(MyProject VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(Qt6 6.5 REQUIRED COMPONENTS Quick Qml) qt_standard_project_setup(REQUIRES 6.5) qt_add_executable(MyProject main.cpp Main.qml ) qt_add_qml_module(MyProject URI MyProject VERSION 1.0 QML_FILES Main.qml ) qt_add_qml_module(mycomponents URI MyComponents VERSION 1.0 QML_FILES components/MyCard.qml components/MyButton.qml components/MyProgressCard.qml ) target_link_libraries(MyProject PRIVATE Qt6::Quick Qt6::Qml)main.cpp 保持 Qt 6 默認模板就行主要是QQuickView或者QQmlApplicationEngine加載 Main.qml。4. 拖拽進來的控件出問題了常見問題與排查實錄我把自己折騰過程中遇到的坑以及給身邊同事排查時最常見的問題整理成了一份速查表每一條都寫清楚現(xiàn)象和解決辦法。4.1 組件庫是空的或者看不到自定義控件分組現(xiàn)象組件路徑配了工程也重新構(gòu)建了但組件庫面板里就是不出MyComponents分組。排查順序先確認 qmldir 文件是否真的生成了。在構(gòu)建目錄里搜一下如果qt_add_qml_module執(zhí)行成功構(gòu)建目錄里應(yīng)該有一個和你 URI 同名的文件夾里面有qmldir和一堆編譯產(chǎn)物。如果沒有說明 CMake 配置有問題大概率是QML_FILES里列的文件路徑寫錯了。再檢查組件路徑是不是指向?qū)α四夸?。Qt Creator 的組件路徑支持兩種一種是“頂層目錄”Qt Creator 會遞歸找模塊另一種是“精確模塊目錄”。我建議剛開始先用精確目錄把路徑指到構(gòu)建目錄下MyComponents這一層最容易定位問題。4.2 控件拖進來后是空白/白屏或者只有一個小方塊現(xiàn)象組件庫顯示正常拖一個MyCard到畫布上但設(shè)計器里看不見內(nèi)容。常見原因有三個。第一控件里用了設(shè)計器不支持的屬性或類型比如直接用了Canvas、ShaderEffect這類高級繪制組件設(shè)計器預(yù)覽能力跟不上顯示就是空的。第二控件高度或?qū)挾葲]有設(shè)置根對象默認是 0 尺寸。所以我在示例里給根對象設(shè)了implicitWidth和implicitHeight設(shè)計器拖拽時會優(yōu)先用它作為初始尺寸。第三控件內(nèi)部使用到了運行時才有值的上下文屬性例如調(diào)用了一個尚未定義的 C 單例屬性設(shè)計器解析時該屬性不存在整個控件渲染報錯。解法也很樸素先做一個極簡的測試控件只放一個 Rectangle 和一個 Text確認能顯示再逐步往里面加內(nèi)容。哪一步畫布變白了問題就出現(xiàn)在剛加的配置上。4.3 屬性面板里看不到自定義屬性現(xiàn)象控件拖進來了但屬性面板只有 x、y、width、height 這些通用屬性自己定義的titleText、cardColor全都不顯示。這八成是因為你沒有在頂層對象上定義property。設(shè)計器解析 .qml 文件的頂層屬性時只認“根對象”里聲明的屬性。你把屬性寫在一個嵌套的 Rectangle 里設(shè)計器不會把它提升為控件可配置項。檢查一下屬性是寫在根對象還是子對象上寫在根對象上才會出現(xiàn)在屬性面板。還有一個低頻但真實的原因?qū)傩悦制磳懟虼笮懖灰恢卤热缍x的是titleText使用時寫title_text設(shè)計器解析后找不到對應(yīng)屬性干脆不顯示。QML 是大小寫敏感的命名統(tǒng)一很重要。4.4 設(shè)計器報錯QML module not found現(xiàn)象打開 Main.qml 切到 Design Mode提示找不到MyComponents模塊但運行時編譯沒問題。這個很典型因為運行時用的是構(gòu)建系統(tǒng)里的模塊路徑設(shè)計器用的是組件路徑。運行時能找到不代表設(shè)計器知道去哪里找。遇到這個報錯先檢查 Qt Creator 的“自定義組件路徑”里是不是把構(gòu)建目錄對應(yīng)的那個模塊路徑加進去了。加了之后還報錯就重啟一遍 Qt Creator。設(shè)計器對 QML 模塊路徑的緩存比較“頑固”我測試時經(jīng)常改完路徑設(shè)置之后必須關(guān)閉整個 IDE再打開才生效。4.5 無邊框窗口和 Window 類控件拖不進設(shè)計器標題熱詞里有人搜索“qml 無邊框窗口實現(xiàn)”如果你把無邊框窗口邏輯寫進一個自定義控件再放進設(shè)計器大概率會遇到渲染異常。無邊框窗口通常會設(shè)置flags: Qt.FramelessWindowHint或使用Window做根對象而Window在 Qt Creator 設(shè)計器里不能作為普通控件拖入它會被當成獨立窗口處理。我的建議是窗口殼子和內(nèi)容控件分開。自定義控件只做窗口內(nèi)部的內(nèi)容組件無邊框窗口本身放在業(yè)務(wù)代碼里創(chuàng)建。這樣內(nèi)容組件可以作為可視化插件拖拽窗口邏輯留在運行時兩不誤。4.6 按鈕文字顏色改了沒反應(yīng)或者文字不顯示熱詞里“修改 qml button 的字體顏色”對應(yīng)的就是這類問題。先說結(jié)論Button 的字體顏色用font.pixelSize和自定義樣式聯(lián)動時最穩(wěn)妥的是改contentItem里的 Text color或者設(shè)置 Button 的palette。但在設(shè)計器里改屬性后沒反應(yīng)往往是綁定覆蓋問題。比如你在自定義控件內(nèi)部寫死了color: white設(shè)計器屬性面板里改了buttonColor但內(nèi)部 Rectangle 的顏色綁定仍然是固定值那就當然看不到效果。正確做法是讓內(nèi)部元素顏色全部綁定到導(dǎo)出的屬性上而不是寫死。設(shè)計器只負責修改屬性值不會幫你“穿透”到內(nèi)部寫死值的地方。4.7 編譯報錯、代碼格式化對齊等周邊問題熱詞里有人問“qt creator 代碼對齊快捷方式不好用”。這和自定義控件可視化本身關(guān)系不大但開發(fā)效率影響不小我順帶說一下。Qt Creator 里重新格式化選中代碼的快捷鍵是 Ctrl Alt F格式化當前文件是 Ctrl Alt F 的上一檔不同版本略有差異有時候快捷鍵沒反應(yīng)是因為和輸入法或系統(tǒng)快捷鍵沖突。在“工具”-“選項”-“環(huán)境”-“鍵盤”里搜索“Reformat”重新綁定一個自己習慣的按鍵即可。另外如果 QML 文件里出現(xiàn)了編譯報錯但運行時能跑通常是因為用了設(shè)計器不支持的寫法比如在屬性綁定里寫了非法的表達式。我建議把設(shè)計器報錯內(nèi)容截圖下來逐條看大部分信息會明確指出哪個文件第幾行有問題比盲目改代碼快得多。4.8 一個更高效的排查路徑如果上面這些都沒有解決你的問題我建議按這條路徑走一遍先放棄設(shè)計器直接運行工程確認控件本身沒有運行時錯誤。新建一個臨時 .qml 文件手動 importMyComponents寫幾行代碼實例化控件編譯運行。如果運行時能顯示說明控件邏輯沒問題純粹是設(shè)計器配置問題。回到設(shè)計器按模塊路徑、組件路徑、緩存順序一級一級排查。這套流程能幫你快速區(qū)分“控件代碼問題”和“設(shè)計器集成問題”而不是在設(shè)計器報錯里亂猜。5. 想在團隊里把這套能力用起來幾個進階技巧自定義控件能拖了只是開始。真正舒服的用法是讓設(shè)計器和代碼協(xié)作起來把團隊里高頻復(fù)用的組件全部推成可拖拽插件UI 搭建效率才能上來。5.1 利用 Qt.designer 條件分支讓控件“設(shè)計時”和“運行時”表現(xiàn)不同QML 里有個很少被提到的功能Qt.designer屬性。在設(shè)計器預(yù)覽時它返回一個對象可以用來判斷當前是否運行在設(shè)計器環(huán)境里。利用這個特性你可以讓同一個控件在設(shè)計器里顯示一個簡化版運行時顯示完整版。Item { property bool isDesigner: typeof Qt.designer ! undefined Qt.designer ! null Rectangle { anchors.fill: parent color: isDesigner ? #EAEAEA : actualColor // 設(shè)計器里顯示灰色占位塊運行時才渲染真實顏色 } }這個寫法對復(fù)雜控件很管用。比如一個圖表控件的真實動畫設(shè)計器渲染不了你可以讓設(shè)計器里只顯示一個靜態(tài)的 Rectangle 占位保證拖拽流暢、預(yù)覽不報錯運行時再加載真正的圖表邏輯。5.2 設(shè)計器里給控件一個“體面”的初始大小和布局行為很多人在設(shè)計器里拖入自定義控件后發(fā)現(xiàn)控件尺寸不是自己想要的樣子原因是控件沒有設(shè)置implicitWidth和implicitHeight。這兩個屬性既影響布局系統(tǒng)也影響設(shè)計器顯示。我在所有自定義控件里都強制要求寫這兩個屬性哪怕值是 0也明確寫上方便后面排查。如果控件內(nèi)部內(nèi)容尺寸不固定可以在根對象里設(shè)置一個合理的默認值比如implicitWidth: 240。這樣使用者拖進去至少能看到一個像樣的組件而不是一個小黑點。5.3 控件分類、圖標、默認值怎么配置純 QML 模塊注冊出來的組件分類默認就是模塊名。想讓組件庫面板更整潔可以在qt_add_qml_module里設(shè)置分類信息或者通過模塊目錄下的qmldir注釋來配置。如果走 C 插件路線則可以用QML_ELEMENT宏和類上的注釋來自動生成分類和版本信息也可以重寫插件類的initializeEngine方法來設(shè)置默認值。圖標方面Qt Creator 會默認顯示一個通用圖標如果想自定義圖標需要在模塊資源里按規(guī)格放置圖標文件并在 qmldir 或插件元數(shù)據(jù)里引用。這個操作網(wǎng)上資料不多實測效果也不如 Qt 自帶的那些控件精致所以我建議初期先不執(zhí)著于圖標用默認圖標跑通流程更重要。5.4 與設(shè)計器生成代碼協(xié)作格式化、對齊、版本管理設(shè)計器拖拽生成的 QML 代碼有時候排版比較亂尤其當你在畫布上拖了很多控件之后。我的習慣是拖完之后立即執(zhí)行一次整個文件的格式化讓代碼對齊統(tǒng)一再手動把 id 改成有業(yè)務(wù)含義的名字。這里提醒一下設(shè)計器生成的代碼和手寫代碼在版本管理里經(jīng)常沖突。如果團隊里多人同時改一個界面文件用可視化拖拽的人和使用代碼編輯器的人很容易互相覆蓋。我推薦的做法是把設(shè)計器拖拽的控件單獨放在一個專屬的 .qml 文件里業(yè)務(wù)邏輯寫在另一個文件通過信號和屬性交互這樣沖突范圍會小很多。5.5 一個日常開發(fā)里很順的組合用法我自己現(xiàn)在的工作流是高頻組件全部寫成自定義控件注冊成MyComponents模塊每次新建頁面打開 Design Mode從組件庫拖出需要的基礎(chǔ)卡片、按鈕、進度條把屬性和文本在右側(cè)面板配好再到代碼里補充連接信號和邏輯。對于老項目里那些已經(jīng)寫好但沒法拖拽的歷史控件我有空就花幾分鐘把它們改造成“設(shè)計器友好”的寫法慢慢把組件庫積累起來。實測下來一個信息化管理系統(tǒng)的界面從原來純手寫要 40 分鐘到現(xiàn)在拖拽加填補邏輯大概 15 分鐘效率提升非常明顯。另外雖然不是每個 QML 項目都適合走“全可視化拖拽”路線但“自定義控件先在設(shè)計器里預(yù)覽、再在代碼里復(fù)用”這個思路對所有 Qt Quick 項目都通用。你不需要把所有頁面都改成拖拽式開發(fā)只要組件庫能用開發(fā)體驗就會有質(zhì)的提升。 QML自定義控件變身Qt Creator設(shè)計器可視化組件
先說明一下我這篇要講的東西。QML 開發(fā)里有個長期被吐槽的點自定義控件寫了幾十個復(fù)用全靠手敲代碼或者靠“復(fù)制粘貼再改 id”遇到主界面要拼一堆業(yè)務(wù)組件時效率極低。而 Qt Creator 設(shè)計器里那只“組件庫”面板默認只放 Qt Quick 自帶的基礎(chǔ)控件自己寫的那些漂亮的儀表盤、卡片、按鈕組根本拖不進去。這篇文章就是解決這個問題的。我會從 Qt 6.5 的模塊化機制講起再用 5 個步驟把你自己寫的 QML 自定義控件掛進 Qt Creator 設(shè)計器的組件庫變成鼠標拖一下就能用的“可視化插件”。整個過程不涉及太底層的 C 插件知識純 QML 工程也能走通適合 QML 新手、做前端界面的 Qt 開發(fā)者以及想把設(shè)計器真正用起來的團隊。1. 先搞清楚Qt Creator 設(shè)計器為什么不認識你的自定義控件很多人第一次在 Design Mode 里找自己的 QML 文件翻遍整個組件庫都看不到第一反應(yīng)是“是不是得寫 C 插件”其實不完全是。要搞明白這個問題得先知道設(shè)計器面板里那些控件是怎么“住”進組件庫的。1.1 設(shè)計器組件庫里的兩類“住客”Qt Creator 的 QML 設(shè)計器Design Mode左下角有個組件庫里面大致住著兩類東西。第一類是 QML 模塊里自帶的類型比如 QtQuick 里的 Rectangle、Text、ButtonQtQuick.Controls 里的各種控件。它們能出現(xiàn)在組件庫里是因為這些模塊本身在安裝 Qt 時就被聲明成了“可被設(shè)計器識別”內(nèi)部有對應(yīng)的元數(shù)據(jù)描述告訴設(shè)計器“我叫 Button我有哪些屬性我的圖標長什么樣”。第二類是項目里臨時加入的可視化類型。你打開一個 .qml 文件并切到 Design Mode 時設(shè)計器實際是在后臺解析這個文件把它當作一棵對象樹。如果你在一個 .qml 文件里定義了一個自定義類型的實例比如你自己寫的Card {}這個Card類型如果已經(jīng)在某個路徑或模塊里注冊過設(shè)計器也能解析出來。難點就在這個“注冊”上。Qt Creator 設(shè)計器默認不會去掃描你的整個硬盤找自定義 QML 文件。它只認兩樣?xùn)|西已安裝 Qt 自帶的 QML 模塊以及你手動告訴它的自定義組件路徑或 QML 模塊。所以你的控件不顯示不是它不存在而是設(shè)計器壓根不知道去哪里找它。1.2 從 .qml 到“可視化插件”的本質(zhì)類型注冊把自定義控件變成設(shè)計器可拖拽組件核心動作是類型注冊。Qt 6 里 QML 的模塊系統(tǒng)比 Qt 5 更嚴格以前可能把一個 .qml 文件放目錄里再寫個 qmldir 就勉強能 importQt 6 會檢查模塊名、版本、插件依賴還推薦用 CMake 的qt_add_qml_module來管理注冊。注冊之后QML 引擎和設(shè)計器才能回答三個問題這個類型叫什么名字它是在哪個模塊URI里定義的它有什么屬性、屬于什么分類設(shè)計器拿到這些信息后才會把類型顯示在組件庫面板里并且在你拖拽時生成對應(yīng)的對象代碼。那到底要不要寫 C看需求。純 QML 自定義控件走“模塊注冊 組件路徑”就能顯示想讓它出現(xiàn)在全局組件庫、帶自定義圖標、有更完善的屬性面板表現(xiàn)那才需要寫一點點 C 包裝插件。文章后面兩種情況都會講你按自己的工程復(fù)雜度選。1.3 Qt6.5 里模塊化帶來的變化Qt 6.5 之后QML 模塊和 CMake 的綁定更深了。用qt_add_qml_module創(chuàng)建模塊時CMake 會自動生成 qmldir、插件元數(shù)據(jù)模塊里的 QML 文件會被自動識別為可注冊的類型。這意味著只要你的自定義控件文件放在模塊目錄里并且QML_FILES列表包含它QML 引擎和設(shè)計器就都能通過模塊名找到它。但這里有個設(shè)計器特有的坑Qt Creator 的組件庫面板默認展示的是“從當前打開項目里能 import 到的類型”。所以即使你的模塊注冊了設(shè)計器能不能立刻看到還和模塊路徑、構(gòu)建目錄、你對組件庫路徑的配置有關(guān)。這就是文章第 3 部分 5 步實操要解決的核心問題。2. 寫控件前先立規(guī)矩能被設(shè)計器識別的 QML 文件長什么樣并不是你隨便寫一個 .qml 文件放在模塊目錄里設(shè)計器就會乖乖把它顯示成可拖拽組件。我一開始吃過不少虧控件寫得很花哨但拖進設(shè)計器要么白屏要么屬性面板一片空。后來總結(jié)出一套“設(shè)計器友好”的 QML 寫法先講清楚這幾個規(guī)矩后面實操才不會翻車。2.1 頂層類型別亂寫id 命名也講究設(shè)計器解析 QML 時最關(guān)心的其實是這個文件的根對象。比如你寫一個MyCard.qml根對象是Rectangle那設(shè)計器拖拽后生成的就是一個 Rectangle 實例如果你的根對象是Window或Item它也能處理但某些特殊根類型在設(shè)計器里的表現(xiàn)會受限。一句話建議自定義控件的根對象盡量用視覺可渲染的類型比如 Item、Rectangle、Control 或基于它們的自定義類型。盡量避免根對象直接是Window、ApplicationWindow這種帶窗口語義的類型設(shè)計器里拖一個窗口進去很尷尬而且 QML 設(shè)計器對 Window 的嵌套支持一直不好。id 命名雜亂無章也會讓生成的代碼難懂。例如控件內(nèi)部有個id: root設(shè)計器在生成對象樹時會參考它但不會完全依賴它。真正影響設(shè)計器的是屬性名和類型名id 主要是可讀性問題。我建議統(tǒng)一用小駝峰命名內(nèi)部 id 和導(dǎo)出的類型名區(qū)分開比如MyCard.qml內(nèi)部根對象id: root避免出現(xiàn)id: rect1、id: item23這種毫無語義的命名。2.2 用屬性暴露“可調(diào)項”設(shè)計器面板才能顯示參數(shù)設(shè)計器之所以能讓你在右側(cè)屬性面板里改顏色、改寬度、改文字靠的是去解析這個 QML 類型里可寫的property。所以自定義控件里那些你認為“用的時候可能要改的”東西都應(yīng)該寫成屬性而不是直接寫死在內(nèi)部。// MyCard.qml import QtQuick import QtQuick.Controls Item { id: root implicitWidth: 240 implicitHeight: 120 property string titleText: 標題 property string descText: 這里是描述內(nèi)容 property color cardColor: #FAFAFA property color titleColor: #333333 property int radius: 12 Rectangle { anchors.fill: parent color: root.cardColor radius: root.radius Column { anchors.centerIn: parent spacing: 6 Text { text: root.titleText font.pixelSize: 18 font.bold: true color: root.titleColor } Text { text: root.descText font.pixelSize: 13 color: #999999 } } } }像這樣的寫法拖進設(shè)計器后屬性面板會列出titleText、descText、cardColor、titleColor、radius這些可配置項使用者不用打開代碼就能把標題、背景色改了。2.3 該寫 alias 的地方要寫 alias但別嵌套太多層QML 中的property alias在設(shè)計器里同樣能被識別。比如一個自定義按鈕你希望別人能直接設(shè)text、onClicked而內(nèi)部實際是Button的屬性可以用別名透出來。// MyButton.qml import QtQuick import QtQuick.Controls Button { id: control property alias text: control.text property alias fontPixelSize: control.font.pixelSize }但有一點要提醒設(shè)計器解析嵌套層次過深的屬性別名時偶爾會卡頓或顯示不全。我遇到過把別名鏈寫到三四層深結(jié)果設(shè)計器屬性面板里能看到屬性名卻改不動值。盡量讓 alias 直連基礎(chǔ)控件的屬性不要 alias 了再 alias這不是硬性語法限制而是設(shè)計器工具鏈的穩(wěn)定性問題。2.4 能不用 JS 邏輯就不用能用綁定就用綁定設(shè)計器可以渲染 QML 里的綁定表達式但遇到復(fù)雜的 JavaScript 邏輯、for 循環(huán)、狀態(tài)機切換它的預(yù)覽和實際運行往往對不上。為了讓控件在設(shè)計器里表現(xiàn)得穩(wěn)定我把自定義控件分成兩層來寫外層組件目錄下的獨立 .qml 文件只做布局、樣式、屬性和簡單綁定這是設(shè)計器能看到的那層。內(nèi)層復(fù)雜邏輯放到業(yè)務(wù)代碼里或 C 中通過信號、屬性通知傳到外層。這種做法能保證控件“設(shè)計時可預(yù)覽”同時又不會因為設(shè)計器解析不了高級 JS 而白屏。你要做一個大而全的復(fù)雜控件建議也拆成“設(shè)計器殼子 運行時內(nèi)核”兩邊各得其所。3. 5 步實操把自己的 QML 控件注冊成可視化插件下面進入正題。我用的環(huán)境是 Qt 6.5.2 Qt Creator 11工程是 CMake 構(gòu)建。整個步驟不要求你寫 C純 QML 模塊就能跑通這是最常見的“把自定義控件變成可拖拽組件”路線。3.1 第一步把自定義控件整理成獨立模塊目錄先建一個目錄專門放你自己的控件。我這個例子里項目結(jié)構(gòu)是這樣MyProject/ ├── CMakeLists.txt ├── Main.qml └── components/ # 自定義控件模塊目錄 ├── CMakeLists.txt # 這個下面會講 ├── MyCard.qml ├── MyButton.qml └── MyProgressCard.qml關(guān)鍵點這些控件文件盡量放在同一目錄最好不要和其他業(yè)務(wù)頁面混在一起。因為qt_add_qml_module是以目錄為單位生成 QML 模塊的模塊名和路徑是綁定的。目錄一亂模塊結(jié)構(gòu)就亂了。3.2 第二步用qt_add_qml_module把模塊掛進工程在 Qt 6.5 的 CMake 工程里注冊自定義 QML 模塊的標準姿勢是qt_add_qml_module。這個函數(shù)會幫你生成模塊需要的 qmldir 文件、插件元數(shù)據(jù)并且把模塊名注冊到構(gòu)建系統(tǒng)里。我來寫一個最小可用的 CMake 配置cmake_minimum_required(VERSION 3.21) project(MyProject VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(Qt6 6.5 REQUIRED COMPONENTS Quick Qml) qt_standard_project_setup(REQUIRES 6.5) qt_add_executable(MyProject main.cpp Main.qml ) qt_add_qml_module(MyProject URI MyProject VERSION 1.0 QML_FILES Main.qml ) # 額外添加自定義控件模塊作為獨立模塊導(dǎo)入 qt_add_qml_module(mycomponents URI MyComponents VERSION 1.0 QML_FILES components/MyCard.qml components/MyButton.qml components/MyProgressCard.qml ) target_link_libraries(MyProject PRIVATE Qt6::Quick Qt6::Qml)這里核心是第二個qt_add_qml_module。我把控件目錄單獨做成了一個 URI 為MyComponents的 QML 模塊這樣你在 Main.qml 里只需要import MyComponents就能用MyCard、MyButton這些類型了。這一步做完編譯運行是沒問題的但這只是“運行時”可見。要讓設(shè)計器也看見還要繼續(xù)。3.3 第三步把模塊路徑告訴 Qt Creator 設(shè)計器這是純 QML 路線里最關(guān)鍵的一步。Qt Creator 設(shè)計器并不會自動去掃描你 CMake 里定義了哪些模塊它需要你告訴它“去哪些路徑下面找 QML 模塊”。打開 Qt Creator菜單欄選“工具” - “選項” - “QML/JS” - “自定義組件路徑”Custom Component Paths。點擊“添加”把包含 qmldir 文件的目錄路徑加進去。這里有個細節(jié)要特別注意要添加的是模塊的根路徑不是控件的具體目錄。也就是說如果你用 CMake 構(gòu)建生成的模塊元數(shù)據(jù)通常在構(gòu)建目錄下比如build/MyComponents你要添加的路徑應(yīng)該是這個包含 qmldir 的目錄如果是純手工目錄就添加components所在的上一層目錄然后里面按模塊名組織子目錄。更省事的做法直接添加你的components目錄然后確保目錄結(jié)構(gòu)是“模塊名/文件”的層次。因為 Qt Creator 支持在組件路徑面板中導(dǎo)入一個根路徑然后它自動搜索這個路徑下所有的子模塊。我項目里components這個根路徑一加MyComponents就出現(xiàn)在組件庫面板里了。3.4 第四步重新加載設(shè)計器找到控件并拖拽路徑配置好了之后記得做兩件事重新構(gòu)建工程確保新模塊的 qmldir 已經(jīng)生成。關(guān)閉當前 .qml 文件窗口重新打開讓設(shè)計器重新解析項目環(huán)境。然后切到 Design Mode左側(cè)組件庫面板最下面通常會出現(xiàn)新的分組分組名對應(yīng)模塊 URI。我這邊顯示的是MyComponents展開就是MyCard、MyButton、MyProgressCard三個控件。直接拖一個MyCard到畫布上設(shè)計器會生成類似這樣的代碼MyCard { id: myCard x: 120 y: 80 titleText: 標題 descText: 這里是描述內(nèi)容 }右側(cè)屬性面板里能改文字、顏色、圓角整個過程和拖 Qt Quick 自帶的 Button 沒什么區(qū)別。走到這一步你的“5 步可視化插件”已經(jīng)完成 80% 了。3.5 第五步進階——用 C 把控件注冊成真正的插件顯示全局組件純 QML 模塊的方式有個限制它依賴你把組件路徑配置好而且組件庫里的分組、圖標、分類都比較樸素。如果你想把控件做成一個真正的、帶圖標的“插件”讓它在任何項目里都能拖那需要用到 C 的 QML 插件機制。思路是這樣寫一個 C 類繼承QQmlExtensionPlugin。在自己的插件類里通過qmlRegisterType注冊 QML 類型。CMake 里用qt_add_qml_module配置PLUGIN_TARGET生成插件。把插件和 qmldir 一起放進 Qt 的 QML 模塊安裝目錄或通過 Qt Creator 的組件路徑指向插件所在目錄。第 2 步注冊的代碼大概是#include QQmlExtensionPlugin #include QQmlEngine class MyComponentsPlugin : public QQmlExtensionPlugin { Q_OBJECT Q_PLUGIN_METADATA(IID QQmlExtensionInterface_iid) public: void registerTypes(const char *uri) override { qmlRegisterType(QUrl(QStringLiteral(qrc:/qt/qml/MyComponents/MyCard.qml)), uri, 1, 0, MyCard); qmlRegisterType(QUrl(QStringLiteral(qrc:/qt/qml/MyComponents/MyButton.qml)), uri, 1, 0, MyButton); } };這里我實際上是用 URL 方式注冊了一個 QML 文件為類型這是 Qt 6 里常用的一種混合注冊方式控件實現(xiàn)仍是 QML插件只負責“告訴設(shè)計器這個類型存在”。這種注冊方式比純 qmldir 更正式一點組件庫面板里面顯示也更穩(wěn)定。寫完后工程里qt_add_qml_module的配置加一行PLUGIN_TARGET就行qt_add_qml_module(mycomponents URI MyComponents VERSION 1.0 PLUGIN_TARGET mycomponentsplugin QML_FILES components/MyCard.qml components/MyButton.qml components/MyProgressCard.qml )編譯生成的插件再配合組件路徑導(dǎo)入Qt Creator 會自動識別。這個方案比起純 QML 更接近“真正的可視化插件”但對工程組織要求更高新手建議先跑通純 QML 方案再把 C 加進來。3.6 完整 CMakeLists.txt 參考為了避免大家拼配置時漏這漏那我把剛才講的完整 CMakeLists.txt 貼一遍基于 Qt 6.5 驗證過cmake_minimum_required(VERSION 3.21) project(MyProject VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(Qt6 6.5 REQUIRED COMPONENTS Quick Qml) qt_standard_project_setup(REQUIRES 6.5) qt_add_executable(MyProject main.cpp Main.qml ) qt_add_qml_module(MyProject URI MyProject VERSION 1.0 QML_FILES Main.qml ) qt_add_qml_module(mycomponents URI MyComponents VERSION 1.0 QML_FILES components/MyCard.qml components/MyButton.qml components/MyProgressCard.qml ) target_link_libraries(MyProject PRIVATE Qt6::Quick Qt6::Qml)main.cpp 保持 Qt 6 默認模板就行主要是QQuickView或者QQmlApplicationEngine加載 Main.qml。4. 拖拽進來的控件出問題了常見問題與排查實錄我把自己折騰過程中遇到的坑以及給身邊同事排查時最常見的問題整理成了一份速查表每一條都寫清楚現(xiàn)象和解決辦法。4.1 組件庫是空的或者看不到自定義控件分組現(xiàn)象組件路徑配了工程也重新構(gòu)建了但組件庫面板里就是不出MyComponents分組。排查順序先確認 qmldir 文件是否真的生成了。在構(gòu)建目錄里搜一下如果qt_add_qml_module執(zhí)行成功構(gòu)建目錄里應(yīng)該有一個和你 URI 同名的文件夾里面有qmldir和一堆編譯產(chǎn)物。如果沒有說明 CMake 配置有問題大概率是QML_FILES里列的文件路徑寫錯了。再檢查組件路徑是不是指向?qū)α四夸?。Qt Creator 的組件路徑支持兩種一種是“頂層目錄”Qt Creator 會遞歸找模塊另一種是“精確模塊目錄”。我建議剛開始先用精確目錄把路徑指到構(gòu)建目錄下MyComponents這一層最容易定位問題。4.2 控件拖進來后是空白/白屏或者只有一個小方塊現(xiàn)象組件庫顯示正常拖一個MyCard到畫布上但設(shè)計器里看不見內(nèi)容。常見原因有三個。第一控件里用了設(shè)計器不支持的屬性或類型比如直接用了Canvas、ShaderEffect這類高級繪制組件設(shè)計器預(yù)覽能力跟不上顯示就是空的。第二控件高度或?qū)挾葲]有設(shè)置根對象默認是 0 尺寸。所以我在示例里給根對象設(shè)了implicitWidth和implicitHeight設(shè)計器拖拽時會優(yōu)先用它作為初始尺寸。第三控件內(nèi)部使用到了運行時才有值的上下文屬性例如調(diào)用了一個尚未定義的 C 單例屬性設(shè)計器解析時該屬性不存在整個控件渲染報錯。解法也很樸素先做一個極簡的測試控件只放一個 Rectangle 和一個 Text確認能顯示再逐步往里面加內(nèi)容。哪一步畫布變白了問題就出現(xiàn)在剛加的配置上。4.3 屬性面板里看不到自定義屬性現(xiàn)象控件拖進來了但屬性面板只有 x、y、width、height 這些通用屬性自己定義的titleText、cardColor全都不顯示。這八成是因為你沒有在頂層對象上定義property。設(shè)計器解析 .qml 文件的頂層屬性時只認“根對象”里聲明的屬性。你把屬性寫在一個嵌套的 Rectangle 里設(shè)計器不會把它提升為控件可配置項。檢查一下屬性是寫在根對象還是子對象上寫在根對象上才會出現(xiàn)在屬性面板。還有一個低頻但真實的原因?qū)傩悦制磳懟虼笮懖灰恢卤热缍x的是titleText使用時寫title_text設(shè)計器解析后找不到對應(yīng)屬性干脆不顯示。QML 是大小寫敏感的命名統(tǒng)一很重要。4.4 設(shè)計器報錯QML module not found現(xiàn)象打開 Main.qml 切到 Design Mode提示找不到MyComponents模塊但運行時編譯沒問題。這個很典型因為運行時用的是構(gòu)建系統(tǒng)里的模塊路徑設(shè)計器用的是組件路徑。運行時能找到不代表設(shè)計器知道去哪里找。遇到這個報錯先檢查 Qt Creator 的“自定義組件路徑”里是不是把構(gòu)建目錄對應(yīng)的那個模塊路徑加進去了。加了之后還報錯就重啟一遍 Qt Creator。設(shè)計器對 QML 模塊路徑的緩存比較“頑固”我測試時經(jīng)常改完路徑設(shè)置之后必須關(guān)閉整個 IDE再打開才生效。4.5 無邊框窗口和 Window 類控件拖不進設(shè)計器標題熱詞里有人搜索“qml 無邊框窗口實現(xiàn)”如果你把無邊框窗口邏輯寫進一個自定義控件再放進設(shè)計器大概率會遇到渲染異常。無邊框窗口通常會設(shè)置flags: Qt.FramelessWindowHint或使用Window做根對象而Window在 Qt Creator 設(shè)計器里不能作為普通控件拖入它會被當成獨立窗口處理。我的建議是窗口殼子和內(nèi)容控件分開。自定義控件只做窗口內(nèi)部的內(nèi)容組件無邊框窗口本身放在業(yè)務(wù)代碼里創(chuàng)建。這樣內(nèi)容組件可以作為可視化插件拖拽窗口邏輯留在運行時兩不誤。4.6 按鈕文字顏色改了沒反應(yīng)或者文字不顯示熱詞里“修改 qml button 的字體顏色”對應(yīng)的就是這類問題。先說結(jié)論Button 的字體顏色用font.pixelSize和自定義樣式聯(lián)動時最穩(wěn)妥的是改contentItem里的 Text color或者設(shè)置 Button 的palette。但在設(shè)計器里改屬性后沒反應(yīng)往往是綁定覆蓋問題。比如你在自定義控件內(nèi)部寫死了color: white設(shè)計器屬性面板里改了buttonColor但內(nèi)部 Rectangle 的顏色綁定仍然是固定值那就當然看不到效果。正確做法是讓內(nèi)部元素顏色全部綁定到導(dǎo)出的屬性上而不是寫死。設(shè)計器只負責修改屬性值不會幫你“穿透”到內(nèi)部寫死值的地方。4.7 編譯報錯、代碼格式化對齊等周邊問題熱詞里有人問“qt creator 代碼對齊快捷方式不好用”。這和自定義控件可視化本身關(guān)系不大但開發(fā)效率影響不小我順帶說一下。Qt Creator 里重新格式化選中代碼的快捷鍵是 Ctrl Alt F格式化當前文件是 Ctrl Alt F 的上一檔不同版本略有差異有時候快捷鍵沒反應(yīng)是因為和輸入法或系統(tǒng)快捷鍵沖突。在“工具”-“選項”-“環(huán)境”-“鍵盤”里搜索“Reformat”重新綁定一個自己習慣的按鍵即可。另外如果 QML 文件里出現(xiàn)了編譯報錯但運行時能跑通常是因為用了設(shè)計器不支持的寫法比如在屬性綁定里寫了非法的表達式。我建議把設(shè)計器報錯內(nèi)容截圖下來逐條看大部分信息會明確指出哪個文件第幾行有問題比盲目改代碼快得多。4.8 一個更高效的排查路徑如果上面這些都沒有解決你的問題我建議按這條路徑走一遍先放棄設(shè)計器直接運行工程確認控件本身沒有運行時錯誤。新建一個臨時 .qml 文件手動 importMyComponents寫幾行代碼實例化控件編譯運行。如果運行時能顯示說明控件邏輯沒問題純粹是設(shè)計器配置問題。回到設(shè)計器按模塊路徑、組件路徑、緩存順序一級一級排查。這套流程能幫你快速區(qū)分“控件代碼問題”和“設(shè)計器集成問題”而不是在設(shè)計器報錯里亂猜。5. 想在團隊里把這套能力用起來幾個進階技巧自定義控件能拖了只是開始。真正舒服的用法是讓設(shè)計器和代碼協(xié)作起來把團隊里高頻復(fù)用的組件全部推成可拖拽插件UI 搭建效率才能上來。5.1 利用 Qt.designer 條件分支讓控件“設(shè)計時”和“運行時”表現(xiàn)不同QML 里有個很少被提到的功能Qt.designer屬性。在設(shè)計器預(yù)覽時它返回一個對象可以用來判斷當前是否運行在設(shè)計器環(huán)境里。利用這個特性你可以讓同一個控件在設(shè)計器里顯示一個簡化版運行時顯示完整版。Item { property bool isDesigner: typeof Qt.designer ! undefined Qt.designer ! null Rectangle { anchors.fill: parent color: isDesigner ? #EAEAEA : actualColor // 設(shè)計器里顯示灰色占位塊運行時才渲染真實顏色 } }這個寫法對復(fù)雜控件很管用。比如一個圖表控件的真實動畫設(shè)計器渲染不了你可以讓設(shè)計器里只顯示一個靜態(tài)的 Rectangle 占位保證拖拽流暢、預(yù)覽不報錯運行時再加載真正的圖表邏輯。5.2 設(shè)計器里給控件一個“體面”的初始大小和布局行為很多人在設(shè)計器里拖入自定義控件后發(fā)現(xiàn)控件尺寸不是自己想要的樣子原因是控件沒有設(shè)置implicitWidth和implicitHeight。這兩個屬性既影響布局系統(tǒng)也影響設(shè)計器顯示。我在所有自定義控件里都強制要求寫這兩個屬性哪怕值是 0也明確寫上方便后面排查。如果控件內(nèi)部內(nèi)容尺寸不固定可以在根對象里設(shè)置一個合理的默認值比如implicitWidth: 240。這樣使用者拖進去至少能看到一個像樣的組件而不是一個小黑點。5.3 控件分類、圖標、默認值怎么配置純 QML 模塊注冊出來的組件分類默認就是模塊名。想讓組件庫面板更整潔可以在qt_add_qml_module里設(shè)置分類信息或者通過模塊目錄下的qmldir注釋來配置。如果走 C 插件路線則可以用QML_ELEMENT宏和類上的注釋來自動生成分類和版本信息也可以重寫插件類的initializeEngine方法來設(shè)置默認值。圖標方面Qt Creator 會默認顯示一個通用圖標如果想自定義圖標需要在模塊資源里按規(guī)格放置圖標文件并在 qmldir 或插件元數(shù)據(jù)里引用。這個操作網(wǎng)上資料不多實測效果也不如 Qt 自帶的那些控件精致所以我建議初期先不執(zhí)著于圖標用默認圖標跑通流程更重要。5.4 與設(shè)計器生成代碼協(xié)作格式化、對齊、版本管理設(shè)計器拖拽生成的 QML 代碼有時候排版比較亂尤其當你在畫布上拖了很多控件之后。我的習慣是拖完之后立即執(zhí)行一次整個文件的格式化讓代碼對齊統(tǒng)一再手動把 id 改成有業(yè)務(wù)含義的名字。這里提醒一下設(shè)計器生成的代碼和手寫代碼在版本管理里經(jīng)常沖突。如果團隊里多人同時改一個界面文件用可視化拖拽的人和使用代碼編輯器的人很容易互相覆蓋。我推薦的做法是把設(shè)計器拖拽的控件單獨放在一個專屬的 .qml 文件里業(yè)務(wù)邏輯寫在另一個文件通過信號和屬性交互這樣沖突范圍會小很多。5.5 一個日常開發(fā)里很順的組合用法我自己現(xiàn)在的工作流是高頻組件全部寫成自定義控件注冊成MyComponents模塊每次新建頁面打開 Design Mode從組件庫拖出需要的基礎(chǔ)卡片、按鈕、進度條把屬性和文本在右側(cè)面板配好再到代碼里補充連接信號和邏輯。對于老項目里那些已經(jīng)寫好但沒法拖拽的歷史控件我有空就花幾分鐘把它們改造成“設(shè)計器友好”的寫法慢慢把組件庫積累起來。實測下來一個信息化管理系統(tǒng)的界面從原來純手寫要 40 分鐘到現(xiàn)在拖拽加填補邏輯大概 15 分鐘效率提升非常明顯。另外雖然不是每個 QML 項目都適合走“全可視化拖拽”路線但“自定義控件先在設(shè)計器里預(yù)覽、再在代碼里復(fù)用”這個思路對所有 Qt Quick 項目都通用。你不需要把所有頁面都改成拖拽式開發(fā)只要組件庫能用開發(fā)體驗就會有質(zhì)的提升。