From a065e04d529da1d847b5062a12c46d916408bf32 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 21:46:22 -0500 Subject: update based on https://github.com/mdn/yari/issues/2028 --- files/zh-tw/webapi/alarm/index.html | 196 ------------ files/zh-tw/webapi/camera/index.html | 20 -- files/zh-tw/webapi/contacts/index.html | 197 ------------ files/zh-tw/webapi/device_storage/index.html | 228 -------------- files/zh-tw/webapi/idle/index.html | 61 ---- files/zh-tw/webapi/network_stats/index.html | 86 ----- files/zh-tw/webapi/power_management/index.html | 102 ------ files/zh-tw/webapi/settings/index.html | 69 ---- files/zh-tw/webapi/simple_push/index.html | 115 ------- files/zh-tw/webapi/tcp_socket/index.html | 69 ---- files/zh-tw/webapi/time_and_clock/index.html | 30 -- files/zh-tw/webapi/web_activities/index.html | 415 ------------------------- files/zh-tw/webapi/webfm_api/index.html | 130 -------- files/zh-tw/webapi/websms/index.html | 130 -------- 14 files changed, 1848 deletions(-) delete mode 100644 files/zh-tw/webapi/alarm/index.html delete mode 100644 files/zh-tw/webapi/camera/index.html delete mode 100644 files/zh-tw/webapi/contacts/index.html delete mode 100644 files/zh-tw/webapi/device_storage/index.html delete mode 100644 files/zh-tw/webapi/idle/index.html delete mode 100644 files/zh-tw/webapi/network_stats/index.html delete mode 100644 files/zh-tw/webapi/power_management/index.html delete mode 100644 files/zh-tw/webapi/settings/index.html delete mode 100644 files/zh-tw/webapi/simple_push/index.html delete mode 100644 files/zh-tw/webapi/tcp_socket/index.html delete mode 100644 files/zh-tw/webapi/time_and_clock/index.html delete mode 100644 files/zh-tw/webapi/web_activities/index.html delete mode 100644 files/zh-tw/webapi/webfm_api/index.html delete mode 100644 files/zh-tw/webapi/websms/index.html (limited to 'files/zh-tw/webapi') diff --git a/files/zh-tw/webapi/alarm/index.html b/files/zh-tw/webapi/alarm/index.html deleted file mode 100644 index fc1eddb8d3..0000000000 --- a/files/zh-tw/webapi/alarm/index.html +++ /dev/null @@ -1,196 +0,0 @@ ---- -title: Alarm API -slug: WebAPI/Alarm -translation_of: Archive/B2G_OS/API/Alarm_API ---- -

{{ SeeCompatTable() }}

-

摘要

-

Alarm API 可存取裝置的警示設定功能。而警示設定功能可排定通知的時間，或在特定時間啟動某個 App。如鬧鐘、行事曆、自動更新等的 Apps，就可能需要透過 Alarm API，在特定時點觸發裝置的特定動作。

-

而 Alarm API 本身僅可進行警示排程。透過 System Message API 即可將警示發送到 Apps，因此若 Apps 要對警示做出反應，就必須先將 Apps 註冊至 alarm 訊息。

-

另外，使用 MozAlarmsManager 介面的 window.navigator.mozAlarms 物件，即可設定警示。

-

警示排程

-

使用警示功能的第一件事，就是警示排程。若依照時區來分，共可分成 2 種警示，且均可透過 MozAlarmsManager.add 函式進行排程。

-
-

注意：若未針對特定 Apps 來設定警示，則只要是正在監聽警示的 Apps，均將接到系統所發送的警示。

-
-

忽略時區的警示

-

系統將根據裝置的本端時間，發送此類警示。若裝置變更了時區設定，則系統將根據新的時區而發送警示。舉例來說，如果使用者位在巴黎，設定了 12 PM CET (Central European Time) 發出警示，結果出差到舊金山時，那同樣會在 12 PM PDT (Pacific Daylight Time) 發送警示。

-
// This the date to schedule the alarm
-var myDate  = new Date("May 15, 2012 16:20:00");
-
-// This is arbitrary data pass to the alarm
-var data    = {
-  foo: "bar"
-}
-
-// The "ignoreTimezone" string is what make the alarm ignoring it
-var request = navigator.mozAlarms.add(myDate, "ignoreTimezone", data);
-
-request.onsuccess = function () {
-  console.log("The alarm has been scheduled");
-};
-
-request.onerror = function () {
-  console.log("An error occurred: " + this.error.name);
-};
-
-

遵守時區的警示

-

系統將根據排程當下的時區，發送此類警示。若裝置因為某個理由變更了時區，系統同樣是根據原始的排程時區而發出警示。舉例來說，如果使用者位在巴黎，設定於 12 PM CET (Central European Time) 發送警示，結果出差到舊金山時，系統將於 3 AM PDT (Pacific Daylight Time) 發送警示。

-
// This the date to schedule the alarm
-var myDate  = new Date("May 15, 2012 16:20:00");
-
-// This is arbitrary data pass to the alarm
-var data    = {
-  foo: "bar"
-}
-
-// The "honorTimezone" string is what make the alarm honoring it
-var request = navigator.mozAlarms.add(myDate, "honorTimezone", data);
-
-request.onsuccess = function () {
-  console.log("The alarm has been scheduled");
-};
-
-request.onerror = function () {
-  console.log("An error occurred: " + this.error.name);
-};
-
-

管理警示

-

針對目前 App 已排定的警示，MozAlarmsManager.getAll 函式將回傳完整的警示清單。這份清單則為 mozAlarm 物件的陣列。

-

mozAlarm

-

這些物件均為非同步 JavaScript 物件，並包含下列屬性：

-
-
- id
-
- 1 組號碼代表警示的 ID
-
- date
-
- Date 物件代表警示的排程時間
-
- respectTimezone
-
- 1 組字串指出警示將遵守或忽略 date 物件的時區資訊。該值可為 ignoreTimezone 或 honorTimezone
-
- data
-
- 與警示一同儲存的所有資料，均納入此 JavaScript 物件中
-
-
var request = navigator.mozAlarms.getAll();
-
-request.onsuccess = function () {
-  this.result.forEach(function (alarm) {
-    console.log('Id: ' + alarm.id);
-    console.log('date: ' + alarm.date);
-    console.log('respectTimezone: ' + alarm.respectTimezone);
-    console.log('data: ' + JSON.stringify(alarm.data));
-  });
-};
-
-request.onerror = function () {
-  console.log("An error occurred: " + this.error.name);
-};
-
-

MozAlarmsManager.remove 函式則可解除已排程的警示。

-
var alarmId;
-
-// Set an alarm and store it's id
-var request = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "honorTimezone");
-
-request.onsuccess = function () {
-  alarmId = this.result;
-}
-
-// ...
-
-// Later on, removing the alarm if it exists
-if (alarmId) {
-  navigator.mozAlarms.remove(alarmId);
-}
-
-

處理警示

-

在系統發送警示之後，任何 Apps 均可做出回應。為了要能處理警示，Apps 必須將本身註冊為警示處理器 (Alarm handler)。透過 System Messaging API 的 2 個步驟即可完成註冊：

-

首先，Apps 必須將 alarm 納入本身 manifest 檔案的 message 屬性中，而此 manifest 檔案需包含「已註冊回呼 (Callback) 函式的文件」之網址。一旦發送警示時，就會呼叫該文件中所註冊的回呼函式。

-
"messages": [
-  { "alarm": "/index.html" }
-]
-

其次，Apps 必須以 alarm 訊息綁定回呼函式；可透過 navigator.mozSetMessageHandler 函式完成此步驟。此回呼函式將接收 mozAlarm 物件，其內為警示所附掛的資料。

-
navigator.mozSetMessageHandler("alarm", function (mozAlarm) {
-  alert("alarm fired: " + JSON.stringify(mozAlarm.data));
-});
-
-

如果 App 想確認是否有警示延宕在系統端尚未發出，則可使用navigator.mozHasPendingMessage 函式並搭配 alarm 值。

-
navigator.mozHasPendingMessage("alarm");
-
-

規格

- - - - - - - - - - - - - - - -
SpecificationStatusComment
{{SpecName('Alarm API')}}{{Spec2('Alarm API')}}Initial specification.
-

瀏覽器相容性

-

{{ CompatibilityTable() }}

-
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatUnknown()}}{{CompatGeckoDesktop("16")}} {{ property_prefix("moz") }}{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}
-
-
- - - - - - - - - - - - - - - - - - - - - -
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatNo() }}{{CompatGeckoMobile("10")}} {{ property_prefix("moz") }}{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}
-
-

