AJAX 请求（JavaScript API）

• Introduction
• 请求工作流
• 可用选项
• 全球事件
• 元素事件
• 使用示例
• 扩展或替换 Request 类

#Introduction

Snowboard 通过以下方式提供核心 AJAX 功能Request 滑雪板插件。这Request 插件在Winter使用后端功能发出 AJAX 请求时提供了强大的灵活性和可重用性。可以通过将以下标记添加到 CMS 主题的页面或布局中来加载它：

{% snowboard request %}

并在您的 JavaScript 中使用以下代码调用：

Snowboard.request('#element', 'onAjax', {});

基地Request 插件使用获取API 在大多数现代浏览器中提供，以在Winter执行从前端到后端的 AJAX 请求。

NOTE: 如果您想替换基础功能的任何部分Request 插件然后你可以写一个自定义滑雪板插件 扩展并覆盖基础Request 插件以根据需要对其进行自定义。

这request 方法接受三个参数：

#请求工作流

AJAX 请求通过Request 类经历以下过程：

• 使用给定的元素和选项初始化和验证请求。
• 如果browserValidate 已启用且 AJAX 请求已通过表单完成，将进行浏览器端验证。如果失败，请求将被取消。
• 如果confirm 指定后，将向用户显示确认信息。如果他们取消，请求将被取消。
• 提供给请求的数据以及任何适用的表格数据将被编译。
• AJAX 请求使用给定的处理程序.
• 从后端上下文接收到响应并进行处理，从这里发生以下三种情况之一：
  • 如果响应成功，则此时将更新指示更新的任何部分。
  • 如果由于验证错误导致响应不成功，则会显示验证消息并突出显示失败的字段。
  • 如果由于任何其他错误导致响应不成功，则会显示一条错误消息。
• 然后请求完成。

#可用选项

以下所有选项都是可选的。

还可以在以下回调中指定options 范围。所有回调都期望提供一个函数。这this所有回调中的关键字将被分配Request 表示当前 AJAX 请求的实例。

最后，以下选项参数定义了各种操作的覆盖功能Request 实例可能在处理响应期间发生。与回调方法一样，这些方法必须作为函数提供。

#全球事件

这Request 类触发几个全局事件，插件可以使用这些事件来增强或覆盖类的功能Request 班级。滑雪板插件 可以配置为通过使用listen() 方法将事件定向到具有插件类的方法。

class HandleFlash extends Snowboard.Singleton
{
    /**
     * Defines listeners for global events.
     *
     * @returns {Object}
     */
    listens() {
        return {
            // when the "ajaxFlashMessages" event is called, run the "doFlashMessage" method in this class
            ajaxFlashMessages: 'doFlashMessages',
        };
    }

    doFlashMessages(messages) {
        Object.entries(messages).forEach((entry) => {
            const [cssClass, message] = entry;

            showFlash(message, cssClass);
        });
    }
}

有些事件称为 Promise 事件，这意味着您的侦听器本身必须返回一个Promise 这要么被解决，要么被拒绝。

class ConfirmEverything extends Snowboard.Singleton
{
    /**
     * Defines listeners for global events.
     *
     * @returns {Object}
     */
    listens() {
        return {
            // when the "ajaxConfirmMessage" event is called, run the "confirm" method in this class
            ajaxConfirmMessage: 'confirm',
        };
    }

    // Confirm all confirmation messages
    confirm() {
        return Promise.resolve(true);
    }
}

Request过程中会调用以下事件：

#元素事件

除了全局事件之外，还会在触发 AJAX 请求的元素上触发本地事件。这些事件被视为DOM 事件 因此可以被普通的 DOM 事件监听器或您选择的框架监听。这Request 类将根据事件的类型和event.request 财产永远是Request 实例。

const element = document.getElementById('my-button');
element.addEventListener('ajaxAlways', (event) => {
    console.log(event.request); // The Request instance
    console.log(event.responseData); // The raw response data as an object
    console.log(event.responseError); // An error object if the response failed
});

在大多数情况下，您可以取消事件，从而取消请求，方法是添加event.preventDefault() 到你的回调。

const element = document.getElementById('my-button');
element.addEventListener('ajaxSetup', (event) => {
    // Never process a request for this element
    event.preventDefault();
});

在请求过程中直接在触发请求的元素上调用以下事件：

#使用示例

在不指定触发元素的情况下向 AJAX 处理程序发出简单请求。

Snowboard.request(null, 'onAjax');

在提交表单之前请求确认，并将它们重定向到成功页面。

Snowboard.request('form', 'onSubmit', {
    confirm: 'Are you sure you wish to submit this data?',
    redirect: '/form/success',
});

运行计算处理程序并从页面注入一些数据，然后更新总数。

Snowboard.request('#calculate', 'onCalculate', {
    data: {
        firstValue: document.getElementById('first-value').value,
        secondValue: document.getElementById('second-value').value,
    },
    update: {
        totalResult: '.total-result'
    },
});

运行计算处理程序并在计算时显示成功消息。

Snowboard.request('#calculate', 'onCalculate', {
    data: {
        firstValue: document.getElementById('first-value').value,
        secondValue: document.getElementById('second-value').value,
    },
    success: (data) => {
        const total = data.total;
        alert('The answer is ' + total);
    },
});

提示用户确认重定向。

Snowboard.request('form', 'onSubmit', {
    handleRedirectResponse: (url) => {
        if (confirm('Are you sure you wish to go to this URL: ' + url)) {
            window.location.assign(url);
        } else {
            alert('Redirect cancelled');
        }
    },
});

跟踪元素何时从 AJAX 请求更新。

const element = document.getElementById('updated-element');
element.addEventListener('ajaxUpdate', (event) => {
    console.log('The "updated-element" event was updated with the following content:', event.content);
});

通过修改 AJAX 请求全局禁用文件上传Request 实例。

// In your own Snowboard plugin
class DisableFileUploads extends Snowboard.Singleton
{
    listens() {
        return {
            ajaxSetup: 'stopFileUploads',
        };
    }

    stopFileUploads(request) {
        request.options.files = false;
    }
}

#扩展或替换 Request 类

作为使 Snowboard 成为可扩展和灵活平台的一部分，开发人员可以选择扩展或完全替换基本 Request 类。这允许开发人员使用他们自己喜欢的平台和框架来执行 AJAX 功能、部分更新等。

例如，如果开发人员想使用axios库 要执行 AJAX 请求，而不是内置的 Fetch API，可以通过创建自己的 Snowboard 插件并扩展Request 类，替换doAjax() 在他们自己的类中的方法：

const axios = require('axios');

class AxiosRequest extends Request
{
    doAjax() {
        // Allow plugins to cancel the AJAX request before sending
        if (this.snowboard.globalEvent('ajaxBeforeSend', this) === false) {
            return Promise.resolve({
                cancelled: true,
            });
        }

        const ajaxPromise = axios({
            method: 'post',
            url: this.url,
            headers: this.headers,
            data: this.data,
        });

        this.snowboard.globalEvent('ajaxStart', ajaxPromise, this);

        if (this.element) {
            const event = new Event('ajaxPromise');
            event.promise = ajaxPromise;
            this.element.dispatchEvent(event);
        }

        return ajaxPromise;
    }
}

然后你可以替换request 使用此类插件，或将其别名为其他名称：

Snowboard.removePlugin('request');
Snowboard.addPlugin('request', AxiosRequest);

// Or run it as an alias
Snowboard.addPlugin('axios', AxiosRequest);
// And call it thusly
Snowboard.axios('#my-element', 'onSubmit');

有关设置 Snowboard 插件的最佳实践的更多信息，请查看插件开发 文档。