mozilla

Revision 349899 of Web Activity

  • Revision slug: Mozilla/Firefox_OS/第三方應用開發者指南/Web_Activity
  • Revision title: Web Activity
  • Revision id: 349899
  • Created:
  • Creator: evelynhung
  • Is current revision? No
  • Comment

Revision Content

Web Activity

許多手機上常見的功能例如:選取聯絡人、撥打電話、照相是您的 App 會需要用到的功能。您可以不必重新發明輪子,而利用「Web Activity」的技術呼叫其他的 App 來完成任務。Web Activity 可以實作兩個 App 間的切換,例如從「相機」切換到「圖片集」,或者是「簡訊」使用「聯絡人」選取一個簡訊發送對象。

在您的 App 中只需要描述所需的操作,系統會幫您檢查手機中有哪些 App 提供這些操作。以下是一個具體的例子。這是在「相機」中的一段程式碼,用來切換到別的 App 瀏覽相片。

  var act = new MozActivity({                                                                                             
    name: 'browse',
    data: {
      type: 'photos'
    }   
  });
  act.onerror = function(e) {
    if (act.error.name === 'NO_PROVIDER') {   
      console.warn('Error: no activity provider');
    }    
    else {
      console.warn('Error: unknown activity - ' + act.error.name);
    }    
  };

在這段程式碼中,「相機」新增了一個 MozActivity 物件並在參數物件中聲明該 activity 是「瀏覽(browse)」的動作,瀏覽的資料是「相片(photos)」。請注意它並非直接指定要切換到「圖片集」 ,而是由系統決定哪個 App 提供這樣的行為,若有多個 App 同時提供一樣的行為時,系統會產生一個選單讓使用者選取。
參數物件的 'data' 欄位可以提供額外所需的資料內容,讓承接 activity 任務的 App 決定是否根據資料內容做其他處理。

讓我們來看看提供 Web Activity 的 App 該如何聲明它的 activity 及相關設定。

"activities": {
  "browse": {
    "filters": {
      "type": "photos"
     },  
    "disposition": "window"
  }
}


像「圖片集」這樣的 App 可以在它的 manifest.webapp 檔案中聲明它提供瀏覽相片的 activity,如上所示。它提供一個「瀏覽(browse)」動作的 activity,瀏覽的資料是「相片(photos)」作為篩選條件。這樣的 activity 聲明宣告,便能與上面的 MozActivity 呼叫匹配,成為能承接這個 activity 的對象之一。若手機中只有這一個 App 有這樣的 activity 宣告,那系統預設就會將這個 App 開啓,但若有多個 App 都能夠執行這個任務,系統會產生一個選單讓使用者選取。

"disposition": "window"

依照不同 App 的需求,目前在 Firefox OS 中有兩種形式的 Web Activity ,一種為「視窗切換」(window disposition) 、一種為「畫面滑入」(inline disposition)。前者視覺上是 App 之間的切換,後者則是承接 activity 的 App 會由下方滑入,覆蓋在目前 App 之上。除了視覺上的效果不同之外,「畫面滑入」的 Web Activity 在 activity 處理結束畫面關閉之後(例如選擇了一張圖片),會回到原本的 App ,而「視窗切換」的 Web Activity 則需要使用者自己手動回到主畫面 (homescreen) 或者 App 列表,才能夠切換回原本的 App 。提供 Web Activity 的 App 可以自行決定提供哪種形式讓其他 App 呼叫。

除了在 manifest.webapp 宣告 Web Activity 之外,程式碼中當然也要有具體的實作。如下所示是「圖片集」 App 的實作程式碼:

  navigator.mozSetMessageHandler('activity', function activityHandler(a) {
    var activityName = a.source.name;    
    if ( activityName === 'browse') {
      // If this was a cold start, then the db needs to be initialized.
      if (!photodb)
        initDB(true);  // Initialize both the photo and video databases
      // Always switch to the list of thumbnails.
      setView(thumbnailListView);
    }
  });