另可參閱

- diff --git a/files/zh-tw/webapi/camera/index.html b/files/zh-tw/webapi/camera/index.html deleted file mode 100644 index f6f1df5e2c..0000000000 --- a/files/zh-tw/webapi/camera/index.html +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Camera API -slug: WebAPI/Camera -translation_of: Archive/B2G_OS/API/Camera_API ---- -

{{ ApiRef() }}

-

{{ non-standard_header() }}

-

{{ B2GOnlyHeader2('certified') }}

-

Camera API 可讓 Apps 管理裝置上的相機，進一步拍照、錄製影片，並取得如焦距、縮放、白平衡、閃光燈等的資訊。Camera API 屬於 Priviledged API，並僅限 Certified Apps 使用。

-
-

注意：除非你打算建構新 App 以取代預設的「Camera」App，否則應不會使用此 API。如果你只是要使用裝置上的相機功能，則應使用 Web Activities API。

-
-

另可參閱

- -

 

diff --git a/files/zh-tw/webapi/contacts/index.html b/files/zh-tw/webapi/contacts/index.html deleted file mode 100644 index 6775c57248..0000000000 --- a/files/zh-tw/webapi/contacts/index.html +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: Contacts API -slug: WebAPI/Contacts -translation_of: Archive/B2G_OS/API/Contacts_API ---- -

{{ SeeCompatTable }}

-

{{ B2GOnlyHeader2('privileged') }}

-

摘要

-

Contacts API 提供簡易的管理介面，可用於系統通訊錄所儲存的聯絡人資訊。Contacts API 的常見使用範例，就是針對通訊錄而建構出管理 Apps。

-
-

注意：由於聯絡人資訊屬於高敏感性的個人資料，因此僅限 Privileged 與 Certified Apps 可直接存取該 API。其他 Apps 均建議透過 Web Activities 而委派相關作業。

-
-

管理聯絡人資訊

-

透過 ContactManager 介面的 navigator.mozContacts 屬性，即可存取儲存於系統通訊錄中的資訊。

-

新增聯絡人

-

若要在系統通訊錄中建立新的項目，可分為 2 個步驟：

-
    -
  1. 建立新的 mozContact 物件，並列出其必要屬性的欄位。mozContact 介面將定義既有聯絡人的所有可能屬性。這些屬性絕大部分均與 vCard 4.0 規格所定義的相同。以下列出例外： - -
    2. -
  2. 以 ContactManager.save() 函式搭配聯絡人物件，並作為第一屬性。此函式將回傳 DOMRequest 以追蹤儲存作業是否成功或發生錯誤。
    3. -
-
var person = new mozContact();
-person.givenName  = ["John"];
-person.familyName = ["Doe"];
-person.nickName   = ["No kidding"];
-
-var saving = navigator.mozContacts.save(person);
-
-saving.onsuccess = function() {
-  console.log('new contact saved');
-  // This update the person as it is stored
-  // It includes its internal unique ID
-  // Note that saving.result is null here
-};
-
-saving.onerror = function(err) {
-  console.error(err);
-};
-
-

尋找聯絡人

-

有 2 個函式可檢索系統通訊錄中的聯絡人：

- -

這 2 組函式都是讓參數 (本身即為物件) 能定義出篩選與排序的選項。ContactManager.getAll 僅接受排序選項。這些選項為：

- -

還有其他搜尋選項：

- -

find 將回傳 DOMRequest 物件；getAll 將回傳 DOMCursor 物件，以存取成功或錯誤的搜尋作業。

-

若搜尋成功，則可於 DOMRequest.result 屬性中找到搜尋結果。可能是 find 的 mozContact 物件陣列；也可能是 getAll 的單一 mozContact 物件。若要以 getAll 接收清單中的其他結果，則可呼叫指示器的 continue() 函式。

-
var options = {
-  filterValue : "John",
-  filterBy    : ["givenName","name","nickName"],
-  filterOp    : "contains",
-  filterLimit : 1,
-  sortBy      : "familyName"
-  sortOrder   : "ascending"
-}
-
-var search = navigator.mozContacts.find(options);
-
-search.onsuccess = function() {
-  if (search.result.length === 1) {
-    var person = search.result[0];
-    console.log("Found:" + person.givenName[0] + " " + person.familyName[0]);
-  } else {
-    console.log("Sorry, there is no such contact.")
-  }
-}
-
-search.onerror = function() {
-  console.warn("Uh! Something goes wrong, no result found!");
-}
-
-var allContacts = navigator.mozContacts.getAll({sortBy: "familyName", sortOrder: "descending"});
-
-allContacts.onsuccess = function(event) {
-  var cursor = event.target;
-  if (cursor.result) {
-    console.log("Found: " + cursor.result.givenName[0] + " " + cursor.result.familyName[0]);
-    cursor.continue();
-  } else {
-    console.log("No more contacts");
-  }
-}
-
-allContacts.onerror = function() {
-  console.warn("Something went terribly wrong! :(");
-}
-
-
-

更新聯絡人

-

在透過 find() 或 getAll() 檢索聯絡人時，又或針對新聯絡人而成功呼叫 save() 時，此聯絡人必須附加某些後設資料 (Meta-data)：

- -

若更新某位聯絡人，其實只是更改其屬性值，再呼叫 save() 函式即可儲存。

-
-

注意：每次只要新增、更新、刪除聯絡人，就會觸發 contactchange 事件，以追蹤系統通訊錄的所有變更。另可透過 ContactManager.oncontactchange 屬性而處理該事件。

-
-

刪除聯絡人

-

呼叫 ContactManager.remove() 函式，只會刪除已傳入的 mozContact 物件。

-

在某些極端情況下，也可透過 ContactManager.clear() 而刪除所有的聯絡人。因為一旦完成就沒辦法恢復資料，所以呼叫此函式時請特別謹慎。

-

規格

- - - - - - - - - - - - - - - - - - - - -
SpecificationStatusComment
{{ SpecName('Contacts', '', 'Contacts Manager API') }}{{ Spec2('Contacts') }}First Working Draft (未穩定)
vCard Format SpecificationRFCRFC6350
-

瀏覽器相容性

-

{{ CompatibilityTable() }}

-
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
基本支援{{CompatNo()}}{{CompatNo()}}{{CompatNo()}}{{CompatNo()}}{{CompatNo()}}
-
-
- - - - - - - - - - - - - - - - - - - - - -
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
基本支援{{CompatNo()}}{{CompatNo()}}{{CompatVersionUnknown()}}{{CompatNo()}}{{CompatNo()}}{{CompatNo()}}
-
-

Gecko 說明

-

此規格尚未確定，因此目前 Gecko 仍屬非標準建構。

-

另可參閱

- diff --git a/files/zh-tw/webapi/device_storage/index.html b/files/zh-tw/webapi/device_storage/index.html deleted file mode 100644 index d09fd49015..0000000000 --- a/files/zh-tw/webapi/device_storage/index.html +++ /dev/null @@ -1,228 +0,0 @@ ---- -title: Device Storage API -slug: WebAPI/Device_Storage -translation_of: Archive/B2G_OS/API/Device_Storage_API ---- -

{{ non-standard_header() }}

-

{{ B2GOnlyHeader2('privileged') }}

-

摘要

-

Device Storage API 可存取 Web Apps 中的檔案系統。存取檔案系統可能牽涉極高的安全敏感度，所以此 API 僅可用於 Privileged Apps。

-
-

注意：若裝置儲存媒體的存取速度極慢，可能是受限於實體層 (Physical level) 的關係。在許多情況下，若以 IndexedDB 資料庫儲存檔案，取代實體的裝置儲存媒體，將可達到更高的速度。

-
-

存取儲存媒體

-

進入點

-

若使用 navigator.getDeviceStorage() 函式，則可存取儲存區。此函式所接受的字串參數，可代表所要存取的儲存媒體名稱。函式回傳的 DeviceStorage 物件，可存取相關的儲存區。

-

Firefox OS 提供下列儲存名稱：

- -
var pics = navigator.getDeviceStorage('pictures');
-

為了要能使用所有儲存區，Apps 必須在自己的 manifest 檔案中載明這些儲存區。舉例來說，如果 Apps 要存取 sdcard 儲存區，則其 manifest 檔案中必須具備「device-storage:sdcard」的授權。

-
"permissions": {
-  "device-storage:videos":{ "access": "readonly" },
-  "device-storage:pictures":{ "access": "readwrite" }
-}
-

