recursal/MDN huggingface dataset:
URL.createObjectURL()
=====================

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

摘要
--

靜態方法 **`URL.createObjectURL()`** 用於建立一個帶有 URL 的 `DOMString` 以代表參數中所傳入的物件. 該 URL 的生命週期與創造它的 window 中的 `document` (en-US)一致. 這個新的物件 URL 代表了所指定的 `File` 物件 或是 `Blob` 物件。

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

語法
--
```

objectURL = URL.createObjectURL(blob);
```

參數
--

*blob*

一個用以建立物件 URL 的 `File` 物件 或是 `Blob` 物件.

範例
--

參見 Using object URLs to display images.(藉由物件 URL 來顯示圖像)

注意事項
----

每次呼叫 `createObjectURL()` 都會產生一個新的 URL, 不論是否曾以同一物件產生過. 當你不再需要它們的時候必須對每一個都呼叫 `URL.revokeObjectURL()` (en-US) 來釋放它們. 瀏覽器會在 document 被 unload 時自動釋放它們; 然而, 為了最佳化效能與記憶體用量, 當有安全的時機請務必手動釋放它們.

規範文件
----

| Specification |
| --- |
| File API # dfn-createObjectURL |

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

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

另見
--

* `URL.revokeObjectURL()` (en-US)
* Using files from web applications
KeyboardEvent()
===============

**`KeyboardEvent()`** constructor 能用來建立一個新的 `KeyboardEvent`。

語法
--
```

 event = new KeyboardEvent(typeArg, KeyboardEventInit);
```

### 參數

`type`

一 `DOMString` 用來表示事件名稱。

`options` 選擇性

一個 `KeyboardEventInit` dictionary，能接受以下參數：

`key` 選擇性

一個字符串，默認值為 `""`，用來設定 `KeyboardEvent.key` (en-US) 的值。

`code` 選擇性

一個字符串，默認值為 `""`，用來設定 `KeyboardEvent.code` (en-US) 的值。

`location` 選擇性

一個 `unsigned long`，默認值為 `0`，用來設定 `KeyboardEvent.location` (en-US) 的值。

`ctrlKey` 選擇性

一個 `Boolean`，默認值為 `false`，用來設定 `KeyboardEvent.ctrlKey` (en-US) 的值。

`shiftKey` 選擇性

一個 `Boolean`，默認值為 `false`，用來設定 `KeyboardEvent.shiftKey` (en-US) 的值。

`altKey` 選擇性

一個 `Boolean`，默認值為 `false`，用來設定 `KeyboardEvent.altKey` (en-US) 的值。

`metaKey` 選擇性

一個 `Boolean`，默認值為 `false`，用來設定 `KeyboardEvent.metaKey` (en-US) 的值。

`repeat` 選擇性

一個 `Boolean`，默認值為 `false`，用來設定 `KeyboardEvent.repeat` (en-US) 的值。

`isComposing` 選擇性

一個 `Boolean`，默認值為 `false`，用來設定 `KeyboardEvent.isComposing` (en-US) 的值。

`charCode` 選擇性

一個 `unsigned long`，默認值為 `0`，用來設定 `KeyboardEvent.charCode` (en-US) 的值。

`keyCode` 選擇性

一個 `unsigned long`，默認值為 `0`，用來設定 `KeyboardEvent.keyCode` (en-US) 的值。

`which` 選擇性

一個 `unsigned long`，默認值為 `0`，用來設定 `KeyboardEvent.which` (en-US) 的值


**備註：** *`KeyboardEventInit` dictionary 亦接受 `UIEventInit` 和`EventInit` 所接受的參數。*

規格
--

| Specification |
| --- |
| UI Events # dom-keyboardevent-keyboardevent |

瀏覽器支援度
------

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

延伸閱讀
----

* `KeyboardEvent` ，此 constructer 所建立的 object 的 interface
FormData.get()
==============

