数据属性 API

数据属性 API 允许您无需任何 JavaScript 即可发出 AJAX 请求。在许多情况下，数据属性 API 比 JavaScript API 更简洁——您编写的代码更少，却能获得相同的结果。支持的 AJAX 数据属性包括：

data-request Attribute	Description
data-request	specifies the AJAX handler name.
data-request-confirm	specifies a confirmation message. A confirmation dialog is displayed before the request is sent. If the user clicks the Cancel button the request isn't sent.
data-request-redirect	specifies a URL to redirect the browser after the successful AJAX request.
data-request-url	specifies a URL to which the request is sent. default: `window.location.href`
data-request-update	specifies a list of partials and page elements (CSS selectors) to update. The format is as follows: `partial: selector, partial: selector`. Usage of quotes is required in some cases, for example: `'my-partial': '#myelement'`. The selector string should start with a `#` or `.` character, except you may also prepend it with `@` to append contents to the element, `^` to prepend, `!` to replace with and `=` to use any CSS selector.
data-request-data	specifies additional POST parameters to be sent to the server. The format is following: `var: value, var: value`. Use quotes if needed: `var: 'some string'`. The attribute can be used on the triggering element, for example on the button that also has the `data-request` attribute, on the closest element of the triggering element and on the parent form element. The framework merges values of the `data-request-data` attributes. If the attribute on different elements defines parameters with the same name, the framework uses the following priority: the triggering element `data-request-data`, the closer parent elements `data-request-data`, the form input data.
data-request-query	specifies additional GET parameters to be sent to the server and added to the current URL query string.
data-request-before-update	specifies JavaScript code to execute directly before the page contents are updated.
data-request-success	specifies JavaScript code to execute after the request is successfully completed. The `data` variable is available in this function containing the response data.
data-request-error	specifies JavaScript code to execute if the request encounters an error. The `data` variable is available in this function containing the response data.
data-request-complete	specifies JavaScript code to execute if the request is successfully completed or encounters an error. The `data` variable is available in this function containing the response data.
data-request-cancel	specifies JavaScript code to execute if the user aborts the request or cancels it via a confirmation dialog.
data-request-message	displays a progress message with the specified text, shown while the request is running. This option is used by the flash messages features.
data-request-loading	specifies a CSS selector for an element to be displayed while the request runs. You can use this option to show an AJAX loading indicator. The feature uses CSS display `block` and `none` attributes to manage the element visibility.
data-request-progress-bar	enable the progress bar when an AJAX request occurs.
data-request-form	explicitly specify a form element to use for sourcing the form data. If this is unspecified, the closest form to the triggering element is used, including if the element itself is a form.
data-request-flash	when included, instructs the server to clear and send any flash messages with the response. This option is used by the flash messages features.
data-request-files	when specified the request will accept file uploads using the `FormData` interface.
data-request-download	when specified file downloads are accepted with a `Content-Disposition` response. This attribute can be added anonymously or set to the downloaded filename.
data-request-bulk	when specified the request be sent as JSON for bulk data transactions.
data-browser-target	when specified with `data-request-download` the output will target this window, for example `_blank`.
data-browser-validate	when specified browser-based client side validation will run on the request before it submits.
data-browser-redirect-back	when a redirect occurs, if the previous URL from the browser is available, use that in place of the redirect URL provided.
data-auto-submit	automatically triggers an AJAX request on elements that also have the `data-request` attribute. The request submits when the browser window is active using the Page Visibility API. The optional attribute value can define the interval, in milliseconds, the framework waits before it sends the request.
data-track-input	can be applied to a text, number, or password input field that also has the `data-request` attribute. When defined, the input field automatically sends an AJAX request when a user types something in the field. The optional attribute value can define the interval, in milliseconds, the framework waits before it sends the requests.

当为一个元素指定 data-request 属性时，该元素会在用户与其交互时触发一个 AJAX 请求。根据元素的类型，该请求会在以下事件上触发：

