# 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 }) } }) ```