`FormData` 的 **`get()`** 方法會返回 `FormData 物件中，指定` key` 值所對應之第一組物件中的 value 值。然而，如果你想要獲得多組以及全部的 value，那應該使用 `getAll()` (en-US) 方法。

**注意**: 這個方法已可以在 Web Worker (en-US) 中使用。

語法
--


```js
formData.get(name);
```

### 參數

`name`

一個 `USVString` (en-US)，代表你想要得到的 value 所對應的 key 值名稱。

### 回傳值

A `FormDataEntryValue` (en-US) containing the value.

範例
--

下面一行程式會產生一個空的 `FormData` 物件：


```js
var formData = new FormData();
```


用 `FormData.append` (en-US) 方法新增兩組 `username` 值


```js
formData.append("username", "Chris");
formData.append("username", "Bob");
```


接下來使用 `get()` 方法，將只會返回上一步驟，第一組新增的 `username` 所對應的值


```js
formData.get("username"); // 返回 "Chris"
```

規範
--

| Specification |
| --- |
| XMLHttpRequest Standard # dom-formdata-get |

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

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

參見
--

* `XMLHTTPRequest`
* 使用 XMLHttpRequest
* 使用 FormData 物件
* `<form>` (en-US)
MediaSource.readyState
======================

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

`MediaSource` 介面的唯讀屬性 **`readyState`** 回傳表示當前 `MediaSource` 狀態的列舉值。三種可能的值為：

* `closed`: 來源 (source) 目前沒有附加到媒體元件 (media element) 。
* `open`: 來源已經附加且可以接收 `SourceBuffer` (en-US) 物件。
* `ended`: 來源已經附加但是串流已經經由 `MediaSource.endOfStream()` (en-US) 結束。
語法
--


```js
var myReadyState = mediaSource.readyState;
```

### 回傳值

一個 `DOMString`。

範例
--

以下片段是由 Nick Desaulniers 所撰寫的簡單範例（在此實際觀看，或者下載原始碼以更進一步研究）


```js
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);
  });
}
```

規格
--

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

相容性表格
-----

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

相關資料
----

* `SourceBuffer` (en-US)
* `SourceBufferList` (en-US)
MediaSource.duration
====================

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

`MediaSource` 介面的 **`duration`** 屬性用來取得以及設置正被表示的媒體時間長度。

語法
--


```js
mediaSource.duration = 5.5; // 5.5 seconds

var myDuration = mediaSource.duration;
```

### 回傳值

單位為秒的 double 型別。

### 錯誤

當設置此屬性一個新的值時以下錯誤可能發生。

| 錯誤 | 解釋 |
| --- | --- |
| `InvalidAccessError` | 嘗試設置的時間長度是負值，或者 `NaN`。 |
| `InvalidStateError` | `MediaSource.readyState` 不是 `open`，或者 `MediaSource.sourceBuffers` (en-US) 中一個或多個以上的 `SourceBuffer` (en-US) 物件正在被更新（例如：他們的 `SourceBuffer.updating` (en-US) 屬性為 `true`。） |

範例
--

以下的片段基於 Nick Desaulniers 所編纂的簡單範例（觀看實際演示，或者下載原始碼以利更進一步研究。）


```js
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();
      mediaSource.duration = 120;
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
};

...
```

規格
--

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

相容性表格
-----

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

相關資料
----

* `SourceBuffer` (en-US)
* `SourceBufferList` (en-US)
MediaSource.activeSourceBuffers
===============================

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

**`activeSourceBuffers`** 是 `MediaSource` 介面的唯讀屬性，回傳一個 `SourceBufferList` (en-US) 物件，含有在 `SourceBuffers` 之中的 `SourceBuffer` (en-US) 物件子集合—物件的串列提供被選擇的影片軌 (video track), 啟用的音軌 (audio tracks), 以及顯示或隱藏的字軌。

語法
--


```js
var myActiveSourceBuffers = mediaSource.activeSourceBuffers;
```

### 回傳值

一個 `SourceBufferList` (en-US) 。

範例
--

以下的片段基於 Nick Desaulniers 所編纂的簡單範例（觀看實際演示，或者下載原始碼 以利更進一步研究。）


```js
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();
      console.log(mediaSource.activeSourceBuffers);
      // will contain the source buffer that was added above,
      // as it is selected for playing in the video player
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
};