Element	Event
Forms	when the form is submitted.
Links, buttons	when the element is clicked.
Text, number, and password fields	when the text is changed and only if the `data-track-input` attribute is presented.
Dropdowns, checkboxes, radios	when the element is selected.

使用示例

当表单提交时，触发 onCalculate 处理程序。更新标识符为 "result" 的元素，使用 calcresult 片段。

html

<form data-request="onCalculate" data-request-update="{ calcresult: '#result' }">

当点击删除按钮时，在发送请求之前，请求确认。

html

<form ... >
    ...
    <button data-request="onDelete" data-request-confirm="Are you sure?">Delete</button>

在请求成功后重定向到另一个页面。

html

<form data-request="onLogin" data-request-redirect="/admin">

请求成功后显示一个弹窗。

html

<form data-request="onLogin" data-request-success="alert('Yay!')">

发送一个 POST 参数 mode 值为 update。

html

<form data-request="onUpdate" data-request-data="{ mode: 'update' }">

传递一个 POST 参数 id 值为 7 跨多个元素。

html

<div data-request-data="{ id: 7 }">
    <button data-request="onDelete">Delete</button>
    <button data-request="onSave">Update</button>
</div>

在当前请求中发送 GET 参数 page 值为 6。

html

<button data-request="onSetPage" data-request-query="{ page: 6 }">
    Page 6
</button>

显示一个即时消息当请求正在加载时。

html

<button data-request="onUpdate" data-request-message="Loading...">
    Save Changes
</button>

包括文件上传随请求。

html

<form data-request="onSubmit" data-request-files>
    <input type="file" name="photo" accept="image/*" />
    <button type="submit">Submit</button>
</form>

包含文件下载在响应中。

html

<button data-request="onDownloadFile" data-request-download>
    Download
</button>

用于指定自定义文件名并在新窗口中打开下载，例如预览 PDF。

html

<button
    data-request="onDownloadFile"
    data-request-download="sample.pdf"
    data-browser-target="_blank">
    Download
</button>

数据属性 API

data-request Attribute	Description
data-request	specifies the AJAX handler name.
data-request-confirm	specifies a confirmation message. A confirmation dialog is displayed before the request is sent. If the user clicks the Cancel button the request isn't sent.
data-request-redirect	specifies a URL to redirect the browser after the successful AJAX request.
data-request-url	specifies a URL to which the request is sent. default: `window.location.href`
data-request-update	specifies a list of partials and page elements (CSS selectors) to update. The format is as follows: `partial: selector, partial: selector`. Usage of quotes is required in some cases, for example: `'my-partial': '#myelement'`. The selector string should start with a `#` or `.` character, except you may also prepend it with `@` to append contents to the element, `^` to prepend, `!` to replace with and `=` to use any CSS selector.
data-request-data	specifies additional POST parameters to be sent to the server. The format is following: `var: value, var: value`. Use quotes if needed: `var: 'some string'`. The attribute can be used on the triggering element, for example on the button that also has the `data-request` attribute, on the closest element of the triggering element and on the parent form element. The framework merges values of the `data-request-data` attributes. If the attribute on different elements defines parameters with the same name, the framework uses the following priority: the triggering element `data-request-data`, the closer parent elements `data-request-data`, the form input data.
data-request-query	specifies additional GET parameters to be sent to the server and added to the current URL query string.
data-request-before-update	specifies JavaScript code to execute directly before the page contents are updated.
data-request-success	specifies JavaScript code to execute after the request is successfully completed. The `data` variable is available in this function containing the response data.
data-request-error	specifies JavaScript code to execute if the request encounters an error. The `data` variable is available in this function containing the response data.
data-request-complete	specifies JavaScript code to execute if the request is successfully completed or encounters an error. The `data` variable is available in this function containing the response data.
data-request-cancel	specifies JavaScript code to execute if the user aborts the request or cancels it via a confirmation dialog.
data-request-message	displays a progress message with the specified text, shown while the request is running. This option is used by the flash messages features.
data-request-loading	specifies a CSS selector for an element to be displayed while the request runs. You can use this option to show an AJAX loading indicator. The feature uses CSS display `block` and `none` attributes to manage the element visibility.
data-request-progress-bar	enable the progress bar when an AJAX request occurs.
data-request-form	explicitly specify a form element to use for sourcing the form data. If this is unspecified, the closest form to the triggering element is used, including if the element itself is a form.
data-request-flash	when included, instructs the server to clear and send any flash messages with the response. This option is used by the flash messages features.
data-request-files	when specified the request will accept file uploads using the `FormData` interface.
data-request-download	when specified file downloads are accepted with a `Content-Disposition` response. This attribute can be added anonymously or set to the downloaded filename.
data-request-bulk	when specified the request be sent as JSON for bulk data transactions.
data-browser-target	when specified with `data-request-download` the output will target this window, for example `_blank`.
data-browser-validate	when specified browser-based client side validation will run on the request before it submits.
data-browser-redirect-back	when a redirect occurs, if the previous URL from the browser is available, use that in place of the redirect URL provided.
data-auto-submit	automatically triggers an AJAX request on elements that also have the `data-request` attribute. The request submits when the browser window is active using the Page Visibility API. The optional attribute value can define the interval, in milliseconds, the framework waits before it sends the request.
data-track-input	can be applied to a text, number, or password input field that also has the `data-request` attribute. When defined, the input field automatically sends an AJAX request when a user types something in the field. The optional attribute value can define the interval, in milliseconds, the framework waits before it sends the requests.

