jQuery 表單驗證插件 Vanadium 使用指南：聲明式規則、自定義提示與精簡打包

Vanadium 是一款輕量、規則豐富、採用聲明式 HTML 屬性配置的 jQuery 表單驗證插件。本文詳細講解引入方式、驗證鉤子語法、多規則組合、錯誤提示自定義、未用規則剔除及核心參數配置，助你快速集成生產級表單驗證。

快速開始

1. 引入文件

<script src="jquery.js"></script>
<script src="vanadium.js"></script>

2. 聲明式驗證規則

在表單控件上添加 class 作為驗證鉤子，格式：:rule_name 或 :rule_name;param。

<form id="regForm">
    <!-- 必填 -->
    <input id="username" class=":required" />

    <!-- 必填 + 長度 4~8 -->
    <input id="password" class=":required :min_length;4 :max_length;8" />

    <!-- 郵箱格式 -->
    <input id="email" class=":required :email" />

    <!-- 數字 + 範圍 -->
    <input id="age" class=":number :min;18 :max;100" />

    <!-- 自定義正則 -->
    <input id="phone" class=":required :regexp;/^1\d{10}$/" />

    <button type="submit">提交</button>
</form>

3. 啟用驗證

$('#regForm').vanadium(); // 默認綁定 submit 事件

核心驗證規則速查

進階配置

1. 自定義錯誤提示樣式與文案

Vanadium 默認生成錯誤提示元素，可通過選項覆蓋樣式類名：

$('#regForm').vanadium({
    valid_class: 'valid-field',      // 驗證通過樣式
    invalid_class: 'invalid-field',  // 驗證失敗樣式
    message_value_class: 'msg-value', // 提示中動態值樣式
    advice_class: 'error-message'    // 錯誤提示文本樣式
});

修改默認提示文案（需編輯 vanadium.js 內部 messages 對象或擴展）：

// 擴展/覆蓋默認消息
$.vanadium.messages = {
    required: '此字段不能為空',
    email: '請輸入有效郵箱',
    min_length: '最少需要 {0} 個字符',
    // ... 其他鍵
};

2. 精簡打包：刪除未用規則

Vanadium 核心文件包含所有規則實現，生產部署前建議：

1. 打開 vanadium.js
2. 保留項目中使用的規則函數（如 required、email、number 等）
3. 刪除其餘規則代碼塊
4. 壓縮混淆（UglifyJS/Terser）

可將文件體積從 ~15KB 減至 ~5KB，加載更快。

3. 核心參數詳解

4. 程式化調用與異步場景

const validator = $('#regForm').vanadium({
    onSuccess: function() {
        // 手動提交 AJAX
        $.post('/api/register', $('#regForm').serialize())
          .done(res => { if (res.ok) location.href = '/welcome'; })
          .fail(() => alert('提交失敗'));
        return false; // 阻止默認提交
    }
});

// 手動觸發驗證
if (validator.vanadium('validate')) { ... }

// 重置表單驗證狀態
validator.vanadium('reset');

避坑指南

• 動態添加字段：調用 $(newField).vanadium() 重新綁定，或使用事件委託模式（插件較舊版本可能不支持）。
• 隱藏字段驗證：默認跳過 :hidden，需顯式調用驗證或設置 ignore: ''（若支持）。
• 多表單頁面：每個 form 獨立調用 .vanadium()，不要在同一頁面多次綁定同一 form。
• 與其他庫衝突：Vanadium 依賴 jQuery，確保版本兼容（建議 jQuery 1.7+ / 2.x / 3.x）。

現代替代方案對比

Vanadium 雖早期停止更新，但其「Class 作為規則聲明」的設計思想極具啟發性。理解其機制後，遷移到現代方案將輕而易舉。