...
```

規格
--

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

相容性表格
-----

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

相關資料
----

* `SourceBuffer` (en-US)
* `SourceBufferList` (en-US)
MediaSource.MediaSource()
=========================

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

`MediaSource` 介面的 **`MediaSource()`** 建構子建構且回傳一個沒有與任何來源緩衝 (source buffer) 關聯的新 `MediaSource` 物件。

語法
--


```js
var mediaSource = new MediaSource();
```

### 參數

無。

範例
--

以下的片段擷取自 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);
}

...
```

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

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

相關資料
----

* `SourceBuffer` (en-US)
* `SourceBufferList` (en-US)
Screen.orientation
==================

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

`Screen.orientation` 屬性可以取得螢幕目前的方向。

語法
--
```

var orientation = window.screen.orientation.type;
```

回傳值
---

回傳值為一個代表螢幕方向的字串，可能是 `portrait-primary`、`portrait-secondary`、`landscape-primary` 或 `landscape-secondary`（請參考 `lockOrientation` 以瞭解更多資訊）。

範例
--


```js
var orientation =
  screen.orientation || screen.mozOrientation || screen.msOrientation;

if (orientation.type === "landscape-primary") {
  console.log("That looks good.");
} else if (orientation.type === "landscape-secondary") {
  console.log("Mmmh... the screen is upside down!");
} else if (
  orientation.type === "portrait-secondary" ||
  orientation.type === "portrait-primary"
) {
  console.log("Mmmh... you should rotate your device to landscape");
}
```

規範
--

| Specification |
| --- |
| Screen Orientation # dom-screen-orientation |

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

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

參見
--

* `Screen.orientation`
* `Screen.unlockOrientation()` (en-US)
* `Screen.onorientationchange` (en-US)
* 控制畫面方向
PositionError.code
==================

**`PositionError.code`** 是一個唯讀無符號整數（`unsigned short`）表示錯誤碼。以下列出可能的值：

| 值 | 相對應的常數 | 描述 |
| --- | --- | --- |
| `1` | `PERMISSION_DENIED` | 取得地理資訊失敗，因為此頁面沒有獲取地理位置信息的權限。 |
| `2` | `POSITION_UNAVAILABLE` | 取得地理資訊失敗，因為至少有一個地理位置信息內的資訊回傳了錯誤。 |
| `3` | `TIMEOUT` | 取得地理資訊超過時限，利用 `PositionOptions.timeout` i 來定義取得地理資訊的時限。 |

語法
--
```

typeErr = poserr.code
```

規格
--

| Specification |
| --- |
| Geolocation API # code-attribute |

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

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

請參考
---

* Using geolocation (en-US)
* 屬於 `PositionError` 。
PositionError.message
=====================

**`PositionError.message`** 是一個可讀的 `DOMString` 來描述錯誤的詳細訊息。

語法
--
```

msg = positionError.message
```

規格
--

| Specification |
| --- |
| Geolocation API # message-attribute |

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

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

請參考
---

* Using geolocation (en-US)
* 屬於 `PositionError`。
DragEvent.dataTransfer
======================

**`DataEvent.dataTransfer`** 屬性保留了拖曳操作中的資料（指向一個 `DataTransfer` (en-US) 物件）。

此屬性為 Read only 。

語法
--
```

var data = dragEvent.dataTransfer;
```

### 回傳值

`data`

一個保存 `DragEvent` 當中資料的 `DataTransfer` (en-US) 物件。

範例
--

This example illustrates accessing the drag and drop data within the `dragend` (en-US) event handler.


```js
function process\_data(d) {
  // Process the data ...
}

dragTarget.addEventListener(
  "dragend",
  function (ev) {
    // Call the drag and drop data processor
    if (ev.dataTransfer != null) process\_data(ev.dataTransfer);
  },
  false,
);
```

規範
--

| Specification |
| --- |
| HTML Standard # dom-dragevent-datatransfer-dev |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
Console.assert()
================

如果斷言（assertion）為非（false），主控台會顯示錯誤訊息；如果斷言為是（true），則不發生任何事。

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

