翻译 - 【Dojo Tutorials】Ajax with dojo/request

原文：Ajax with dojo/request

dojo/request是自Dojo1.8才引入的新API，用于客户端向服务端发起请求。本教程主要介绍dojo/request的API：你将会学到如何从服务端获取一个文本文件，如果有错误发生该如何处理，向服务端提交数据，通知API的优点，通过注册使用同样的代码从不同地址请求数据。

开始

dojo/request允许你在不刷新页面的情况下向服务端发送数据或从服务端接收数据（通常所有的AJAX）。这个新功能引入了如何写出更紧凑的代码及如何快速的执行。在dojo/request用于异步编程时，该教程有提到dojo/promise和dojo/Deferred。因为不可能一次把所有东西都学习完，所以在本教程中你只需要了解到promise和Deferred是用于提高非阻塞异步编程的易用性的就好了。在本教程后，你可以去学习关于他们的专题教程。

介绍dojo/request

让我来看一个简单的例子：

require(['dojo/request'], function(request) {
    request('hellowrold.txt').then(
        function(text) {
            console.log("The file's content is : " + text);
        },
        function(error) {
            console.log("An error occurred: " + error);
        }
    );
});

 

在浏览器中，上面的代码使用一个XMLHttpRequest发起一个HTTP GET请求并返回一个dojo/promise/Promise实例。如果请求成功，作为then的第一个参数的函数将被执行，文件中的内容作为该函数的仅有参数被传入；如果请求失败，作为then的第二个参数的函数将被执行，一个错误对象作为该函数的参数被传入。但是如何使用表单向服务端提交数据呢？又或者返回的是JSON或XML呢？没有问题，dojo/request允许你对请求做私人订制。

dojo/request的API

每个请求都需要一样东西：一个目标。正因如此，dojo/request的第一个参数就是请求的URL。

web开发者在他们的工具中需要灵活性，为了能适应它们到他们的应用或者多个环境中。dojo/request正是基于这样的宗旨：第一个必须的参数作为请求的URL。第二个参数是用于定制请求的对象。该对象一些有用的选项如下：

• method - 一个大写的字符串用于表示HTTP请求的方法。为了让指定这些选项更方便提供了一些帮助方法（request.get，request.post，request.put，request.del）。
• sync - 一个布尔值，如果为真表示请求是阻塞的，直到服务端返回数据或者超时。
• query - 一个字符串或者键值对象用于追加到请求URL后面。
• data - 一个字符串，或键值对象，或包含数据的FormData对象用于传递到服务端。
• timeout - 使用毫秒设置请求的超时时间
• handles - 一个字符串表示在将返回的文本数据传递给成功回调函数之前如何处理数据。有几种处理方式，默认的是text，另有json，javascript，xml。
• headers - 一个键值对象用于设置额外的请求头。

让我来看一个使用了一些选项的例子：

require(["dojo/request"], function(request) {
  request.post("post-content.php", {
    data: {
      color: "blur",
      answer: 42
    },
    headers: {
      "X-Something": "A value"
    }
  }).then(function(text) {
    console.log("The server returned: ", text);
  });
});

 

这个例子发送一个HTTP POST请求到post-content.php；一个对象被序列化同一个X-Something请求头被发送到服务端。当服务端返回，内容作为一个值被从request.post返回的promise使用。

例子：request.get和request.post

接下来是一些dojo/request的一般用法。

将文本文件的内容展示到页面上

这个例子使用dojo/request.get请求一个文本文件。这种用法常用于为站点提供条款，条件，隐私的文本，因为如果需要文本文件只需要发送大客户端即可，且在文件中维护文字比在代码中更容易。

require(["dojo/dom", "dojo/on", "dojo/request", "dojo/domReady!"], function(dom, on, request) {
  // Results will be displayed in resultDiv
  var resultDiv = dom.byId("resultDiv");

  on(dom.byId("textButton"), "click", function(evt) {
    request.get("../resources/text/psalm_of_file.txt").then(
      function(response) {
        resultDiv.innerHTML = "<pre>" + response + "</pre>";
      },
      function(error) {
        resultDiv.innerHTML = "<div class="\error\">" + error "</div>"; 
      }
    );
  });
});