當有 MozActivity 的呼叫發生時,會以系統訊息的方式通知將要被開啓的 App 。因此這個 App 必須要註冊 'activity' 的系統訊息,提供對應的回呼函示 (callback function),明白表示當 MozActivity 的呼叫發生時, App 被開啓後將如何處理這個 activity。這邊「圖片集」 App 執行初始化圖庫、以縮圖方式列出圖庫內的相片。
「圖片集」 App 在 manifest.webapp 的聲明中使用 window disposition 的方式處理 activity,表示使用者並不會在完成什麼動作之後回到「相機」 App 。「圖片集」 App 就如同是被使用者手動在主畫面(homescreen)點選開啟一般,由使用者自行決定何時離開。

"disposition": "inline"

我們來看另一種形式的  Web Activity。同樣以「圖片集」 App 為例,它可以提供一個  Web Activity 供其他 App 挑選照片。挑選照片的 actvity 必須要把被挑選到的相片名稱、路徑…等等的資訊傳回給呼叫方(caller),並且在挑選動作完成後回到呼叫方的 App 。這個情況下,使用 inline disposition 的形式來實作。
manifest.webapp 的宣告是這樣的:

"activities": {
  "pick": {
    "filters": {
      "type": ["image/jpeg", "image/png"]
    },  
    "disposition": "inline",
    "returnValue": true,
    "href": "/index.html#pick"
  }  
}


它提供一個「挑選(pick)」動作的 activity,挑選的資料形態以一個陣列作為篩選條件,提供挑選 "image/jpeg" 或 "image/png" 圖檔,並且會回傳挑選的值。
由於 inline disposition 的 Web Activity 是以單一畫面滑入的形式被開啓,不同於 window disposition 是整個 App 被開啓,這裡我們可以多指派一個聲明表示要處理這個  Web Activity 的頁面位置 ("href": "/index.html#pick")。

這個頁面會有具體的程式碼實作如下:

  navigator.mozSetMessageHandler('activity', function activityHandler(activityRequest) {
    var activityName = activityRequest.source.name;                                                                                    
    if (activityName === 'pick') {
      var pickType = activityRequest.source.data.type;
      var width = activityRequest.source.data.width;
      var height = activityRequest.source.data.height;
      var blob = startPick(pickType, width, height);
      if (blob) {     
        activityRequest.postResult({type: pickType, blob: blob});
      } else {
        activityRequest.postError('pick cancelled');
      }
    }
  });


當有 MozActivity 的呼叫發生時,「圖片集」 App 收到 'activity' 的系統訊息,回呼函示 (callback function)會被運行,它可以讀取請求此 activity 的 App 所提供的數據,例如所需的圖片類型、寬度、高度… 等,作為陳列圖片清單的參考。當使用者成功選取了一張圖片,呼叫 activityRequest.postResult 傳回挑選結果。這個結果是個物件,讓呼叫 MozActivity 的 App 能夠知道圖片相關的資訊。

在「設定」 App 中希望能讓使用者選取一張圖片做為桌布,只需要呼叫 activity 來完成。

  var activityRequest = new MozActivity({
     name: 'pick',
     data: {
        type: 'image/jpeg',
        width: 320,
        height: 480
      }   
  });
  activityRequest.onsuccess = function onPickSuccess() {
    if (!activityRequest.result.blob)
      return;

    var reader = new FileReader();
    reader.readAsDataURL(activityRequest.result.blob);
    reader.onload = function() {
       navigator.mozSettings.createLock().set({
          'wallpaper.image': reader.result
       });
       displayImgae(reader.result);
    };
  };  
  activityRequest.onerror = function onPickError() {
     console.warn('pick failed!');
  };

在這段程式碼中,「設定」呼叫了一個 MozActivity 並在參數物件中聲明該 activity 是「挑選(pick)」的動作,挑選的是「image/jpeg」檔案,限定寬度與高度為 320 x 480。同樣的,「設定」 App 不知道實際上哪個 App 會被呼叫,它只在意當挑選動作完成時,它的 onsuccess 回呼函示會被執行,取得 blob 內容,並且畫面焦點將回到它身上,讓它可以顯示選取的圖片。系統將決定哪個 App 提供這樣的行為,若有多個 App 同時提供一樣的行為時,系統會產生一個選單讓使用者選取。
 

Revision Source