**備註：** 在 Node.js 內 `console.assert()` 方法的實做，與瀏覽器並不相同。瀏覽器內呼叫 falsy 的 `console.assert()` 斷言出現 `message`，但不會中斷程式碼的執行。然而在 Node.js 裡面，falsy 斷言會拋出 `AssertionError` 錯誤。

語法
--


```js
assert(assertion, obj1)
assert(assertion, obj1, obj2)
assert(assertion, obj1, obj2, /\* …, \*/ objN)

assert(assertion, msg)
assert(assertion, msg, subst1)
assert(assertion, msg, subst1, /\* …, \*/ substN)
```

### 參數

`assertion`

布林表達式。如果斷言為非，訊息會出現在主控台上。

`obj1` ... `objN`

要印出來的 JavaScript 物件名單。 The string representations of each of these objects are appended together in the order listed and output.

`msg`

包含零個以上的 JavaScript 替代（substitution）字串。

`subst1` ... `substN`

JavaScript objects with which to replace substitution strings within `msg`. This parameter gives you additional control over the format of the output.

請參見 `console` (en-US) 的 Outputting text to the console (en-US) 以獲取詳細資訊。

範例
--

以下程式碼示範一個 JavaScript 物件的斷言使用：


```js
const errorMsg = "the # is not even";
for (let number = 2; number <= 5; number += 1) {
  console.log("the # is " + number);
  console.assert(number % 2 === 0, { number: number, errorMsg: errorMsg });
  // or, using ES2015 object property shorthand:
  // console.assert(number % 2 === 0, {number, errorMsg});
}
// output:
// the # is 2
// the # is 3
// Assertion failed: {number: 3, errorMsg: "the # is not even"}
// the # is 4
// the # is 5
// Assertion failed: {number: 5, errorMsg: "the # is not even"}
```


請注意，雖然包含替換字符串的字符串在 Node 中用作 `console.log` 的參數，但很多（如果不是大多數）瀏覽器...


```js
console.log("the word is %s", "foo");
// output: the word is foo
```


...在所有瀏覽器中，使用此類字符串目前無法作為 console.assert 的參數使用：


```js
console.assert(false, "the word is %s", "foo");
// correct output in Node (e.g. v8.10.0) and some browsers
// (e.g. Firefox v60.0.2):
// Assertion failed: the word is foo
// incorrect output in some browsers
// (e.g. Chrome v67.0.3396.87):
// Assertion failed: the word is %s foo
```


有關詳細信息，請參閱 `console` (en-US) 文檔中的將文本輸出到控制台 (en-US)。

規範
--

| Specification |
| --- |
| Console Standard # assert |

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

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

參見
--

* WHATWG Console Standard: console.assert
* Opera Dragonfly documentation: Console
* MSDN: Using the F12 Tools Console to View Errors and Status
* Chrome Developer Tools: Using the Console
HTMLMediaElement: ratechange
============================

`ratechange` 事件將在播放速度改變時被觸發

基本資訊
----

規格

HTML5 Media

介面

事件

是否冒泡

否

是否可取消

否

目標

元素

預設行為

無

屬性
--

| 屬性 | 類型 | 描述 |
| --- | --- | --- |
| `target` Read only  | `EventTarget` | 事件目標（DOM 樹中最頂層的目標) |
| `type` Read only  | `DOMString` | 事件類型 |
| `bubbles` Read only  | `Boolean` | 事件是否觸發冒泡 |
| `cancelable` Read only  | `Boolean` | 事件是否可取消 |

規範
--

| Specification |
| --- |
| HTML Standard # event-media-ratechange |
| HTML Standard # handler-onratechange |

相關事件
----

* `playing` (en-US)
* `waiting` (en-US)
* `seeking` (en-US)
* `seeked` (en-US)
* `ended` (en-US)
* `loadedmetadata` (en-US)
* `loadeddata` (en-US)
* `canplay` (en-US)
* `canplaythrough` (en-US)
* `durationchange` (en-US)
* `timeupdate` (en-US)
* `play` (en-US)
* `pause` (en-US)
* `ratechange`
* `volumechange` (en-US)
* `suspend` (en-US)
* `emptied` (en-US)
* `stalled` (en-US)
HTMLMediaElement.readyState
===========================