登录演示

下面的这个例子，演示了一个POST请求将用户名和密码发送到服务端并将服务端的返回展示出来：

require([
    "dojo/dom", 
    "dojo/on", 
    "dojo/request", 
    "dojo/dom-form"
], function(dom, on, request, domForm) {
    
    var form = dom.byId("formNode");

    // Attach the onsubmit event handler of the form
    on(form, "submit", function(evt) {

        // prevent the page from navigating after submit
        evt.stopPropagation();
        evt.preventDefault();

        // Post the data to the server
        request.post("../resources/php/login-demo.php", {
            // Send the username and password
            data: domForm.toObject("formNode"),
            // Wait 2 seconds for a response
            timeout: 2000
        }).then(function(response) {
            dom.byId("svrMessage").innerHTML = response;
        });
    });
});

 

请求头示例

下面这个例子像上面那个一样使用了POST请求，且接收一个请求头Auth-Token。

为了接收请求头，使用了原始Promise的promise.response.getHeader方法（从XHR返回的Promise是没有这个属性的）。另外，当使用promise.response.then的时候，response不是data数据，而是包含了data属性的对象。

require([
    "dojo/dom", 
    "dojo/on", 
    "dojo/request", 
    "dojo/dom-form"
], function(dom, on, request, domForm) {
    
    var form = dom.byId("formNode");

    // Attach the onsubmit event handler of the form
    on(form, "submit", function(evt) {

        // prevent the page from navigating after submit
        evt.stopPropagation();
        evt.preventDefault();

        // Post the data to the server
        var promise = request.post("../resources/php/login-demo.php", {
            // Send the username and password
            data: domForm.toObject("formNode"),
            // Wait 2 seconds for a response
            timeout: 2000
        });

        promise.response.then(function(response) {

            // get the message from the data property
            var message = response.data;

            // Access the 'Auth-Token' header
            var token = response.getHeader('Auth-Token');
            dom.byId('svrMessage').innerHTML = message;
            dom.byId('svrToken').innerHTML = token;
        });
    });
});

JSON

JSON是一种常用于AJAX的数据编码方式，因为它易读，易操作，更简洁。JSON可以用于编码任意类型的数据：很多语言都支持JSON格式，包括PHP，Java，Perl，Python，Ruby和ASP。

JSON编码的对象

{
    "title": "JSON Sample Data",
    "items": [{
        "name": "text",
        "value": "text data"
    }, {
        "name": "integer",
        "value": 100
    }, {
        "name": "float",
        "value": 5.65
    }, {
        "name": "boolean",
        "value": false
    }]
}

 

当把handleAs设置为"json"时，dojo/request把返回内容作为JSON对待并解析为JavaScript对象。

require([
    "dojo/dom", 
    "dojo/request", 
    "dojo/json", 
    "dojo/_base/array", 
    "dojo/domReady!"
], function(dom, request, JSON, arrayUtil) {
    // Results will be displayed in resultDiv
    var resultDiv = dom.byId("resultDiv");

    // Request the JSON data form the server
    request.get("../resources/data/sample.json.php", {
        // Parse data from JSON to a JavaScript object
        handleAs: "json"
    }).then(function(data) {
        // Display the data sent from the server
        var html = "<h2>JSON Data</h2>" +
            "<p>JSON encoded data:</p>" +
            "<p><code>" + JSON.stringify(data) + "</code></p>" +
            "<h3>Accessing the JSON data</h3>" +
            "<p><strong>title</strong> " + data.title + "</p>" +
            "<p><strong>items</strong> An array of item." +
            "Each item has a name and a value. The type of " +
            "the value is shown in parentheses.</p><dl>";

        arrayUtil.forEach(data.items, function(item, i) {
            html += "<dt>" + item.name + 
                "</dt><dd>" + item.value +
                " (" + (typeof item.value) + ")</dd>";
        });
        html += "</dl>";

        resultDiv.innerHTML = html;
    }, function(error) {
        // Display the error returned
        resultDiv.innerHTML = error;
    });
});

 

JSONP