使用儲存媒體

-

只要 Apps 能夠存取儲存區，就可在該儲存區中新增、取得、移除檔案。

-

新增檔案

-

透過 addNamed 或 add 函式，即可新增檔案。前者可在儲存檔案時，設定明確的名稱；而後者則可自動建立名稱。這 2 組函式均屬非同步函式，並將回傳 DOMRequest 物件以處理作業的 success 或 error 狀態。因為在實體層上讀/寫檔案極為緩慢，所以此作業特別重要。

-

這 2 組函式均以 Blob 作為其第一參數。此物件將於背景之下轉為檔案並儲存起來。當建立 Blob 物件時將強制給予其 type，而因為某些儲存區會因類型而有所限制，所以此 MIME 類型格外重要：

- -
var sdcard = navigator.getDeviceStorage("sdcard");
-var file   = new Blob(["This is a text file."], {type: "text/plain"});
-
-var request = sdcard.addNamed(file, "my-file.txt");
-
-request.onsuccess = function () {
-  var name = this.result;
-  console.log('File "' + name + '" successfully wrote on the sdcard storage area');
-}
-
-// An error typically occur if a file with the same name already exist
-request.onerror = function () {
-  console.warn('Unable to write the file: ' + this.error);
-}
-
-
-

注意：儲存區中的 Repository (Repo) 屬於隱性 (Implicit)，因此不能建立顯性 (Explicit) 的空白 Repo。如果要使用 Repo 的結構，則必須針對 Repo 的名稱，使之成為儲存檔案名稱的一部分。所以，如果你要在 foo 庫中儲存 bar 檔案，就必須使用 addNamed 函式再搭配 addNamed(blob, "foo/bar") 檔案的完整路徑名稱。一旦要使用這個名稱檢索檔案，也可使用同樣的方式 (參閱下列)。

-

基於安全理由，如果檔案新增於既定的受限儲存區內，則檔案路徑名稱不能以「/」或「../」開頭 (且「./」為無意義)。

-
-

取得檔案

-

現有 2 種方法可檢索檔案：使用檔案名稱，或依序存取檔案列表。

-

最簡單的方式，就是使用 get 與 getEditable 函式來檢索檔案。前者可提供File 物件，即如同唯讀檔案一樣；後者則提供 FileHandle 物件，可更新底層檔案 (Under-laying file)。這 2 組函式均屬非同步函式，並會回傳 DOMRequest 物件，以處理作業的 success 或 error 狀態。

-
var sdcard = navigator.getDeviceStorage('sdcard');
-
-var request = sdcard.get("my-file.txt");
-
-request.onsuccess = function () {
-  var file = this.result;
-  console.log("Get the file: " + file.name);
-}
-
-request.onerror = function () {
-  console.warn("Unable to get the file: " + this.error);
-}
-
-

另一個檔案檢索方式，就是透過 enumerate 與 enumerateEditable 函式瀏覽儲存區的內容。前者可提供 File 物件；後者則提供 FileHandle 物件。此 2 組均為非同步函式，並可回傳 DOMCursor 物件以依序存取檔案列表。DOMCursor 其實就是 DOMRequest，但又額外具備「非同步依序存取列表 (這裡則指檔案列表)」的功能。

-
var pics = navigator.getDeviceStorage('pictures');
-
-// Let's browse all the images available
-var cursor = pics.enumerate();
-
-cursor.onsuccess = function () {
-  var file = this.result;
-  console.log("File found: " + file.name);
-
-  // Once we found a file we check if there is other results
-  if (!this.done) {
-    // Then we move to the next result, which call the cursor
-    // success with the next file as result.
-    this.continue();
-  }
-}
-
-cursor.onerror = function () {
-  console.warn("No file found: " + this.error);
-}
-
-
-

只要傳送 2 組選擇性參數至 enumerate 與 enumerateEditable 函式，即可限制結果的數量。

-

第一組參數可為字串，代表所要搜尋的子資料夾。

-

第二組參數則是具備 since 屬性的物件，可限制在既定期間內搜尋。

-
var pics = navigator.getDeviceStorage('pictures');
-
-// Lets retrieve picture from the last week.
-var param = {
-  since: new Date((+new Date()) - 7*24*60*60*1000)
-}
-
-var cursor = pics.enumerate(param);
-
-cursor.onsuccess = function () {
-  var file = this.result;
-  console.log("Picture taken on: " + file.lastModifiedDate);
-
-  if (!this.done) {
-    this.continue();
-  }
-}
-
-
-

刪除檔案

-

透過 delete 函式，即可從儲存區移除檔案。此函式僅需所要刪除的檔案名稱。如同來自於 DeviceStorage 介面的其他所有函式，此函式亦屬於非同步 API，並會回傳 DOMRequest 物件，以處理作業的 success 或 error 的狀態。

-
var sdcard = navigator.getDeviceStorage('sdcard');
-
-var request = sdcard.delete("my-file.txt");
-
-request.onsuccess = function () {
-  console.log("File deleted");
-}
-
-request.onerror = function () {
-  console.log("Unable to delete the file: " + this.error);
-}
-
-
-

儲存資訊

-

除了存取檔案之外，儲存區亦提供數個函式，可輕鬆取得某些重要資訊。

-

可用空間

-

在儲存檔案時，必須先了解的要素之一就是可用空間。DeviceStorage 介面則針對空間而提供 2 組有用函式：

- -

這些函式亦屬於非同步 APIs，並會回傳 DOMRequest 物件，以處理作業的 success 或 error 的狀態。

-
var videos = navigator.getDeviceStorage('videos');
-
-var request = videos.usedSpace();
-
-request.onsuccess = function () {
-  // The result is express in bytes, lets turn it into megabytes
-  var size = this.result / 1000000;
-
-  console.log("The videos on your device use a total of " + size.toFixed(2) + "Mo of space.");
-}
-
-request.onerror = function () {
-  console.warn("Unable to get the space used by videos: " + this.error);
-}
-
-

監聽變動狀態

-

可能有許多 Apps 同時存取相同的儲存區。如果 Apps 能知道儲存區中的變化，則可避免不必要的錯誤。又若 Apps 不依賴 DeviceStorage 介面的函式所回傳的 DOMRequest 物件，卻需執行非同步作業，那得知儲存區的變化亦頗有助益。

-

因為如此，只要建立、修改、刪除了某個檔案，就會觸發 change 事件。而透過 onchange 屬性或 addEventListener() 函式，即可取得這個事件。而事件處理器 (Event Handler) 所取得的 DeviceStorageChangeEvent 物件，則是擁有額外 2 組屬性的常態 Event 物件：

- -
var sdcard = navigator.getDeviceStorage('sdcard');
-
-sdcard.onchange = function (change) {
-  var reason = change.reason;
-  var path   = change.path;
-
-  console.log('The file "' + path + '" has been ' + reason);
-}
-
-

規格

-

目前尚無規格。

-

瀏覽器相容性

-

{{ CompatibilityTable() }}

-
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}
-
-
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}
-
-

另可參閱

- diff --git a/files/zh-tw/webapi/idle/index.html b/files/zh-tw/webapi/idle/index.html deleted file mode 100644 index e4eaaaaac2..0000000000 --- a/files/zh-tw/webapi/idle/index.html +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Idle -slug: WebAPI/Idle -translation_of: Archive/B2G_OS/API/Idle_API ---- -

{{ non-standard_header() }}

-

{{ B2GOnlyHeader2('certified') }}

-

摘要

-

當使用者讓裝置進入閒置/待機狀態，可通知 App 以採取相對應的行動。最常見的情形就是待機省電。而待機省電狀態又可另外搭配 Power Management API。

-

Idle Observer

-

若要讓任一 App 收到「系統閒置」的通知，就必須先註冊 Idle Observer。而 Idle Observer 物件具備了 3 項屬性：

- -
// NOTE: mozPower is part of the Power Management API
-
-var fadeLight = {
-  time: 10, // Ten seconds
-
-  onidle: function () {
-    // The user does not seem active, let's dim the screen down
-    navigator.mozPower.screenBrightness = 0.5;
-  },
-
-  onactive: function () {
-    // Ok, the user is back, let's brighten the screen up
-    navigator.mozPower.screenBrightness = 1;
-  }
-}
-
-var screenOff = {
-  time: 15, // fifteen seconds
-
-  onidle: function () {
-    // Ok, the user had his chance but he's really idle, let's turn the screen off
-    navigator.mozPower.screenEnabled = false;
-  },
-
-  onactive: function () {
-    // Ok, the user is back, let's turn the screen on
-    navigator.mozPower.screenEnabled = true;
-  }
-}
-
-

