API 參考
本文檔提供 SQL 格式化工具的功能與實作技術細節。
工具設定
格式化選項
此工具支援以下設定選項：
interface FormattingOptions {
indentSize: number; // 2, 4, or 8 spaces
keywordCase: "upper" | "lower" | "preserve";
uppercaseKeywords: boolean;
uppercaseFunctions: boolean;
uppercaseDataTypes: boolean;
alignCommas: boolean;
breakBeforeBooleanOperator: boolean;
}
預設設定
const defaultOptions: FormattingOptions = {
indentSize: 2,
keywordCase: "upper",
uppercaseKeywords: true,
uppercaseFunctions: true,
uppercaseDataTypes: true,
alignCommas: false,
breakBeforeBooleanOperator: true,
};
支援的 SQL 關鍵字
資料操作語言（DML）
- SELECT：從資料表查詢資料
- INSERT：插入新記錄
- UPDATE：修改既有記錄
- DELETE：刪除記錄
資料定義語言（DDL）
- CREATE：建立資料庫物件
- ALTER：修改資料庫物件
- DROP：移除資料庫物件
- TRUNCATE：刪除資料表中的所有記錄
資料控制語言（DCL）
- GRANT：授與權限
- REVOKE：撤銷權限
交易控制
- COMMIT：儲存交易變更
- ROLLBACK：還原交易變更
- SAVEPOINT：建立儲存點
支援的 SQL 函式
彙總函式
- COUNT：計算資料列或非空值數量
- SUM：計算總和
- AVG：計算平均值
- MIN：找出最小值
- MAX：找出最大值
字串函式
- UPPER：轉換為大寫
- LOWER：轉換為小寫
- LENGTH：取得字串長度
- SUBSTRING：擷取子字串
- CONCAT：串接字串
- TRIM：移除前後空白
日期/時間函式
- NOW：取得目前時間戳
- DATE：擷取日期部分
- TIME：擷取時間部分
- YEAR：擷取年份
- MONTH：擷取月份
- DAY：擷取日期
數學函式
- ROUND：依指定小數位四捨五入
- FLOOR：向下取整
- CEIL：向上取整
- ABS：取得絕對值
- SQRT：計算平方根
- POWER：次方運算
支援的資料型別
數值型別
- INT：整數值
- INTEGER：整數值
- BIGINT：大型整數值
- SMALLINT：小型整數值
- TINYINT：極小整數值
- DECIMAL：定點小數
- NUMERIC：定點小數
- FLOAT：浮點數
- DOUBLE：雙精度浮點數
- REAL：單精度浮點數
字串型別
- CHAR：固定長度字串
- VARCHAR：可變長度字串
- TEXT：大型文字資料
- BLOB：二進位大型物件
日期/時間型別
- DATE：日期值
- TIME：時間值
- DATETIME：日期與時間值
- TIMESTAMP：時間戳值
其他型別
- BOOLEAN：布林值
- BIT：位元值
- JSON：JSON 資料
格式化規則
縮排規則
- SELECT 子句：每個欄位獨立一行並套用縮排
- FROM 子句：資料表名稱依規則縮排
- JOIN 子句：JOIN 條件使用適當縮排
- WHERE 子句：條件依規則縮排
- GROUP BY：分組欄位使用縮排
- ORDER BY：排序欄位使用縮排
大小寫轉換規則
- 關鍵字：轉換為指定大小寫（大寫/小寫/保留）
- 函式：函式名稱轉換為指定大小寫
- 資料型別：資料型別名稱轉換為指定大小寫
- 識別字：資料表與欄位名稱保留原始大小寫
換行規則
- 主要子句：在 SELECT、FROM、WHERE、GROUP BY、ORDER BY 前換行
- JOIN 子句：每種 JOIN 類型前換行
- 布林運算子：啟用時在 AND/OR 前換行
- 逗號對齊：啟用時在 SELECT 清單中對齊逗號
歷史記錄管理
歷史記錄結構
interface HistoryRecord {
id: string;
input: string;
output: string;
options: FormattingOptions;
timestamp: number;
}
歷史記錄操作
- 新增記錄：自動新增新的格式化記錄
- 刪除記錄：移除指定歷史項目
- 清空歷史：刪除所有歷史記錄
- 載入記錄：從歷史中還原 SQL 與選項
儲存限制
- 最大記錄數：50 筆歷史記錄
- 儲存位置：瀏覽器本機儲存
- 持久性：資料可跨瀏覽器工作階段保留
錯誤處理
常見錯誤
- SQL 語法無效：SQL 查詢格式錯誤
- 不支援的結構：格式化器不支援的 SQL 特性
- 大型查詢：超出處理限制的查詢
- 瀏覽器限制：本機儲存或記憶體限制
錯誤復原
- 語法驗證：基本 SQL 語法檢查
- 優雅降級：為複雜查詢提供部分格式化
- 使用者回饋：清楚的錯誤訊息與建議
- 替代方案：提供其他格式化方式
效能考量
處理限制
- 查詢大小：可處理最多 10,000 個字元的查詢
- 複雜度：支援最多 10 層巢狀查詢
- 處理時間：通常可在 100ms 內完成
最佳化功能
- 增量處理：僅處理變更部分
- 快取：為重複操作快取格式化結果
- 延遲載入：按需載入歷史記錄
瀏覽器相容性
支援的瀏覽器
- Chrome：80+ 版本
- Firefox：75+ 版本
- Safari：13+ 版本
- Edge：80+ 版本
必要功能
- ES6 支援：箭頭函式、樣板字串
- Local Storage：瀏覽器本機儲存 API
- Clipboard API：現代剪貼簿存取能力
- CSS Grid：版面配置支援
整合
嵌入選項
此工具可整合到其他應用程式中：
- Iframe 嵌入：以 iframe 形式嵌入
- API 整合：直接使用格式化函式
- 元件整合：作為 Vue 元件引入
自訂
- 主題支援：淺色與深色主題
- 語言支援：多語言選項
- 自訂樣式：支援 CSS 樣式自訂