React Query Builder：组件、工具函數和配套包
專案速覽：React 的查詢產生器元件。 [!TIP] 若要啟用拖放功能，請使用 @react-querybuilder/dnd。
秒懂
- 它是什麼？
- 一個用于 React 的可自定义查询構建器的 TypeScript 倉庫，支持导入和导出 SQL 與 MongoDB，并提供樣式庫的官方配套包。
- 適合誰用？
- 适合需要在 React 表单或後台頁面中组合查询条件，并希望把查询导入或导出為 SQL、MongoDB 等格式的团队；不适合把拖放、日期時間或规则引擎能力当作主包默認功能的人。先运行 README 的最小组件示例，檢查 defaultQuery、onQueryChange 與樣式导入，再按需驗證配套包。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 5 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
核心组件和查询语言工具函數 · react-querybuilder-react-querybuilder-deep-analysis
React Query Builder 是一個单一倉庫，包含主要的 QueryBuilder React 组件和一组工具函數。這些工具函數用于從多种查询语言导入查询定义并导出到這些语言，包括 SQL 和 MongoDB，如 README 所述。该组件本身被描述為完全可自定义，并且文檔站点提供了在線演示的链接。根據倉庫的语言元數據，该项目使用 TypeScript 编寫。README 没有列举每個自定义点，這些细节位于 react-querybuilder.js.org 的完整文檔中。
react-querybuilder 的 query 由 fields、combinators、operators 和 rules 組成，組件顯示只是這份資料的編輯介面。應先固定 initialQuery，觸發新增規則、改變 field、輸入 value，再檢查 onQueryChange 的 JSON 結構。尤其要確認 field 元件與 valueEditor 使用的 valueType 相符。
formatQuery 可將同一份 query 轉成 SQL、MongoDB 或其他格式，但格式化結果仍受自訂 operator、field path 與 value 處理影響。以含巢狀群組和 NOT 條件的測試查詢比較輸出，並檢查使用者輸入是否經過參數化處理。展示查詢字串不等於已完成資料庫安全設計。
react-querybuilder-react-querybuilder-deep-analysis 第 1 節的檢查記錄應包含 package.json 與 README.md，並保留該節所述輸入與輸出。這個欄位能把文件中的功能描述連到實際程式狀態，避免只依畫面或單次成功結果下結論。對失敗案例也要保存錯誤文字與觸發條件，才能分辨設定問題、版本差異和程式邏輯。
组件入门 · react-querybuilder-react-querybuilder-deep-analysis
README 展示了一個最小化設置：导入 QueryBuilder 组件和樣式表，然後使用有状态的查询對象渲染它。示例使用 React 的 useState 钩子，初始查询的 combinator 為 'and'，rules 數组為空。组件接收 defaultQuery 和 onQueryChange 属性。樣式表可以從 'react-querybuilder/dist/query-builder.css' 或對應的 .scss 文件导入。為了更完整的介绍，README 指向主包 README、完整文檔以及倉庫內的示例项目。這些示例项目在 README 中仅提及存在，没有進一步描述。
react-querybuilder-react-querybuilder-deep-analysis 第 2 節的檢查記錄應包含 src/index.js 與 build 目錄，並保留該節所述輸入與輸出。這個欄位能把文件中的功能描述連到實際程式狀態，避免只依畫面或單次成功結果下結論。對失敗案例也要保存錯誤文字與觸發條件，才能分辨設定問題、版本差異和程式邏輯。
官方配套包 · react-querybuilder-react-querybuilder-deep-analysis
除了主包，倉庫還托管了多個樣式庫的官方兼容包：Ant Design、Bootstrap、Bulma、Chakra UI、Fluent UI、Mantine、MUI、PrimeReact 和 Tremor。還有一個 React Native 组件。另外，還提到了四個功能包：@react-querybuilder/dnd 用于拖放，@react-querybuilder/datetime 用于增强日期時間处理，@react-querybuilder/expr 用于在规则中啟用表达式，@react-querybuilder/rules-engine 用于 if-then-else 规则引擎功能。README 没有给出這些包的安装命令，只说明了它们提供的功能。
react-querybuilder-react-querybuilder-deep-analysis 第 3 節的檢查記錄應包含 onQueryChange 與 defaultValues，並保留該節所述輸入與輸出。這個欄位能把文件中的功能描述連到實際程式狀態，避免只依畫面或單次成功結果下結論。對失敗案例也要保存錯誤文字與觸發條件，才能分辨設定問題、版本差異和程式邏輯。
迁移指南和文檔 · react-querybuilder-react-querybuilder-deep-analysis
README 引用了两個迁移指南：一個用于從早期版本的 react-querybuilder 迁移，另一個用于從 react-awesome-query-builder（RAQB）迁移。两者都托管在文檔站点上。README 還链接到完整文檔和单独的演示頁面。根據元數據，倉庫的主分支名為 main，项目未被归檔。README 中没有提供發布历史或版本号的信息。
react-querybuilder-react-querybuilder-deep-analysis 第 4 節的檢查記錄應包含 formState.errors 與 schema，並保留該節所述輸入與輸出。這個欄位能把文件中的功能描述連到實際程式狀態，避免只依畫面或單次成功結果下結論。對失敗案例也要保存錯誤文字與觸發條件，才能分辨設定問題、版本差異和程式邏輯。
開發、贡献和倉庫状态 · react-querybuilder-react-querybuilder-deep-analysis
README 指向 CONTRIBUTING.md 文件以获取開發指南。贡献者部分遵循 all-contributors 规范，徽章显示有 48 位贡献者。倉庫元數據记錄了 1,711 個星標、312 個復刻和 9 個未關閉的问題。项目未被归檔。README 说明欢迎任何类型的贡献，贡献者表格列出了個人及其贡献，但此处未復現该表格。開發過程本身除了贡献指南链接外没有描述。
react-querybuilder-react-querybuilder-deep-analysis 第 5 節的檢查記錄應包含 Podfile 與 Metro 日誌，並保留該節所述輸入與輸出。這個欄位能把文件中的功能描述連到實際程式狀態，避免只依畫面或單次成功結果下結論。對失敗案例也要保存錯誤文字與觸發條件，才能分辨設定問題、版本差異和程式邏輯。
許可證和灵感來源 · react-querybuilder-react-querybuilder-deep-analysis
组件的 README 將 jQuery QueryBuilder、Angular QueryBuilder 和 React Awesome Query Builder 列為灵感來源。该軟件采用 MIT 許可證，版權归 Jake Boone 和其他贡献者所有。許可證授予使用、復制、修改、合并、發布、分發、再許可和出售軟件副本的權利，但需在所有副本或實质性部分中包含上述版權声明和許可声明。軟件按"原樣"提供，不提供任何形式的担保，作者不對任何索赔或损害承担責任。許可證文本未涉及安全性、支持或维護承诺。
react-querybuilder-react-querybuilder-deep-analysis 第 6 節的檢查記錄應包含 StreamSubscription 與 cancel，並保留該節所述輸入與輸出。這個欄位能把文件中的功能描述連到實際程式狀態，避免只依畫面或單次成功結果下結論。對失敗案例也要保存錯誤文字與觸發條件，才能分辨設定問題、版本差異和程式邏輯。
react-querybuilder 的自訂控件也會改變資料契約。替換 valueEditor、addRuleToNewGroups 或 controlElements 後，應重新測試 ruleGroup、combinator 和 field 的預設值，並用 formatQuery 產生 SQL 與 MongoDB 兩種結果。對含引號、空值和巢狀群組的輸入，保存原始 query 與格式化字串，才能審核轉換是否符合資料庫介面。
並核對 SQL 參數與欄位型別，避免字串看似正確。
並測試刪除群組後的 combinator 狀態。
確認查詢結果可安全執行。
編輯結論
适合需要在 React 表单或後台頁面中组合查询条件，并希望把查询导入或导出為 SQL、MongoDB 等格式的团队；不适合把拖放、日期時間或规则引擎能力当作主包默認功能的人。先运行 README 的最小组件示例，檢查 defaultQuery、onQueryChange 與樣式导入，再按需驗證配套包。
社群筆記