AJAX请求被限制在了同域中。如果你需要从不同的域获取数据，你可以使用JSONP。当使用JSONP时，一个script标签被嵌入到当前页面，它的src文件被请求，服务端将数据包裹在一个回调函数中，当响应被解析，回调函数将被调用，数据作为它的第一个参数传入。可以使用dojo/request/script发起JSONP请求。

让我们看一些例子：

使用JSONP从服务端请求数据并处理响应内容

require([
    "dojo/dom",
    "dojo/on",
    "dojo/request/script",
    "dojo/json",
    "dojo/domReady!"
], function(dom, on, script, JSON) {
    // Results will be displayed in resultDiv
    var resultDiv = dom.byId("resultDiv");

    // Attach the onclick event handler to the makeRequest button
    on(dom.byId("makeRequest"), "click", function(evt) {

        // When the makeRequest button is clicked, send the current
        // date an time to the server in a JSONP request
        var d = new Date(),
            dateNow = d.toString();
        script.get("../resources/php/jsonp-demo.php", {
            // Tell the server that the callback name to
            // use is in the "callback" query parameter
            jsonp: "callback",
            // Send the date and time
            query: {
                clienttime: dateNow
            }
        }).then(function(data) {
            // Display the result
            resultDiv.innerHTML = JSON.stringify(data);
        });
    });
});

 

使用JSONP从GitHub API请求Dojo的pull请求

require([
    "dojo/dom",
    "dojo/on",
    "dojo/request/script",
    "dojo/dom-construct",
    "dojo/_base/array",
    "dojo/domReady!"
], function(dom, on, script, domContruct, arrayUtil){
    var pullsNode = dom.byId("pullrequests");

    // Attach the onclick event handler to tweetButton
    on(dom.byId("pullrequestsButton"), "click", function(evt) {
        // Request the open pull requests from Dojo's GitHub repo
        script.get("https://api.github.com/repos/dojo/dojo/pulls", {
            // Use the "callback" query parameter to tell
            // GitHub's services the name of the function
            // to wrap the data in
            jsonp: "callback"
        }).then(function(response) {
            // Empty the tweets node
            domContruct.empty(pullsNode);

            // Create a document fragment to keep from
            // doing live DOM manipulation
            var fragment = document.createDocumentFragment();

            // Loop through each pull request and create a list item
            // for it
            arrayUtil.forEach(response.data, function(pull) {
                var li = domContruct.create("li", {}, fragment);
                var link = domContruct.create("a", {href: pull.url, innerHTML: pull.title}, li);
            });

            // Append the document fragment to the list
            domContruct.place(fragment, pullsNode);
        });
    });
});

报告状态

dojo/request/notify提供了一种机制，用于向使用dojo/request发起的请求报告状态。dojo/request/notify允许供应者出发事件，可以被监听，用于报告请求的状态。为了监听一个事件，调用dojo/request/notify模块返回的值，且带有两个参数：一个事件名称和监听器函数。下面是dojo/request提供者可以出发的事件：

dojo/request/notify支持的事件

• start
• send
• load
• error
• done
• stop

start与stop的监听器没有参数。send的监听器接受两个参数：一个表示请求的对象和一个取消函数。调用取消函数将会在请求开始之前取消它。load，error和done的监听器接受一个参数：一个表示从服务端响应的数据。让我们看一些实战例子：

使用dojo/request/notify监视请求进度

require([
    "dojo/dom",
    "dojo/request",
    "dojo/request/notify",
    "dojo/on",
    "dojo/dom-construct",
    "dojo/query",
    "dojo/domReady!"
], function(dom, request, notify, on, domContruct) {
    // Listen for events from request providers
    notify("start", function() {
        domContruct.place("<p>Sent request</p>", "divStatus");
    });

    notify("send", function(data, cancel) {
        domContruct.place("<p>Sent request</p>", "divStatus");
    });

    notify("load", function(data) {
        domContruct.place("<p>Load (response received)</p>", "divStatus");
    });

    notify("error", function(error) {
        domContruct.place("<p class=\"error\">Error</p>", "divStatus");
    });

    notify("done", function(data) {
        domContruct.place("<p>Done (response processed)</p>", "divStatus");
        if(data instanceof Error) {
            domContruct.place("<p class=\"error\">Error</p>", "divStatus");
        } else {
            domContruct.place("<p class=\"success\">Success</p>", "divStatus");
        }
    });
    notify("stop", function() {
        domContruct.place("<p>Stop</p>", "divStatus");
        domContruct.place("<p class=\"ready\">Ready</p>", "divStatus");
    });

    // Use event delegation to only listen for clicks that
    // come from nodes with a class of "action"
    on(dom.byId("buttonContainer"), ".action:click", function(evt) {
        domContruct.empty("divStatus");
        request.get("../resources/php/notify-demo.php", {
            query: {
                success: this.id === "successBtn"
            },
            handleAs: "json"
        });
    });
});

 