**`HTMLMediaElement.readyState`** 屬性回傳目前媒體的就緒狀態。

語法
--
```

var readyState = audioOrVideo.readyState;
```

### 值

一個 `unsigned short`，可能的值有：

| 常數 | 值 | 描述 |
| --- | --- | --- |
| HAVE\_NOTHING | 0 | 沒有可用的媒體資源。 |
| HAVE\_METADATA | 1 | 已經取得足夠的媒體資源並已初始化元資料。繼續取得媒體資源不會導致例外。 |
| HAVE\_CURRENT\_DATA | 2 | 媒體資料已經足夠播放目前的時間，但沒有足夠的資料再播放一幀。 |
| HAVE\_FUTURE\_DATA | 3 | 資料已經足夠播放目前的時間，而且有至少一點點資料可以播放未來的時間（換句話說，可能只多了一到兩幀）。 |
| HAVE\_ENOUGH\_DATA | 4 | 資料足夠，且下載率夠高。媒體可以播放到結束而不被中斷。 |

範例
--

下面這個例子會監聽 `example` 這個元素，並檢查是否已載入足夠的媒體資源。如果是的話，它會繼續播放。


```html
<audio id="example" preload="auto">
  <source src="sound.ogg" type="audio/ogg" />
</audio>
```



```js
var obj = document.getElementById("example");

obj.addEventListener("loadeddata", function () {
  if (obj.readyState >= 2) {
    obj.play();
  }
});
```

標準
--

| Specification |
| --- |
| HTML Standard # dom-media-readystate-dev |

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

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

也參考看看
-----

* The interface defining it, `HTMLMediaElement` (en-US).
abort
=====

當資源載入被拒絕時將會觸發\*\*`abort`\*\*事件。

一般資訊
----

規範

DOM L3

介面

若由使用者介面產生，為 UIEvent，否則為 Event。

是否向上(冒泡)

否

是否為可取消

否

目標對象

Element

預設行為

無

屬性
--

| 屬性 | 型態 | 描述 |
| --- | --- | --- |
| `target` Read only  | `EventTarget` | 事件的目標對象 (DOM 樹中最頂層的對象)。 |
| `type` Read only  | `DOMString` | 事件的型態。 |
| `bubbles` Read only  | `Boolean` (en-US) | 事件是否向上冒泡。 |
| `cancelable` Read only  | `Boolean` (en-US) | 事件是否能夠取消。 |
| `view` Read only  | `WindowProxy` | `document.defaultView` (該文檔(Document)的`window`) |
| `detail` Read only  | `long` (`float`) | 0. |

規範
--

| Specification |
| --- |
| HTML Standard # event-media-abort |
| HTML Standard # handler-onabort |
Canvas 教學文件
===========

**`<canvas>`** 是一個 HTML 元素，我們可以利用程式腳本在這個元素上繪圖（通常是用 JavaScript）。除了繪圖，我們還可以合成圖片或做一些簡單（或是不那麼簡單）的動畫。右方的影像便是一些運用 <canvas> 的例子，接下來我們將會在教學文件中一一說明。

本教學從基礎知識開始，描述如何利用 <canvas> 進行 2D 繪圖。教學中的範例會讓各位清楚瞭解 <canvas> 該如何運用，另外也會提供程式碼範例，讓大家嘗試製作自己的內容。

`<canvas>` 最早是由 Apple 為 Mac OS X Dashboard 所提出，之後 Safari 和 Google Chrome 也都採用。Gecko 1.8 作基礎的瀏覽器，如 Firefox 1.5 也都提供了支援。`<canvas>` 元素是 WhatWG Web applications 1.0（也就是 HTML5）規範的一部分，目前所有主流的瀏覽器都已支援。

在開始之前
-----

`<canvas>` 並不困難，但你需要了解基本的 HTML 與 JavaScript。部分舊版瀏覽器不支援 `<canvas>`，不過基本上現今所有主流的瀏覽器都有支援。預設的畫布大小是 300px \* 150px（寬 \* 高）。但你也可以透過 HTML 寬、高屬性（attribute）自訂。為了在畫布上作畫，我們使用了一個 JavaScript context 物件來即時繪製圖形。