<h4>Web Activity</h4>
<p>許多手機上常見的功能例如:選取聯絡人、撥打電話、照相是您的 App 會需要用到的功能。您可以不必重新發明輪子,而利用「Web Activity」的技術呼叫其他的 App 來完成任務。Web Activity 可以實作兩個 App 間的切換,例如從「相機」切換到「圖片集」,或者是「簡訊」使用「聯絡人」選取一個簡訊發送對象。<br />
  <br />
  在您的 App 中只需要描述所需的操作,系統會幫您檢查手機中有哪些 App 提供這些操作。以下是一個具體的例子。這是在「相機」中的一段程式碼,用來切換到別的 App 瀏覽相片。</p>
<pre>
  var act = new MozActivity({                                                                                             
    name: 'browse',
    data: {
      type: 'photos'
    }   
  });
  act.onerror = function(e) {
    if (act.error.name === 'NO_PROVIDER') {   
      console.warn('Error: no activity provider');
    }    
    else {
      console.warn('Error: unknown activity - ' + act.error.name);
    }    
  };</pre>
<p>在這段程式碼中,「相機」新增了一個 MozActivity 物件並在參數物件中聲明該 activity 是「瀏覽(browse)」的動作,瀏覽的資料是「相片(photos)」。請注意它並非直接指定要切換到「圖片集」 ,而是由系統決定哪個 App 提供這樣的行為,若有多個 App 同時提供一樣的行為時,系統會產生一個選單讓使用者選取。<br />
  參數物件的 'data' 欄位可以提供額外所需的資料內容,讓承接 activity 任務的 App 決定是否根據資料內容做其他處理。<br />
  <br />
  讓我們來看看提供 Web Activity 的 App 該如何聲明它的 activity 及相關設定。</p>
<pre>
"activities": {
  "browse": {
    "filters": {
      "type": "photos"
     },  
    "disposition": "window"
  }
}</pre>
<p><br />
  像「圖片集」這樣的 App 可以在它的 manifest.webapp 檔案中聲明它提供瀏覽相片的 activity,如上所示。它提供一個「瀏覽(browse)」動作的 activity,瀏覽的資料是「相片(photos)」作為篩選條件。這樣的 activity 聲明宣告,便能與上面的 MozActivity 呼叫匹配,成為能承接這個 activity 的對象之一。若手機中只有這一個 App 有這樣的 activity 宣告,那系統預設就會將這個 App 開啓,但若有多個 App 都能夠執行這個任務,系統會產生一個選單讓使用者選取。</p>
<h4>"disposition": "window"</h4>
<p>依照不同 App 的需求,目前在 Firefox OS 中有兩種形式的 Web Activity ,一種為「視窗切換」(window disposition) 、一種為「畫面滑入」(inline disposition)。前者視覺上是 App 之間的切換,後者則是承接 activity 的 App 會由下方滑入,覆蓋在目前 App 之上。除了視覺上的效果不同之外,「畫面滑入」的 Web Activity 在 activity 處理結束畫面關閉之後(例如選擇了一張圖片),會回到原本的 App ,而「視窗切換」的 Web Activity 則需要使用者自己手動回到主畫面 (homescreen) 或者 App 列表,才能夠切換回原本的 App 。提供 Web Activity 的 App 可以自行決定提供哪種形式讓其他 App 呼叫。<br />
  <br />
  除了在 manifest.webapp 宣告 Web Activity 之外,程式碼中當然也要有具體的實作。如下所示是「圖片集」 App 的實作程式碼:</p>
<pre>
  navigator.mozSetMessageHandler('activity', function activityHandler(a) {
    var activityName = a.source.name;    
    if ( activityName === 'browse') {
      // If this was a cold start, then the db needs to be initialized.
      if (!photodb)
        initDB(true);  // Initialize both the photo and video databases
      // Always switch to the list of thumbnails.
      setView(thumbnailListView);
    }
  });
</pre>
<p>當有 MozActivity 的呼叫發生時,會以系統訊息的方式通知將要被開啓的 App 。因此這個 App 必須要註冊 'activity' 的系統訊息,提供對應的回呼函示 (callback function),明白表示當 MozActivity 的呼叫發生時, App 被開啓後將如何處理這個 activity。這邊「圖片集」 App 執行初始化圖庫、以縮圖方式列出圖庫內的相片。<br />
  「圖片集」 App 在 manifest.webapp 的聲明中使用 window disposition 的方式處理 activity,表示使用者並不會在完成什麼動作之後回到「相機」 App 。「圖片集」 App 就如同是被使用者手動在主畫面(homescreen)點選開啟一般,由使用者自行決定何時離開。</p>
