From 218934fa2ed1c702a6d3923d2aa2cc6b43c48684 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:43:23 -0500 Subject: initial commit --- files/zh-tw/webapi/web_activities/index.html | 415 +++++++++++++++++++++++++++ 1 file changed, 415 insertions(+) create mode 100644 files/zh-tw/webapi/web_activities/index.html (limited to 'files/zh-tw/webapi/web_activities/index.html') diff --git a/files/zh-tw/webapi/web_activities/index.html b/files/zh-tw/webapi/web_activities/index.html new file mode 100644 index 0000000000..6c71c46bd8 --- /dev/null +++ b/files/zh-tw/webapi/web_activities/index.html @@ -0,0 +1,415 @@ +--- +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 上的討論。

+

另可參閱

+ -- cgit v1.2.3-54-g00ecf