教學文件
----

* 基本用途
* 繪製圖形
* 套用樣式與顏色
* 繪製文字
* 使用影像
* 變形效果
* 合成效果
* 基礎動畫 (en-US)
* 進階動畫
* 像素控制
* Hit regions and accessibility
* 最佳化 canvas (en-US)
* Finale (en-US)
參見
--

* Canvas topic page
* Adobe Illustrator to Canvas plug-in
* HTML5CanvasTutorials
* 31 days of canvas tutorials
* Drawing Graphics with Canvas (en-US)
* Canvas examples
* HTML5 Tutorial
* Drawing Text Using a Canvas
* Adding Text to Canvas
* Canvas Demos - Games, applications, tools and tutorials
* Canvas Drawing and Animation Application
* interactive canvas tutorial
* Canvas Cheat Sheet with all attributes and methods
* Adobe Illustrator to Canvas plug-in
* HTML5CanvasTutorials
* How to draw N grade Bézier curves with the Canvas API
* 31 days of canvas tutorials
* W3C Standard
致歉各位貢獻者
-------

由於 2013/6/17 那一週的不幸技術錯誤，所有有關本教學的歷史紀錄，包括過去所有貢獻者的紀錄都遺失了，我們深感抱歉，希望各位可以原諒這一次不幸的意外。

* 次頁 »
最佳化canvas
=========

`<canvas>`在網頁 2D 繪圖上被大量運用於遊戲和複雜視覺化效果上。隨著繪圖複雜度越來越高，效能問題也會逐一浮現，所以最後我們在這邊列出一些最佳化畫布的方法，避免一些效能問題:

* 在畫面之外的畫布上先行渲染相似或重複的物件
* 批次性執行繪圖，例如一次畫數個線條而非分開一次一次畫
* 使用整數位座標值，盡量避免小數點值
* 避免不必要的畫布狀態改變
* 只渲染不同處，不要全部重新渲染
* 對於複雜需求可以利用多個畫布分層構成
* 盡量不要用 shadowBlur 屬性
* 使用`window.requestAnimationFrame()`
* 用JSPerf測試效能
* « 前頁 (en-US)
合成效果
====

* « 前頁
* 次頁 »

在前述的範例中，新繪製的圖形總會覆蓋在之前的圖形上，對大多數情況來說這相當正常，不過它也限制了圖形繪製的順序。其實我們可以透過 globalCompositeOperation 屬性來改變這項預設行為。

`globalCompositeOperation`
--------------------------

利用 globalCompositeOperation，我們可以將新圖形繪製在舊圖形之下、遮蓋部分區域、清除畫布部分區域 (不同於 clearRect() 函式只能清除矩形區域)。

`globalCompositeOperation = type`

type 字串可指定為以下 12 種合成設定之一，每一種合成設定均將套用到新繪製的圖形上。

See compositing examples (en-US) for the code of the following examples.

裁剪路徑
----

![](/zh-TW/docs/Web/API/Canvas_API/Tutorial/Compositing/canvas_clipping_path.png)裁剪路徑就像是一般畫布圖形繪圖，但就如同遮罩一樣，會蓋掉不需要的部分，如右圖所示。紅邊星星是我們的裁剪路徑，在路徑區域以外部分都不會出現在畫布上。

和上述 globalCompositeOperation 相比，可以發現 source-in 和 source-atop 這兩種構圖組合所達到的效果，和裁剪路徑類似，而其中最大差異在於裁剪路徑不需加入新圖形，消失的部分也不會出現在畫布上，所以，如果想要限定繪圖區域，裁剪路徑會是更理想的作法。

在繪畫圖形一章中，我們只提到 stroke() 和 fill() 函式，但其實還有第三個函式，那就是 clip() 函式。

`clip()`

轉換目前繪圖路徑為裁剪路徑。

呼叫 clip() 除了會替代 closePath() 來關閉路徑之外，還會轉換目前填滿或勾勒繪圖路徑為裁剪路徑。

`<canvas>` 畫布預設有一個等同於本身大小的裁剪路徑，等同於無裁剪效果。

### `clip` 範例