任一 App 均可依需要而定義為多個 Idle Observer。但不論定義成幾個 Idle Observer，都必須以 navigator.addIdleObserver() 函式完成註冊，才能由系統所處理。

-
navigator.addIdleObserver(fadeLight);
-navigator.addIdleObserver(screenOff);
-
-

又如果 App 不再需要知道使用者是否閒置了系統，則可透過 navigator.removeIdleObserver() 函式移除 Idle Observer。

-
navigator.removeIdleObserver(fadeLight);
-navigator.removeIdleObserver(screenOff);
-
-

規格

-

目前仍未有任何規格，但 W3C 將此 API 納入為 System Applications Working Group 討論的一部分。

-

另可參閱

- diff --git a/files/zh-tw/webapi/network_stats/index.html b/files/zh-tw/webapi/network_stats/index.html deleted file mode 100644 index c9aa8a94c1..0000000000 --- a/files/zh-tw/webapi/network_stats/index.html +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: 網路流量統計 -slug: WebAPI/Network_Stats -translation_of: Archive/B2G_OS/API/Network_Stats_API ---- -

{{ non-standard_header() }}

-

{{ B2GOnlyHeader2('certified') }}

-

摘要

-

Network Stats API 將監控資料用量，並將此數據提供給 Certified Apps。

-

navigator.mozNetworkStats 屬於 MozNetworkStatsManager 介面的實體 (Instance)。透過 navigator.mozNetworkStats 即可取得相關資料。

-

存取資料

-

有關已接收/已傳送資料量的資訊，均將由系統自動儲存。而 MozNetworkStatsManager.getNetworkStats() 函式可存取相關資訊。此函式的第一組參數屬於組態物件，且必備下列屬性：

- -

一旦呼叫此函式，隨即回傳 DOMRequest 以處理資訊請求的成功或失敗狀態。若為成功狀態，則請求的 result 即為 MozNetworkStats 物件。

-
var manageWifi   = navigator.mozNetworkStats.connectionTypes.indexOf('wifi')   > -1;
-var manageMobile = navigator.mozNetworkStats.connectionTypes.indexOf('mobile') > -1;
-
-var config = {
-  start: new Date(),
-  end  : new Date(),
-  connectionType: manageWifi ? 'wifi' : null
-};
-
-var request = navigator.mozNetworkStats.getNetworkStats(config);
-
-request.onsuccess = function () {
-  console.log("Data received: " + request.result.data[0].rxBytes + " bytes");
-  console.log("Data sent: " + request.result.data[0].txBytes + " bytes")
-}
-
-request.onerror = function () {
-  console.log("Something goes wrong: ", request.error);
-}
-
-

隨著時間連續取樣

-

資料總量的相關資訊均儲存於區塊 (Chunk) 中，以利隨時查看資料流量。各個區塊均為 1 組值，代表上個區塊儲存之後所交換的資料總量。

-

在請求統計資料時，MozNetworkStats 物件將針對 start 與 end 日期之間所定義的間隔，儘量攜帶夠多的資料區塊。區塊的總數將因下列 2 組參數 (均屬唯讀參數) 而有所變化：

- -

各個資料區塊均為 1 個 MozNetworkStatsData 物件。透過MozNetworkStats.data 屬性即可取得各個既定時間框架 (Time frame) 的所有資料區塊，進而形成 MozNetworkStatsData 物件的 Array。

-
var rate = navigator.mozNetworkStats.sampleRate;
-var max  = navigator.mozNetworkStats.maxStorageSample;
-
-var config = {
-  start: new Date() - (rate * max), // This allows to get all the available data chunks.
-  end  : new Date(),
-  connectionType: 'mobile'
-};
-
-var request = navigator.mozNetworkStats.getNetworkStats(config);
-
-request.onsuccess = function () {
-  var total = {
-    receive: 0,
-    send   : 0
-  };
-
-  this.result.forEach(function (chunk) {
-    total.receive += chunk.rxBytes;
-    total.send    += chunk.txBytes;
-  });
-
-  console.log("Since: " + config.start.toString());
-  console.log("Data received: " + (total.receive * 1000).toFixed(2) + "Ko");
-  console.log("Data sent: " + (total.send * 1000).toFixed(2) + "Ko")
-}
-
-request.onerror = function () {
-  console.log("Something goes wrong: ", request.error);
-}
-

規格

-

尚無任何規格。

-

另可參閱

- diff --git a/files/zh-tw/webapi/power_management/index.html b/files/zh-tw/webapi/power_management/index.html deleted file mode 100644 index da501d4238..0000000000 --- a/files/zh-tw/webapi/power_management/index.html +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Power Management -slug: WebAPI/Power_Management -translation_of: Archive/B2G_OS/API/Power_Management_API ---- -

{{ non-standard_header() }}

-

{{ B2GOnlyHeader2('certified') }}

-

摘要

-

Power Management API 可管理裝置的耗電情形。

-

管理電力

-

電力管理與電力本身不盡相同，如避免大量耗電、限制回流 (Reflow) 等等，都屬於電源管理的一部分。而 Power Management API 則直接控管如 CPU 與螢幕等的耗電量。透過 navigator.mozPower 即可存取電力管理的主要介面。而 navigator.mozPower 則為 PowerManager 介面的實例 (Instance)。

-

基本電力操作

-

PowerManager 介面可管理基本的電力操作情形。

-

通用電力操作

-

powerOff() 函式可關閉裝置；reboot() 函式則可重新開機。

-
navigator.mozPower.powerOff();
-

螢幕電力操作

-

透過可讀寫的 screenEnabled 屬性即可開/關螢幕畫面；而存取/更改畫面亮度也能達到相同效果。如可讀寫的 screenBrightness (用以定義螢幕背光的亮度) 就能變更畫面亮度，可調整為 0 (全暗) 到 1 (全亮)。

-
// It doesn't make sense to change the brightness if the screen is off
-if (navigator.mozPower.screenEnabled) {
-  navigator.mozPower.screenBrightness = 0.5;
-}
-

CPU 電力操作

-

目前並無法直接關閉 CPU。但可進一步設定 cpuSleepAllowed，以決定關閉畫面之時是否要關閉 CPU。在畫面關閉 (true) 或開啟 (false) 時，此函式可定義是否讓裝置的 CPU 休眠。若畫面處於開啟狀態 (false)，則該函式將避免裝置進入靜止狀態。

-

進階電力操作

-

若管理電力的 Apps 可確實接收到第三方 Apps 的需求通知，就能達到更好的電力管理效果。舉例來說，在使用者欣賞影片時，當然不希望系統在幾分鐘之後自動關閉畫面。

-

請求 Wake locks

-

任何 Apps 均可請求 Wake locks，避免裝置切斷 Apps 本身所需資源的電力。可透過 navigator.requestWakeLock() 函式請求 Wake locks。

-

特定資源所要求的 Wake locks，可能會因不同的理由而取消。舉例來說，行動裝置的電力管理功能，可能會在閒置一段時間之後決定關閉畫面，進而達到省電目的。在關閉相關資源之前，處理資源的 Apps 往往會檢查相關資源的鎖定狀態。再舉個例子，某個頁面可能持續 screen 上的鎖定狀態，以避免畫面關閉或螢幕保護程式運作。

-

依預設值，Firefox OS 允許 screen、cpu、wifi 資源。但只要是處理資源的任何 App 均可定義資源名稱，並針對該鎖定功能設定規則。舉例來說，資源管理功能可無視 Apps 對 screen 所進行的 Wake locks，讓 Apps 無法插手鎖定狀態。

-
var lock = navigator.requestWakeLock('screen');
-

requestWakeLock 函式所回傳的物件將包含 topic 屬性，代表目前要鎖定的資源。而 unlock() 函式可供手動解鎖。另請注意，若 App 進入關閉狀態 (真的關閉，而不是閒置)，就會自動送出該 App 需要的所有鎖定請求。

-

處理 Wake locks

-

只要是可管理鎖定的 Certified Apps，均可得知鎖定狀態的變化。其實任何管理電力的 Apps 均應監聽 screen 與 cpu 鎖定狀態的變化。透過 PowerManager.addWakeLockListener() 函式即可達到此目的。另可透過 PowerManager.removeWakeLockListener() 函式而停止監聽鎖定請求。

-

