数据属性 API

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

属性	描述
data-request	指定 AJAX 处理程序名称。
data-request-confirm	指定确认消息。在发送请求之前会显示确认对话框。如果用户点击取消按钮，则不会发送请求。
data-request-redirect	指定在 AJAX 请求成功后重定向浏览器的 URL。
data-request-url	指定发送请求的 URL。默认值：`window.location.href`
data-request-update	指定要更新的部分和页面元素（CSS 选择器）列表。格式如下：`partial: selector, partial: selector`。在某些情况下需要使用引号，例如：`'my-partial': '#myelement'`。选择器字符串应以 `#` 或 `.` 字符开头，但您也可以在其前面加上 `@` 以追加内容到元素，`^` 以前置，`!` 以替换，`=` 以使用任何 CSS 选择器。
data-request-data	指定要发送到服务器的其他 POST 参数。格式如下：`var: value, var: value`。如果需要，请使用引号：`var: 'some string'`。该属性可用于触发元素，例如在同时具有 `data-request` 属性的按钮上，在触发元素的最接近元素上和父表单元素上。框架会合并 `data-request-data` 属性的值。如果不同元素上的属性定义了同名参数，框架将使用以下优先级：触发元素的 `data-request-data`、更接近的父元素的 `data-request-data`、表单输入数据。
data-request-query	指定要发送到服务器并添加到当前 URL 查询字符串的其他 GET 参数。
data-request-before-update	指定在更新页面内容之前直接执行的 JavaScript 代码。
data-request-success	指定在请求成功完成后执行的 JavaScript 代码。此函数中可以使用包含响应数据的 `data` 变量。
data-request-error	指定在请求遇到错误时执行的 JavaScript 代码。此函数中可以使用包含响应数据的 `data` 变量。
data-request-complete	指定在请求成功完成或遇到错误时执行的 JavaScript 代码。此函数中可以使用包含响应数据的 `data` 变量。
data-request-cancel	指定在用户中止请求或通过确认对话框取消请求时执行的 JavaScript 代码。
data-request-message	显示指定文本的进度消息，在请求运行时显示。此选项由 flash messages features 使用。
data-request-loading	指定在请求运行时显示的元素的 CSS 选择器。您可以使用此选项显示 AJAX 加载指示器。该功能使用 CSS display `block` 和 `none` 属性来管理元素的可见性。
data-request-progress-bar	在发生 AJAX 请求时启用 progress bar。
data-request-form	明确指定用于获取表单数据的表单元素。如果未指定，则使用最接近触发元素的表单，包括元素本身是表单的情况。
data-request-flash	当包含时，指示服务器清除并发送响应中的任何 flash 消息。此选项由 flash messages features 使用。
data-request-files	当指定时，请求将使用 `FormData` 接口接受文件上传。
data-request-download	当指定时，文件下载将接受带有 `Content-Disposition` 响应。此属性可以匿名添加或设置为下载的文件名。
data-request-bulk	当指定时，请求将作为 JSON 发送以进行批量数据事务。
data-browser-target	当与 `data-request-download` 一起指定时，输出将定位到此窗口，例如 `_blank`。
data-browser-validate	当指定时，基于浏览器的客户端验证将在提交请求之前运行。
data-browser-redirect-back	当发生重定向时，如果浏览器中的上一个 URL 可用，则使用该 URL 代替提供的重定向 URL。
data-auto-submit	自动触发同时具有 `data-request` 属性的元素上的 AJAX 请求。请求在浏览器窗口处于活动状态时使用 Page Visibility API 提交。可选的属性值可以定义框架在发送请求之前等待的间隔（以毫秒为单位）。
data-track-input	可以应用于同时具有 `data-request` 属性的文本、数字或密码输入字段。当定义时，输入字段在用户在字段中键入内容时自动发送 AJAX 请求。可选的属性值可以定义框架在发送请求之前等待的间隔（以毫秒为单位）。

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

元素	事件
表单	当表单提交时。
链接、按钮	当元素被点击时。
文本、数字和密码字段	当文本更改时，并且仅在存在 `data-track-input` 属性时。
下拉框、复选框、单选按钮	当元素被选中时。

