docs(request): edit Request API

docs/request.md

@@ -2,6 +2,8 @@
 
 浏览器原生提供 Request() 构造函数，用来构造发给服务器的 HTTP 请求。它生成的 Response 实例，可以作为`fetch()`的参数。
 
+注意，构造一个 Request 对象，只是构造出一个数据结构，本身并不会发出 HTTP 请求，只有将它传入`fetch()`方法才会真的发出请求。
+
 ## 构造方法
 
 Request 作为构造函数的语法如下，返回一个 Request 实例对象。
@@ -10,67 +12,166 @@ Request 作为构造函数的语法如下，返回一个 Request 实例对象。
 new Request(url: String, [init: Object]): Request
 ```
 
-它的第一个参数是请求的 URL 字符串，第二个参数是一个可选的对象，用来构造 HTTP 请求，它的类型如下。
+它的第一个参数是请求的 URL 字符串，第二个参数是一个可选的配置对象，用来构造 HTTP 请求，该对象的类型描述如下。
 
 ```javascript
 {
-  body : Object	// 发送的数据体，必须是 Blob、BufferSource、FormData、String、URLSearchParams 类型之一
-  cache : String
-  credentials :	String
-  headers :	Object
-  integrity :	String
-  keepalive :	Boolean
-  method :	String // HTTP 方法，必须是 'GET'、'POST'、'DELETE' 等值
-  mode :	String
-  redirect :	String // 必须是 'follow'、'error'、'manual' 之一
-  referrer :	String
-  referrerPolicy :	String
-  requestMode :	String
-  requestCredentials :	String
-  signal :	AbortSignal
+  body: Object
+  cache: String
+  credentials: String
+  headers: Object
+  integrity: String
+  keepalive: Boolean
+  method: String
+  mode: String
+  redirect:	String
+  referrer:	String
+  referrerPolicy: String
+  requestMode: String
+  requestCredentials: String
+  signal: AbortSignal
 }
 ```
 
-它的第一个参数也可以是另一个 Request 对象，通过第二个参数对其进行修改。
+第二个参数配置对象的各个属性的含义如下。
+
+- `body`：HTTP 请求的数据体，必须是 Blob、BufferSource、FormData、String、URLSearchParams 类型之一。
+- `cache`：请求的缓存模式。
+- `credentials`：请求所用的凭证，可以设为 omit、same-origini、include。Chrome 47 之前，默认值为 same-origin；Chrome 47 之后，默认值为 include。
+- `headers`：一个代表 HTTP 请求数据头的对象，类型为 Headers 对象实例。
+- `integrity`：请求的资源的资源完整度验证值，比如`sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`。
+- `method`：HTTP 方法，一般为`GET`、`POST`、`DELETE`，默认是`GET`。
+- `mode`：请求模式，比如 cors、no-cors、navigate，默认为 cors。
+- `redirect`：请求所用的模式，可以设为 error、follow、manual，默认为 follow。
+- `referrer`：请求的来源，默认为 about:client。
+
+下面是两个示例。
+
+```javascript
+// 示例一
+const request = new Request('flowers.jpg');
+
+// 示例二
+const myInit = {
+  method: "GET",
+  headers: {
+    "Content-Type": "image/jpeg",
+  },
+  mode: "cors",
+  cache: "default",
+};
+
+const request = new Request('flowers.jpg', myInit);
+```
+
+`Request()`还有另一种语法，第一个参数是另一个 Request 对象，第二个参数还是一个配置对象。它返回一个新的 Request 对象，相当于对第一个参数 Request 对象进行修改。
 
 ```javascript
 new Request(request: Request, [init: Object]): Request
 ```
 
 ## 实例属性
 
-- bodyUsed : Boolean  readonly
-- cache : String  readonly。Will be one of: 'default', 'force-cache', 'no-cache', 'no-store', 'only-if-cached', 'reload'.
-- credentials : String  readonly。Will be one of: 'include', 'omit', 'same-origin'.
-- destination : String  readonly。Will be one of: '', 'audio', 'audioworklet', 'document', 'embed', 'font', 'frame', 'iframe', 'image', 'manifest', 'object', 'paintworklet', 'report', 'script', 'sharedworker', 'style', 'track', 'video', 'worker', 'xslt'.
-- headers : Headers  readonly。
-- integrity : String  readonly。
-- isHistoryNavigation : Boolean  readonly。
-- isReloadNavigation : Boolean  readonly。
-- keepalive : Boolean  readonly。
-- method : String  readonly。
-- mode : String  readonly。Will be one of: 'same-origin', 'no-cors', 'cors'.
-- redirect : String  readonly。
-- referrer : String  readonly。
-- referrerPolicy : String  readonly。
-- signal : AbortSignal  readonly。
-- url : String  readonly。
+Request 实例对象的属性，大部分就是它的构造函数第二个参数配置对象的属性。
+
+（1）`body`
+
+`body`属性返回 HTTP 请求的数据体，它的值是一个 ReadableStream 对象或 null（`GET`或`HEAD`请求时没有数据体）。
+
+```javascript
+const request = new Request('/myEndpoint', {
+  method: "POST",
+  body: "Hello world",
+});
+
+request.body; // ReadableStream 对象
+```
+
+注意，Firefox 不支持该属性。
+
+（2）`bodyused`
+
+`bodyUsed`属性是一个布尔值，表示`body`是否已经被读取了。
+
+（3）`cache`
+
+`cache`属性是一个只读字符串，表示请求的缓存模式，可能的值有 default、force-cache、no-cache、no-store、only-if-cached、reload。
+
+（4）`credentials`
+
+`credentials`属性是一个只读字符串，表示跨域请求时是否携带其他域的 cookie。可能的值有 omit（不携带）、 include（携带）、same-origin（只携带同源 cookie）。
+
+（5）`destination`
+
+`destination`属性是一个字符串，表示请求内容的类型，可能的值有 ''、'audio'、'audioworklet'、'document'、'embed'、'font'、'frame'、'iframe'、'image'、'manifest'、'object'、'paintworklet'、 'report'、'script'、'sharedworker'、'style'、'track'、'video'、'worker'、'xslt' 等。
+
+（6）`headers`
+
+`headers`属性是一个只读的 Headers 实例对象，表示请求的数据头。
+
+（7）`integrity`
+
+`integrity`属性表示所请求资源的完整度的验证值。
+
+（8）`method`
+
+`method`属性是一个只读字符串，表示请求的方法（GET、POST 等）。
+
+（9）`mode`
+
+`mode`属性是一个只读字符串，用来验证是否可以有效地发出跨域请求，可能的值有 same-origin、no-cors、cors。
+
+（10）`redirect`
+
+`redirect`属性是一个只读字符串，表示重定向时的处理模式，可能的值有 follow、error、manual。
+
+（11）`referrer`
+
+`referrer`属性是一个只读字符串，表示请求的引荐 URL。
+
+（12）`referrerPolicy`
+
+`referrerPolicy`属性是一个只读字符串，决定了`referrer`属性是否要包含在请求里面的处理政策。
+
+（13）`signal`
+
+`signal`是一个只读属性，包含与当前请求相对应的中断信号 AbortSignal 对象。
+
+（14）`url`
+
+`url`是一个只读字符串，包含了当前请求的字符串。
+
+```javascript
+const myRequest = new Request('flowers.jpg');
+const myURL = myRequest.url;
+```
 
 ## 实例方法
 
-### 取出数据体
+### 取出数据体的方法
 
 - arrayBuffer()：返回一个 Promise 对象，将 Request 的数据体作为 ArrayBuffer 对象返回。
 - blob()：返回一个 Promise 对象，将 Request 的数据体作为 Blob 对象返回。
 - json()：返回一个 Promise 对象，将 Request 的数据体作为 JSON 对象返回。
 - text()：返回一个 Promise 对象，将 Request 的数据体作为字符串返回。
 - formData()：返回一个 Promise 对象，将 Request 的数据体作为表单数据 FormData 对象返回。
 
-`.formData()`方法返回一个 Promise 对象，最终得到的是一个 FormData 表单对象，里面是用键值对表示的各种表单元素。
+下面是`json()`方法的一个示例。
 
-该方法很少使用，因为需要拦截发给服务器的请求的场景不多，一般用在 Service Worker。它需要拦截和处理网络请求，修改表单数据，然后将修改后的表单数据发送到服务器。
+```javascript
+const obj = { hello: "world" };
 