addWakeLockListener 函式所接收的回呼 (Callback) 需具備 2 組參數。第一組字串代表應處理的資源 (本範例為 screen 或 cpu)；第二組字串則代表鎖定的狀態。

-

鎖定可分為 3 種狀態：

-
-
- unlocked
-
- 沒有任何 App 針對既有資源持續 Wake lock。
-
- locked-foreground
-
- 至少 1 個 App 持續 Wake lock，且於前景顯示該 App。
-
- locked-background
-
- 至少 1 個 App 持續 Wake lock，但所有 Apps 均在背景而未顯示。
-
-
// This is used to keep track of the last change on the lock state
-var screenTimeout;
-
-// A reference to the Power Manager
-var power = window.navigator.mozPower;
-
-// Here are the actions to handle based on the lock state
-var powerAction = {
-
-  // If there is no lock at all, we will suspend the device:
-  // * Turn the screen off
-  // * Allow the cpu to shut down
-  unlocked: function suspendDevice() {
-    power.cpuSleepAllowed = true;
-    power.screenEnabled   = false;
-  },
-
-  // If there is a lock but the applications requesting it
-  // are all in the background, we just turn the screen off
-  'locked-background': function shutOffOnlyScreen() {
-    power.cpuSleepAllowed = false;
-    power.screenEnabled   = false;
-  },
-
-  // At last, if there is an active application that requests a lock,
-  // actually there is nothing to do. That's the whole point.
-}
-
-function screenLockListener(topic, state) {
-  // If the lock is not about the screen, there is nothing to do.
-  if ('screen' !== topic) return;
-
-  // Each time the lock changes state, we stop any pending power management operations
-  window.clearTimeout(screenTimeout);
-
-  // If there is an action defined for the given state
-  if (powerAction[state]) {
-    // We delay that action by 3s
-    screenTimeout = window.setTimeout(powerAction[state], 3000);
-  }
-}
-
-// We make sure our power management application is listening for any change on locks.
-power.addWakeLockListener(screenLockListener);
-

規格

-

尚無任何規格。

-

另可參閱

- diff --git a/files/zh-tw/webapi/settings/index.html b/files/zh-tw/webapi/settings/index.html deleted file mode 100644 index 2e5198a2a0..0000000000 --- a/files/zh-tw/webapi/settings/index.html +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Settings API -slug: WebAPI/Settings -translation_of: Archive/B2G_OS/API/Settings_API ---- -

{{ non-standard_header() }}

-

{{ B2GOnlyHeader2('certified') }}

-

摘要

-

Settings API 可存取、變更、監聽裝置設定的任何變化。裝置的設定選項可能帶有高敏感度的資訊並可能危害整個系統，因此僅限 Certified Apps 可使用此 API。

-

使用設定選項

-

透過 naviator.mozSettings 物件 (即 SettingsManager 介面的實例)，即可操作設定選項。

-

存取設定選項

-

若要存取設定選項，必須先以 createLock() 函式建立鎖定機制。因為可能有多個 Apps 同時存取並更改設定，所以必須確保各個 App 不會受到其他 Apps 的影響。而建立鎖定機制之後，各個 App 均可於特定時間單獨存取設定。

-

在 Apps 擁有鎖定機制後，即可透過 get() 函式讀取任何設定。此函式將回傳 DOMRequest 物件，以處理成功或失敗的作業。不論任何狀況下，只要完成了成功/失敗的請求，均會自動解鎖之後才讓其他 Apps 存取設定。若有必要，也可透過鎖定機制的 closed 屬性，得知是否已解開鎖定。

-

在下列程式碼片段中，則建立了鎖定並請求了系統 wifi.enabled 設定的數值。另呼叫 console.log() 即可於主控台上顯示輸出的結果：

-
var lock    = navigator.mozSettings.createLock();
-var setting = lock.get('wifi.enabled');
-
-setting.onsuccess = function () {
-  console.log('wifi.enabled: ' + setting.result);
-}
-
-setting.onerror = function () {
-  console.warn('An error occured: ' + setting.error);
-}
-
-

更改設定

-

設定值的更改程序與存取程序完全相同，但必須呼叫 set() 函式，此函式將回傳 DOMRequest 物件，讓你知道設定更改請求是否成功。

-

set() 函式會將物件作為自己的輸入參數。此物件為鍵值/數值的集合，而各個鍵值即代表 1 組設定的名稱，對應的數值又是設定的新數值。可參閱 Firefox OS 設定清單以進一步了解 (另請注意，不同裝置所使用的設定亦將有所差異)。

-

這裡可看到建立的 1 組鎖定，並於主控台上顯示 wifi.enabled 設定的結果。

-
var lock = navigator.mozSettings.createLock();
-var result = lock.set({
-  'wifi.enabled': true
-});
-
-result.onsuccess = function () {
-  console.log("the settings has been changed");
-}
-
-result.onerror = function () {
-  console.log("An error occure, the settings remain unchanged");
-}
-

監聽設定中的變化

-

App 除了讀取、更改設定之外，亦可監聽發生過的任何變更。只要變更過設定，系統隨即觸發 settingchange 事件。此事件為 MozSettingEvent。此常態事件又可透過 2 項額外屬性進一步延伸：

- -

只要設定 SettingsManager.onsettingchange 以指定 1 組回呼 (Callback，只要設定改變就會呼叫該回呼) 即可監聽 settingchange 事件。如果只想監聽某一特定設定的變化，則可呼叫如下的 SettingsManager.addObserver() 函式：

-
function handleWifi(event) {
-  if (event.settingValue === true) {
-    console.log("Hey! I can download that crazy heavy 4GB file")
-  } else {
-    console.log("Oh! I should stop downloading that crazy 4GB file")
-  }
-}
-
-navigator.mozSettings.addObserver('wifi.enabled', handleWifi);
-
-

 

-

規格

-

目前仍未有任何規格。可參與 W3C 於 System Applications Working Group 中對此API 的討論。

-

另可參閱

- diff --git a/files/zh-tw/webapi/simple_push/index.html b/files/zh-tw/webapi/simple_push/index.html deleted file mode 100644 index da0015bd11..0000000000 --- a/files/zh-tw/webapi/simple_push/index.html +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Simple Push API -slug: WebAPI/Simple_Push -translation_of: Archive/B2G_OS/API/Simple_Push_API ---- -

{{ SeeCompatTable() }}

-

Simple Push API 也是所謂的 Push Notification API，可在接收通知時喚醒 App。多個 App 可請求「共用其伺服器」的單一網址，以便傳送 App 的後續版本號碼。另外亦可作為同步化機制，從第三方伺服器取得最新資料。

-

SimplePush API 可透過 push 屬性 (來自於 PushManager 專案) 而擴充 window.navigator，並添增新的事件給使用者，以監控推播 (Push) 的狀態。

-

範例

-

在本範例中，我們將依照下列步驟而設定完整的推播：

-
    -
  1. 將 push 的授權新增至 manifest 檔案中
    2. -
  2. 呼叫 push.register() 以請求終端 (Endpoint)
    3. -
  3. 將終端傳送到自己的伺服器
    4. -
  4. 針對 App 之內的推播通知，新增訊息處理器 (Message handler)
    5. -
  5. 從自己的伺服器中送出通知
    6. -
-

修改 manifest 檔案

-

另外需修改 manifest 檔案中的 2 個地方：

-
    -
  1. messages 欄位：新增 push 與 push-register 訊息。
    2. -
  2. permissions 欄位：新增想要接收推播通知的 App。
    3. -
-
"messages": [
-   { "push": "/index.html"},
-   { "push-register": "/index.html"}
-],
-"permissions": {
-  "push": {
-    "description": "Required for be updated with new goals in soccer matchs",
-  }
-}
-

呼叫 {{domxref("PushManager.register")}} 以請求終端

-

一旦你認為該是請求終端的時候 (例如使用者登入，或有人想看場棒球賽的時候)，即可呼叫此程式碼。

-
if (navigator.push) {
-  var req = navigator.push.register();
-
-  req.onsuccess = function(e) {
-    var endpoint = req.result;
-      debug("New endpoint: " + endpoint );
-    }
-
-   req.onerror = function(e) {
-     debug("Error getting a new endpoint: " + JSON.stringify(e));
-   }
-} else {
-  // No push on the DOM
-}
-

將終端傳送至自己的伺服器

-

一旦獲得終端之後，就必須將之傳送至自己的 App 伺服器上。現有很多傳送終端的方法，如寄送電子郵件，或透過 POST、PUT、GET 均可傳送終端。我們建議以「來自於 App 的使用者資料」來儲存終端，例如 cookie、使用者名稱，或任何你用來識別終端使用者的資料均可。

