[jquery] Form plugin 參數

API

Form插件API
Form插件提供一些方法，這些方法使你能夠輕鬆地管理form數據和form提交。

ajaxForm
使用JAJAX通過添加所有必要的事件監聽來準備好一個被提交的form。這個並沒有提交表單。在文檔的ready方法中使用ajaxForm來為AJAX提交準備好form。ajaxForm沒有或只有一個參數。唯一的參數既可以是回調方法，也可以是一個可選對象。

Chainable（這個詞不知道什麼意思）：Yes

例子：

CODE:

$('#myFormId').ajaxForm();

ajaxSubmit
使用AJAX立即提交form。在大多數情況下它作為對用戶提交表單的回應中被調用。ajaxSubmit沒有或只有一個參數。唯一的參數既可以是回調方法，也可以是一個可選對象。

Chainable：Yes

例子：

CODE:

// attach handler to form's submit event
$('#myFormId')submit(function() {
// submit the form
$(this).ajaxSubmit();
// return false to prevent normal browser submit and page navigation
return false;
});

formSerialize
連載（Serializes）form至一個查詢字符串。這個方法將會返回一個這種格式的字符串：name1=value1&name2=value2

Chainable: No, this method returns a String

例子：

CODE:

var queryString = $('#myFormId').formSerialize();

// the data could now be submitted using $.get, $.post, $.ajax, etc
$.post('myscript.php', queryString);

fieldSerialize
連載（Serializes）字段元素至一個查詢字符串。當你想要連載form中的一部分字段值得時候這樣做很方便。這個方法將會返回一個這種格式的字符串：name1=value1&name2=value2

Chainable: No, this method returns a String

例子：

CODE:

var queryString = $('#myFormId .specialFields').fieldSerialize();

fieldValue
匹配元素中的數組形式的返回值。在.91版本中，這個方法經常返回一個數組。如果沒有可用的值被確認這個數組將會被請空，否則它將會包含一個或多個值。

Chainable: No, this method returns an array

例子：

CODE:

// get the value of the password input
var value = $('#myFormId :password').fieldValue();
alert('The password is: ' + value[0]);

resetForm
避免使用form元素本身的DOM方法來重置form

Chainable: Yes

例子：

CODE:

$('#myFormId').resetForm();

clearForm
清除form元素。這個方法會請空所有的text輸入框，password輸入框和textarea元素，清除任何選擇元素的選項，並且將所有選擇按鈕設置為未選中。

Chainable: Yes

例子：

CODE:

$('#myFormId').clearForm();

可選對象

ajaxForm和ajaxSubmit都支持一些選項，這些選項都可以通過使用一個可選的對象被提供。這個可選的對象就是一個簡單的包含屬性和值的JavaScript對象，就像下邊這樣：

target
伴隨服務器響應識別將要被更新的頁面中的元素。這個值可以被特定為一個jQuery選擇器字符串，一個jQuery對象或者一個DOM元素。

默認值: null

url
form將要被提交到的URL

默認值：form的action的值

type
form數據將要提交的方法，「GET」或「POST」

默認值：form的method的值（如果沒有找到的話就是「GET」）

beforeSubmit
在form被提交前調用的回調函數。「beforeSubmit」回調可以被提供作為一個鉤子（hook）用來執行預提交（pre-submit）邏輯或 者驗證form的數據。如果「beforeSubmit」回調返回false，那麼form就不會被提交。「beforeSubmit」回調調用有三個參 數：數組形式的form數據，對於form的jQuery對象，和傳遞給ajaxForm/ajaxSubmit的可選對象。數組形式的form數據是下 邊的形式：

CODE:

[ { name: 'username', value: 'jresig' }, { name: 'password', value: 'secret' } ]

默認值：null

success
在form被提交後調用的回調函數。如果一個「success」回調函數被提供的話，它會在響應從服務器上被返回後被調用。它傳遞responseText或responseXML值（決定於dataType選項的值）

默認值：null

dataType
響應所希望的數據類型。可以是：null，'xml'，'script'，或者'json'。dataType選項提供了一種用來特定服務器響應應當如何被操作。

「xml」：如果dataType == 'xml'，那麼服務器響應就會被處理為XML並且「success」回調方法，如果被指定，將會被傳遞responseXML值
「json」：如果dataType == 'json'，the server response will be evaluted and passed to the 'success' callback, if specified
「script」：如果dataType == 'script'，the server response is evaluated in the global context

semantic（太難了，不會翻譯，大家自己研究吧）
Boolean flag indicating whether data must be submitted in strict semantic order (slower). Note that the normal form serialization is done in semantic order with the exception of input elements of type="image". You should only set the semantic option to true if your server has strict semantic requirements and your form contains an input element of type="image".

resetForm
布爾標誌表明了當form被成功提交後是否重置form

默認值：null

clearForm
布爾標誌表明了當form被成功提交後form是否被清空
默認值：null

例子：

CODE:

// prepare Options Object
var options = {
target: '#divToUpdate',
url: 'comment.php',
success: function() {
alert('Thanks for your comment!');
}
};

// pass options to ajaxForm
$('#myForm').ajaxForm(options);

我們注意到：這些個可選對象同樣也被用來向jQuery的$.ajax傳遞值。如果你習慣於$.ajax所提供的選項的話你就會在可選對象中使傳遞他們給ajaxForm和ajaxSubmit了。