# JavaScript API ## JavaScript API ### JavaScript API - `request`方法可以與表單內部或表單元素上的任何元素一起使用 - 當該方法與表單內的元素一起使用時，它將被轉發到表單。 - `request`方法具有一個必填參數-AJAX處理程序名稱。例： - 方法的第二個參數`request`是options對象 ``` <form onsubmit="$(this).request('onProcess'); return false;"> ... ``` | 選項 | 描述 | | --- | --- | |**update** | 指定一個對象要更新的列表局部和頁面元素（作為CSS選擇器）：{'partial'：'#select'}。如果選擇器字符串前面帶有`@`符號，則將從服務器接收的內容添加到元素中，而不是替換現有內容。 | |**confirm** | 如果設置，則確認在發送請求之前顯示。如果用戶單擊“取消”按鈕，則請求將取消。 | |**data** | 指定要與表單數據一起發送到服務器的數據：{var：'value'}。如果`files`為true，則還可以使用 | [`Blob`objects](https://developer.mozilla.org/en-US/docs/Web/API/Blob)將要上傳的文件包括在該[對象中](https://developer.mozilla.org/en-US/docs/Web/API/Blob)。要指定任何`Blob`對象的文件名，只需`filename`在`Blob`對象上設置屬性。（例`var blob = new Blob(variable); blob.filename = 'test.txt'; var data = {'uploaded_file': blob};`） | |**redirect** | 字符串，指定成功請求后將瀏覽器重定向到的URL。 | |**beforeUpdate** | 在頁面元素更新之前執行的回調函數。該函數獲取3個參數：從服務器接收的數據對象，文本狀態字符串和jqXHR對象。的`this`在函數內部變量解決請求內容-包含一個對象2個屬性：`handler`與`options`表示原始請求（）的參數。 | |**success** | 在請求成功的情況下執行的回調函數。如果提供此選項，它將覆蓋默認框架的功能：不更新元素，`beforeUpdate`不觸發事件，不觸發`ajaxUpdate`和`ajaxUpdateComplete`事件。事件處理程序獲取3個參數：從服務器接收的數據對象，文本狀態字符串和jqXHR對象。但是，您仍然可以在函數`this.success(...)`內部調用默認框架功能。 | |**error** | 發生錯誤時執行回調函數。默認情況下，顯示警報消息。如果覆蓋此選項，則不會顯示警報消息。處理程序獲取3個參數：jqXHR對象，文本狀態字符串和錯誤對象-請參見[jQuery AJAX函數](http://api.jquery.com/jQuery.ajax/)。 | |**complete** | 在成功或錯誤的情況下執行的回調函數。 | |**form** | 一個表單元素，用于獲取與請求一起發送的表單數據，可以作為選擇器字符串或表單元素傳遞。 | |**flash** | 如果為true，則指示服務器清除并發送帶有響應的任何Flash消息。默認值：false | |**files** | 如果為true，則請求將接受文件上傳，這需要`FormData`瀏覽器提供接口支持。默認值：false | |**browserValidate** | 如果為true，則將在提交之前對請求執行基于瀏覽器的客戶端驗證。這僅適用于在`<form>`元素上下文中觸發的請求。\*\*注意：\*\*這種形式的驗證不適用于復雜的形式，在這種情況下，用戶可能無法100％地看到已驗證的字段。建議您避免在最簡單的表單上使用它。 | |**loading** | 運行請求時顯示的可選字符串或對象。該字符串應為元素的CSS選擇器，該對象應支持`show()`和`hide()`功能來管理可見性。您可以`$.oc.stripeLoadIndicator`在使用[Extras框架](https://octobercms.com/docs/ajax/extras)時傳遞全局對象。您還可以通過傳遞新功能作為選項來覆蓋某些請求邏輯。這些邏輯處理程序可用。 | |處理程序 |描述 | | --- | --- | |**handleConfirmMessage(message)** | 在請求用戶確認時調用。 | |**handleErrorMessage(message)** | 在顯示錯誤消息時調用。 | |**handleValidationMessage(message, fields)** | 使用驗證時，將焦點放在第一個無效字段上。 | |**handleFlashMessage(message, type)** | 使用**Flash**選項提供Flash消息時調用（見上文）。 | |**handleRedirectResponse(url)** | 瀏覽器應重定向到另一個位置時調用。### 用法示例 | 在發送onDelete請求之前，請請求確認： ``` $('form').request('onDelete', { confirm: '你確定要操作嗎?', redirect: '/dashboard' }) ``` 運行`onCalculate`處理程序，并將呈現的**calcresult**部分與**結果**CSS類一起注入到page元素中： ``` $('form').request('onCalculate', { update: {calcresult: '.result'} }) ``` `onCalculate`使用一些額外的數據運行處理程序： ``` $('form').request('onCalculate', {data: {value: 55}}) ``` `onCalculate`在頁面元素更新之前，運行處理程序并運行一些自定義代碼： ``` $('form').request('onCalculate', { update: {calcresult: '.result'}, beforeUpdate: function() { /* do something */ } }) ``` 運行`onCalculate`處理程序，如果成功，則運行一些自定義代碼和默認`success`功能： ``` $('form').request('onCalculate', {success: function(data) { //... do something ... this.success(data); }}) ``` 執行不帶FORM元素的請求： ``` $.request('onCalculate', { success: function() { console.log('Finished!'); } }) ``` 運行`onCalculate`處理程序，如果成功，請在完成默認`success`功能后運行一些自定義代碼： ``` $('form').request('onCalculate', {success: function(data) { this.success(data).done(function() { //... do something after parent success() is finished ... }); }}) ``` ### AJAX全局事件 AJAX框架在更新的元素，觸發元素，表單和窗口對象上觸發多個事件。無論使用哪個API（數據屬性API或JavaScript API），都會觸發事件。 | 事件 | 描述 | | --- | --- | | **ajaxBeforeSend** | 在發送請求之前在窗口對象上觸發。 | | **ajaxBeforeUpdate** | 在請求完成之后，但在頁面更新之前，直接在表單對象上觸發。處理程序獲取5個參數：事件對象，上下文對象，從服務器接收的數據對象，狀態文本字符串和jqXHR對象。 | | **ajaxUpdate** | 使用框架更新后在頁面元素上觸發。處理程序獲取5個參數：事件對象，上下文對象，從服務器接收的數據對象，狀態文本字符串和jqXHR對象。 | | **ajaxUpdateComplete** | 在框架更新所有元素之后，在window對象上觸發。處理程序獲取5個參數：事件對象，上下文對象，從服務器接收的數據對象，狀態文本字符串和jqXHR對象。 | | **ajaxSuccess** | 成功完成請求后，在表單對象上觸發。處理程序獲取5個參數：事件對象，上下文對象，從服務器接收的數據對象，狀態文本字符串和jqXHR對象。 | | **ajaxError** | 如果請求遇到錯誤，則在表單對象上觸發。處理程序獲取5個參數：事件對象，上下文對象，錯誤消息，狀態文本字符串和jqXHR對象。 | | **ajaxErrorMessage** | 如果請求遇到錯誤，則在窗口對象上觸發。處理程序獲取2個參數：事件對象和從服務器返回的錯誤消息。 | | **ajaxConfirmMessage** | `confirm`給定選項時在窗口對象上觸發。處理程序獲得2個參數：事件對象和作為`confirm`選項一部分分配給處理程序的文本消息。這對于實現自定義確認邏輯/接口（而非本機javascript確認框）很有用。- 這些事件在觸發元素上觸發： | | 事件 | 描述 | | --- | --- | | **ajaxSetup** | 在形成請求之前觸發，從而允許通過`context.options`對象修改選項。 | | **ajaxPromise** | 在AJAX請求發送之前直接觸發。 | | **ajaxFail** | 如果AJAX請求失敗，則最終觸發。 | | **ajaxDone** | 如果AJAX請求成功，則最終觸發。 | | **ajaxAlways** | 無論AJAX請求失敗還是成功都將觸發。 | ### 用法示例 `ajaxUpdate`在元素上觸發事件時執行JavaScript代碼。 ``` $('.calcresult').on('ajaxUpdate', function() { console.log('Updated!'); }) ``` 使用邏輯處理程序執行顯示Flash消息的單個請求。 ``` $.request('onDoSomething', { flash: 1, handleFlashMessage: function(message, type) { $.oc.flashMsg({ text: message, class: type }) } }) ``` 將配置全局應用于所有AJAX請求。 ``` $(document).on('ajaxSetup', function(event, context) { //對所有AJAX請求啟用AJAX處理Flash消息 context.options.flash = true //在所有AJAX請求上啟用StripeLoadIndicator context.options.loading = $.oc.stripeLoadIndicator //通過觸發Error類型的flashMsg來處理錯誤消息 context.options.handleErrorMessage = function(message) { $.oc.flashMsg({ text: message, class: 'error' }) } //通過觸發消息類型的flashMsg來處理Flash消息 context.options.handleFlashMessage = function(message, type) { $.oc.flashMsg({ text: message, class: type }) } }) ```