Authorization - HTTP

Authorization
=============

 HTTP 請求中的 **`Authorization`** 是 user agent 用來向伺服器做身份認證（authentication）的憑證（credentials），
 通常是在伺服器回應 `401` (en-US)
`Unauthorized` 狀態及 `WWW-Authenticate` (en-US) 標頭後才會在後續請求使用這個標頭。

| Header type | Request header (en-US) |
| --- | --- |
| Forbidden header name (en-US) | no |

語法
--

```http
Authorization: <type> <credentials>
```

指令
--

<type>

認證方式 (en-US)，通常是 "Basic" (en-US)。其他方式可以參考：

* IANA registry of Authentication schemes
* Authentification for AWS servers (`AWS4-HMAC-SHA256`)

<credentials>

如果使用「Basic」方式，則憑證的格式會長的像這樣：

* 帳號、密碼會用冒號（:）串起來（`aladdin:opensesame`）。
* 然後在以 base64 (en-US) 編碼 (`YWxhZGRpbjpvcGVuc2VzYW1l`)。

**備註：** Base64 編碼不是加密也不是雜湊（Hash）！就算用明文直接傳，安全性也跟用 base64 編碼過一樣（base64 是可以解碼的）。最好用 HTTPS 搭配這種驗證方式。

範例
--
```

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
```

 可以看看 HTTP authentication (en-US) 中的範例
 教你如何在 Apache 或 nginx 上啟用 HTTP basic authentication 來保護你的網站。

規範
--

| Specification |
| --- |
| HTTP Semantics # field.authorization |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* HTTP authentication (en-US)
* `WWW-Authenticate` (en-US)
* `Proxy-Authorization` (en-US)
* `Proxy-Authenticate` (en-US)
* `401` (en-US), `403`, `407` (en-US)


Date - HTTP

Date
====

**`Date`** 標頭的值是傳送當下的日期與時間。

**警告：** `Date` 被列在 fetch spec 的 forbidden header names 清單中 ── 也就是說這段程式不會送出 `Date` 標頭：

```js
fetch("https://httpbin.org/get", {
  headers: {
    Date: new Date().toUTCString(),
  },
});
```

| Header type | General header (en-US) |
| --- | --- |
| Forbidden header name (en-US) | yes |

語法
--

```http
Date: <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT
```

指令
--

<day-name>

代表星期幾，為 Mon、Tue、Wed、Thu、Fri、Sat 或 Sun 之一（區分大小寫）。

<day>

二位數日期，比如「04」或「23」。

<month>

月份，為 Jan、Feb、Mar、Apr、May、Jun、Jul、Aug、Sep、Oct、Nov、Dec 之一（區分大小寫）。

<year>

四位數年份，比如「1990」或「2016」。

<hour>

二位數小時，比如「09」或「23」。

<minute>

二位數分鐘，比如「04」或「59」。

<second>

二位數秒，比如「04」或「59」。

GMT

格林威治標準時間的意思。在 HTTP 中日期都是採用 GMT，絕不會顯示當地時間。

範例
--
```

Date: Wed, 21 Oct 2015 07:28:00 GMT
```

```js
new Date().toUTCString();
// "Mon, 09 Mar 2020 08:13:24 GMT"
```

規格
--

| Specification |
| --- |
| HTTP Semantics # field.date |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參閱
--

* `Age`


Accept - HTTP

Accept
======

**`Accept`** HTTP 請求標頭（以 MIME type (en-US) 標示）會對伺服器告知用戶端可解讀的內容類型。伺服器可以透過 content negotiation (en-US) 來選用可行的協定，並以 `Content-Type` 標頭告知用戶端。針對本標頭，瀏覽器可以根據完成請求的脈絡，來決定適合的數值：像是擷取 CSS 時，給予的值就會和圖片、影像、腳本不一樣。

| 標頭類型 | Request header (en-US) |
| --- | --- |
| Forbidden header name (en-US) | no |
| CORS-safelisted request header (en-US) | yes, with the additional restriction that values can't contain a *CORS-unsafe request header byte*: `"():<>?@[\]{}`, Delete, Tab and control characters: 0x00 to 0x19. |

語法
--
```

Accept: <MIME_type>/<MIME_subtype>
Accept: <MIME_type>/*
Accept: */*

// Multiple types, weighted with the quality value (en-US) syntax:
Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8
```

指令
--

`<MIME_type>/<MIME_subtype>`

一個精確的 MIME type (en-US)，例如`text/html`。

`<MIME_type>/*`

一個不指定子類的 MIME type。`image/*` 會配對到 `image/png`, `image/svg`, `image/gif` 和等圖片類型。

`*/*`

所有 MIME type

`;q=` (q-factor weighting)

Any value used is placed in an order of preference expressed using relative quality value (en-US) called the *weight*.

示例
--
```

Accept: text/html

Accept: image/*

// General default
Accept: */*

// Default for navigation requests
Accept: text/html, application/xhtml+xml, application/xml;q=0.9, */*;q=0.8
```

規範
--

| Specification |
| --- |
| HTTP Semantics # field.accept |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* HTTP content negotiation (en-US)
* Header with the result of the content negotiation: `Content-Type`
* 類似標頭：`TE` (en-US), `Accept-Encoding` (en-US), `Accept-Charset` (en-US), `Accept-Language` (en-US)


Cookie - HTTP

Cookie
======

**`Cookie`** 是 HTTP 請求標頭，它的值包含由伺服器設定的 HTTP cookies （透過 `Set-Cookie` (en-US) 標頭設定，或者透過 Javascript 的 `Document.cookie` (en-US) 設定）。

`Cookie` 標頭不是必要的，比如瀏覽器可能會因為隱私設定而直接省略 Cookie 不傳。

| Header type | Request header (en-US) |
| --- | --- |
| Forbidden header name (en-US) | yes |

Syntax
------

```http
Cookie: <cookie-list>
Cookie: name=value
Cookie: name=value; name2=value2; name3=value3
```

<cookie-list>

一連串名值對（name-value pair），格式為： `<cookie-name>=<cookie-value>`。每對之間由一個分號與一個空白分隔（`'; '`）。

範例
--
```

Cookie: PHPSESSID=298zf09hf012fh2; csrftoken=u32t4o3tb3gg43; _gat=1
```

Specifications
--------------

| Specification |
| --- |
| HTTP State Management Mechanism # cookie |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Set-Cookie` (en-US)
* `Document.cookie` (en-US)


X-Forwarded-For - HTTP

X-Forwarded-For
===============

**`X-Forwarded-For`**（XFF）標頭是辨識用戶端透過 HTTP 代理或負載平衡 IP 位置來源的，事實上的標準。如果流量是在伺服器與用戶端中間擷取，伺服器日誌就只會代理或負載平衡的 IP 位置。如果要檢查用戶端的 IP 的原始來源，就會去檢查 `X-Forwarded-For` 請求標頭。

這個標頭用於除錯、分析、產生與位置相關的內容、透過設計也洩漏部分隱私資訊，例如用戶端的 IP 位置。因此在部署此標頭時，必須考慮到用戶的隱私。

此 HTTP 標頭的標準化版本為 `Forwarded` (en-US) 標頭。

`X-Forwarded-For` 也是個說明 email-message 是從哪個帳戶轉發的 email-header。

| 標頭屬性 | Request header (en-US) |
| --- | --- |
| Forbidden header name (en-US) | no |

語法
--

```http
X-Forwarded-For: <client>, <proxy1>, <proxy2>
```

指令
--

<client>

用戶端的 IP 位置

<proxy1>, <proxy2>

如果請求用上了多個代理，則列出每個後續代理的 IP 地址。也就是說，最右邊的 IP 位置，是最新代理的 IP 位置；最左邊的 IP 位置，是用戶端原始來源的 IP 位置。

示例
--

```http
X-Forwarded-For: 2001:db8:85a3:8d3:1319:8a2e:370:7348

X-Forwarded-For: 203.0.113.195

X-Forwarded-For: 203.0.113.195, 70.41.3.18, 150.172.238.178
```

其他非標準變體：
```

# Used for some Google services
X-ProxyUser-Ip: 203.0.113.19
```

規範
--

任何版本都沒有被標準化。標準化版本的標頭為 `Forwarded` (en-US)。

參見
--

* `Forwarded` (en-US)
* `X-Forwarded-Host` (en-US)
* `X-Forwarded-Proto` (en-US)
* `Via` (en-US)


Server - HTTP

Server
======

**`Server`** 標頭描述處理請求的伺服器軟體資訊：也就是產生回應的伺服器資訊。

**警告：** 請避免 Server 值的資訊過度冗長與詳盡，因為它們可能會洩漏實做細節、讓攻擊者容易找到已知安全漏洞並利用之。

| 標頭類型 | Response header (en-US) |
| --- | --- |
| Forbidden header name (en-US) | 否 |

語法
--
```

Server: <product>
```

指令
--

<product>

處理請求的軟體（或組件）名。語法通常與 `User-Agent` 相似。

How much detail to include is an interesting balance to strike; exposing the OS version is probably a bad idea, as mentioned in the earlier warning about overly-detailed values. However, exposed Apache versions helped browsers work around a bug those versions had with `Content-Encoding` (en-US) combined with `Range` (en-US).

示例
--
```

Server: Apache/2.4.1 (Unix)
```

規範
--

| Specification |
| --- |
| HTTP Semantics # field.server |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `Allow` (en-US)


ETag - HTTP

ETag
====

**`ETag`** 是 HTTP 回應標頭，用來標誌資源的版本。它可以使快取機制更有效率並節省頻寬，
 畢竟資料沒有變動的話，伺服器就不需要再次傳回整份資料。
 而且，它還可以用來預防多人同步更新資料時覆蓋掉彼此的資料（"mid-air collisions"）。

 如果一個網址的資源有更新，就*必須*重新產生它的 `Etag` 值。
 比較前後版本的 ETag 就能知道資源有沒有變化，所以 Etags 的作用就跟指紋一樣。有些伺服器便會把它用在追蹤用途上，而且可能會永久保存這些資訊。

| Header type | Response header (en-US) |
| --- | --- |
| Forbidden header name (en-US) | no |

Syntax
------

```http
ETag: W/"<etag\_value>"
ETag: "<etag\_value>"
```

Directives
----------

`W/` 選擇性

`'W/'` （區分大小寫）表示資源使用 Weak etags (en-US)。
 Weak etags 很容易產生，但較不適合用在版本比對；Strong etags 很難有效率的產生，但很適合用在版本比對。
 同一資源的兩個 weak etags 一致時，可以視為是同個版本，但其內容並非分毫不差。
 比如說 weak etags 可以用在 byte range requests (en-US) 上預防快取，不過帶有 strong etags 的請求仍然可能被快取住。

"<etag\_value>"

 代表資源的版本。它的格式是由雙引號包著的 ASCII 字元組成的，像是： `"675af34563dc-tr34"`。
 產生 `ETag` 值的方式沒有一定。不過通常會是資料的 hash 值、最後修改時間的 hash 值，或者是版本號。
 比如說，MDN 就是使用 wiki 文章的十六進位內文 hash 值。

範例
--
```

ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
ETag: W/"0815"
```

### 避免空中碰撞

有了 `ETag` 以及 `If-Match` (en-US) 標頭，你可以偵測空中碰撞。

比如說，在進入 wiki 編輯頁時，當下可以把內文的 hash 值放到 HTTP 回應中的 `Etag` 標頭：
```

ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
```

 當儲存更新時， `POST` (en-US) 請求就會有一個 `If-Match` (en-US) 標頭，其值為 `ETag`
 的值，這樣便可以用來檢查資料新鮮度。
```

If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
```

 如果 hash 沒有對上，就代表文件已經在你的編輯過程中，被別人先修改了，便會回傳
 `412` (en-US) `Precondition Failed` 錯誤。

### 快取沒更新過的資源

 另一個 `ETag` 標頭的好用處是用來快取沒更新過的資源。如果一位使用者再次造訪一個網址（而且前一次有設定 `ETag`），而資源已經*過期*了（舊到不能用），
 則客戶端會把 `ETag` 的值放在 `If-None-Match` (en-US) 標頭內傳送：
```

If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
```

 伺服器會比對客戶端傳來的 `ETag` （放在 `If-None-Match` 標頭中） 與該資源在伺服器上的現有版本的 `ETag` 值，如果兩者一樣（代表沒更新過），
 伺服器便會傳回 `304` (en-US) `Not Modified` 狀態且不帶資料，
 這就可以讓客戶端知道自己快取住的版本仍然可用（可視為是*新鮮的*）。

規格
--

| Specification |
| --- |
| HTTP Semantics # field.etag |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `If-Match` (en-US)
* `If-None-Match` (en-US)
* `304` (en-US) `Not Modified`
* `412` (en-US) `Precondition Failed`
* W3C Note: Editing the Web – Detecting
the Lost Update Problem Using Unreserved Checkout


CONNECT - HTTP

CONNECT
=======

**HTTP `CONNECT`** 方法會利用請求資源啟動一個雙向通訊。這通常可用於建立隧道。

舉例來說，`CONNECT` 方法可以用於存取使用 SSL (en-US) (HTTPS (en-US)) 的網站。客戶端請求 HTTP Proxy 伺服器建立 TCP 連結的隧道到指定的位置。伺服器接著代表客戶端建立連結。一但連結建立，Proxy 伺服器會持續收送 TCP 流到客戶端。

`CONNECT` 是個逐跳方法。

| 請求具有 Body | 否 |
| --- | --- |
| 成功回覆具有 Body | 是 |
| Safe (en-US) | 否 |
| Idempotent (en-US) | 否 |
| Cacheable | 否 |
| 可用於 HTML 表單 | 否 |

語法
--
```

CONNECT www.example.com:443 HTTP/1.1
```

範例
--

有些 Proxy 伺服器也許需要授權以建立隧道。請見 `Proxy-Authorization` (en-US) 標頭。
```

CONNECT server.example.com:80 HTTP/1.1
Host: server.example.com:80
Proxy-Authorization: basic aGVsbG86d29ybGQ=
```

規格
--

| Specification |
| --- |
| HTTP Semantics # CONNECT |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* Proxy server (en-US)
* `Proxy-Authorization` (en-US)


GET - HTTP

GET
===

**HTTP `GET` method** 方法請求展示指定資源。 使用 `GET` 的請求只應用於取得資料。

| Request 有 body | No |
| --- | --- |
| 成功的 response 有 body | Yes |
| Safe (en-US) | Yes |
| Idempotent (en-US) | Yes |
| Cacheable | Yes |
| 允許在 HTML 表單 | Yes |

格式
--
```

GET /index.html
```

規範
--

| Specification |
| --- |
| HTTP Semantics # GET |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `Range` (en-US)


204 No Content - HTTP

204 No Content
==============

HTTP **`204 No Content`** 成功狀態碼表明請求成功，但客戶端不需要更新目前的頁面。204 回應預設是可被快取的，此類回應中會包含 `ETag` 標頭。

回傳 `204` 的常見情況是作為 `PUT` (en-US) 請求的回應，更新一個資源且沒有更動目前顯示給使用者的頁面內容。若是有資源被建立，`201` `Created` 則應該被回傳。而若頁面應該更新為新的頁面，則應使用 `200` 。

狀態
--
```

204 No Content
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.204 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相容性事項
-----

* 雖然此狀態碼意圖表示不具主體的回應，伺服器仍可能錯誤地在標頭後加入資料。通訊協定允許使用者代理更動此回應的處理方式 (關於規範的討論請參見此處)。這在持久連接中可以被觀察到，無效的主體可能會包含後續請求的不同回應 。
 Apple Safari 拒收這些資料。Google Chrome 及 Microsoft Edge 在有效回應之前丟棄最多四個無效的位元組。Firefox 容許在有效回應之前超過 1KB 的無效資料。
參見
--

* HTTP 請求方法


503 Service Unavailable - HTTP

503 Service Unavailable
=======================

超文本傳輸協定(英文：HyperText Transfer Protocol (HTTP) ) **`503 Service Unavailable`** 表示目前伺服器暫時不能處理連線的請求。

起因通常是伺服器正在進行維護或是當下流量過載。這種錯誤回傳應該是暫時性的，並且`Retry-After` (en-US) HTTP header 中要盡可能描述到系統大概恢復正常的時間。.

**備註：** 回傳這種錯誤的同時，也要同時顯示一張對使用者友善的網頁，來簡單描述問題。

回傳此錯誤時，務必注意和快取存取相關的標頭（Caching-related headers），因為 503 狀態通常要是暫時性的，而這種回應不應該被暫存至快取。

狀態
--
```

