1 files changed, 130 insertions, 0 deletions
diff --git a/files/zh-tw/webapi/webfm_api/index.html b/files/zh-tw/webapi/webfm_api/index.html
new file mode 100644
index 0000000000..76a85372f1
--- /dev/null
+++ b/files/zh-tw/webapi/webfm_api/index.html
@@ -0,0 +1,130 @@
+---
+title: WebFM API
+slug: WebAPI/WebFM_API
+translation_of: Archive/B2G_OS/API/WebFM_API
+---
+<p>{{ non-standard_header() }}</p>
+<p>{{ B2GOnlyHeader2('installed') }}</p>
+<h2 id="摘要">摘要</h2>
+<p>WebFM API 可存取裝置的 FM 收音機，進而開/關收音機並切換電台。另可透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator.mozFMRadio" title="/en-US/docs/Web/API/window.navigator.mozFMRadio"><code>navigator.mozFMRadio</code></a> 屬性 (為 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio" title="/en-US/docs/Web/API/FMRadio"><code>FMRadio</code></a> 物件) 而存取此 API。</p>
+<h2 id="開關收音機">開/關收音機</h2>
+<p><a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.enable" title="/en-US/docs/Web/API/FMRadio.enable"><code>FMRadio.enable()</code></a> 函式可開啟收音機；<a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.disable" title="/en-US/docs/Web/API/FMRadio.disable"><code>FMRadio.disable()</code></a> 函式則是關閉收音機。</p>
+<p>在開啟收音機之前，應先檢查裝置是否具備天線 (若無天線，內建的收音機當然也收不到訊號)。透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.antennaAvailable" title="/en-US/docs/Web/API/FMRadio.antennaAvailable"><code>FMRadio.antennaAvailable</code></a> 屬性即可獲得天線資訊。行動裝置往往將耳機纜線作為收音機天線。由於使用者可隨時插入/拔除耳機，因此每次只要天線狀態改變，WebFM API 均將發出 <code><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/antennaavailablechange" title="/en-US/docs/Web/Reference/Events/antennaavailablechange">antennaavailablechange</a></code> 事件。</p>
+<p>開啟收音機就必須要有可聆聽的頻道。而頻率 (以 MHz 為單位) 將以數字形式傳送至 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.enable" title="/en-US/docs/Web/API/FMRadio.enable"><code>FMRadio.enable()</code></a> 函式。</p>
+<pre class="brush: js">// The frequency of the radio station
+// to listen express in MHz
+var frequency = 99.1;
+var radio = navigator.mozFMRadio;
+
+if (radio.antennaAvailable) {
+  radio.enable(frenquency);
+} else {
+  alert("You need to plug your headphone");
+}
+
+radio.addEventListener('antennaavailablechange', function () {
+  if (radio.antennaAvailable) {
+    radio.enable(frenquency);
+  } else {
+    radio.disable();
+  }
+})
+</pre>
+<div class="note">
+  <p><strong>注意：</strong>透過裝置上的可用 <code>normal</code> 音訊通道，即可輸出音訊。</p>
+</div>
+<h2 id="切換不同頻率">切換不同頻率</h2>
+<p>使用者可手動或讓裝置自動切換頻率。不論是手動或自動，均將透過 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.frequency" title="/en-US/docs/Web/API/FMRadio.frequency"><code>FMRadio.frequency</code></a> 屬性存取目前的收音機頻率。該屬性則以 <a href="http://en.wikipedia.org/wiki/Hertz" title="http://en.wikipedia.org/wiki/Hertz">MHz</a> 呈現頻率。</p>
+<h3 id="手動切換">手動切換</h3>
+<p>必須以 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.setFrequency" title="/en-US/docs/Web/API/FMRadio.setFrequency"><code>FMRadio.setFrequency()</code></a> 函式設定新的頻率，但所能設定的值有某些限制。此函式將回傳 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest" title="/en-US/docs/Web/API/DOMRequest"><code>DOMRequest</code></a> 物件，以處理函式呼叫的成功或錯誤狀態。而頻率必須滿足下列要求：</p>
+<ul>
+  <li>頻率必須落在 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.frequencyLowerBound" title="/en-US/docs/Web/API/FMRadio.frequencyLowerBound"><code>FMRadio.frequencyLowerBound</code></a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.frequencyUpperBound" title="/en-US/docs/Web/API/FMRadio.frequencyUpperBound"><code>FMRadio.frequencyUpperBound</code></a> 所定義的範圍中。若頻率在此範圍之外，就會產生錯誤。</li>
+  <li>頻率必須根據 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.channelWidth" title="/en-US/docs/Web/API/FMRadio.channelWidth"><code>FMRadio.channelWidth</code></a> 的值而變化，否則亦將四捨五入。舉例來說，若 100 Mz 為有效頻率，且 channelWidth 為 0.2 時，則 100.2 與 99.8 將成為有效頻率。但若是 100.15 將四捨五入為 100.2。</li>
+</ul>
+<pre class="brush: js">var change = radio.setFrequency(frequency);
+
+change.onerror = function () {
+  var min = radio.frequencyLowerBound;
+  var max = radio.frequencyUpperBound;
+  console.warn('The frequency must be within the range [' + min + ',' + max + ']');
+}
+
+change.onsuccess = function () {
+  console.log('The frequency has been set to ' + radio.frequency);
+}
+</pre>
+<h3 id="自動搜尋">自動搜尋</h3>
+<p>WebFM API 亦可自動搜尋收音機頻道。我們使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.seekUp" title="/en-US/docs/Web/API/FMRadio.seekUp"><code>FMRadio.seekUp()</code></a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.seekDown" title="/en-US/docs/Web/API/FMRadio.seekDown"><code>FMRadio.seekDown()</code></a> 函式。前者將從目前頻道再尋找更高的頻率；後者反之。此 2 組函式均將回傳 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest" title="/en-US/docs/Web/API/DOMRequest"><code>DOMRequest</code></a> 物件，以處理函式呼叫的成功或錯誤狀態。</p>
+<p>WebFM API 亦可自動搜尋收音機頻道。我們使用 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.seekUp" title="/en-US/docs/Web/API/FMRadio.seekUp"><code>FMRadio.seekUp()</code></a> 與 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.seekDown" title="/en-US/docs/Web/API/FMRadio.seekDown"><code>FMRadio.seekDown()</code></a> 函式。前者將從目前頻道再尋找更高的頻率；後者反之。此 2 組函式均將回傳 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest" title="/en-US/docs/Web/API/DOMRequest"><code>DOMRequest</code></a> 物件，以處理函式呼叫的成功或錯誤狀態。</p>
+<p>且此 2 組函式在到達 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.frequencyLowerBound" title="/en-US/docs/Web/API/FMRadio.frequencyLowerBound"><code>frequencyLowerBound</code></a> 或 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.frequencyUpperBound" title="/en-US/docs/Web/API/FMRadio.frequencyUpperBound"><code>frequencyUpperBound</code></a> 的值之後，均將再次循環較高/較低頻率。一旦找到新頻道，就會更改目前頻率並發出 <code><a href="https://developer.mozilla.org/en-US/docs/Web/Reference/Events/frequencychange" title="/en-US/docs/Web/Reference/Events/frequencychange">frequencychange</a></code> 事件。</p>
+<p>此 2 組函式並無法同時搜尋，也就是無法同時往上並往下搜尋頻率，否則將發生錯誤。而呼叫 <a href="https://developer.mozilla.org/en-US/docs/Web/API/FMRadio.cancelSeek" title="/en-US/docs/Web/API/FMRadio.cancelSeek"><code>FMRadio.cancelSeek()</code></a> 函式即可停止搜尋頻率。此函式亦將回傳 <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest" title="/en-US/docs/Web/API/DOMRequest"><code>DOMRequest</code></a> 物件。</p>
+<pre class="brush: js">var radio   = navigator.mozFMRadio;
+var seeking = false;
+var UP      = document.querySelector("button.up");
+var DOWN    = document.querySelector("button.down");
+
+// When the frequency change, the seek
+// functions automatically stop to seek.
+radio.onfrequencychange = function () {
+  seeking = false;
+}
+
+function seek(direction) {
+  var cancel, search;
+
+  // If the radio is already seeking
+  // we will cancel the current search.
+  if (seeking) {
+    var cancel = radio.cancelSeek();
+    cancel.onsuccess = function () {
+      seeking = false;
+
+      // Once the radio no longer seek,
+      // we can try to seek as expected
+      seek(direction);
+    }
+
+  // Let's seek up
+  } else if (direction === 'up') {
+    // Just to be sure that the radio is turned on
+    if (!radio.enabled) {
+      radio.enable(radio.frequencyLowerBound);
+    }
+    search = radio.seekUp();
+
+  // Let's seek up
+  } else if (direction === 'down' {
+    // Just to be sure that the radio is turned on
+    if (!radio.enabled) {
+      radio.enable(radio.frequencyUpperBound);
+    }
+    search = radio.seekDown();
+  }
+
+  if (search) {
+    search.onsuccess = function () {
+      // Ok, we are seeking now.
+      seeking = true;
+    };
+    search.onerror = function () {
+      // Something goes wrong... ok, let's try again.
+      seek(direction);
+    }
+  }
+}
+
+UP.addEventListener('click', function () {
+  seek('up');
+});
+
+DOWN.addEventListener('click', function () {
+  seek('down');
+});
+</pre>
+<h2 id="規格">規格</h2>
+<p>尚無任何規格。</p>
+<h2 id="另可參閱">另可參閱</h2>
+<ul>
+  <li>{{domxref("FMRadio")}}</li>
+  <li><a href="https://github.com/mozilla-b2g/gaia/tree/master/apps/fm" title="https://github.com/mozilla-b2g/gaia/tree/master/apps/fm">Gaïa 上的 FM App</a></li>
+</ul>