本範例使用了圓形的裁剪路徑，來限定畫星星時的繪圖區域。


```js
function draw() {
  var ctx = document.getElementById("canvas").getContext("2d");
  ctx.fillRect(0, 0, 150, 150);
  ctx.translate(75, 75);

  // Create a circular clipping path
  ctx.beginPath();
  ctx.arc(0, 0, 60, 0, Math.PI \* 2, true);
  ctx.clip();

  // draw background
  var lingrad = ctx.createLinearGradient(0, -75, 0, 75);
  lingrad.addColorStop(0, "#232256");
  lingrad.addColorStop(1, "#143778");

  ctx.fillStyle = lingrad;
  ctx.fillRect(-75, -75, 150, 150);

  // draw stars
  for (var j = 1; j < 50; j++) {
    ctx.save();
    ctx.fillStyle = "#fff";
    ctx.translate(
      75 - Math.floor(Math.random() \* 150),
      75 - Math.floor(Math.random() \* 150),
    );
    drawStar(ctx, Math.floor(Math.random() \* 4) + 2);
    ctx.restore();
  }
}

function drawStar(ctx, r) {
  ctx.save();
  ctx.beginPath();
  ctx.moveTo(r, 0);
  for (var i = 0; i < 9; i++) {
    ctx.rotate(Math.PI / 5);
    if (i % 2 == 0) {
      ctx.lineTo((r / 0.525731) \* 0.200811, 0);
    } else {
      ctx.lineTo(r, 0);
    }
  }
  ctx.closePath();
  ctx.fill();
  ctx.restore();
}
```


```
<canvas id="canvas" width="150" height="150"></canvas>
```


```
draw();
```


一開始我們先畫了一個黑色矩形作為畫布背景，然後移動畫布原點到中央，接著我們繪製弧線並呼叫 clip()，藉以建立圓形的裁剪路徑。畫布儲存狀態亦可儲存裁剪路徑。若要保留原本的裁剪路徑，則可於繪製新的裁剪路徑之前，先行儲存畫布狀態。

繪製裁剪路徑之後，所產生的所有圖形都只會出現在路徑以內，從後來繪製的漸層背景中可看出此特性。我們用自訂的 drawStar() 函數產生 50 個隨機散佈、大小不一的星星。這些星星同樣只會出現在裁剪路徑的範圍之內。

| Screenshot | Live sample |
| --- | --- |
|  |  |

* « 前頁
* 次頁 » (en-US)
GainNode.gain
=============

`GainNode` 介面的 `gain` 屬性是 a-rate (en-US) `AudioParam` (en-US)，代表增益的數值。

語法
--


```js
var audioCtx = new AudioContext();
var gainNode = audioCtx.createGain();
gainNode.gain.value = 0.5;
```

### 傳回值

一個 `AudioParam` (en-US).

**備註：** 雖然傳回的 `AudioParam` 是唯讀的，但是它所代表的值可以更改。

範例
--

See `BaseAudioContext.createGain()` (en-US) for example code showing how to use an `AudioContext` to create a `GainNode`, which is then used to mute and unmute the audio by changing the gain property value.

規格
--

| Specification |
| --- |
| Web Audio API # dom-gainnode-gain |

瀏覽器相容度
------

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

參見
--

* Using the Web Audio API (en-US)
Position.timestamp
==================

**`Position.timestamp`** 是一個唯讀的 `DOMTimeStamp` (en-US) 物件, 此物件代表建立 `Position` 物件的日期和時間，精確度為毫秒。

語法
--
```

coord = position.timestamp
```

規格
--

| Specification |
| --- |
| Geolocation API # timestamp-attribute |

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

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

請參考
---

* Using geolocation (en-US)
* 屬於 `Position`。
Position.coords
===============

**`Position.coords`** 是一個 `Coordinates` 物件的唯讀屬性，表示地理的特性：回傳的物件中包括位置、地球經緯度、海拔高度和速度，同時也包含著這些值的精準度訊息。

語法
--
```

coord = position.coords
```

規格
--

| Specification |
| --- |
| Geolocation API # coords-attribute |

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

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

請參考
---

* Using geolocation (en-US)
* 屬於 `Position`。