-

但如果你正把資料傳送到伺服器，我們還是建議下列要點：

-
    -
  1. 以 XMLHttpRequest 傳送。
    2. -
  2. 最好使用 HTTPS。如果某人中斷了你的終端，即可開始將通知傳送到自己的 App。
    3. -
  3. 使用如 cookie 的機制，可比對使用者 (或 App 安裝作業) 與終端。
    4. -
-

新增 push 訊息處理器

-

一旦設定終端完畢，就可讓 App 開始監聽推播訊息。此功能亦可註冊在主要的 index.html 檔案，或註冊在自己的 main.js 指令碼中；也能註冊在特殊的 push-message.html 檔案 (特殊之處在於該檔案之內僅有指令碼) 上。這功能之所以方便的原因在於：如果接收到 push 訊息且 App 處於關閉狀態時，則該 App 只會載入一小部分的 HTML/JavaScript 程式碼，而且你也可以決定是否要完全開啟 App，或在背景中執行某些作業即可。

-
if (window.navigator.mozSetMessageHandler) {
-  window.navigator.mozSetMessageHandler('push', function(e) {
-    debug('My endpoint is ' + e.pushEndpoint);
-    debug('My new version is ' +  e.version);
-    //Remember that you can handle here if you have more than
-    //one pushEndpoint
-    if (e.pushEndpoint === emailEndpoint) {
-      emailHandler(e.version);
-    } else if (e.pushEndpoint === imEndpoint) {
-      imHandler(e.version);
-    }
-  });
-} else {
-  // No message handler
-}
-

新增 push-register 訊息處理器

-
-

請確實添增此處理器，並檢查是否正常運作。只要在產生 push-register 訊息當下，你並未重新註冊自己的終端，則之後將無法繼續接收其他推播通知。

-
-

一旦裝置變更了自己的 UAID (可能是因為推播伺服器變更，或當機之後需恢復作業，或其他更多情形)，就會將 push-register 訊息傳送至所有 App。也就是說，因為你之前的終端均已無效，所以你必須再次重新註冊所有的終端。

-
if (window.navigator.mozSetMessageHandler) {
-  window.navigator.mozSetMessageHandler('push-register', function(e) {
-    console.log('push-register received, I need to register my endpoint(s) again!');
-
-    var req = navigator.push.register();
-    req.onsuccess = function(e) {
-      var endpoint = req.result;
-      console.log("New endpoint: " + endpoint );
-      localStorage.endpoint = endpoint;
-    }
-
-    req.onerror = function(e) {
-      console.error("Error getting a new endpoint: " + JSON.stringify(e));
-    }
-  });
-} else {
-  // No message handler
-}
-

傳送通知

-

一旦你的伺服器擁有 endpoint 之後，「傳送通知」就如同「將 HTTP PUT 的請求 (其內容具備 version=<version>) 傳送至終端」一樣簡單。先假想某個終端具備下列網址：

-

https://push.src.openwebdevice.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef

-

而且是版本 5：

-

version=5

-

搭配 curl：

-

curl -X PUT -d "version=5" https://push.src.openwebdevice.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef

-

如果伺服器正確運作，所取得的反應內容就會包含 200 Status (OK) 與 {} 各 1 組作為內容 (Body)。如果發生錯誤，則會送出有效的 JSON 以解釋該錯誤。

-

另請注意，版號應該為逐漸遞增的整數。如果新版本的版號，小於裝置/伺服器上已儲存的版本，則 App 不會獲得新的通知。

-

規格

-

{{page("/en-US/docs/Web/API/PushManager","Specifications")}}

-

瀏覽器相容性

-

{{page("/en-US/docs/Web/API/PushManager","Browser_compatibility")}}

-

另可參閱

- diff --git a/files/zh-tw/webapi/tcp_socket/index.html b/files/zh-tw/webapi/tcp_socket/index.html deleted file mode 100644 index ae0c75e434..0000000000 --- a/files/zh-tw/webapi/tcp_socket/index.html +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: TCP Socket -slug: WebAPI/TCP_Socket -translation_of: Archive/B2G_OS/API/TPC_Socket_API ---- -

{{ non-standard_header() }}

-

{{ B2GOnlyHeader2('privileged') }}

-

摘要

-

TCPSocket API 可開啟並使用 TCP 連線，亦可讓 Apps 開發者基於 TCP 架構，建構相關通訊協定 (如 IMAP、IRC、POP、HTTP等)；甚至建立自己所需的協定以滿足特殊需求。

-

概述

-

透過 navigator.mozTCPSocket 屬性 (本身為 TCPSocket 物件) 即可存取此 API。

-

開啟 Socket

-

TCPSocket.open() 函式即可開啟 Socket。該函式共有 3 組參數：

-
    -
  1. 以 1 組字串代表所要連線的伺服器主機名稱 (亦可為該伺服器的原始 IP 位址)。
    2. -
  2. 以 1 組數字代表 Socket 所要使用的 TCP 通訊埠 (某些協定擁有標準埠，如 HTTP 為 80、SSL 為 447、SMTP 為 25 等。若為 1024 以上的通訊埠數字，則不會用於任何特定的通訊協定，也就是說可用於任何用途)。
    3. -
  3. 最後是 1 組選填的物件，內含最多 2 個選項。
    - i.) 名為 useSSL 的 Boolean 值，代表 Socket 必須使用 SSL，預設值為 false。
    - ii.) 名為 binaryType 的字串，可指定 Apps 透過 data 事件所取得的資料型態，可為 string 或 arraybuffer 值。預設值為 string。
    4. -
-
var socket = navigator.mozTCPSocket.open('localhost', 80);
-
-

注意：僅限 Certified Apps 可使用 1024 以下的通訊埠。

-
-

傳送資料

-

TCPSocket.send() 函式將透過 1 組字串，或 1 組 Uint8Array 物件而傳送資料。另請注意，由於 TCP Socket 僅處理二進制資料，因此使用 Uint8Array 可達較高的安全性。

-

對 TCP 通訊協定而言，單次傳輸量最好以 64kb 為上限而能達到最佳效果。只要緩衝的資料不到 64kb，送至 send 函式的呼叫即會回傳 true。一旦緩衝區滿載，則函式隨即回傳 false，進而要求該 App 暫停並清空緩衝區。每次只要清空緩衝區就會發出 drain 事件，讓該 App 針對此事件再度開始傳送資料。

-

透過 TCPSocket.bufferedAmount 屬性，即可得知目前已緩衝的實際資料量。

-
function getData() {
-  var data;
-
-  // do stuff that will retrieve data
-
-  return data;
-}
-
-function pushData() {
-  var data;
-
-  do {
-    data = getData();
-  } while (data != null && socket.send(data));
-}
-
-// Each time the buffer is flushed
-// we try to send data again.
-socket.ondrain = pushData;
-
-// Start sending data.
-pushData();
-
-

取得資料

-

只要 Socket 獲得主機所傳來的資料，就會發出 data 事件。App 可透過此事件而存取來自於 Socket 的資料。當 Socket 為開啟狀態時，則資料型態將根據已設定的選項而有所不同 (可參閱前述的第三種參數)。

-
socket.ondata = function (event) {
-  if (typeof event.data === 'string') {
-    console.log('Get a string: ' + event.data);
-  } else {
-    console.log('Get a Uint8Array');
-  }
-}
-

在送出所需的 data 事件之後，有時也必須暫停後續資料流入。此時呼叫 TCPSocket.suspend() 函式，即可暫停讀取後續資料並停止發送 data。若要再次開始讀取資料並發送事件，則可呼叫 TCPSocket.resume() 函式。

-

關閉 Socket

-

TCPSocket.close() 可關閉 Socket。

-

標準

-

尚未有任何規格。若要進一步了解此 API，可至 W3C 的 Raw Sockets 提案之下，參閱 System Applications Working Group 的相關討論。

-

另可參閱

- diff --git a/files/zh-tw/webapi/time_and_clock/index.html b/files/zh-tw/webapi/time_and_clock/index.html deleted file mode 100644 index aa772cf083..0000000000 --- a/files/zh-tw/webapi/time_and_clock/index.html +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Time and Clock API -slug: WebAPI/Time_and_Clock -translation_of: Archive/B2G_OS/API/Time_and_Clock_API ---- -

{{ non-standard_header() }}

-

{{ B2GOnlyHeader2('certified') }}

-

摘要

-

Time/Clock API 可輕鬆更改系統的時間。

-