当为一个元素指定 data-request 属性时，该元素会在用户与其交互时触发一个 AJAX 请求。根据元素的类型，该请求会在以下事件上触发：

Element	Event
Forms	when the form is submitted.
Links, buttons	when the element is clicked.
Text, number, and password fields	when the text is changed and only if the `data-track-input` attribute is presented.
Dropdowns, checkboxes, radios	when the element is selected.

使用示例

当表单提交时，触发 onCalculate 处理程序。更新标识符为 "result" 的元素，使用 calcresult 片段。

html

<form data-request="onCalculate" data-request-update="{ calcresult: '#result' }">

当点击删除按钮时，在发送请求之前，请求确认。

html

<form ... >
    ...
    <button data-request="onDelete" data-request-confirm="Are you sure?">Delete</button>

在请求成功后重定向到另一个页面。

html

<form data-request="onLogin" data-request-redirect="/admin">

请求成功后显示一个弹窗。

html

<form data-request="onLogin" data-request-success="alert('Yay!')">

发送一个 POST 参数 mode 值为 update。

html

<form data-request="onUpdate" data-request-data="{ mode: 'update' }">

传递一个 POST 参数 id 值为 7 跨多个元素。

html

<div data-request-data="{ id: 7 }">
    <button data-request="onDelete">Delete</button>
    <button data-request="onSave">Update</button>
</div>

在当前请求中发送 GET 参数 page 值为 6。

html

<button data-request="onSetPage" data-request-query="{ page: 6 }">
    Page 6
</button>

显示一个即时消息当请求正在加载时。

html

<button data-request="onUpdate" data-request-message="Loading...">
    Save Changes
</button>

包括文件上传随请求。

html

<form data-request="onSubmit" data-request-files>
    <input type="file" name="photo" accept="image/*" />
    <button type="submit">Submit</button>
</form>

包含文件下载在响应中。

html

<button data-request="onDownloadFile" data-request-download>
    Download
</button>

用于指定自定义文件名并在新窗口中打开下载，例如预览 PDF。

html

<button
    data-request="onDownloadFile"
    data-request-download="sample.pdf"
    data-browser-target="_blank">
    Download
</button>

文档导航

数据属性 API

使用示例

数据属性 API

使用示例