-下面是 Service Worker 拦截表单提交请求，并使用`.formData()`方修改表单数据的例子。
+const request = new Request("/myEndpoint", {
+  method: "POST",
+  body: JSON.stringify(obj),
+});
+
+request.json().then((data) => {
+  // 处理 JSON 数据
+});
+```
+
+`.formData()`方法返回一个 Promise 对象，最终得到的是一个 FormData 表单对象，里面是用键值对表示的各种表单元素。该方法很少使用，因为需要拦截发给服务器的请求的场景不多，一般用在 Service Worker 拦截和处理网络请求，以修改表单数据，然后再发送到服务器。
 
 ```javascript
 self.addEventListener('fetch', event => {
@@ -103,3 +204,8 @@ async function handleFormSubmission(request) {
 
 `clone()`用来复制 HTTP 请求对象。
 
+```javascript
+const myRequest = new Request('flowers.jpg');
+const newRequest = myRequest.clone();
+```
+

docs/response.md

@@ -20,15 +20,15 @@ new Response(body, options)
 
 它带有两个参数，都是可选的。
 
-第一个参数`body`是一个对象，代表服务器返回的数据体，必须是下面类型之一：ArrayBuffer、ArrayBufferView、Blob、FormData、ReadableStream、String、URLSearchParams。
+第一个参数`body`代表服务器返回的数据体，必须是下面类型之一：ArrayBuffer、ArrayBufferView、Blob、FormData、ReadableStream、String、URLSearchParams。也就是说，它可以是对象或字符串。
 
 第二个参数`init`是一个对象，代表服务器返回的数据头，类型描述如下。
 
 ```javascript
 {
-  status :	Number
-  statusText :	String
-  headers :	Object
+  status: Number
+  statusText: String
+  headers: Object
 }
 ```