概述

-

此 API 可被存取，且回傳的物件可揭露單一函式。

-

而該函式可用以實際更改系統時間，並接受某個數字或 Date 物件作為參數。在提供了數字之後，就會開始 1970 年 1 月 1 日 (UTC 時區) 起算的時間，並以毫秒 (Millisecond) 計算。

-

每次只要更改了時間，就會啟動事件。而只要透過函式 (使用 moztimechange 事件名稱)，或將事件處理器 (Event Handler) 附加至屬性，即可在 window 物件層級擷取到該事件。

-
-

注意：如果你要更改自己裝置的時區，就必須使用 Settings API。

-
-

範例

-
function setTime(time) {
-  navigator.mozTime.set(time);
-}
-
-window.addEventListener('moztimechange', function () {
-  console.log('Time has changed');
-});
-
-setTime(new Date());
-
-
-

規格

-

不屬於任何規格

diff --git a/files/zh-tw/webapi/web_activities/index.html b/files/zh-tw/webapi/web_activities/index.html deleted file mode 100644 index 6c71c46bd8..0000000000 --- a/files/zh-tw/webapi/web_activities/index.html +++ /dev/null @@ -1,415 +0,0 @@ ---- -title: Web Activities -slug: WebAPI/Web_Activities -translation_of: Archive/B2G_OS/API/Web_Activities ---- -

{{ non-standard_header() }}

-

{{B2GOnlyHeader2('installed')}}

-

摘要

-

Web Activities 即定義「App 將 Activity 委託 (Delegate) 予另一個 App (往往是由使用者所選擇)」的方法。

-

Web Activities 目前僅能用於 Firefox OS 上，而完整規格可參閱 WikiMo。

-

Activity

-

所謂「Activity」就是使用者想做的事情，如選取影像、傳送電子郵件等。App 開發者可能會定義某個 App 去處理該 Activity，或定義某個 App 委託予 Activity。

-

將 App 註冊為 Activity handler

-

App 開發者可建構 App 以處理單或多個 Activity。也就是說，這個 App 可經由其他 App 呼叫之後，而執行 Activity 所定義的某些特定動作。舉例來說，我們可能用其他 App 呼叫相片管理 App，進而選取相片。若 App 是作為 Activity Handler，就會成為其他 App 作業流程的一部分。

-

註冊 Activity

-

如果要將 App 註冊為 Activity Handler，目前唯一方法就是到 App 的 manifest 檔案中宣告。

-
-

注意：任何 App 均可針對現有的 Activity，將本身註冊為 Activity Handler；亦可建立自己的 Activity。不論是哪種情況，對 manifest 檔案的處理方式都相同。但若要建立新的 Activity，最好是在新 Activity 名稱的前方加上網址 (例如 example.org/myActivity 或 org.example.myActivity)，以避免發生衝突。

-
-

App manifest (亦所謂的宣告註冊)

-

如同下列範例所示，必須透過 App 的 manifest 檔案，宣告 App 將會處理 Activity：

-
{
-  // Other App Manifest related stuff
-
-  // Activity registration
-  "activities": {
-
-    // The name of the activity to handle (here "pick")
-    "pick": {
-      "href": "./pick.html",
-      "disposition": "inline",
-      "filters": {
-        "type": ["image/*","image/jpeg","image/png"]
-      },
-      "returnValue": true
-    }
-  }
-}
-
-

動態註冊

-

透過 navigator 物件，即可讓 App 動態的註冊自己。但目前尚未提供此 API。可留意 bug 775181 以持續追蹤此 API。

-

Activity Handler 說明

-
-
- href
-
- 當其他 App 或網頁所啟動的 Activity，同樣也受到此 App 所支援時，則只要選定此 App 執行 Activity，則 href 將指定所應開啟的網頁。另可透過 disposition 屬性指定網頁的開啟方式。 -
- 注意：此頁面的 URL 將受到同源規範 (Same-origin policy) 的限制。
-
-
-
-
- disposition {{optional_inline()}}
-
-
-
- 在開始 Activity 時，指定「href 所指定的頁面」呈現方式。其值必為下列之一 (若略過不設定，則預設為 window)： -
    -
  • window ─ 只要是處理 Activity 的頁面，均將以新視窗開啟之；若在行動裝置上，則是以此畫面取代「請求該 Activity 的原始 App」。頁面必須針對自己所支援的各個 Activity，呼叫 navigator.mozSetMessageHandler()，再執行「接收到訊息」的Activity。
    • -
  • inline ─ 將以覆蓋原頁面的方式，開啟「處理 Activity 的頁面」；若在行動裝置上，則會在「請求該 Activity 的原始 App」上彈出框。如果 disposition 同樣是 window，則後續動作將一模一樣。
    • -
-
-
-
-
- returnValue {{optional_inline()}}
-
- 表示 Activity 是否將回傳數值。如果 App 不回傳數值，則一旦選定 App，UA 隨即傳送 - - success - 事件。如果要回傳數值，那只要 Activity 成功，Activity Handler 會呼叫 MozActivityRequestHandler.postResult()；反之則呼叫 MozActivityRequestHandler.postError()。此處 Activity Handler 中，將於 mozSetMessageHandler 指定第一引數的類型，其實就是 MozActivityRequestHandler。在事件處理器呼叫了 postResult 或 postError 之後，將分別觸發 success 或 error 事件。
-
-
-
- filters {{optional_inline()}}
-
- 此 Dictionary 收錄了「用以指定篩選器 (Filter)」的各個屬性。在確認 App 是否適合處理目前 Activity 時，就會套用這些篩選器。篩選器名稱可為任何形式的文字，但需對應 MozActivityOptions 的 data 屬性名稱。篩選器的值可能為基本數值 (數字或字串)、基本數值構成的陣列，或篩選器的定義物件。任一 Activity 必須先滿足所有篩選器之後，才會決定是否要處理其他 Activity。
-
-

根據各個篩選器數值的不同，處理篩選器的方式也有所差異：

- -

處理 Activity

-

一旦把 App 宣告為 Activity Handler 之後，我們就必須在實作中處理其他 App 所傳來的 Activity 請求。

-

若要處理 Activity，就必須註冊「執行所有必要動作」的函式。先透過 navigator.mozSetMessageHandler() 來設定訊息處理器 (Message handler)，並特別指派至「activity」訊息 (不能為 Activity 的名稱)。接著將傳入 MozActivityRequestHandler 物件，以作為 Activity Handler 函式的參數。

-
navigator.mozSetMessageHandler('activity', function(activityRequest) {
-  // Do something to handle the activity
-});
-

在 Activity Handler 函式執行動作時，將透過 Activity 請求而檢索 Activity 的相關資訊，並依需要而回傳答案。

-

另外，呼叫 Activity 的 App 必須提供某些資料 (請參閱下表)。而透過請求的 source 屬性 (亦為 MozActivityOptions 物件) 即可取得這些資料。該物件將提供 Activity 呼叫的 name 與相關 data。

-
navigator.mozSetMessageHandler('activity', function(activityRequest) {
-  var option = activityRequest.source;
-
-  if (option.name === "pick") {
-    // Do something to handle the activity
-  }
-});
-

一旦執行所有動作以處理 Activity 之後，我們就可以呼叫請求的 postResult() 函式，針對委託該 Activity 的 App，回傳所需的結果。

-

如果發生錯誤，則可呼叫請求的 postError() 函式，以回傳該 Activity 的錯誤訊息。

-
navigator.mozSetMessageHandler('activity', function(activityRequest) {
-  var option = activityRequest.source;
-
-  if (option.name === "pick") {
-    // Do something to handle the activity
-    ...
-
-    // Send back the result
-    if (picture) {
-      activityRequest.postResult(picture);
-    } else {
-      activityRequest.postError("Unable to provide a picture");
-    }
-  }
-});
-
-

注意：如果並未呼叫 postError 或 postResult()，則均應由 UA 送出錯誤訊息；例如使用者離開了 App (關閉桌面上的分頁，或回到行動裝置的首頁) 的情形。

-
-

開始 Activity

-

就 Web Activities 的另一方面來說，就是有 App 會將 Activity 委託予我們的 App。若要執行這種委託作業，則 App 必須建立 (Instantiate) MozActivity 物件，進而呼叫 Activity。這種物件其實就是 DOMRequest 物件，可等待來自於 Activity Handler 的任何反應。只要建立了物件之後，就會開始 Activity (也會立刻為使用者顯示 UI)。