使用示例

触发 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	指定 AJAX 处理程序名称。
data-request-confirm	指定确认消息。在发送请求之前会显示确认对话框。如果用户点击取消按钮，则不会发送请求。
data-request-redirect	指定在 AJAX 请求成功后重定向浏览器的 URL。
data-request-url	指定发送请求的 URL。默认值：`window.location.href`
data-request-update	指定要更新的部分和页面元素（CSS 选择器）列表。格式如下：`partial: selector, partial: selector`。在某些情况下需要使用引号，例如：`'my-partial': '#myelement'`。选择器字符串应以 `#` 或 `.` 字符开头，但您也可以在其前面加上 `@` 以追加内容到元素，`^` 以前置，`!` 以替换，`=` 以使用任何 CSS 选择器。
data-request-data	指定要发送到服务器的其他 POST 参数。格式如下：`var: value, var: value`。如果需要，请使用引号：`var: 'some string'`。该属性可用于触发元素，例如在同时具有 `data-request` 属性的按钮上，在触发元素的最接近元素上和父表单元素上。框架会合并 `data-request-data` 属性的值。如果不同元素上的属性定义了同名参数，框架将使用以下优先级：触发元素的 `data-request-data`、更接近的父元素的 `data-request-data`、表单输入数据。
data-request-query	指定要发送到服务器并添加到当前 URL 查询字符串的其他 GET 参数。
data-request-before-update	指定在更新页面内容之前直接执行的 JavaScript 代码。
data-request-success	指定在请求成功完成后执行的 JavaScript 代码。此函数中可以使用包含响应数据的 `data` 变量。
data-request-error	指定在请求遇到错误时执行的 JavaScript 代码。此函数中可以使用包含响应数据的 `data` 变量。
data-request-complete	指定在请求成功完成或遇到错误时执行的 JavaScript 代码。此函数中可以使用包含响应数据的 `data` 变量。
data-request-cancel	指定在用户中止请求或通过确认对话框取消请求时执行的 JavaScript 代码。
data-request-message	显示指定文本的进度消息，在请求运行时显示。此选项由 flash messages features 使用。
data-request-loading	指定在请求运行时显示的元素的 CSS 选择器。您可以使用此选项显示 AJAX 加载指示器。该功能使用 CSS display `block` 和 `none` 属性来管理元素的可见性。
data-request-progress-bar	在发生 AJAX 请求时启用 progress bar。
data-request-form	明确指定用于获取表单数据的表单元素。如果未指定，则使用最接近触发元素的表单，包括元素本身是表单的情况。
data-request-flash	当包含时，指示服务器清除并发送响应中的任何 flash 消息。此选项由 flash messages features 使用。
data-request-files	当指定时，请求将使用 `FormData` 接口接受文件上传。
data-request-download	当指定时，文件下载将接受带有 `Content-Disposition` 响应。此属性可以匿名添加或设置为下载的文件名。
data-request-bulk	当指定时，请求将作为 JSON 发送以进行批量数据事务。
data-browser-target	当与 `data-request-download` 一起指定时，输出将定位到此窗口，例如 `_blank`。
data-browser-validate	当指定时，基于浏览器的客户端验证将在提交请求之前运行。
data-browser-redirect-back	当发生重定向时，如果浏览器中的上一个 URL 可用，则使用该 URL 代替提供的重定向 URL。
data-auto-submit	自动触发同时具有 `data-request` 属性的元素上的 AJAX 请求。请求在浏览器窗口处于活动状态时使用 Page Visibility API 提交。可选的属性值可以定义框架在发送请求之前等待的间隔（以毫秒为单位）。
data-track-input	可以应用于同时具有 `data-request` 属性的文本、数字或密码输入字段。当定义时，输入字段在用户在字段中键入内容时自动发送 AJAX 请求。可选的属性值可以定义框架在发送请求之前等待的间隔（以毫秒为单位）。

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

元素	事件
表单	当表单提交时。
链接、按钮	当元素被点击时。
文本、数字和密码字段	当文本更改时，并且仅在存在 `data-track-input` 属性时。
下拉框、复选框、单选按钮	当元素被选中时。

使用示例

触发 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

使用示例