--- 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)：
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 如下：

Name Application Expected Data (filters) Comments
browse Gallery 
type: "photos"
  
configure Settings 
target: "device"
  
costcontrol/balance Costcontrol None  
costcontrol/data_usage Costcontrol None  
costcontrol/telephony Costcontrol None  
dial Communication 
type: "webtelephony/number",
number: {
  regexp:/^[\\d\\s+#*().-]{0,50}$/
}
 當 App 要傳送一通電話時使用。
new Communication 
type: "webcontacts/contact"
 當 App 要建立新的聯絡人資料時使用。
Email 
type: "mail"
  
SMS 
type: "websms/sms",
number: {
  regexp:/^[\\w\\s+#*().-]{0,50}$/
}
 當 App 要傳送一封文字簡訊時使用。
open Communication 
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 同樣可辦到) 。
pick Camera, Gallery, Wallpaper 
type: ["image/*", "image/jpeg"]
 當 App 要取得圖片時使用。
Communication 
type: [
  "webcontacts/contact",
  "webcontacts/email"
]
 當 App 要檢索某個聯絡人資訊或電子郵件時使用。
record Camera 
type: ["photos", "videos"]
 當 App 要錄製影片時使用。
save-bookmark Homescreen 
type: "url",
url: {
  required:true,
  regexp:/^https?:/
}
  
share Bluetooth 
number: 1
 
Email, Wallpaper 
type: "image/*"
 當 App 要分享圖片時使用。
view Browser 
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 同樣可辦到)。
update Communication 
type: "webcontacts/contact"
 當 App 要更新聯絡人時使用。

規格

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

另可參閱