-
var activity = new MozActivity({
-  // Ask for the "pick" activity
-  name: "pick",
-
-  // Provide de data required by the filters of the activity
-  data: {
-    type: "image/jpeg"
-  }
-});
-
-activity.onsuccess = function() {
-  var picture = this.result;
-  console.log("A picture has been retrieve");
-};
-
-activity.onerror = function() {
-  console.log(this.error);
-};
-
-

Firefox OS 的 Activity

-

Gaia 即為 Firefox OS 的原生介面，並已內建許多 App 以定義基本的 Activity。這些 Activity 如下：

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameApplicationExpected Data (filters)Comments
browseGallery - 
-type: "photos"
- 		 
configureSettings - 
-target: "device"
- 		 
costcontrol/balanceCostcontrolNone 
costcontrol/data_usageCostcontrolNone 
costcontrol/telephonyCostcontrolNone 
dialCommunication - 
-type: "webtelephony/number",
-number: {
-  regexp:/^[\\d\\s+#*().-]{0,50}$/
-}
- 		當 App 要傳送一通電話時使用。
newCommunication - 
-type: "webcontacts/contact"
- 		當 App 要建立新的聯絡人資料時使用。
Email - 
-type: "mail"
- 		 
SMS - 
-type: "websms/sms",
-number: {
-  regexp:/^[\\w\\s+#*().-]{0,50}$/
-}
- 		當 App 要傳送一封文字簡訊時使用。
openCommunication - 
-type: "webcontacts/contact"
- 		 
Gallery - 
-type: [
-  "image/jpeg",
-  "image/png",
-  "image/gif",
-  "image/bmp"
-]
- 		 
Music - 
-type: [
-  "audio/mpeg",
-  "audio/ogg",
-  "audio/mp4"
-]
- 		 
Video - 
-type: [
-  "video/webm",
-  "video/mp4",
-  "video/3gpp",
-  "video/youtube"
-]
-

Also expect a blob property which is a {{domxref("Blob")}} object.

- 		當 App 要顯示影片時使用 (而 view 的Activity 同樣可辦到) 。
pickCamera, Gallery, Wallpaper - 
-type: ["image/*", "image/jpeg"]
- 		當 App 要取得圖片時使用。
Communication - 
-type: [
-  "webcontacts/contact",
-  "webcontacts/email"
-]
- 		當 App 要檢索某個聯絡人資訊或電子郵件時使用。
recordCamera - 
-type: ["photos", "videos"]
- 		當 App 要錄製影片時使用。
save-bookmarkHomescreen - 
-type: "url",
-url: {
-  required:true,
-  regexp:/^https?:/
-}
- 		 
shareBluetooth - 
-number: 1
-
- 		 
Email, Wallpaper - 
-type: "image/*"
- 		當 App 要分享圖片時使用。
viewBrowser - 
-type: "url"
-url: {
-  required: true,
-  regexp: /^https?:.{1,16384}$/
-}
- 		當 App 要開啟 URL 時使用。
Email - 
-type: "url",
-url: {
-  required:true,
-  regexp:/^mailto:/
-}
- 		 
PDFjs - 
-type: "application/pdf"
- 		當 App 要顯示 PDF 文件內容時使用。
Video - 
-type: [
-  "video/webm",
-  "video/mp4",
-  "video/3gpp",
-  "video/youtube"
-]
-

Also expect a url property which is a string.

- 		當 App 要顯示影片時使用 (而 open 的 Activity 同樣可辦到)。
updateCommunication - 
-type: "webcontacts/contact"
- 		當 App 要更新聯絡人時使用。
-

規格

-

Web Activities 目前尚不屬於任何規格，但其中某些部分與當前的 Web Intents 有所重複。事實上，Mozilla 規劃 Web Activities 正是想提議用以替代 Web Intents。若要進一步了解相關資訊，可參閱 Web Intents Task Force ML 上的討論。

-

另可參閱

- diff --git a/files/zh-tw/webapi/webfm_api/index.html b/files/zh-tw/webapi/webfm_api/index.html deleted file mode 100644 index 76a85372f1..0000000000 --- a/files/zh-tw/webapi/webfm_api/index.html +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: WebFM API -slug: WebAPI/WebFM_API -translation_of: Archive/B2G_OS/API/WebFM_API ---- -

{{ non-standard_header() }}

-

{{ B2GOnlyHeader2('installed') }}

-

摘要

-

WebFM API 可存取裝置的 FM 收音機，進而開/關收音機並切換電台。另可透過 navigator.mozFMRadio 屬性 (為 FMRadio 物件) 而存取此 API。

-

開/關收音機

-

FMRadio.enable() 函式可開啟收音機；FMRadio.disable() 函式則是關閉收音機。

-

在開啟收音機之前，應先檢查裝置是否具備天線 (若無天線，內建的收音機當然也收不到訊號)。透過 FMRadio.antennaAvailable 屬性即可獲得天線資訊。行動裝置往往將耳機纜線作為收音機天線。由於使用者可隨時插入/拔除耳機，因此每次只要天線狀態改變，WebFM API 均將發出 antennaavailablechange 事件。

-

開啟收音機就必須要有可聆聽的頻道。而頻率 (以 MHz 為單位) 將以數字形式傳送至 FMRadio.enable() 函式。

-
// 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();
-  }
-})
-
-
-

注意：透過裝置上的可用 normal 音訊通道，即可輸出音訊。

-
-

切換不同頻率

-

使用者可手動或讓裝置自動切換頻率。不論是手動或自動，均將透過 FMRadio.frequency 屬性存取目前的收音機頻率。該屬性則以 MHz 呈現頻率。

-

手動切換

-

必須以 FMRadio.setFrequency() 函式設定新的頻率，但所能設定的值有某些限制。此函式將回傳 DOMRequest 物件，以處理函式呼叫的成功或錯誤狀態。而頻率必須滿足下列要求：

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

自動搜尋

-

WebFM API 亦可自動搜尋收音機頻道。我們使用 FMRadio.seekUp() 與 FMRadio.seekDown() 函式。前者將從目前頻道再尋找更高的頻率；後者反之。此 2 組函式均將回傳 DOMRequest 物件，以處理函式呼叫的成功或錯誤狀態。

-

WebFM API 亦可自動搜尋收音機頻道。我們使用 FMRadio.seekUp() 與 FMRadio.seekDown() 函式。前者將從目前頻道再尋找更高的頻率；後者反之。此 2 組函式均將回傳 DOMRequest 物件，以處理函式呼叫的成功或錯誤狀態。

-

且此 2 組函式在到達 frequencyLowerBound 或 frequencyUpperBound 的值之後，均將再次循環較高/較低頻率。一旦找到新頻道，就會更改目前頻率並發出 frequencychange 事件。

-

此 2 組函式並無法同時搜尋，也就是無法同時往上並往下搜尋頻率，否則將發生錯誤。而呼叫 FMRadio.cancelSeek() 函式即可停止搜尋頻率。此函式亦將回傳 DOMRequest 物件。

-
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');
-});
-
-

規格

-

尚無任何規格。

-

另可參閱

- diff --git a/files/zh-tw/webapi/websms/index.html b/files/zh-tw/webapi/websms/index.html deleted file mode 100644 index 16ef3887cf..0000000000 --- a/files/zh-tw/webapi/websms/index.html +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: WebSMS -slug: WebAPI/WebSMS -translation_of: Archive/B2G_OS/API/Mobile_Messaging_API ---- -

{{ non-standard_header() }}

- -

{{ B2GOnlyHeader2('certified') }}

- -

摘要

- -

WebSMS API 可讓網頁內容能建立、傳送、接收文字簡訊 (SMS) 或多媒體訊息 (MMS)。

- -

透過 window.navigator.mozSms (將回傳 MozSmsManager 物件)，或是 window.navigator.mozMobileMessage (將回傳 MozMobileMessageManager 物件)，均可存取此 API。

- -

DOM 介面

- -

SMS 介面

- - - -

MMS 與 SMS 介面

- - - -

範例程式碼與介紹

- - - -

規格

- -

此 API 目前尚未成為標準規格。可至 W3C 的 System Application Working Group 參與相關討論。

- - - - - - - - - - - - - - - - -
SpecificationStatusComment
{{SpecName('Messaging')}}{{Spec2('Messaging')}}Editor Draft (WIP).
- -

瀏覽器相容性

- -

當然，主要支援行動瀏覽器。

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatNo() }}{{ CompatGeckoMobile("12.0") }}{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}
-
- -

相關設定

- - - -

另可參閱

- - -- cgit v1.2.3-54-g00ecf