dojo/request/registry

dojo/request/registry提供了一种机制，基于请求URL来路由请求。一般用法是基于请求是否在同域指派一个提供者，当前域使用JSON，否则使用JSONP。如果在进程中你的URL基于操作有所变化，你也会使用这种方法的。

dojo/request/registry语法

request.register(url, provider, first);

dojo/request/registry参数

•  url - url可以是字符串，正则表达式或者函数
  • string - 如果是字符串，提供者将使用它如果url匹配上
  • regExp - 
  • function - 
• provider - 处理的请求的提供者
• first - 是个可选的布尔参数，如果为真，注册器将提供者加到已有的提供者前面。

让我来看看最终的例子：

使用dojo/request/registry根据请求的URL指派提供者

require([
    "dojo/request/registry",
    "dojo/request/script",
    "dojo/dom",
    "dojo/dom-construct",
    "dojo/on",
    "dojo/domReady!"
], function(request, script, dom, domContruct, on) {
    // Registers anything that starts with "http://"
    // to be sent to the script provider
    // requests for a local search will use xhr
    request.register(/^https?:\/\//i, script);

    // When the search button is clicked
    on(dom.byId("searchButton"), "click", function() {
        // First send a request to twitter for all tweets
        // tagged with the search string
        request("http://search.twitter.com/search.json", {
            query: {
                q: "#" + dom.byId("searchText").value,
                result_type: "mixed",
                lang: "en"
            },
            jsonp: "callback"
        }).then(function(data) {
            // If the tweets node exists, destroy it
            if(dom.byId("tweets")) {
                domContruct.destroy("tweets");
            }
            // If at least one result was returned
            if (data.results.length > 0) {
                // Create a new tweet list
                domContruct.create("ul", {id: "tweets"}, "twitterDiv");
                // Add each tweet as a li
                while(data.results.length > ) {
                    domContruct.create("li", {innerHTML: data.result.shift().text}, "tweets");
                }
            } else {
                // No results returned
                domContruct.create("p", {id: "tweets", innerHTML: "None"}, "twitterDiv");
            }
        });

        // Next send a request to the local search
        request("../resources/php/search.php", {
            query: {
                q: dom.byId("searchText").value
            },
            handleAs: "json"
        }).then(function(data) {
            dom.byId("localResourceDiv").innerHTML =
                "<p><strong>" + data.name + "</strong><br/>" +
                "<a href=\"" + data.url + "\">" + data.url + "</a><br/>";
        }, function(error) {
            // If no results are found, the local search results a 404
            dom.byId("localResourceDiv").innerHTML = "<p>None</p>";
        });
    });
});

最佳实践

dojo/request的最佳实践包括：

• 谨慎的选择请求方法。一般情况下，GET用于没有安全考虑的请求。GET通常比POST快。POST通常用于发送表单数据且数据不会附加在URL中。
• 应该在HTTPS的页面上发起HTTPS的请求。
• 由于AJAX请求不会刷新页面，用户都比较喜欢状态更新，从加载到结束。
• 使用有效的开发工具解决问题更快速。
• 在尽可能多的浏览器上测试你的应用。

总结

dojo/request为请求当前域及其他域提供了一个跨浏览器遵循AJAX接口，包括优雅的错误处理，支持通知，根据URL路由请求。dojo/request返回一个promise，允许一系列的请求被发布和异步处理响应内容。页面可以包含多个源的内容，使用每个请求返回的数据。使用dojo/request增强你的页面吧！