503 Service Unavailable
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.503 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

以下資訊是從 MDN 的 GitHub 取得 (https://github.com/mdn/browser-compat-data).

請參閱
---

* `Retry-After` (en-US)
了解更多
----

### 一般知識

* HTTP/1.1: Status Code Definitions
* HTTP Error 503
* 503 Service Unvailaible WordPress
* 如何修復在 WordPress 當中「503 Service Unavailable Error」的問題？


200 OK - HTTP

200 OK
======

HTTP **`200 OK`** 成功狀態碼表明請求成功。200 回應預設上是緩存的（cacheable）。

所謂「成功」的定義，取決於 HTTP 的請求方法：

* `GET`：資源已取得，並傳送到訊息內文（message body）。
* `HEAD` (en-US)：整個標已經放在訊息內文了。
* `POST` (en-US): 描述動作結果的資源已經傳送到訊息內文。
* `TRACE` (en-US)：訊息內文包含了請求訊息，伺服器也接受了請求。

`PUT` (en-US) 或 `DELETE` (en-US) 的成功訊息，通常不是 `200 OK`，而是 `204` `No Content`（或著在資源首次上傳時，`201` `Created`）。

狀態
--
```

200 OK
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.200 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* HTTP 請求方法


415 Unsupported Media Type - HTTP

415 Unsupported Media Type
==========================

HTTP **`415 Unsupported Media Type`** 用戶端的錯誤表示被請求資源的多媒體類型不被伺服器支援，因此該請求被拒絕。

該格式問體可能源自於請求中設置的 `Content-Type` 或 `Content-Encoding` (en-US) 或對資料的直接訪問。

狀態
--
```

415 Unsupported Media Type
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.415 |

參見
--

* `Content-Type`
* `Content-Encoding` (en-US)
* `Accept`


409 Conflict - HTTP

409 Conflict
============

HTTP **`409 Conflict`** 表示請求與伺服器目前狀態衝突

衝突通常發生於 `PUT` (en-US) 請求。如上傳一個已經有舊版本存在於伺服器的檔案而導致版本控制衝突時，會回復一個 409 錯誤。

狀態
--
```

409 Conflict
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.409 |

參見
--

* `PUT` (en-US)


411 Length Required - HTTP

411 Length Required
===================

超文本傳輸協定 (HTTP) **`411 Length Required`** 用戶端錯誤表示伺服器拒絕接收沒有定義 `Content-Length` (en-US) 頭的請求。

**備註：** by specification, when sending data in a series of chunks, the `Content-Length` header is omitted and at the beginning of each chunk you need to add the length of the current chunk in hexadecimal format. See `Transfer-Encoding` (en-US) for more details.

狀態
--
```

411 Length Required
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.411 |

參見
--

* `Content-Length` (en-US)
* `Transfer-Encoding` (en-US)


205 Reset Content - HTTP

205 Reset Content
=================

HTTP **`205 Reset Content`** 狀態碼用來通知客戶端重置文件視圖，例如：清除表單內容、重置畫布狀態或刷新使用者界面。

狀態
--
```

205 Reset Content
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.205 |

相容性事項
-----

* 若是此回應在持久連線中錯誤地包含了主體，不同瀏覽器將會有不同的行為。細節參見 204 No Content 。
參見
--

* `204` No Content


502 Bad Gateway - HTTP

502 Bad Gateway
===============

`502 Bad Gateway` 錯誤表明伺服器以閘道器或代理訪問時，收到了來自上游服務器的無效回應。

**備註：** 閘道器可能位於網路上的不同地方。502 錯誤通常也不是開發者可以修復的，他通常需要在要訪問的的伺服器或代理修復之。

狀態
--
```

502 Bad Gateway
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.502 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

The information shown below has been pulled from MDN's GitHub (https://github.com/mdn/browser-compat-data).

See also
--------

* WordPress 出現 502 Bad Gateway Error 解決方法
* `504`
* HTTP/1.1: Status Code Definition
* 502 bad gateway fix
* 502 Bad Gateway error on WordPress
* 502 error with Cloudflare


404 Not Found - HTTP

404 Not Found
=============

HTTP **`404 Not Found`** 用戶端錯誤回應碼，表明了伺服器找不到請求的資源。引發 404 頁面的連結，通常被稱作斷連或死連（broken or dead link）、並可以導到失效連結（link rot）頁面。

404 狀態碼並沒有表明資源是暫時不見、還是永遠不見。如果資源是永遠不見，就應該用 `410` (en-US)(Gone) 而不是 404。

狀態
--
```

404 Not Found
```

自訂錯誤頁面
------

很多網站都會自訂 404 錯誤頁面，以便在指引用戶後續動作方面，提供進一步的幫助。Apache 伺服器可以透過 `.htaccess` 檔案設定，程式碼如下：

```bash
ErrorDocument 404 /notfound.html
```

要參考自訂 404 錯誤頁面範例，請看看 MDN 的 404 頁面。

**備註：** 適度地客製是件好事：你可以讓 404 頁面幽默和人性化，但不要讓用戶困惑。

規範
--

| Specification |
| --- |
| HTTP Semantics # status.404 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `410` (en-US)
* 維基百科的 HTTP 404
* 404 Error


418 I'm a teapot - HTTP

418 I'm a teapot
================

HTTP **`418 I'm a teapot`** 用戶端錯誤碼表明了伺服器是個（永久性的）茶壺，所以拒絕煮咖啡。一個結合了咖啡與茶壺的壺子暫時沒咖啡的情境，應該回傳 503。這個錯誤是源自於 1998 與 2014 的愚人節玩笑「超文字咖啡壺控制協定」（Hyper Text Coffee Pot Control Protocol）。

狀態
--
```

418 I'm a teapot
```

規範
--

| Specification |
| --- |
| RFC 2324 # section-2.3.2 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* 維基百科的「超文字咖啡壺控制協定」


201 Created - HTTP

201 Created
===========

HTTP **`201 Created`** 成功狀態碼表示請求成功且有一個新的資源已經依據需要而被建立。實際上，在此回應傳送前，新資源就已被建立，且其內容在訊息的主體中傳回，其位置為請求的 URL 或是 `Location` (en-US) 標頭的內容。

此狀態碼通常用於 `POST` (en-US) 請求的回應中。

狀態
--
```

201 Created
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.201 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* HTTP 請求方法


101 Switching Protocols - HTTP

101 Switching Protocols
=======================

HTTP **`101 Switching Protocols`** 回應碼表示伺服器正在切換到用戶端在請求標頭`Upgrade` (en-US) 中所要求的通訊協定。

伺服端將在回應中包含 `Upgrade` (en-US) 標頭以表明其所切換的通訊協定。此過程在文章 Protocol upgrade mechanism 中有更加詳細的描述。

狀態
--
```

101 Switching Protocols
```

範例
--

通訊協定切換可能會用於 WebSockets 中。
```

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.101 |

參見
--

* Protocol upgrade mechanism
* WebSockets
* `Upgrade` (en-US)
* `426` (en-US) `Upgrade Required`


500 Internal Server Error - HTTP

500 Internal Server Error
=========================

HTTP **`500 Internal Server Error`** 伺服器錯誤回應表明了伺服器碰上意外情況，令伺服器無法完成請求。不管你的網站是不是採用 WordPress 系統，任何放在伺服器當中的網頁都有可能發生這種錯誤。

本錯誤回應屬於通用的「全方位」回應。一般來說，這代碼代表程式無法給出比 500 更適當的回應。有時候，伺服器管理者會針對 500 這樣的錯誤回應，記錄詳細的相關信息，以避免未來出現同樣的錯誤。

狀態
--
```

500 Internal Server Error
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.500 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參考資料
----

* 如何修復 WordPress 出現 500 Internal Server Error 的解決方法
* 500 Internal Server Error


301 Moved Permanently - HTTP

301 Moved Permanently
=====================

HTTP **`301 Moved Permanently`** 重新導向狀態代碼代表所請求的資源已經被明確移動到 `Location` (en-US) 標頭所指示的 URL。瀏覽器會重新導向到此頁面，而搜尋引擎則會更新該資源的連結。用 SEO 的話來說，就是連結養分（link-juice）把你送到了新的 URL 去。

儘管規範要求當執行重新導向時，請求方法（以及主體）不應該被更動，但並非所有的用戶代理皆遵循它——你依然可以找到具有此類漏洞的軟體。因此，推薦只使用 `301` 回應碼作為 `GET` 或 `HEAD` (en-US) 方法的回應，另外使用 `308 Permanent Redirect` (en-US) 作為 `POST` (en-US) 方法的替代，因為請求方法的更動在此狀態中是被明確禁止的。

狀態
--
```

301 Moved Permanently
```

範例
--

### 用戶端請求
```

GET /index.php HTTP/1.1
Host: www.example.org
```

### 伺服端回應
```

HTTP/1.1 301 Moved Permanently
Location: http://www.example.org/index.asp
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.301 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `308 Permanent Redirect` (en-US)
* `302 Found` (en-US), 臨時重新導向


504 Gateway Timeout - HTTP

504 Gateway Timeout
===================

**`504 Gateway Timeout`** 錯誤表明伺服器以閘道器或代理訪問時，並沒有上游伺服器即時收到完成請求所需的回應。

**備註：** 閘道器可能位於網路上的不同地方。502 錯誤通常也不是開發者可以修復的，通常需要在要訪問的的伺服器或代理修復之。

狀態
--
```

504 Gateway Timeout
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.504 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

The information shown below has been pulled from MDN's GitHub (https://github.com/mdn/browser-compat-data).

See also
--------

* HTTP/1.1: Status Code Definitions
* `502`


203 Non-Authoritative Information - HTTP

203 Non-Authoritative Information
=================================

HTTP **`203 Non-Authoritative Information`** 狀態碼表明請求成功，但是與原始伺服器的 `200` (`OK`) 回應相比，隨附的酬載已被具轉換功能的 代理伺服器 (en-US) 所修改。

`203` 回應相似於 `Warning` (en-US) 標頭的 `214 Transformation Applied`，但後者的額外的優點在於可以套用到任何狀態碼的回應中。

狀態
--
```

203 Non-Authoritative Information
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.203 |

參見
--

* `200`
* Proxy server (en-US)
* `Warning` (en-US)


451 Unavailable For Legal Reasons - HTTP

451 Unavailable For Legal Reasons
=================================

HTTP **`451 Unavailable For Legal Reasons`** 用戶端錯誤回應碼表明用戶請求的資源，出於法律原因而無法使用，例如遭受法律訴訟的網頁。

狀態
--
```

451 Unavailable For Legal Reasons
```

示例
--

此示例擷取自 IETF RFC（參見以下章節）、包含了萬世魔星的引用。

**註：**`Link` (en-US) 標頭可能包含 `rel="blocked-by"` 以表明是誰封鎖該資源，而非來自其他強制力量。

需要為該資源無效的負責者，例如請求法律移除內容的人名或組織名，並不會放在 `rel="blocked-by"` link 裡面。
```

HTTP/1.1 451 Unavailable For Legal Reasons
Link: <https://spqr.example.org/legislatione>; rel="blocked-by"
Content-Type: text/html
```

```
<html>
      <head><title>Unavailable For Legal Reasons</title></head>
      <body>
            <h1>Unavailable For Legal Reasons</h1>
            <p>This request may not be serviced in the Roman Province
            of Judea due to the Lex Julia Majestatis, which disallows
            access to resources hosted on servers deemed to be
            operated by the People's Front of Judea.</p>
     </body>
</html>
```

規範
--

| Specification |
| --- |
| An HTTP Status Code to Report Legal Obstacles # n-451-unavailable-for-legal-reasons |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

The information shown below has been pulled from MDN's GitHub (https://github.com/mdn/browser-compat-data).

參見
--

* 維基百科的 HTTP 451
* 維基百科的華氏 451 度（該請求碼的數字詞源）


206 Partial Content - HTTP

206 Partial Content
===================

HTTP **`206 Partial Content`** 成功狀態碼表明請求成功，且主體包含在請求標頭`Range` (en-US) 中所指定的資料區間。

若只包含一個區間，則整個回應的 `Content-Type` 將會被設為該文件的類型 ，且會包含一個 `Content-Range` (en-US) 標頭。

若有多個區間，則整個回應的 `Content-Type` 會被設為 `multipart/byteranges` ，且每個分段會對應一個區間，並有 `Content-Range` (en-US) 及 `Content-Type` 描述各個區間。

狀態
--
```

206 Partial Content
```

範例
--

一個包含單一區間的回應：
```

HTTP/1.1 206 Partial Content
Date: Wed, 15 Nov 2015 06:25:24 GMT
Last-Modified: Wed, 15 Nov 2015 04:58:08 GMT
Content-Range: bytes 21010-47021/47022
Content-Length: 26012
Content-Type: image/gif

... 26012 bytes of partial image data ...
```

一個包含多個區間的回應：
```

HTTP/1.1 206 Partial Content
Date: Wed, 15 Nov 2015 06:25:24 GMT
Last-Modified: Wed, 15 Nov 2015 04:58:08 GMT
Content-Length: 1741
Content-Type: multipart/byteranges; boundary=String_separator

--String_separator
Content-Type: application/pdf
Content-Range: bytes 234-639/8000

...the first range...
--String_separator
Content-Type: application/pdf
Content-Range: bytes 4590-7999/8000

...the second range
--String_separator--
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.206 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `If-Range` (en-US)
* `Range` (en-US)
* `Content-Range` (en-US)
* `Content-Type`


300 Multiple Choices - HTTP

300 Multiple Choices
====================

HTTP **`300 Multiple Choices`** 重定向回應碼代表該請求具有超過一種可能的回應。用戶代理或使用者應該從中挑選一個。由於不存在標準化的選擇回應方式，此回應碼非常少被使用。

若是伺服端有偏好的選擇，則應該產生 `Location` (en-US) 標頭。

狀態
--
```

300 Multiple Choices
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.300 |

參見
--

* `301` `Moved Permanently`
* `302` (en-US) `Found`, the temporary redirect
* `308` (en-US) `Permanent Redirect`


202 Accepted - HTTP

202 Accepted
============

HTTP **`202 Accepted`** 成功狀態碼表示此請求已經被接受但尚未處理。此狀態為非承諾性，代表 HTTP 無法在之後傳送一個非同步的回應告知請求的處理結果。最初目的為外部程序或其他伺服器處理請求的情況，或用於批次處理中。

狀態
--
```

202 Accepted
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.202 |

參見
--

* `Accept`


403 Forbidden - HTTP

403 Forbidden
=============

HTTP **`403 Forbidden`** 客戶端錯誤狀態碼表示伺服器理解該請求但拒絕核准。

該狀態碼與 HTTP `401` (en-US) 類似，但重新身分驗證不能提供幫助。 存取被永久性禁止，且與應用程式邏輯有關，如資源的訪問權限不足。

狀態
--
```

403 Forbidden
```

回應範例
----
```

HTTP/1.1 403 Forbidden
Date: Wed, 21 Oct 2015 07:28:00 GMT
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.403 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `401` (en-US)


100 Continue - HTTP

100 Continue
============

HTTP **`100 Continue`** 訊息狀態回應碼表示，目前為止的一切完好，用戶端應該繼續完成請求，或當請求已經完成的狀態下應忽略此訊息。

若要使伺服器確認請求標頭，用戶端必須在最初請求的標頭中，傳送`Expect` (en-US)`: 100-continue` ，並且在傳送主體前，接收 `100 Continue` 狀態碼。

狀態
--
```

100 Continue
```

規範
--

| Specification |
| --- |
| HTTP Semantics # status.100 |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `Expect` (en-US)
* `417` (en-US)


行動無障礙檢核清單 - 無障礙網頁

行動無障礙檢核清單
=========

本文提供行動應用程式開發者一個簡潔的無障礙必備要件檢核清單，本文將隨著更多模型產生而不斷地演進。

顏色
--

* 顏色對比**必須**符合WCAG 2.0 AA 等級要求:
    + 一般文字對比值為 4.5:1(小於 18 點字或 14 點粗體)
    + 大文字對比值為 3:1(大於 18 點字或 14 點粗體)
* 透過顏色傳遞資訊 **必須** 能藉由其他方式獲得資訊 (底線文字表示連結等)

**備註：** Jon Snook 已撰寫實用的 Colour Contrast Checker 能用於檢查背景與前景顏色的對比。同樣地，Tanaguru Contrast-Finder 也提供類似功能，而且建議相似且更好的對比顏色提供你考量使用。

可視性
---

* 內容隱藏技術如完全不透明、Z 型態索引順序與螢幕外的配置**必須不能**單獨用於處理可視性。
* 目前可視螢幕之外的所有事物**必須**真正地不可見(特別適用於具有多個卡片的單一頁面應用程式)：
    + **使用** `hidden` 屬性或 `visibility` 或 `display` 樣式屬性。
    + 除非絕對無法避免，否則**不應**使用`aria-hidden` 屬性。
焦點
--

* 所有可觸發的元素**必須**可獲得焦點：
    + 標準的控制措施如連結、按鈕與表單輸入框預設為可獲得焦點。
    + 非標準的控制措施**必須**賦予它們合適的 ARIA Role，如按鈕、連結或核取框。
* 焦點應該以邏輯的順序與一致的方式處理。
文字相等意義
------

* 在應用程式之中，為每一個非嚴格呈現的非文字元素提供文字相等意義。
    + 在適當情況下使用*alt 與 title*(使用指引請參見 Steve Faulkner 關於Using the HTML title attribute的文章)。
    + 如果上述屬性不適用，則使用合適的ARIA 屬性如`aria-label`、`aria-labelledby`或 `aria-describedby。`
* 文字圖片 **必須**避免使用。
* 所有表單控制措施**必須**有標籤(`<label>` (en-US) 元素) ，以利於螢幕報讀器使用者使用。
處理狀態
----

* 標準控制措施如選項按鈕與核取框可被作業系統處理。然而，其他客製的控制措施狀態改變必須透過ARIA 狀態如 `aria-checked`、`aria-disabled`、`ria-selected`、`aria-expanded`與`aria-pressed`來提供。
一般準則
----

* 應用程式的名稱**必須**提供。
* 標題**必須**不能破壞層級結構。

```html
<h1>Top level heading</h1>
<h2>Secondary heading</h2>
<h2>Another secondary heading</h2>
<h3>Low level heading</h3>
```

* ARIA 地標角色**應該**用於描述應用程式或文件結構，例如`banner`、`complementary`、`contentinfo`、 `main`、 `navigation`、`search`。
* 觸控事件處理器**必須**只有在`touchend`事件上觸發。
* 觸控目標**必須**提供使用者足夠大的互動操作(有用的觸控目標大小指引請參見BBC Mobile Accessibility Guidelines)。

**備註：** Tanaguru 自動無障礙測試服務提供有用的方法去發現一些發生於網頁或安裝的網頁應用程式(如 Firefox OS)無障礙錯誤。你可在tanaguru.org找到更多關於 Tanaguru 技術開發，以及貢獻該專案的資訊。

**備註：** 本文件原始版本由Yura Zenevich撰寫。


Using ARIA - 無障礙網頁

Using ARIA
==========

Roles（角色）
---------

### Widget roles（局部組件）

* Button （按鈕）
* Checkbox （複選核取方塊）
* Dialog （對話）
* Gridcell （網格欄）
* Link （超連結）
* Log （紀錄）
* Marquee
* Menuitem
* Menuitemcheckbox
* Menuitemradio
* Option
* Progressbar （進度條）
* Radio （單選選項鈕）
* Scrollbar
* Slider （滑軌控制鈕）
* Spinbutton
* status （狀態）
* Tab （頁籤）
* Tabpanel （頁籤面板）
* textbox （頁籤容器）
* Timer （計時器）
* Tooltip （提示）
* Treeitem
* switch （開關） (en-US)
### Composite roles

下面的技術，描述了每個複合角色，以及他們的必要和可選的子角色。

* Combobox （組合框）
* Grid （網格）(包含 row （橫列）, gridcell （網格欄）, rowheader （橫列表頭）, columnheader （欄表頭） roles)
* Listbox （列表框） (包含 option role)
* Menu （選單）
* Menubar （選單條）
* Radiogroup （單選選項群組） (see radio role)
* Tablist （頁籤列表） (包含 tab 和 tabpanel roles)
* Tree
* Treegrid
### Document structure roles

* Article
* Definition
* Directory
* Document
* Group
* Heading
* Img
* List
* Listitem
* Math
* Note
* Presentation
* Region
* Separator
* Toolbar
### Landmark roles

* Application
* Banner
* Complementary
* Contentinfo
* Form
* Main
* Navigation
* Search
States and properties
---------------------

### Widget attributes

* aria-autocomplete
* aria-checked
* aria-current
* aria-disabled
* aria-expanded
* aria-haspopup
* aria-hidden
* aria-invalid
* aria-label
* aria-level
* aria-multiline
* aria-multiselectable
* aria-orientation
* aria-pressed
* aria-readonly
* aria-required
* aria-selected
* aria-sort
* aria-valuemax
* aria-valuemin
* aria-valuenow
* aria-valuetext
### Live region attributes

* aria-live
* aria-relevant
* aria-atomic
* aria-busy
### Drag & drop attributes

* aria-dropeffect
* aria-dragged
### Relationship attributes

* aria-activedescendant
* aria-controls
* aria-describedby
* aria-flowto
* aria-labelledby
* aria-owns
* aria-posinset
* aria-setsize


Media container formats (file types) - Web media technologies

Media container formats (file types)
====================================

視訊與音訊的檔案格式被定義成兩個部分（當然如果一個檔案同時擁有影、音的話，那就有三個）：一個是音訊或/和視訊的編解碼器(codecs，由 compress 和 decompress 所組成的詞語)，另一個是媒體封裝的格式(media container format，即檔案類型)。在本次導覽中，我們將會看到網路上最常見的封裝格式，並介紹它們的基本規格、優點、限制，以及理想的使用情形。

網頁即時通訊(WebRTC) (en-US)並不採用容器(container)，而是以 `MediaStreamTrack` (en-US) 物件來表示編碼過的影軌和音軌(一個物件表示一種媒體軌)，直接從一端串流到另一端。你可以參閱 WebRTC 使用的編解碼器 (en-US)來了解進行 WebRTC 時常用的編解碼器，以及瀏覽器對它們的相容性。

常見的封裝格式
-------

世上的媒體封裝格式多如牛毛，所以我們在這裡僅列出你最有機會遇到的幾種，其中有的只支援音訊，有的影音都支援。我們也會列出它們各自的媒體類型(MIME type)和副檔名(extension)。網路上最常見的封裝容器有 MPEG-4 (MP4)、QuickTime Movie (MOV)，以及 Wavefile Audio File Format (WAV)。當然你也可能會遇到如 MP3、Ogg、WebM、AVI 等其他格式，但不是所有瀏覽器都支援它們就是了。為了方便起見，同時也是因為它們實在太常見了，有些封裝容器與編解碼器的組合會有專屬它們的副檔名跟媒體類型。好比說，只有一個 Opus 音軌的 Ogg 檔通常會被稱為 Opus 檔，它有自己的副檔名 `.opus`，但它其實還是一個 Ogg 檔。

由於特定的編解碼器通常會放在特定的封裝容器裡，所以這樣的組合會被特別看待，比方說 MP3 音訊檔就是一個很好的例子，它是由 MPEG-1 封裝容器與一個以 MPEG-1 Audio Layer III encoding 編碼過的音軌所組成，這種檔案使用 `audio/mp3` 作為媒體類型；`.mp3` 作為副檔名，即便它的封裝容器不過就是 MPEG 罷了。

### 索引

點擊列表中你想知道的封裝格式，即會將你傳送到該項目的細節內容，其中包含它的用途、它支援的編解碼器、支援它的瀏覽器等等。

| 編解碼器名(縮寫) | 完整編解碼器名 | 瀏覽器相容性1 |
| --- | --- | --- |
| 3GP | Third Generation Partnership | Firefox for Android |
| ADTS | Audio Data Transport Stream | Firefox2 |
| FLAC | Free Lossless Audio Codec | Chrome 56, Edge 16, Firefox 51, Safari 11 |
| MPEG / MPEG-2 | Moving Picture Experts Group (1 and 2) | — |
| MPEG-4 (MP4) | Moving Picture Experts Group 4 | Chrome 3, Edge 12, Firefox, Internet Explorer 9, Opera 24, Safari 3.1 |
| Ogg | Ogg | Chrome 3, Firefox 3.5, Edge 173 (desktop only), Internet Explorer 9, Opera 10.50 |
| QuickTime (MOV) | Apple QuickTime movie | 只有舊版的 Safari 和其他支援 Apple 的 QuickTime plugin 的瀏覽器 |
| WebM | Web Media | Chrome 6, Edge 173 (desktop only), Firefox 4, Opera 10.6, Safari (WebRTC only) |

[1] 除非特別說明，否則表中提及的瀏覽器包含其行動版與桌面版。此外「支援」指的是針對封裝容器本身，而非特定的編解碼器。

[2] 只在作業系統底層的媒體框架(media framework)有支援時才有。

[3] 需要安裝網路媒體延伸模組。

### 3GP

**3GP** 或 **3GPP** 是用來封裝音訊和/或視訊的媒體容器，它服務的對象是透過行動網路(cellular network)進行傳輸的行動裝置。雖然這個格式是為了 3G 行動電話設計的，但現代的手機與網路還是可以使用它。話雖如此，由於現今的網路有更大的頻寬和更為寬鬆的公平使用原則(data caps)，所以現在 3GP 格式也不是那麼需要了，只有較慢的網路和較差的手機才會使用這種格式。

這個媒體封裝格式衍生自 ISO Base Media File Format 和 MPEG-4，特別針對低頻寬的情形做了最佳化。

| 音訊 | 視訊 |
| --- | --- |
| `audio/3gpp` | `video/3gpp` |
| `audio/3gpp2` | `video/3gpp2` |
| `audio/3gp2` | `video/3gp2` |

上表是基本的 3GP 媒體型態，依照使用的編解碼器的不同，可能還會有其他型態。此外，你可以在媒體型態字串中添加 `codecs` 參數 (en-US)來指明你的音軌和/或影軌所採用的編解碼器，也可以提供 組態(profile)、層級(level)等其他編解碼器的配置細節。

3GP 支援的視訊編解碼器| 編解碼器 | 支援的瀏覽器 |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| AVC (H.264) |  |  | Yes1,2 |  |
| H.263 |  |  | Yes1 |  |
| MPEG-4 Part 2 (MP4v-es) |  |  | Yes1 |  |
| VP8 |  |  | Yes1 |  |

[1] Firefox 只在基於 OpenMAX 的裝置上支援 3GP，以目前的情況來看就是 Boot to Gecko (B2G) 平台.

[2] Firefox 支援 H.264 與否取決於作業系統的媒體建設如何，也就是說得要系統支援才行。

3GP 支援的音訊編解碼器| 編解碼器 | 支援的瀏覽器 |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| AMR-NB |  |  | Yes1 |  |
| AMR-WB |  |  | Yes1 |  |
| AMR-WB+ |  |  | Yes1 |  |
| AAC-LC |  |  | Yes1,2 |  |
| HE-AAC v1 |  |  | Yes1,2 |  |
| HE-AAC v2 |  |  | Yes1,2 |  |
| MP3 |  |  | Yes1 |  |

[1] Firefox 只在基於 OpenMAX 的裝置上支援 3GP，以目前的情況來看就是 Boot to Gecko (B2G) 平台.

[2] Firefox 支援 AAC 與否取決於作業系統的媒體建設如何，也就是說得要系統支援才行。

### ADTS

**Audio Data Transport Stream** (**ADTS**) 是 MPEG-4 Part 3 為音訊資料所訂定的封裝格式，著眼於音訊串流，如網路電台。它基本上是一個空的 AAC 音訊資料串流，由 ADTS 幀(frame)和一個很小的 header 組成。

| 音訊 |
| --- |
| `audio/aac`[1] |
| `audio/mpeg`[1] |

[1] ADTS 使用哪個媒體型態依它使用的音訊幀(audio frame)而定。如果它使用 ADTS 幀，其媒體型態為 `audio/aac`；如果它使用 MPEG-1/MPEG-2 Audio Layer I, II, or III 格式的音訊幀，它的媒體型態為 `audio/mpeg`。

ADTS 支援的音訊編解碼器| 編解碼器 | 支援的瀏覽器 |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| AAC |  |  | Yes1 |  |
| MP3 |  |  | Yes |  |

[1] Firefox 支援 AAC 與否取決於作業系統的媒體建設如何，也就是說得要系統支援才行。

### FLAC

**Free Lossless Audio Codec** (**FLAC**) 是一個無損的音訊編解碼器，它有一個相關的精簡音訊封裝格式，也叫做 FLAC，這個格式不受任何專利約束，因此你可以安心地使用它。FLAC 檔只能用來封裝 FLAC 音訊資料。

| 音訊 |
| --- |
| `audio/flac` |
| `audio/x-flac` (非標準) |

FLAC 支援的音訊編解碼器| 編解碼器 | 支援的瀏覽器 |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| FLAC |  |  | Yes |  |

### MPEG/MPEG-2

**MPEG-1** 和 **MPEG-2** 基本上是相同的。這兩個格式由 Moving Picture Experts Group (MPEG) 創造，廣泛用於實體媒體上，如 DVD 媒體所用的視訊格式。

在網路上最常用來封裝音訊資料的 MPEG 檔案格式可能是 Layer\_III/MP3。也正是因為 MP3 檔被世界各地的數位音樂裝置使用，MPEG-1 和 MPEG-2 才能如此廣泛地應用於網路內容中。

MPEG-1 和 MPEG-2 最主要的差別在於媒體資料格式而非封裝格式。MPEG-1 首見於西元 1992 年；而 MPEG-2 則出現在西元 1996 年。

| 音訊 | 視訊 |
| --- | --- |
| `audio/mpeg` | `video/mpeg` |

MPEG-1 與 MPEG-2 支援的視訊編解碼器| 編解碼器 | 支援的瀏覽器 |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| MPEG-1 Part 2 |  |  | No |  |
| MPEG-2 Part 2 |  |  | No |  |

MPEG-1 與 MPEG-2 支援的音訊編解碼器| 編解碼器 | 支援的瀏覽器 |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| MPEG-1 Audio Layer I |  |  | No |  |
| MPEG-1 Audio Layer II |  |  | No |  |
| MPEG-1 Audio Layer III (MP3) |  |  | Yes |  |

### MPEG-4 (MP4)

**MPEG-4** (**MP4**) 是最新版 MPEG 檔案格式。這個格式有兩種版本，分別定義於規範中的 part 1 和 part 14。MP4 是現今流行的封裝容器，它支援了大部份常用的編解碼器，同時它也廣泛地被支援。

初版的 MPEG-4 Part 1 檔案格式首見於西元 1999 年；第二版定義於 Part 14 在西元 2003 年時加入。MP4 檔案格式衍生於 ISO base media file format，而該格式則是衍生於 Apple 開發的 QuickTime file format。

| 音訊 | 視訊 |
| --- | --- |
| `audio/mp4` | `video/mp4` |

上表是基本的 MPEG-4 媒體型態，依照使用的編解碼器的不同，可能還會有其他型態。此外，當指出 MPEG-4 媒體型態時 (`audio/mp4` 或 `video/mp4`)，你可以在媒體型態字串中加上 `codecs` 參數 (en-US)來指明你的音軌和/或影軌所採用的編解碼器，也可以提供組態(profile)、層級(level)等其他編解碼器的配置細節。

MPEG-4 支援的視訊編解碼器| 編解碼器 | 支援的瀏覽器 |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| AVC (H.264) |  |  | Yes1 |  |
| AV1 |  |  | Yes1 |  |
| H.263 |  |  | No |  |
| MPEG-4 Part 2 Visual |  |  | No |  |
| VP9 |  |  | Yes |  |

[1] Firefox 支援 H.264 與否取決於作業系統的媒體建設如何，也就是說得要系統支援才行。

[2] Firefox 目前對 AV1 的支援預設是關閉的，它可以透過在偏好設定中將 `media.av1.enabled` 設定為 `true` 來開啟。

MPEG-4 支援的音訊編解碼器| 編解碼器 | 支援的瀏覽器 |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| AAC |  |  | Yes1 |  |
| FLAC |  |  | Yes |  |
| MPEG-1 Audio Layer III (MP3) |  |  | Yes |  |
| Opus |  |  | Yes |  |

[1] Firefox 支援 H.264 與否取決於作業系統的媒體建設如何，也就是說得要系統支援才行。

### Ogg

The **Ogg** container format is a free and open format maintained by the Xiph.org Foundation. The Ogg framework also defines patent unencumbered media data formats, such as the Theora video codec and the Vorbis and Opus audio codecs. Xiph.org documents about the Ogg format are available on their web site.

While Ogg has been around for a long time, it has never gained the wide support needed to make it a good first choice for a media container. You are typically better off using WebM, though there are times when Ogg is useful to offer, such as when you wish to support older versions of Firefox and Chrome which don't yet support WebM. For example, Firefox 3.5 and 3.6 support Ogg, but not WebM.

You can get more information about Ogg and its codecs in the Theora Cookbook.

| Audio | Video |
| --- | --- |
| `audio/ogg` | `video/ogg` |

The `application/ogg` MIME type can be used when you don't necessarily know whether the media contains audio or video. If at all possible, you should use one of the specific types, but fall back to `application/ogg` if you don't know the content format or formats.

You can also add the `codecs` parameter (en-US) to the MIME type string to indicate which codecs are used for the audio and/or video tracks, and to optionally further describe the track media formats.

Video codecs supported by Ogg| Codec | Browser support |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| Theora |  |  | Yes |  |
| VP8 |  |  | Yes |  |
| VP9 |  |  | Yes |  |

Audio codecs supported by Ogg| Codec | Browser support |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| FLAC |  |  | Yes |  |
| Opus |  |  | Yes |  |
| Vorbis |  |  | Yes |  |

### QuickTime

The **QuickTime** file format (**QTFF**, **QT**, or **MOV**) was created by Apple for use by its media framework of the same name. The extension for these files, `.mov`, comes from the fact that the format was initially used for movies and was usually called the "QuickTime movie" format. While QTFF served as the basis for the MPEG-4 file format, there are differences and the two are not quite interchangeable.

QuickTime files support any sort of time-based data, including audio and video media, text tracks, and so forth. QuickTime files are primarily supported by macOS, but for a number of years, QuickTime for Windows was available to access them on Windows. However, QuickTime for Windows is no longer supported by Apple as of early 2016, and *should not be used*, as there are known security concerns. However, Windows Media Player now has integrated support for QuickTime version 2.0 and earlier files; support for later versions of QuickTime requires third-party additions.

On Mac OS, the QuickTime framework not only supported QuickTime format movie files and codecs, but supported a vast array of popular and specialty audio and video codecs, as well as still image formats. Through QuickTime, Mac applications (including web browsers, through the QuickTime plugin or direct QuickTime integration) were able to read and write audio formats including AAC, AIFF, MP3, PCM, and Qualcomm PureVoice; and video formats including AVI, DV, Pixlet, ProRes, FLAC, Cinepak, 3GP, H.261 through H.265, MJPEG, MPEG-1 and MPEG-4 Part 2, Sorenson, and many more.

In addition, a number of third-party components are available for QuickTime, some of which add support for additional codecs.

Because QuickTime support is, for all intents and purposes, primarily available on Apple devices, it is no longer widely used on the internet. Apple itself generally now uses MP4 for video. In addition, the QuickTime framework has been deprecated on the Mac for some time, and is no longer available at all starting in macOS 10.15 Catalina.

| Video |
| --- |
| `video/quicktime` |

The `video/quicktime` MIME type is the fundamental type for the QuickTime media container. It's worth noting that QuickTime (the media framework on Mac operating systems) supports a wide variety of containers and codecs, so it actually supports many other MIME types.

You can add the `codecs` parameter (en-US) to the MIME type string to indicate which codecs are used for the audio and/or video tracks, and to optionally provide details about the profile, level, and/or other codec configuration specifics.

Video codecs supported by QuickTime| Codec | Browser support |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| AVC (H.264) |  |  | No |  |
| Cinepak |  |  | No |  |
| Component Video |  |  | No |  |
| DV |  |  | No |  |
| H.261 |  |  | No |  |
| H.263 |  |  | No |  |
| MPEG-2 |  |  | No |  |
| MPEG-4 Part 2 Visual |  |  | No |  |
| Motion JPEG |  |  | No |  |
| Sorenson Video 2 |  |  | No |  |
| Sorenson Video 3 |  |  | No |  |

Audio codecs supported by QuickTime| Codec | Browser support |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| AAC |  |  | No |  |
| ALaw 2:1 |  |  | No |  |
| Apple Lossless (ALAC) |  |  | No |  |
| HE-AAC |  |  | No |  |
| MPEG-1 Audio Layer III (MP3) |  |  | No |  |
| Microsoft ADPCM |  |  | No |  |
| µ-Law 2:1 (u-Law) |  |  | No |  |

### WAVE (WAV)

The **Waveform Audio File Format** (**WAVE**), usually referred to simply as WAV due to its filename extension being `.wav`, is a format developed by Microsoft and IBM to store audio bitstream data.

It is derived from the Resource Interchange File Format (RIFF), and as such is similar to other formats such as Apple's AIFF. The WAV codec registry can be found at RFC 2361; however, because nearly all WAV files use linear PCM, support for the other codecs is sparse.

The WAVE format was first released in 1991.

| Audio |
| --- |
| `audio/wave`1 |
| `audio/wav` |
| `audio/x-wav` |
| `audio/x-pn-wav` |

[1] The `audio/wave` MIME type is the standard type, and is preferred; however, the others have been used by various products over the years and may be used as well in some environments.

Audio codecs supported by WAVE| Codec | Browser support |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| ADPCM (Adaptive Differential Pulse Code Modulation) |  |  | No |  |
| GSM 06.10 |  |  | No |  |
| LPCM (Linear Pulse Code Modulation) |  |  | Yes |  |
| MPEG-1 Audio Layer III (MP3) |  |  | No |  |
| µ-Law (u-Law) |  |  | No |  |

### WebM

**WebM** (**Web Media**) is a format based on Matroska which is designed specifically for use in modern web environments. It's based entirely on free and open technologies and primarily uses codecs that are in turn free and open, although some products support other codecs in WebM containers as well.

WebM was first introduced in 2010 and is now widely supported. Compliant implementations of WebM are required to support the VP8 and VP8 video codecs and the Theora and Opus audio codecs. The WebM container format and its required codecs are all available under open licenses. Any other codecs may require a license to use.

| Audio | Video |
| --- | --- |
| `audio/webm` | `video/webm` |

Video codecs supported by WebM| Codec | Browser support |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| AV1 | Yes | Yes | Yes1 | Yes |
| VP8 | Yes | Yes | Yes | Yes |
| VP9 | Yes | Yes | Yes | Yes |

[1] Firefox support for AV1 was added to macOS in Firefox 66; for Windows in Firefox 67; and Firefox 68 on Linux. Firefox for Android does not yet support AV1; the implementation in Firefox is designed to use a secure process, which is not supported yet in Android.

Audio codecs supported by WebM| Codec | Browser support |
| --- | --- |
| Chrome | Edge | Firefox | Safari |
| Opus | Yes | Yes | Yes | Yes |
| Vorbis | Yes | Yes | Yes | Yes |

Choosing the right container
----------------------------

There are a few factors to consider when selecting the best container or containers to use for your media. The relative importance of each will depend on your needs, your license requirements, and the compatibility requirements of your target audience.

### Guidelines

The best choice also depends on what you'll be doing with the media. Playing back media is a different thing than recording and/or editing it. If you're going to be manipulating the media data, using an uncompressed format can improve performance, while using a lossless compressed format at least prevent the accumulation of noise as compression artifacts are multiplied with each re-compression that occurs.

* If your target audience is likely to include users on mobile, especially on lower-end devices or on slow networks, consider providing a version of your media in a 3GP container with appropriate compression.
* If you have any specific encoding requirements, make sure the container you choose supports the appropriate codecs.
* If you want your media to be in a non-proprietary, open format, consider using one of the open container formats such as FLAC (for audio) or WebM (for video).
* If for any reason you are only able to provide media in a single format, choose a format that's available on the broadest selection of devices and browsers, such as MP3 (for audio) or MP4 (for video and/or audio).
* If your media is audio-only, choosing an audio-only container format likely makes sense. Now that the patents have all expired, MP3 is a widely supported and good choice. WAVE is good but uncompressed, so be aware of that before using it for large audio samples. FLAC is a very good choice, due to its lossless compression, if the target browsers all support it.

Unfortunately, neither of the relatively major lossless compression formats (FLAC and ALAC) are universally supported. FLAC is the more broadly supported of the two, but is not supported by macOS without additional software installed, and is not supported at all on iOS. If you need to offer lossless audio, you may need to provide both FLAC and ALAC to get close to universal compatibility.

### Container selection advice

The tables below offer suggested containers to use in various scenarios. These are just suggestions. Be sure to consider the needs of your application and your organization before selecting a container format.

#### Audio-only files

| If you need... | Consider using this container format |
| --- | --- |
| Compressed files for general-purpose playback | MP3 (MPEG-1 Audio Layer III) |
| Losslessly compressed files | FLAC with ALAC fallback |
| Uncompressed files | WAV |

Now that MP3's patents have all expired, the choice of audio file format has become much easier to make. It's no longer necessary to choose between MP3's broad compatibility and the need to pay royalties when using it.

#### Video files

| If you need... | Consider using this container format |
| --- | --- |
| General purpose video, preferably in an open format | WebM (ideally with MP4 fallback) |
| General purpose video | MP4 (ideally with WebM or Ogg fallback) |
| High compression optimized for slow connections | 3GP (ideally with MP4 fallback) |
| Compatibility with older devices/browsers | QuickTime (ideally with AVI and/or MPEG-2 fallback) |

These suggestions make a number of assumptions. You should carefully consider the options before making a final decision, especially if you have a lot of media that will need to be encoded.

Maximizing compatibility with multiple containers
-------------------------------------------------

To optimize compatibility, it's worth considering providing more than one version of media files, using the `<source>` (en-US) element to specify each source within the `<audio>` (en-US) or `<video>` (en-US) element. For example, you can offer an Ogg or WebM video as the first choice, with a fallback in MP4 format. You could even choose to offer a retro-like QuickTime or AVI fallback for good measure.

To do this, you create a `<video>` (or `<audio>`) element with no `src` (en-US) attribute. Then add child `<source>` (en-US) elements within the `<video>` element, one for each version of the video you offer. This can be used to offer various versions of a video that can be selected depending on bandwidth availability, but in our case, we'll use it to offer format options.

In the example shown here, a video is offered to the browser in two formats: WebM and MP4.

嘗試一下
----

The video is offered first in WebM format (with the `type` (en-US) attribute set to `video/webm`). If the user agent (en-US) can't play that, it moves on to the next option, whose `type` is specified as `video/mp4`. If neither of those can be played, the text "This browser does not support the HTML5 video element." is presented.

Specifications
--------------

| Specification | Comment |
| --- | --- |
| ETSI 3GPP | Defines the 3GP container format |
| ISO/IEC 14496-3 (MPEG-4 Part 3 Audio) | Defines MP4 audio including ADTS |
| FLAC Format | The FLAC format specification |
| ISO/IEC 11172-1 (MPEG-1 Part 1 Systems) | Defines the MPEG-1 container format |
| ISO/IEC 13818-1 (MPEG-2 Part 1 Systems) | Defines the MPEG-2 container format |
| ISO/IEC 14496-14 (MPEG-4 Part 14: MP4 file format) | Defines the MPEG-4 (MP4) version 2 container format |
| ISO/IEC 14496-1 (MPEG-4 Part 1 Systems) | Defines the original MPEG-4 (MP4) container format |
| RFC 3533 | Defines the Ogg container format |
| RFC 5334 | Defines the Ogg media types and file extensions |
| QuickTime File Format Specification | Defines the QuickTime movie (MOV) format |
| Multimedia Programming Interface and Data Specifications 1.0 | The closest thing to an official WAVE specification |
| Resource Interchange File Format (used by WAV) | Defines the RIFF format; WAVE files are a form of RIFF |
| WebM Container Guidelines | Guide for adapting Matroska for WebM |
| Matroska Specifications | The specification for the Matroska container format upon which WebM is based |
| WebM Byte Stream Format | WebM byte stream format for use with Media Source Extensions (en-US) |

Browser compatibility
---------------------

| Container format name | Audio | Video |
| --- | --- | --- |
| MIME type | Extension(s) | Browser support | MIME type | Extension(s) | Browser support |
| 3GP | `audio/3gpp` | `.3gp` | Firefox | `video/3gpp` | `.3gp` | Firefox |
| ADTS (Audio Data Transport Stream) | `audio/aac` | `.aac` | Firefox | — | — | — |
| FLAC | `audio/flac` | `.flac` | Firefox | — | — | — |
| MPEG-1 / MPEG-2 (MPG or MPEG) | `audio/mpeg` | `.mpg``.mpeg` | Firefox | `video/mpeg` | `.mpg``.mpeg` | Firefox |
| `audio/mp3` | `.mp3` | Firefox |
| MPEG-4 (MP4) | `audio/mp4` | `.mp4``.m4a` | Firefox | `video/mp4` | `.mp4``.m4v``.m4p` | Firefox |
| Ogg | `audio/ogg` | `.oga``.ogg` | Firefox | `video/ogg` | `.ogv``.ogg` | Firefox |
| QuickTime Movie (MOV) | — | — | — | `video/quicktime` | `.mov` | Safari |
| WAV (Waveform Audiofile) | `audio/wav` | `.wav` | Firefox | — | — | — |
| WebM | `audio/webm` | `.webm` | Firefox | `video/webm` | `.webm` | Firefox |

See also
--------

* WebRTC API (en-US)
* MediaStream Recording API (en-US)
* `<audio>` (en-US) and `<video>` (en-US) elements


弱簽章演算法 - Web 安全

弱簽章演算法
======

### 簽章演算法的重要性

在簽署憑證時，雜湊演算法的完整性是非常重要的一環。雜湊演算法的漏洞可能導致攻擊者獲取假造的憑證。隨著科技發展出現更多可行的攻擊新手法，並不建議繼續使用舊的演算法，且這些演算法最終該被移除。

### SHA-1

以 SHA-1 為基礎的簽章非常普遍：因為到目前為止大部分憑證皆使用 SHA-1。然而考慮到 SHA-1 已經太過老舊，不建議繼續使用下去。當未來要替換憑證時，請先確認使用的是強簽章演算法。更多資訊請查閱 Mozilla Security Blog post 上的內容。

### MD5

以 MD5 為基礎的簽章已在 2012 初被移除。


不安全的密碼 - Web 安全

不安全的密碼
======

提供 HTTP 的登入表單非常危險，因為目前有很多已知的用戶密碼擷取手法。竊聽者可以透過側錄該網路或修改傳輸頁面進行大量的惡意攻擊，並直接竊取用戶憑證或密碼。本頁將詳細說明 Firefox 用以警示用戶與開發者有關不安全的密碼及密碼竊取風險的安全機制。

HTTPS (en-US) 通訊協定，旨在保護用戶的資料於傳輸時不會遭到竊聽與竄改，並保護其機密性與原始完整性。負責處理用戶資料的網站應使用 HTTPS 保護其用戶不受惡意駭客攻擊。如果沒有使用 HTTPS，竊取諸如登入憑證之類的用戶資訊是小事一樁。著名的 Firesheep 附加套件曾示範過此種攻擊方式。

要處理這個問題，請安裝並設定網站伺服器的 SSL/TLS 憑證。目前有許多免費與付費的憑證供應商。如果是使用雲端，雲端服務商可能提供了啟動 HTTPS 的方法。

重複使用相同密碼
--------

網站有時會需要用戶名稱與密碼，但並不實際儲存敏感資料。例如，新聞網站可能會儲存用戶想要再次閱覽的文章，但不會儲存其它用戶資料。上述範例的網頁開發者可能較無動機保護他們的網站與用戶憑證。

不幸的是，重複使用相同密碼是非常危險的。用戶在多個網站皆使用相同密碼(如新聞網站、社群網站、電子信箱等)。因此，即使非法存取貴網站的用戶名稱與密碼並不對你構成嚴重問題，對於在不同網站(如網路銀行)使用相同名稱與密碼的用戶而言，卻會造成嚴重威脅。攻擊者愈來愈聰明，他們會從一個網站竊取用戶名稱與密碼的配對，並在更有利可圖的網站上重複嘗試。

參見
--

* No More Passwords over HTTP, Please! — 提供詳細資訊和常見問題的部落格文章


同源政策 (Same-origin policy) - Web 安全

同源政策 (Same-origin policy)
=========================

同源政策限制了程式碼和不同網域資源間的互動。

同源定義
----

所謂同源是指兩份網頁具備相同協定、埠號 (如果有指定) 以及主機位置，下表提供了一些例子展示那些來源和 `http://store.company.com/dir/page.html` 屬於同源:

| URL | Outcome | Reason |
| --- | --- | --- |
| `http://store.company.com/dir2/other.html` | 同源 |  |
| `http://store.company.com/dir/inner/another.html` | 同源 |  |
| `https://store.company.com/secure.html` | 不同源 | 協定不同 |
| `http://store.company.com:81/dir/etc.html` | 不同源 | 埠號不同 |
| `http://news.company.com/dir/other.html` | 不同源 | 主機位置不同 |

另外請參考 file 來源定義: URL。

Cookie 的來源定義和上述不一樣。

變更來源
----

網頁能夠有限地變更來源，我們可以將 `document.domain` (en-US) 存為目前網域後半部，然後較短的網域就會作為之後來源檢查，譬如我們在 `http://store.company.com/dir/other.html` 的文件裡執行以下程式碼:
```

document.domain = "company.com";
```

執行完後，網頁能以 `http://company.com/dir/page.html` 通過同源檢查。然而基於同源檢查，company.com 無法將 document.domain 存為 othercompany.com。

任何變更 document.domain 行為，包括 document.domain = document.domain 都會導致埠號重置為 null，因此無法只藉由執行 document.domain = "company.com" 讓 company.com:8080 和 company.com 互動，必須兩邊都重新設定好讓埠號都一致重置為 null。

**備註：** 為了讓子網域可以安全的存取其母網域，我們需要一起改變子、母網域的 document.domain 為相同值，即使只是將母網域設回原始值也是必要，否則將會導致許可權錯誤 (Permission Error)。

跨來源網路存取
-------

同源政策控制了兩個不同網域來源互動，例如當使用`XMLHttpRequest`。這些互動可分為以下三類:

* 跨來源寫(Cross-origin writes)通常被允許，例如有連結、重新導向以及表單送出。少數某些 HTTP 請求需要先導請求。
* 跨來源嵌入(Cross-origin embedding)通常被允許，例子請參照下方。
* 跨來源讀取(Cross-origin read) 通常不被允許，不過通常可以藉由嵌入來繞道讀取，例如嵌入影像寬高讀取、嵌入程式碼或嵌入資源。

下面是一些能跨來源嵌入的資源:

* `<script src="…"></script>` 內的 JavaScript，但語法錯誤訊息只限於同源程式碼腳本。
* CSS 的 `<link rel="stylesheet" href="...">`，由於 CSS 寬鬆語法規則，跨來源 CSS 要求正確的 Content-Type 標頭。限制在瀏覽器間各有差異: IE, Firefox, Chrome, Safari (請至 CVE-2010-0051)以及Opera.
* `<img>` (en-US)的影像；支援格式有 PNG, JPEG, GIF, BMP, SVG 等等
* `<video>` (en-US)和`<audio>` (en-US)媒體檔案
* `<object>` (en-US), `<embed>` (en-US)和`<applet>`的外掛
* `@font-face` 的字型；有些瀏覽器允許跨來源字型，有些則不。
* `<frame>` (en-US)以及`<iframe>` (en-US)中的內容；如果一個網站想要避免跨來源載入互動，可以藉由`X-Frame-Options`標頭避免。
### 如何允許跨來源存取

使用CORS允許跨來源存取

### 如何阻擋跨來源存取

* 藉由檢查請求中包含的無法猜測的特殊記號(token)可以避免跨來源寫入，還有跨來源讀取知道此記號的網頁，這個記號即為跨站偽造(Cross-Site Request Forgery, CSRF)記號。
* 確保資源無法被嵌入來防止跨來源讀取。
* 為了防止跨來源嵌入，請確保資源不被解讀為上述可嵌入格式之一；瀏覽器通常不會理會 Content-Type，比如說有一個指向 HTML 文件的<script>標籤，瀏覽器還是會嘗試解析該 HTML 文件為 Javascript；當你的資源不是網站進入點，可以使用 CSRF 記號。
跨來源程式腳本存取
---------

Javascript API 例如`iframe.contentWindow` (en-US), `window.parent` (en-US), `window.open` (en-US)以及`window.opener`，允許文件之間直接互相參照，當兩份文件的來源不同，參照存取Window和Location物件將受到限制；一些瀏覽器比規範准許存取更多屬性。文件間的溝通也可以改用`window.postMessage` (en-US)來進行。

延伸閱讀
----

* Same-origin policy for file: URIs
* Same-Origin Policy at W3C


混合內容 - Web 安全

混合內容
====

當使用者以 HTTPS (en-US) 瀏覽網站時，他們與伺服器之間的連線就會以 TLS (en-US) 加密，以防受到竊聽或中間人攻擊。一個含有 HTTP 明文內容的 HTTPS 頁面稱為**混合內容（mixed content）**。這種頁面只有部份加密，沒有加密的內容，易於遭到竊聽和中間人攻擊。這會令網頁不安全。

混合內容的類型
-------

混合內容的類型有兩種：**被動/顯示型混合內容（mixed passive/display content）**與**主動型混合內容（mixed active content）**。兩者不同處在於內容遭中間人攻擊竄改後，其最壞情況下的威脅程度。如果是被動型混合內容，威脅程度較低（可能有錯誤內容、或者用戶的 cookie 遭到竊取）。如果是主動型混合內容，威脅就可能會變成網絡釣魚、敏感資料洩露、被重定向到惡意網站……等等。

### 被動/顯示型混合內容

被動/顯示型混合內容內容是指包在 HTTPS 頁面，但無法改變其他部分的 HTTP 內容。例如，攻擊者能把放在 HTTP 的圖像，換成對用戶而言不適當的圖片或訊息。攻擊者也能監看圖片提供給哪些用戶，來推斷用戶活動的相關資訊：圖片通常只能在網站內的特定頁面提供。如果攻擊者觀察了某些圖片的 HTTP 請求，他們還能確認用戶在訪問哪個網頁。

#### 被動型混合內容清單

以下列出會被視為被動型混合內容的 HTTP 請求：

* `<img>` (en-US)（`src` 屬性）
* `<audio>` (en-US)（`src` 屬性）
* `<video>` (en-US)（`src` 屬性）
* `<object>` (en-US) subresource（如果 `<object>` 發起 HTTP 請求）
### 主動型混合內容

**主動型混合內容**是指有權訪問文件 HTTPS 頁面、物件模型的內容。這種混合內容可以改變 HTTPS 頁面行為、並暗自竊取用戶的敏感資訊。因此，主動型混合內容除了內容除了上文所述的風險外，還容易受到其他攻擊媒介的威脅。

針對主動型混合內容，中間人攻擊者可以攔截 HTTP 內容的請求、並竄改回應以植入惡意 JavaScript 程式碼。惡意的主動型混合內容能竊取用戶的憑證、用戶的敏感資料、甚至透過如瀏覽器或套件的漏洞，嘗試安裝惡意軟體。

混合內容涉及的風險，取決於用戶訪問的網站類型、還有該網站資訊的敏感程度。網頁可能有公諸於世的公開資料、也可能有僅限授權者閱覽的私人資料。即使網頁是公開的，也沒有用戶的敏感資料，混合內容依舊給攻擊者把用戶重定向到其他 HTTP 頁面、並從這些網站竊取 HTTP cookie 的機會。

#### 主動型混合內容示例

以下列出會被視為主動型混合內容的 HTTP 請求：

* `<script>`（`src` 屬性）
* `<link>` (en-US)（`href` 屬性）（包含 CSS 樣式表）
* `<iframe>` (en-US)（`src` 屬性）
* `XMLHttpRequest` 請求
* `fetch()` (en-US) 請求
* 所有用到 `url()` (en-US) 的 CSS 值（`@font-face`、`cursor` (en-US)、`background-image` (en-US)……等等）。
* `<object>` (en-US)（`data` 屬性）

其他資源如 web fonts 與 workers 也可能被認定為主動型混合內容，因為在 Chromium 就是這樣。

網頁主控台的警告
--------

Firefox 網頁主控台會在網站含有混合內容時，於「網路」標籤顯示警告。以 HTTP 傳輸的混合內容資源會被標為紅色，後面會附上導往這一頁的「混合內容」標註。

![Screen shot of the web console displaying a mixed content warning.](/zh-TW/docs/Web/Security/Mixed_content/mixed_content_-_net_pane.png)

找到網頁主控台的警告後，可以在你的網站使用 Content Security Policy (CSP) (en-US) 或網站爬蟲找到問題，，例如 HTTPS Checker 或是 Mixed Content Scan。

從 Firefox 23 以後，預設會封鎖混合內容（要封鎖混合的顯示內容也可以設定）。為了令 web 開發者便於尋找混合內容的錯誤，所有遭到封鎖的混合內容會被紀錄到網頁主控台的安全標籤，如下所示：

![A screenshot of blocked mixed content errors in the Security Pane of the Web Console](/zh-TW/docs/Web/Security/Mixed_content/mixed_content_webconsole.png)

要修正這個錯誤，就要移除所有的 HTTP 請求、並以 HTTPS 取代之。部份例子包含 JavaScript 檔案、CSS 樣式表、影像檔、影片檔或是其他多媒體文件。

**備註：** Firefox 55 以後，在本機端會允許混合內容的載入（請參見 Firefox bug 903966）。

參見
--

* Mixed Content - W3C Editor's Draft
* 如何修正含有混和內容的網站


如何修正含有混合內容的網站 - Web 安全

如何修正含有混合內容的網站
=============

自 Firefox 23 (en-US) 起，Firefox 會預設阻擋主動型混合內容。這項動作是跟在 IE 9 和 Chrome 後實行的。

本頁面會告訴你，身為一個網頁開發者需要知道甚麼。

你的網站可能出問題了
----------

如果你的網站由 HTTPS 傳輸，那麼本頁所有由 HTTP 接收的主動型混合內容就會被封鎖。你的網站可能就會讓使用者遇到一些問題（像是 iframes 或擴充套件無法載入…之類的）。至於 被動型混合內容 預設是會顯示出來的，可是使用者也可以設定將這類內容擋下來。

值得注意的是，由於阻擋混合內容已經在 Chrome 和 Internet Explorer 中實行了，所以如果你的網站已經在這些瀏覽器中出問題，那麼在 Firefox 也很有可能會發生相同情況。

在任何情況下，要知道網站是否出問題的最好方法，就是下載 最新的 Firefox Developer Edition，然後到網站中的不同頁面打開網頁主控台（要啟用「安全」訊息）、並檢查是否有任何混合內容的回報。也可以用 SSL-check or Missing Padlock 這網路爬蟲、或是桌面桌面， HTTPSChecker 來檢查並抓出不安全的內容、另外還有文字介面的工具 mcdetect。如果檢查不到任何有關於混和式內容的東西，就代表你的網站狀態良好：繼續建置你出色的網站吧！

如何修復你的網站
--------

避免混合內容阻塞最好的方法，就是使用 HTTPS 而不是 HTTP 來傳輸所有的內容。

\*\*對於你自己的域名，\*\*使用 HTTPS 來傳輸所有內容並修正你的連結。一般而言 HTTPS 版本的內容都已經存在了，只需要在連結後面加上「s」：就是將 http:// 改成 https:// 。

但有時候，媒體的路徑可能不正確。按照作業系統的不同，你可以使用線上或離線的工具如 linkchecker 來解決問題。

\*\*對於其他域名，\*\*盡可能使用該網站的 HTTPS 版本。如果 HTTPS 不能用，試著跟域名擁有者聯絡並詢問他們是否可以使用 HTTPS 傳輸內容。


Response - Web APIs

Response
========

Fetch API 的 **`Response`** 介面代表了一個請求會返回的回應。

你可以用 `Response.Response()` (en-US) 建構子創建一個新的 `Response`物件。但實務上碰到 Response 物件的時機，比較常出現在進行了一個 API 操作後，得到返回的 Response 物件。舉例而言，使用 service worker `Fetchevent.respondWith` (en-US) 或是使用單純的`GlobalFetch.fetch()` (en-US)。

建構子
---

`Response()` (en-US)

創建一個新的 `Response` 物件。

屬性
--

`Response.headers` (en-US) Read only

包含與此 response 相關的 `Headers` (en-US) 物件。

`Response.ok` (en-US) Read only

無論此 response 是不是成功 ( 狀態碼 200-299 ) 都會包含一個 boolean 狀態。

`Response.redirected` (en-US) Read only

指出此 response 是不是個重新導向的結果，如果是的話，代表此 URL 具有一個以上的入口。

`Response.status` (en-US) Read only

包含此 response 的狀態碼(例如：成功時為 `200` )。

`Response.statusText` (en-US) Read only

包含狀態碼所對應的狀態文字 (例如： `OK` 對應 `200`)。

`Response.type` (en-US) Read only

包含此 response 的類型 (例如： `basic`, `cors`)。

`Response.url` (en-US) Read only

包含此 response 的 URL。

`Response.useFinalURL`

包含一個 boolean 狀態，指出此 URL 是否為此 response 的最後一步。

`Response` 實做了`Body`, 所以它另有以下可用的屬性：

`Body.body` (en-US) Read only

A simple getter used to expose a `ReadableStream` (en-US) of the body contents.

`Body.bodyUsed` (en-US) Read only

Stores a `Boolean` (en-US) that declares whether the body has been used in a response yet.

方法
--

`Response.clone()` (en-US)

建立一份 `Response` 的複製物件。

`Response.error()` (en-US)

Returns a new `Response` object associated with a network error.

`Response.redirect()` (en-US)

Creates a new response with a different URL.

`Response` implements `Body`, so it also has the following methods available to it:

`Body.arrayBuffer()` (en-US)

Takes a `Response` stream and reads it to completion. It returns a promise that resolves with an `ArrayBuffer`.

`Body.blob()` (en-US)

Takes a `Response` stream and reads it to completion. It returns a promise that resolves with a `Blob`.

`Body.formData()` (en-US)

Takes a `Response` stream and reads it to completion. It returns a promise that resolves with a `FormData` object.

`Body.json()` (en-US)

Takes a `Response` stream and reads it to completion. It returns a promise that resolves with the result of parsing the body text as `JSON`.

`Body.text()` (en-US)

Takes a `Response` stream and reads it to completion. It returns a promise that resolves with a `USVString` (en-US) (text).

範例
--

在基本 fetch 範例 (run example live) 中，我們使用 `fetch()` 呼叫來得到圖片，並使用 `<img>` (en-US) tag 顯示。 這裡的`fetch()` 呼叫返回了一個 promise，它使用與資源 fetch 操作有關的 `Response` 進行解析。你可能有發現，由於我們要求的是一張圖片，所以需要用 `Body.blob` (en-US) (`Response` 時做了 body) 讓 response 有正確的 MIME 類型。

```js
const image = document.querySelector(".my-image");
fetch("flowers.jpg")
  .then(function (response) {
    return response.blob();
  })
  .then(function (blob) {
    const objectURL = URL.createObjectURL(blob);
    image.src = objectURL;
  });
```

除此之外，你也能用 `Response.Response()` (en-US) 建構子去建立自己的客製化 `Response` 物件：

```js
const response = new Response();
```

規範
--

| Specification |
| --- |
| Fetch Standard # response-class |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參考
--

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


MediaSource - Web APIs

MediaSource
===========

**實驗性質:** **這是一個實驗中的功能 (en-US)**
此功能在某些瀏覽器尚在開發中，請參考兼容表格以得到不同瀏覽器用的前輟。

Media Source Extensions API (en-US) 的 **`MediaSource`** 介面代表 `HTMLMediaElement` (en-US) 物件的媒體資料來源。一個 `MediaSource` 物件可以被附加到一個 `HTMLMediaElement` (en-US) 以被用戶代理 (user agent) 播放。

EventTarget

MediaSource建構子 (Constructor)
-----------------

`MediaSource()`

建構且回傳一個新的 `MediaSource` 物件但不與任何來源緩衝 (source buffers) 關聯 (associate)。

屬性 (Properties)
---------------

`MediaSource.sourceBuffers` (en-US) Read only

回傳一個含有與此 `MediaSource` 關聯的 `SourceBuffer` (en-US) 物件串列的 `SourceBufferList` (en-US) 物件。

`MediaSource.activeSourceBuffers` Read only

回傳一個 `SourceBufferList` (en-US) 物件，含有 `SourceBuffers` 的子集合 `SourceBuffer` (en-US) 物件 — 物件的串列提供被選擇的影片軌 (video track), 啟用的音軌 (audio tracks), 以及顯示或隱藏的字軌。

`MediaSource.readyState` Read only

回傳一個列舉類型表示目前 `MediaSource` 的狀態：沒有附加到媒體元件 (`closed`)，已經附加且可以接收 `SourceBuffer` (en-US) 物件 (`open`)，已經附加但是串流已經經由 `MediaSource.endOfStream()` (en-US) 結束 (`ended`)。

`MediaSource.duration`

取得或設置現在正被表示的媒體的時間長度。

### 事件處理函數 (Event handlers)

`MediaSource.onsourceclose`

`sourceclose` 事件的事件處理函數。

`MediaSource.onsourceended`

`sourceended` 事件的事件處理函數。

`MediaSource.onsourceopen`

`sourceopen` 事件的事件處理函數。

方法 (Methods)
------------

*從親介面 (parent interface) `EventTarget` 繼承屬性。*

`MediaSource.addSourceBuffer()` (en-US)

依據指定的 MIME 類型建立一個新的 `SourceBuffer` (en-US) 且將其加入 `MediaSource` 的 `SourceBuffers` 串列。

`MediaSource.clearLiveSeekableRange()` (en-US)

清除先前藉由呼叫 `setLiveSeekableRange()` 所設定的可尋找範圍。

`MediaSource.endOfStream()` (en-US)

示意串流的結束。

`MediaSource.removeSourceBuffer()` (en-US)

從與此 `MediaSource` 物件關聯的 `SourceBuffers` 串列移除指定的 `SourceBuffer` (en-US)。

`MediaSource.setLiveSeekableRange()` (en-US)

設定使用者可以在媒體元素中的可尋找範圍。

靜態方法 (Static methods)
---------------------

`MediaSource.isTypeSupported()` (en-US)

回傳一個 `Boolean` (en-US) 值表示指定的 MIME 類型是否被現在的用戶代理支援 — 意即可否成功的為該 MIME 類型建立 `SourceBuffer` (en-US) 物件。

範例
--

以下簡單的範例儘快的載入一個個影片塊 (chunk) 且儘快的播放。這個範例是由 Nick Desaulniers 所撰寫且可以在此實際觀看（你也可以下載原始碼以更進一步研究）

```js
var video = document.querySelector("video");

var assetURL = "frag\_bunny.mp4";
// Need to be specific for Blink regarding codecs
// ./mp4info frag\_bunny.mp4 | grep Codec
var mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"';

if ("MediaSource" in window && MediaSource.isTypeSupported(mimeCodec)) {
  var mediaSource = new MediaSource();
  //console.log(mediaSource.readyState); // closed
  video.src = URL.createObjectURL(mediaSource);
  mediaSource.addEventListener("sourceopen", sourceOpen);
} else {
  console.error("Unsupported MIME type or codec: ", mimeCodec);
}

function sourceOpen(\_) {
  //console.log(this.readyState); // open
  var mediaSource = this;
  var sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener("updateend", function (\_) {
      mediaSource.endOfStream();
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
}

function fetchAB(url, cb) {
  console.log(url);
  var xhr = new XMLHttpRequest();
  xhr.open("get", url);
  xhr.responseType = "arraybuffer";
  xhr.onload = function () {
    cb(xhr.response);
  };
  xhr.send();
}
```

規格
--

| Specification |
| --- |
| Media Source Extensions™ # mediasource |

相容性表格
-----

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相關資料
----

* `SourceBuffer` (en-US)
* `SourceBufferList` (en-US)


NamedNodeMap - Web APIs

NamedNodeMap
============

**`NamedNodeMap`** 介面表示了 `Attr` (en-US) 物件的集合。雖然 `NamedNodeMap` 與 `NodeList` 都能如陣列一般透過索引訪問成員，但和 `NodeList` 不同的是，`NamedNodeMap` 中的成員並沒有順序。

`NamedNodeMap` 物件具有*即時性（live）*，如果其內部成員（屬性節點物件）發生改變，`NamedNodeMap` 物件會自動更新至最新的狀態。

**備註：** 僅管被稱作 `NamedNodeMap`，但本介面並不是直接用來處理節點物件（`Node` (en-US)），而是專門負責屬性節點物件（`Attr` (en-US)）。屬性節點是一種特殊的節點，在部分瀏覽器實作中依然存在。

屬性
--

*This interface doesn't inherit any property.*

`NamedNodeMap.length` (en-US) Read only

Returns the amount of objects in the map.

方法
--

*This interface doesn't inherit any method.*

`NamedNodeMap.getNamedItem()` (en-US)

Returns a `Attr` (en-US), corresponding to the given name.

`NamedNodeMap.setNamedItem()` (en-US)

Replaces, or adds, the `Attr` (en-US) identified in the map by the given name.

`NamedNodeMap.removeNamedItem()` (en-US)

Removes the `Attr` (en-US) identified by the given map.

`NamedNodeMap.item()` (en-US)

Returns the `Attr` (en-US) at the given index, or `null` if the index is higher or equal to the number of nodes.

`NamedNodeMap.getNamedItemNS()` (en-US)

Returns a `Attr` (en-US) identified by a namespace and related local name.

`NamedNodeMap.setNamedItemNS()` (en-US)

Replaces, or adds, the `Attr` (en-US) identified in the map by the given namespace and related local name.

`NamedNodeMap.removeNamedItemNS()` (en-US)

Removes the `Attr` (en-US) identified by the given namespace and related local name.

規範
--

| Specification |
| --- |
| DOM Standard # interface-namednodemap |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `Element.attributes` (en-US)


Coordinates - Web APIs

Coordinates
===========

**`Coordinates`** 這個介面用來存取裝置的經緯度，速度以及這些數值的準確度。

屬性
--

*`Coordinates` 這個介面沒有繼承任何屬性*。

`Coordinates.latitude` Read only

回傳一個十進位的 double 代表緯度。

`Coordinates.longitude` Read only

回傳一個十進位的 double 代表經度。

`Coordinates.altitude` Read only

回傳一個 double 代表距離海平面的高度，單位為公尺。如果無法提供這個值則回傳 null。

`Coordinates.accuracy` Read only

回傳一個 double 代表經緯度的精準值，單位為公尺。

`Coordinates.altitudeAccuracy` Read only

回傳一個 double 代表高度的精準度，單位為公尺。如果無法提供這個值則回傳 null。

`Coordinates.heading` Read only

回傳一個 double 代表裝置前進的方向，這個數值代表你偏離北方多少度，0 度代表你向著正北方，照著順時針的方向遞增(90 度代表正東方，270 度代表正西方) 。如果速度值為 0 度，則此值為 `NaN` (en-US)。如果無法提供這個值則回傳 null。

`Coordinates.speed` Read only

回傳一個 double 代表速度，單位為公尺/秒。如果無法提供這個值則回傳 null。

方法
--

**`Coordinates` 這個介面**，沒有實作也沒有繼承自任何的方法。

規格
--

| Specification |
| --- |
| Geolocation API # coordinates\_interface |

瀏覽器的相容性
-------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

請參考
---

* Using geolocation (en-US)
* `Geolocation` 介面使用此物件。


ClipboardEvent - Web APIs

ClipboardEvent
==============

**實驗性質:** **這是一個實驗中的功能 (en-US)**
此功能在某些瀏覽器尚在開發中，請參考兼容表格以得到不同瀏覽器用的前輟。

**`ClipboardEvent`** 介面表示了與修改剪貼簿相關的事件，包括 `cut` (en-US)、`copy` (en-US) 及 `paste` (en-US) 事件。

屬性
--

*Also inherits properties from its parent `Event`*.

`ClipboardEvent.clipboardData` (en-US) Read only

Is a `DataTransfer` (en-US) object containing the data affected by the user-initiated `cut` (en-US), `copy` (en-US), or `paste` (en-US) operation, along with its MIME type.

建構式
---

`ClipboardEvent()` (en-US)

Creates a `ClipboardEvent` event with the given parameters.

方法
--

*No specific methods; inherits methods from its parent `Event`*.

規範
--

| Specification |
| --- |
| Clipboard API and events # clipboard-event-interfaces |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* Copy-related events: `copy` (en-US), `cut` (en-US), `paste` (en-US)


WebSockets - Web APIs

WebSockets
==========

**實驗性質:** **這是一個實驗中的功能 (en-US)**
此功能在某些瀏覽器尚在開發中，請參考兼容表格以得到不同瀏覽器用的前輟。

WebSocket 是一種讓瀏覽器與伺服器進行一段互動通訊的技術。這個 API 在不必輪詢（poll）伺服器下，讓使用者傳送訊息至伺服器並接受事件驅動回應。

|  |  |
| --- | --- |
| 文件

製作 WebSocket 客戶端應用程式
指導如何製作在瀏覽器上跑 WebSocket 客戶端的教程。
WebSockets 參考手冊
客戶端的 WebSocket API 參考手冊。
The WebSocket protocol
WebSocket 協定參考。
Writing WebSocket servers
處理 WebSocket 協定的伺服器端代碼書寫指引。
 | 工具* Socket.IO：一個強大的跨平台 WebSocket
 API，建構在 Node.js 之上。
* WebSocket-Node：一個 WebSocket 伺服器 API 的實作，建構在
 Node.js 之上。

相關主題

AJAX、JavaScript
 |

參見
--

* WebSocket API Specification
* Server-Sent Events
瀏覽器兼容
-----

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Battery Status API - Web APIs

Battery Status API
==================

**Battery Status API** 也就是所謂的 **Battery API**，將提供系統電池充電容量的資訊，並在電池容量變化時送出事件，以通知使用者。此 API 可調整 Apps 的資源耗用量，在電力偏低時縮減耗電量；或可在電力耗盡之前儲存檔案，避免資料遺失。

Battery Status API 是以 `window.navigator.battery` (en-US) 屬性 (為 `BatteryManager` (en-US) 物件) 而擴充了 `window.navigator` (en-US)，並新增數項可讓使用者接收的新事件，以隨時監控電池狀態。

範例
--

在此範例中，我們將分別監聽 chargingchange 與 levelchange 事件，而看到充電狀態 (不論是否插電進行充電) 與電池容量的變化。

```js
var battery =
  navigator.battery || navigator.mozBattery || navigator.webkitBattery;

function updateBatteryStatus() {
  console.log("Battery status: " + battery.level \* 100 + " %");

  if (battery.charging) {
    console.log("Battery is charging");
  }
}

battery.addEventListener("chargingchange", updateBatteryStatus);
battery.addEventListener("levelchange", updateBatteryStatus);
updateBatteryStatus();
```

另可參閱規格所提供之範例。

規格
--

| Specification |
| --- |
| Battery Status API  |

瀏覽器相容性
------

### api.BatteryManager

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Navigator.getBattery

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

另請參閱
----

* 部落格文章 - Using the Battery API
* David Walsh 所寫的 JavaScript Battery Api
* battery.js - 跨瀏覽器 wrapper
* `BatteryManager` (en-US)
* `navigator.battery` (en-US)
* `測試你的瀏覽器是否支援 Battery Status API。可掃 QR Code:`
* ![QR Code to Battery Status API Test Page](http://x.co/qr/batstat?s=165)


Blob - Web APIs

Blob
====

`Blob`（Binary Large Object）物件代表了一個相當於檔案（原始資料）的不可變物件。Blob 中的資料並不一定是 JavaScript 原生的格式。`File` 介面基於 `Blob，`繼承 blob 並擴充其功能以支援操作使用者系統上的檔案。

從其它非 Blob 物件或資料來建構 `Blob` 物件，可以使用 `Blob()` 建構式。要建立一個包含目前 blob 內容子集的 blob，可使用 `slice()` (en-US) 方法。若要自使用者系統上的檔案取得 `Blob` 物件，請參考 `File` 文件。

接受 Blob 物件的 API 可以在 `File` 上找到。

**備註：** 早期 `slice()` 方法擁有第二個參數 `length` 以指定在建立新 `Blob` 物件時要複製的位元組（byte）數量。假如指定的 `start + length` 超出了來源 `Blob` 的大小，則回傳的 `Blob` 會包含自索引 `start` 至結尾的完整來源內容。

**備註：** 需注意在部分瀏覽器版本中，`slice()` 方法帶有前綴：Firefox 12 與之前的版本為 `blob.mozSlice()`，Safari 中是 `blob.webkitSlice()`。舊的、無前綴字版本的 `slice()` 方法則有不同的語意（semantics），但這是已淘汰的方法。瀏覽器對 `blob.mozSlice()` 的支援已在 Firefox 30 時中止。

建構式
---

`Blob(blobParts[, options])`

回傳新建立的 `Blob` 物件，包含了建構式參數傳入之陣列所串聯後的值。第二個參數為 BlobPropertyBag 物件，其擁有 `type` 和 `endings` 屬性。

屬性
--

`Blob.size` Read only

以 byte 為單位的 `Blob` 物件大小。

`Blob.type` Read only

`Blob` 物件中資料的型態，以 MIME 類型的字串表示。若型態為未知，則為空字串。

方法
--

`Blob.slice([start[, end[, contentType]]])` (en-US)

回傳一個包含當前 `Blob` 物件之指定資料範圍（byte）內容的新 `Blob` 物件。

範例
--

### Blob 建構函數用法範例

`Blob() constructor` 建構式允許由其它物件建立 blob 物件。以下的範例演示了以字串來建構 blob 物件：

```js
var debug = { hello: "world" };
var blob = new Blob([JSON.stringify(debug, null, 2)], {
  type: "application/json",
});
```

**警告：** 在 Blob 建構式出現之前，可以透過 `BlobBuilder` (en-US) 來建立 blob 物件（目前已不建議使用）：

```js
var builder = new BlobBuilder();
var fileParts = ['<a id="a"><b id="b">hey!</b></a>'];
builder.append(fileParts[0]);
var myBlob = builder.getBlob("text/xml");
```

### 藉型別陣列建構的 blob 來建立 URL

範例程式碼：

```js
var typedArray = GetTheTypedArraySomehow();
var blob = new Blob([typedArray], { type: "application/octet-binary" }); // pass a useful mime type here
var url = URL.createObjectURL(blob);
// url will be something like: blob:d3958f5c-0777-0845-9dcf-2cb28783acaf
// now you can use the url in any context that regular URLs can be used in, for example img.src, etc.
```

### 從 Blob 取出資料

從 Blob 讀取資料的唯一方式就是使用 `FileReader`。以下範例展示了讀取 Blob 內容作為型別陣列：

```js
var reader = new FileReader();
reader.addEventListener("loadend", function () {
  // reader.result contains the contents of blob as a typed array
});
reader.readAsArrayBuffer(blob);
```

藉由操作 `FileReader` 的其他方法，將 Blob 讀取成字串或是 data URL 是有可能的。

規範
--

| Specification |
| --- |
| File API # blob-section |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `BlobBuilder` (en-US)
* `File`
* `URL.createObjectURL` (en-US)
* Components.utils.importGlobalProperties


Payment Request API - Web APIs

Payment Request API
===================

**Secure context:** This feature is available only in secure contexts (en-US) (HTTPS), in some or all supporting browsers.

Payment Request API 提供商家與用戶雙方一致的用戶體驗。它並不是嶄新的支付方式、而是讓用戶選擇偏好的支付方式、並把該方式提供給商家。

Payment Request 的概念和用法
----------------------

很多放棄線上購物的問題，與結帳表單的填寫有關：填寫這些東西既困難又耗時、步驟還極度繁雜。**Payment Request API**正是為減少、甚至擺脫要完成表單所需的填寫步驟而生。它藉由不假手 HTML 表單的情況下，記下要傳給商家的用戶資訊，來簡化結帳步驟。

針對信用卡付款，使用 Payment Request API 的好處有：

* **快速的訂購體驗**：用戶在進入瀏覽器時輸入資訊、接著就備齊網路購物所需。用戶再也無須於多個網站，填寫相同資訊。
* **各站一致且支援 API 的用戶體驗**：由於是瀏覽器在掌管付款資訊，用戶體驗將能客製化、還可以把 UI 本土化為用戶偏好的語言。
* **無障礙**：由於是瀏覽器在掌管輸入表單，各網站針對鍵盤和螢幕閱讀器的無障礙將確保一致，而無須開發者動工。瀏覽器還能調整輸入表單的字體大小、色彩對比，讓用戶能更輕鬆地完成付款。
* **憑證管理**：用戶能在瀏覽器，管理信用卡與送達地址的資訊。瀏覽器還能跨設備同步這些「憑證」，以便用戶在電腦與手機周旋間，依舊能輕易付款。
* **一致的錯誤處理**：瀏覽器會檢查信用卡號碼、並告訴用戶該卡片（將）過期與否；瀏覽器也可以藉由商家的使用模式或限制（例如「只接受 Visa 卡或萬事達卡（Mastercard）」）自動提示用戶、或允許其選擇偏好的信用卡。

要請求支付的話，建立 `PaymentRequest` 物件的網頁，將回應用戶發動付款的行為，像是點選「購物」按鈕。`PaymentRequest` 將允許網頁在用戶提供完成交易所需資訊時交換之。

你可以在 使用 Payment Request API (en-US) 文章看到完整教學。

**備註：** 此 API 只有在設定 `allowpaymentrequest` (en-US) 屬性下，才可支援跨域 `<iframe>` (en-US) 元素。

介面
--

`PaymentAddress` (en-US)

地址資訊物件，具體用途有付款與送達。

`PaymentRequest`

提供 API 以便建立與管理用戶代理的付款介面物件。

`PaymentRequestEvent` (en-US)

建立 `PaymentRequest` 時發送給付款處理器（payment handler）的事件。

`PaymentRequestUpdateEvent` (en-US)

允許網頁針對用戶行為，發動更新用戶付款資訊的請求。

`PaymentMethodChangeEvent` (en-US)

表示用戶更改付款工具（例如從信用卡轉為簽帳金融卡）。

`PaymentResponse` (en-US)

在用戶選取付款方法、並同意付款請求後，所回傳的物件。

`MerchantValidationEvent` (en-US)

表示商家（網站）要求使用特定支付方法的瀏覽器驗證處理器（例如：要不要放行 Apple Pay）

字詞（dictionary）
--------------

`AddressErrors`

此字詞包含任何與 `PaymentAddress` (en-US) entry 錯誤相關的描述性解釋字串。

`PayerErrors`

此字詞包含任何與 `PaymentResponse` (en-US) 的 email、電話、名字屬性（name attribute）錯誤相關之描述性解釋字串。

`PaymentDetailsUpdate` (en-US)

此物件描述伺服器在用戶開始互動前、實例化支付界面後，針對行為需要修改的付款資訊。

### Related dictionaries for the Basic Card specification

`BasicCardChangeDetails`

An object providing *redacted* address information that is provided as the `methodDetails` (en-US) on the `paymentmethodchange` event sent to the `PaymentRequest` when the user changes payment information.

`BasicCardErrors`

An object providing any error messages associated with the fields in the `BasicCardResponse` object that are not valid. This is used as the value of the `paymentMethod` property on the `PaymentValidationErrors` (en-US) object sent to the `PaymentRequest` when an error occurs.

`BasicCardRequest`

Defines an object structure for containing payment request details such as card type.

`BasicCardResponse`

Defines an object structure for payment response details such as the number/expiry date of the card used to make the payment, and the billing address.

規範
--

| Specification |
| --- |
| Payment Request API 1.1 # paymentrequest-interface |

瀏覽器相容性
------

### PaymentRequest 介面

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* 使用 Payment Request API (en-US)
* Payment 處理概念 (en-US)
* Introducing the Payment Request API for Apple Pay
* Google Pay API PaymentRequest Tutorial
* W3C Payment Request API FAQ


CustomEvent - Web APIs

CustomEvent
===========

**`CustomEvent`** interface 是應用程式為了任意目的所初始化的事件。

**備註：** 此功能可在 Web Worker (en-US) 中使用

Event

CustomEvent建構式
---

`CustomEvent()`

建立一個 `CustomEvent`。

屬性
--

*此介面繼承了其父介面 `Event` 的屬性。*

`CustomEvent.initCustomEvent()` (en-US)
已棄用

初始化一個`CustomEvent`物件。若該事件已經被觸發，則不會進行任何動作。

規格
--

| Specification |
| --- |
| DOM Standard # interface-customevent |

瀏覽器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `Window.postMessage()` (en-US)
* Creating and triggering events


Event - Web APIs

Event
=====

**`Event`** 介面表示了一個在 DOM 物件上所發生的事件。

一個事件可以是由使用者的操作行為所產生（如：點擊滑鼠按鈕或敲打鍵盤），或是來自 API 因處理非同步任務所產生。事件也可以為程式所觸發，例如呼叫元素的 `HTMLElement.click()` 方法，或是自行定義事件並使用 `EventTarget.dispatchEvent()` 發送至特定的目標。

事件有多種不同的類型，部分事件是使用基於 `Event` 的子介面。`Event` 本身包含了所有事件共同的屬性及方法。

許多 DOM 元素可被設定接受（accept，或稱為 listen "監聽"）這些事件，並在發生時執行處理（process、handle）事件的程式碼。事件處理器（Event-handlers）通常會使用 `EventTarget.addEventListener()` 來被連結（connected，或稱為 attached "附加"）至各個 HTML 元素 (en-US)（例如 <button>、<div>、<div>、<span> 等），且此方式一般也是用來取代舊的 HTML 事件處理器屬性（attributes） (en-US)。此外，在需要時也可以使用 `removeEventListener()` (en-US) 來中斷事件處理器與元素的連結。請留意一個元素可以擁有多個事件處理器（即使是處理同一種事件的不同處理器），特別是那些被切分開來彼此獨立且有不同目標的程式模組（舉例來說，廣告及統計模組可以同時監控網頁中的影片觀看資訊）。

When there are many nested elements, each with its own handler(s), event processing can become very complicated — especially where a parent element receives the very same event as its child elements because "spatially" they overlap so the event technically occurs in both, and the processing order of such events depends on the Event bubbling and capture (en-US) settings of each handler triggered.

基於 `Event` 的子介面
---------------

Below is a list of interfaces which are based on the main `Event` interface, with links to their respective documentation in the MDN API reference. Note that all event interfaces have names which end in "Event".

* `AnimationEvent`
* `AudioProcessingEvent` (en-US)
* `BeforeInputEvent`
* `BeforeUnloadEvent` (en-US)
* `BlobEvent` (en-US)
* `ClipboardEvent`
* `CloseEvent`
* `CompositionEvent` (en-US)
* `CSSFontFaceLoadEvent`
* `CustomEvent`
* `DeviceLightEvent`
* `DeviceMotionEvent` (en-US)
* `DeviceOrientationEvent` (en-US)
* `DOMTransactionEvent`
* `DragEvent`
* `EditingBeforeInputEvent`
* `ErrorEvent`
* `FetchEvent` (en-US)
* `FocusEvent` (en-US)
* `GamepadEvent` (en-US)
* `HashChangeEvent` (en-US)
* `IDBVersionChangeEvent` (en-US)
* `InputEvent` (en-US)
* `KeyboardEvent`
* `MediaStreamEvent` (en-US)
* `MessageEvent`
* `MouseEvent` (en-US)
* `MutationEvent` (en-US)
* `OfflineAudioCompletionEvent` (en-US)
* `OverconstrainedError` (en-US)
* `PageTransitionEvent` (en-US)
* `PaymentRequestUpdateEvent` (en-US)
* `PointerEvent` (en-US)
* `PopStateEvent` (en-US)
* `ProgressEvent` (en-US)
* `RelatedEvent`
* `RTCDataChannelEvent` (en-US)
* `RTCIdentityErrorEvent`
* `RTCIdentityEvent`
* `RTCPeerConnectionIceEvent` (en-US)
* `SensorEvent`
* `StorageEvent` (en-US)
* `SVGEvent` (en-US)
* `SVGZoomEvent`
* `TimeEvent` (en-US)
* `TouchEvent` (en-US)
* `TrackEvent` (en-US)
* `TransitionEvent` (en-US)
* `UIEvent`
* `WebGLContextEvent` (en-US)
* `WheelEvent`
建構式
---

`Event()`

建立一個 `Event` 物件。

屬性
--

`Event.bubbles` Read only

布林值，表示事件是否會向上冒泡傳遞。

`Event.cancelBubble` (en-US)

由於歷史性因素，此屬性的效果等同於 `stopPropagation()` 方法。若在事件處理器回傳前設定此值為 `true`，可阻止事件繼續向上冒泡傳遞。

`Event.cancelable` (en-US) Read only

布林值，表示事件是否能被取消。

`Event.composed` (en-US) Read only

A Boolean value indicating whether or not the event can bubble across the boundary between the shadow DOM and the regular DOM.

`Event.currentTarget` Read only

指向目前處理事件之監聽器所屬的 DOM 物件。

`Event.deepPath` (en-US)
非標準

An `Array` of DOM `Node` (en-US)s through which the event has bubbled.

`Event.defaultPrevented` Read only

布林值，表示事件的預設行為是否被 `preventDefault()` 方法所取消。

`Event.eventPhase` Read only

表示事件目前的傳遞階段。

`Event.explicitOriginalTarget` (en-US)
非標準
 Read only

事件的明確原定目標（Mozilla 專屬）。

`Event.originalTarget` (en-US)
非標準
 Read only

事件重新導向前的原定目標（Mozilla 專屬）。

`Event.returnValue` (en-US)

非標準屬性。用以替代 `preventDefault()` 方法與 `defaultPrevented` 屬性（舊版 Internet Explorer 專屬）。

`Event.scoped` (en-US) Read only
已棄用

A `Boolean` indicating whether the given event will bubble across through the shadow root into the standard DOM. This property has been renamed to `composed` (en-US).

`Event.srcElement` (en-US)
非標準

非標準屬性。為 `target` 屬性的別名（舊版 Internet Explorer 專屬）。

`Event.target` Read only

指向最初觸發事件的 DOM 物件。

`Event.timeStamp` Read only

事件發生（事件物件建立）至今的時間。

`Event.type` Read only

事件類型（不區分大小寫）。

`Event.isTrusted` Read only

表示事件物件是否為瀏覽器建立（比如在用戶點擊之後），或由程式碼所建立（使用建立事件的方法，如 `initEvent()` (en-US)）。

### Obsolete properties

`Event.scoped` (en-US) Read only
已棄用

A `Boolean` indicating whether the given event will bubble across through the shadow root into the standard DOM. This property has been renamed to `composed` (en-US).

方法
--

`Event.createEvent()` (en-US)
已棄用

Creates a new event, which must then be initialized by calling its `initEvent()` method.

`Event.composedPath()` (en-US)

Returns the event's path (objects on which listeners will be invoked). This does not include nodes in shadow trees if the shadow root was created with its `ShadowRoot.mode` (en-US) closed.

`Event.initEvent()` (en-US)
已棄用

初始化已經建立的事件。若該事件已經被處理過，這方法就不會執行任何東西。

`Event.preventDefault()`

取消該事件（如果該事件的 `cancelable` (en-US) 屬性為 `true`）。

`Event.stopImmediatePropagation()`

一旦事件物件呼叫此方法，目前元素中尚未執行的已註冊之相同事件類型監聽器將不會被呼叫，而事件也不會繼續捕捉或冒泡傳遞。

`Event.stopPropagation()`

阻止事件物件繼續捕捉或冒泡傳遞。

### 已廢棄方法

`Event.getPreventDefault()`
非標準

非標準方法。回傳 `defaultPrevented` 屬性值。請直接改用 `defaultPrevented` 屬性。

`Event.preventBubble()`
非標準

已棄用

已廢棄方法。阻止事件繼續冒泡傳遞。請改用 `stopPropagation()` 方法。

`Event.preventCapture()`
非標準

已棄用

已廢棄方法。請改用 `stopPropagation()` 方法。

規範
--

| Specification |
| --- |
| DOM Standard # interface-event |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* 可用的事件類型：Event reference
* 各種 Event Targets 的比較 (en-US) (target vs currentTarget vs relatedTarget vs originalTarget)
* 建立和觸發事件
* 給 Firefox 插件開發者：
    + Listening to events in Firefox extensions
    + Listening to events on all tabs


XMLHttpRequest - Web APIs

XMLHttpRequest
==============

藉由 `XMLHttpRequest`（XHR）物件的方式來存取伺服器端的資料，可以讓你直接經由指定的 URL 擷取資料卻不用刷新整個網頁。這樣一來當想要更新網頁中的部分資料時，不再需要藉由刷新整個頁面的方法而中斷使用者的操作。在AJAX應用中 `XMLHttpRequest` 被大量的使用。

雖然 `XMLHttpRequest` 這個物件的命名包含了 XML 與 HTTP 等字眼，但實際上 `XMLHttpRequest` 可用來接收任何類型的資料，不限於 XML 類型而已。

如果在資料交換的時候，需要接收從伺服器端傳來的事件或訊息：可以考慮透過`EventSource` (en-US)介面使用server-sent 事件。對於和伺服器全雙工的資訊交換，WebSockets 可能是較佳的選擇。

建構式
---

`XMLHttpRequest()`

建構式用來初始化一個 `XMLHttpRequest` 物件。必須在其他任何所屬方法被呼叫之前被呼叫。

屬性
--

*此介面也繼承了 `XMLHttpRequestEventTarget` (en-US) 及 `EventTarget` 的屬性。*

`XMLHttpRequest.onreadystatechange` (en-US)

一個事件處理器函式，會於 `readyState` 屬性之狀態改變時被呼叫。

`XMLHttpRequest.readyState` Read only

回傳一個無符號短整數（`unsigned short`）代表請求之狀態。

`XMLHttpRequest.response` (en-US) Read only

回傳的內容可能是 `ArrayBuffer`、`Blob`、`Document` (en-US)、JavaScript 物件或 `DOMString`。完全根據 `XMLHttpRequest.responseType` (en-US) 的值決定回傳的內容為何種型態，資料為回應實體中的內容（response entity body）。

`XMLHttpRequest.responseText` (en-US) Read only

回傳一個 `DOMString`，其內容為請求之回應的文字內容。如請求失敗或尚未發送，則為 `null`。

`XMLHttpRequest.responseType` (en-US)

為一可列舉（enumerated）值，定義回應內容的資料類型（response type）。

`XMLHttpRequest.responseURL` (en-US) Read only

回傳一個回應（response）的序列化 URL，如 URL 為 null 則回傳空字串。

`XMLHttpRequest.responseXML` (en-US) Read only

回傳一個 `Document` (en-US)，其內容為請求之回應內容所解析成的文件物件。如請求失敗或尚未發送，又或是無法解析成 XML、HTML，則為 `null`。Not available in workers.

`XMLHttpRequest.status` Read only

回傳一個無符號短整數（`unsigned short`）表示已發送請求之回應的狀態。

`XMLHttpRequest.statusText` (en-US) Read only

回傳一個 `DOMString` 表示 HTTP 伺服器回應之字串。和 `XMLHTTPRequest.status` 不同的是，`XMLHttpRequest.statusText` 包含了回應的整個文字訊息（如 "`200 OK`"）。

**備註：** The HTTP/2 specification (8.1.2.4 Response Pseudo-Header Fields), HTTP/2 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status line.

`XMLHttpRequest.timeout` (en-US)

為一無符號長整數（`unsigned long`），代表一個請求在逾時而被自動中止前的可等待時間（毫秒）。

`XMLHttpRequestEventTarget.ontimeout`

為一 event handler 物件，會於請求逾時時被呼叫。

`XMLHttpRequest.upload` (en-US) Read only

為一 `XMLHttpRequestUpload` (en-US) 物件，代表上傳的進度。

`XMLHttpRequest.withCredentials`

`布林值` (en-US)。表示是否允許在跨站存取（cross-site `Access-Control`）之請求當中，發送如 cookies 或 authorization headers 等憑證資訊（credentials）。

### 非標準屬性

`XMLHttpRequest.channel` (en-US)Read only

是一個 `nsIChannel`。當執行要求時，物件使用的頻道（Channel）。

`XMLHttpRequest.mozAnon` (en-US)Read only

為一個布林值。如果為真，請求就會以沒有 cookie 及 authentication headers 的方式送出。

`XMLHttpRequest.mozSystem` (en-US)Read only

這是一個布林值。If true, the same origin policy will not be enforced on the request.

`XMLHttpRequest.mozBackgroundRequest` (en-US)

這是一個布林值。指出該物件是否為一個背景型態的服務要求。

`XMLHttpRequest.mozResponseArrayBuffer`
已棄用
 Read only

Is an `ArrayBuffer`. The response to the request, as a JavaScript typed array.

`XMLHttpRequest.multipart`
已棄用

**This Gecko-only feature, a boolean, was removed in Firefox/Gecko 22.** Please use Server-Sent Events, Web Sockets, or `responseText` from progress events instead.

### 事件處理器

所有瀏覽器都支援 `XMLHttpRequest` 物件實體的 `onreadystatechange` 屬性。

之後，各個瀏覽器實作了多種額外的事件處理器（如 `onload`、`onerror`、`onprogress` 等）。請參考使用 XMLHttpRequest。

除了以 `on*` 屬性來設定事件處理函式，更多現代覽瀏器（包括 Firefox）也支援使用標準的 `addEventListener()` API 註冊監聽 `XMLHttpRequest` 的事件。

方法
--

`XMLHttpRequest.abort()` (en-US)

中止已發出的請求。

`XMLHttpRequest.getAllResponseHeaders()` (en-US)

回傳所有的回應標頭（response headers），為一以斷行字元（CRLF (en-US)）分行的字串，如未接收到回應則為 `null`。

`XMLHttpRequest.getResponseHeader()` (en-US)

回傳指定標頭文字之字串，假如回應尚未被接收或是標頭不存在於回應中則為 `null`。

`XMLHttpRequest.open()` (en-US)

初始化一個請求。此方法用於 JavaScript 中；若要在 native code 中初始化請求，請以 `openRequest()` 作為替代。

`XMLHttpRequest.overrideMimeType()` (en-US)

覆寫伺服器回傳的 MIME type。

`XMLHttpRequest.send()` (en-US)

發送請求。如果為非同步請求（預設值），此方法將在發出請求後便立即回傳（return）。

`XMLHttpRequest.setRequestHeader()`

設定 HTTP 請求標頭（request header）值。`setRequestHeader()` 可被呼叫的時間點必須於 `open()` 之後、在 `send()` 之前。

### 非標準方法

`XMLHttpRequest.init()`

使用 C++ 程式時，用來初始化這個物件。

**警告：** 請勿在 JavaScript 中呼叫這個方法。

`XMLHttpRequest.openRequest()`

初始化請求。這方法是用於原生程式，若想在 JavaScript 中初始化一個請求，請使用 `open()` 這個方法來代替。請參照 `open()` 的相關文件。

`XMLHttpRequest.sendAsBinary()`
已棄用

另一種 `send()` 方法，用來送出二進位資料。

規範
--

| Specification |
| --- |
| XMLHttpRequest Standard # interface-xmlhttprequest |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

參見
--

* `XMLSerializer` (en-US)：將 DOM 樹解析為 XML 物件
* 使用 XMLHttpRequest
* Fetch API


Server-sent events - Web APIs

Server-sent events
==================

網頁一般來說是由客戶端向伺服器請求資料. 藉由 server-sent 事件, 伺服器在任何時候都可以向客戶端推送資料. 即將推送進來的訊息可以自客戶端上做 *Events (en-US) + data* 處理.

文件
--

使用 server-sent events (en-US)

有關如何在伺服器端和客戶端使用 server-sent 事件的教學文章.

參考 EventSource (en-US)

關於客戶端的 EventSource API.

工具
--

* Remy Sharp's EventSource polyfill
* Yaffle's EventSource polyfill
* Rick Waldron's jquery plugin
相關主題
----

* AJAX, JavaScript, WebSockets
規範
--

| Specification |
| --- |
| HTML Standard # server-sent-events |

參見
--

* A Twitter like application powered by server-sent events and its code on Github.
* HTML5 and Server-sent events
* Server-sent events using Asp.Net


地理位置定位 (Geolocation) - Web APIs

地理位置定位 (Geolocation)
====================

Web Apps 若需要使用者的位置，可透過 **Geolocation API** 取得相關資訊。而基於隱私權的考量，這些 Web Apps 均必須取得使用者的許可之後，才能發佈位置資訊。

地理位置定位 (Geolocation) 物件
-----------------------

Geolocation API，是透過 `navigator.geolocation` (en-US) `物件`所發佈。

若該物件可用，即可進行地理位置定位服務。因此可先測試地理位置定位是否存在：

```js
if ("geolocation" in navigator) {
  /\* geolocation is available \*/
} else {
  /\* geolocation IS NOT available \*/
}
```

**備註：** 在 Firefox 24 之後的版本，即使停用此 API，`navigator` 中的「`geolocation`」也同樣回傳 `true`。此問題已根據規格而於` Firefox 25 中修正 (bug 884921)。

### 取得目前位置

 若要取得使用者目前的位置，可呼叫 `getCurrentPosition()` 函式。如此將啟動非同步化的請求，以偵測使用者的位置，並將查詢定位硬體而取得最新資訊。一旦決定位置，隨即執行特定的回呼常式 (Callback routine)。若發生錯誤，則可選擇是否提供第二次回呼。第三項參數為選項介面 (亦可選擇是否使用之)，可設定位置回傳的的最長時間，與請求的等待時間。
 若不論定位精確度而想儘快固定單一位置，則可使用 `getCurrentPosition()`。以具備 GPS 的裝置為例，往往需耗時 1 分鐘或更長的時間而固定 GPS 資訊。也因此，`getCurrentPosition()` 可能取得較低精確度的資料 (IP 位置或 WiFi) 而隨即開始作業。

**備註：** 依預設值，`getCurrentPosition()` (en-US) 將儘快回傳較低精確度的結果。若不論精確度而只要儘快獲得答案，則可使用 `getCurrentPosition()` (en-US)。舉例來說，搭載 GPS 的裝置可能需要一段時間才能取得 GPS 定位資訊，所以可能將低精確度的資料 (IP 位置或 Wifi) 回傳至 `getCurrentPosition()` (en-US)。

```js
navigator.geolocation.getCurrentPosition(function (position) {
  do\_something(position.coords.latitude, position.coords.longitude);
});
```

一旦取得定位位置之後，上列範例隨即將執行 `do_something()` 函式。

### 觀看目前位置

如果定位資料改變 (可能是裝置移動，或取得更精確的地理位置資訊)，則可設定 1 組回呼函式，使其隨著更新過的定位資訊而呼叫之。而這個動作可透過 `watchPosition() 函式`完成。`watchPosition()` (en-US) 所具備的輸入參數與 `getCurrentPosition()`相同。回呼函式將呼叫數次，讓瀏覽器可於使用者移動期間更新位置，或可根據目前所使用的不同定位技術，提供更精確的定位資訊。若一直未回傳有效結果，則錯誤回呼 (Error Callback) 函式僅將呼叫 1 次。另請注意，錯誤回呼函式僅限於 `getCurrentPosition()，因此為選填`。

**備註：** 不需啟動 `getCurrentPosition()` (en-US) 呼叫，亦可使用 `watchPosition()` (en-US)。

```js
var watchID = navigator.geolocation.watchPosition(function (position) {
  do\_something(position.coords.latitude, position.coords.longitude);
});
```

`watchPosition()` 函式將回傳 1 組 ID 編號，專用以識別必要的定位監看員 (Watcher)。而此數值若搭配 `clearWatch()` 函式，即可停止觀看使用者的位置。
```

navigator.geolocation.clearWatch(watchID);
```

### 微調回應

`getCurrentPosition()` (en-US) 與 `watchPosition()` (en-US) 均可容納 1 組成功回呼、1 組錯誤回呼 (選填)、1 組 `PositionOptions` 物件 (選填)。

對 `watchPosition` (en-US) 的呼叫應類似如下：

```js
function geo\_success(position) {
  do\_something(position.coords.latitude, position.coords.longitude);
}

function geo\_error() {
  alert("Sorry, no position available.");
}

var geo_options = {
  enableHighAccuracy: true,
  maximumAge: 30000,
  timeout: 27000,
};

var wpid = navigator.geolocation.watchPosition(
  geo_success,
  geo_error,
  geo_options,
);
```

現成的 watchPosition Demo：http://www.thedotproduct.org/experiments/geo/

敘述位置
----

以 `Position` 物件參照 `Coordinates` 物件，即可敘述使用者的位置。

處理錯誤
----

在呼叫 `getCurrentPosition()` 或 `watchPosition() 時，`若獲得錯誤回呼函式，則`錯誤回呼函式的第一組參數將為 PositionError 物件：`

```js
function errorCallback(error) {
  alert("ERROR(" + error.code + "): " + error.message);
}
```

地理位置定位實際範例
----------

### HTML 內容

```html
<p><button onclick="geoFindMe()">Show my location</button></p>
<div id="out"></div>
```

### JavaScript 內容

```js
function geoFindMe() {
  var output = document.getElementById("out");

  if (!navigator.geolocation) {
    output.innerHTML = "<p>Geolocation is not supported by your browser</p>";
    return;
  }

  function success(position) {
    var latitude = position.coords.latitude;
    var longitude = position.coords.longitude;

    output.innerHTML =
      "<p>Latitude is " +
      latitude +
      "° <br>Longitude is " +
      longitude +
      "°</p>";

    var img = new Image();
    img.src =
      "http://maps.googleapis.com/maps/api/staticmap?center=" +
      latitude +
      "," +
      longitude +
      "&zoom=13&size=300x300&sensor=false";

    output.appendChild(img);
  }

  function error() {
    output.innerHTML = "Unable to retrieve your location";
  }

  output.innerHTML = "<p>Locating…</p>";

  navigator.geolocation.getCurrentPosition(success, error);
}
```

### 現場測試結果

若無法顯示，可至本文右上角「Language」切換回英文原文觀看。

請求權限
----

addons.mozilla.org 上所提供的任何附加元件，只要使用地理位置定位資料，均必須明確取得許可才能繼續作業。下列函式詢問許可的方法，則類似網頁詢問許可的自動提示方法，但更為簡單。若為可套用的狀態，則使用者的回應將儲存於 `pref` 參數所指定的偏好中。於 `callback` 參數中所提供的函式，將透過 1 組代表使用者反應的布林值而呼叫之。若使用者的回應為 `true`，則附加元件才會存取地理位置定位資料。

```js
function prompt(window, pref, message, callback) {
  let branch = Components.classes[
    "@mozilla.org/preferences-service;1"
  ].getService(Components.interfaces.nsIPrefBranch);

  if (branch.getPrefType(pref) === branch.PREF\_STRING) {
    switch (branch.getCharPref(pref)) {
      case "always":
        return callback(true);
      case "never":
        return callback(false);
    }
  }

  let done = false;

  function remember(value, result) {
    return function () {
      done = true;
      branch.setCharPref(pref, value);
      callback(result);
    };
  }

  let self = window.PopupNotifications.show(
    window.gBrowser.selectedBrowser,
    "geolocation",
    message,
    "geo-notification-icon",
    {
      label: "Share Location",
      accessKey: "S",
      callback: function (notification) {
        done = true;
        callback(true);
      },
    },
    [
      {
        label: "Always Share",
        accessKey: "A",
        callback: remember("always", true),
      },
      {
        label: "Never Share",
        accessKey: "N",
        callback: remember("never", false),
      },
    ],
    {
      eventCallback: function (event) {
        if (event === "dismissed") {
          if (!done) callback(false);
          done = true;
          window.PopupNotifications.remove(self);
        }
      },
      persistWhileVisible: true,
    },
  );
}

prompt(
  window,
  "extensions.foo-addon.allowGeolocation",
  "Foo Add-on wants to know your location.",
  function callback(allowed) {
    alert(allowed);
  },
);
```

規範
--

| Specification |
| --- |
| Geolocation API # geolocation\_interface |

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Gecko 註記
--------

Firefox 可透過 Google 的定位服務 (Google Location Services，GLS)，根據使用者的 WiFi 資訊而找出使用者的位置。與 Google 之間所交換的資料，包含 WiFi 存取點 (Access Point) 資料、Access token (類似 2 個禮拜的 cookie)、使用者的 IP 位址。若需更多資訊，可參閱 Mozilla 的隱私權政策與 Google 的隱私權政策。其內將詳述資料的使用方式。

Firefox 3.6 (Gecko 1.9.2) 新支援了 GPSD (GPS daemon) 服務，適合 Linux 的地理位置定位。

另請參閱
----

* `navigator.geolocation` (en-US)
* w3.org 的 Geolocation API
* Geolocation API 相關 Demos


MediaQueryList - Web APIs

MediaQueryList
==============

**實驗性質:** **這是一個實驗中的功能 (en-US)**
此功能在某些瀏覽器尚在開發中，請參考兼容表格以得到不同瀏覽器用的前輟。

`MediaQueryList` 物件維護一組針對 `document` (en-US) 的 media querie (en-US) , 並且當 media querie 相對應的文件狀態改變時，觸發註冊的事件處理器通知之。

MediaQueryList 物件讓我們不用一直定期去偵測，而是直接去觀察文件的狀態變化。

Method overview
---------------

| `void addListener(MediaQueryListListener listener);` |
| --- |
| `void removeListener(MediaQueryListListener listener);` |

Properties
----------

| Property | Type | Description |
| --- | --- | --- |
| `matches` | `boolean` | `true` 當 `document` (en-US) 目前狀態符合 media query list 所維護的條件; 否則 false。 唯獨\*\*。\*\* |
| `media` | `DOMString` | 序列化 (serialized) 的 media query list. |

Methods
-------

### addListener()

添加一個新的事件處理器 (listener)，若 listener 已存在則無作用。
```

void addListener(
  MediaQueryListListener listener
);
```

#### Parameter (for addListener method)

`listener`

當 media query 對應的狀態改變時所觸發的事件處理函數 (`MediaQueryListListener` (en-US))。

### removeListener()

移除一個事件處理器 (listener)，若 listener 不存在則無作用。
```

void removeListener(
  MediaQueryListListener listener
);
```

#### Parameter (for removeListener method)

`listener`

欲移除的事件處理函數 (`MediaQueryListListener` (en-US))。

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

規範標準
----

* The CSSOM View Module: The MediaQueryList Interface
延伸閱讀
----

* Media queries (en-US)
* Using media queries from code (en-US)
* `window.matchMedia()` (en-US)
* `MediaQueryListListener` (en-US)