<h4>"disposition": "inline"</h4>
<p>我們來看另一種形式的&nbsp; Web Activity。同樣以「圖片集」 App 為例,它可以提供一個&nbsp; Web Activity 供其他 App 挑選照片。挑選照片的 actvity 必須要把被挑選到的相片名稱、路徑…等等的資訊傳回給呼叫方(caller),並且在挑選動作完成後回到呼叫方的 App 。這個情況下,使用 inline disposition 的形式來實作。<br />
  manifest.webapp 的宣告是這樣的:</p>
<pre>
"activities": {
  "pick": {
    "filters": {
      "type": ["image/jpeg", "image/png"]
    },  
    "disposition": "inline",
    "returnValue": true,
    "href": "/index.html#pick"
  }  
}</pre>
<p><br />
  它提供一個「挑選(pick)」動作的 activity,挑選的資料形態以一個陣列作為篩選條件,提供挑選 "image/jpeg" 或 "image/png" 圖檔,並且會回傳挑選的值。<br />
  由於 inline disposition 的 Web Activity 是以單一畫面滑入的形式被開啓,不同於 window disposition 是整個 App 被開啓,這裡我們可以多指派一個聲明表示要處理這個&nbsp; Web Activity 的頁面位置 ("href": "/index.html#pick")。<br />
  <br />
  這個頁面會有具體的程式碼實作如下:</p>
<pre>
  navigator.mozSetMessageHandler('activity', function activityHandler(activityRequest) {
    var activityName = activityRequest.source.name;                                                                                    
    if (activityName === 'pick') {
      var pickType = activityRequest.source.data.type;
      var width = activityRequest.source.data.width;
      var height = activityRequest.source.data.height;
      var blob = startPick(pickType, width, height);
      if (blob) {     
        activityRequest.postResult({type: pickType, blob: blob});
      } else {
        activityRequest.postError('pick cancelled');
      }
    }
  });</pre>
<p><br />
  當有 MozActivity 的呼叫發生時,「圖片集」 App 收到 'activity' 的系統訊息,回呼函示 (callback function)會被運行,它可以讀取請求此 activity 的 App 所提供的數據,例如所需的圖片類型、寬度、高度… 等,作為陳列圖片清單的參考。當使用者成功選取了一張圖片,呼叫 activityRequest.postResult 傳回挑選結果。這個結果是個物件,讓呼叫 MozActivity 的 App 能夠知道圖片相關的資訊。<br />
  <br />
  在「設定」 App 中希望能讓使用者選取一張圖片做為桌布,只需要呼叫 activity 來完成。</p>
<pre>
  var activityRequest = new MozActivity({
     name: 'pick',
     data: {
        type: 'image/jpeg',
        width: 320,
        height: 480
      }   
  });
  activityRequest.onsuccess = function onPickSuccess() {
    if (!activityRequest.result.blob)
      return;

    var reader = new FileReader();
    reader.readAsDataURL(activityRequest.result.blob);
    reader.onload = function() {
       navigator.mozSettings.createLock().set({
          'wallpaper.image': reader.result
       });
       displayImgae(reader.result);
    };
  };  
  activityRequest.onerror = function onPickError() {
     console.warn('pick failed!');
  };
</pre>
<p>在這段程式碼中,「設定」呼叫了一個 MozActivity 並在參數物件中聲明該 activity 是「挑選(pick)」的動作,挑選的是「image/jpeg」檔案,限定寬度與高度為 320 x 480。同樣的,「設定」 App 不知道實際上哪個 App 會被呼叫,它只在意當挑選動作完成時,它的 onsuccess 回呼函示會被執行,取得 blob 內容,並且畫面焦點將回到它身上,讓它可以顯示選取的圖片。系統將決定哪個 App 提供這樣的行為,若有多個 App 同時提供一樣的行為時,系統會產生一個選單讓使用者選取。<br />
  &nbsp;</p>
Revert to this revision