Android API Guides---App Widget Host

Android API Guides---App Widget Host
應用的Widget主機
大多數Android裝置上可用的Andr??oid主畫面允許使用者嵌入應用小工具，以便快速存取的內容。如果你正在構建一個家庭更換或類似的應用程式，也可以允許使用者通過實現AppWidgetHost嵌入應用程式組件。這不是大多數應用程式都不會需要做的事情，但如果你正在建立您自己的主機，它瞭解合約義務的主機隱含同意是非常重要的。

本檔案的重點參與實施定製AppWidgetHost的責任。對於如何?一個AppWidgetHost樣本，請參見為Android主畫面啟動的原始碼。

這裡是參與實施定製AppWidgetHost關鍵類和概念的概述：

應用的Widget HOST-的AppWidgetHost提供與AppWidget服務的應用程式，如主畫面，希望嵌入應用小組件在其UI互動。一個AppWidgetHost必須有一個ID，它是主機自己的包中是唯一的。此ID在跨越主機的所有使用持久性。該ID通常是在應用程式中指定一個寫入程式碼值。
應用小工具ID-每個應用外掛程式執行個體是在結合的時間分配了一個唯一的ID（見bindAppWidgetIdIfAllowed（），更詳細地在裝訂應用程式視窗小組件所討論的）。唯一ID是通過使用allocateAppWidgetId（）主機獲得。該ID是橫跨外掛程式，即的壽命持久，直到它從主機中刪除。任何特定的主機的狀態（例如大小和小組件的位置）應當由主機包被持久並與該應用微件ID相關聯。
應用程式的widget主機取景AppWidgetHostView可以被認為是一幀，該外掛程式是包裹在每當需要將其顯示出來。應用程式外掛程式每小組件是由主機充氣時間分配給AppWidgetHostView。
選項??Bundle-該AppWidgetHost使用選項束將資訊傳達給所述AppWidgetProvider如何正在顯示微件（例如，尺寸範圍，以及是否該視窗小組件上的鎖定螢幕或主畫面）。該資訊允許AppWidgetProvider的基礎上如何以及在哪裡顯示定製Widget的內容和外觀。您可以使用updateAppWidgetOptions（）和updateAppWidgetSize（）來修改應用程式widget的包。這兩種方法觸發一個回調至AppWidgetProvider。
結合應用小工具


當使用者將某個應用外掛程式到主機時，發生所謂的裝訂處理。結合是指一種特定的應用微件ID，以一個特定的主機和一個特定AppWidgetProvider相關聯。有實現這一目標，取決於什麼版本的Andr??oid您的應用程式上啟動並執行不同方式。


在Android 4.0和更低的結合應用小工具

在運行Android 4.0版和更低的裝置，使用者通過系統的活動，允許使用者選擇一個小組件添加應用程式組件。這含蓄地做了許可權檢查，也就是說，通過將應用程式視窗小組件，使用者被隱性授予許可權，以您的應用程式小組件添加到主機。這裡是示出該方法中，從原來的啟動器所採取的樣本。在這個片段中，一個事件處理常式調用startActivityForResult（）在響應使用者操作的請求代碼REQUEST_PICK_APPWIDGET：

private static final int REQUEST_CREATE_APPWIDGET = 5;private static final int REQUEST_PICK_APPWIDGET = 9;...public void onClick(DialogInterface dialog, int which) {  switch (which) {  ...    case AddAdapter.ITEM_APPWIDGET: {      ...      int appWidgetId =           Launcher.this.mAppWidgetHost.allocateAppWidgetId();      Intent pickIntent =           new Intent(AppWidgetManager.ACTION_APPWIDGET_PICK);      pickIntent.putExtra          (AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);      ...      startActivityForResult(pickIntent, REQUEST_PICK_APPWIDGET);      break;  }  ...}

當系統活動結束時，它返回與使用者選擇的應用小工具，你的活動的結果。在下面的例子中，該活動通過調用廣告AppWidget（）添加應用程式組件響應：

public final class Launcher extends Activity     implements View.OnClickListener, OnLongClickListener {  ...  @Override  protected void onActivityResult(int requestCode, int resultCode, Intent data) {    mWaitingForResult = false;    if (resultCode == RESULT_OK && mAddItemCellInfo != null) {      switch (requestCode) {        ...        case REQUEST_PICK_APPWIDGET:          addAppWidget(data);          break;        case REQUEST_CREATE_APPWIDGET:          completeAddAppWidget(data, mAddItemCellInfo, !mDesktopLocked);          break;        }    }     ...  }}

該方法添加AppWidget（）檢查是否應用程式組件需要它添加之前配置：

void addAppWidget(Intent data) {  int appWidgetId = data.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, -1);  String customWidget = data.getStringExtra(EXTRA_CUSTOM_WIDGET);  AppWidgetProviderInfo appWidget =       mAppWidgetManager.getAppWidgetInfo(appWidgetId);  if (appWidget.configure != null) {    // Launch over to configure widget, if needed.    Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_CONFIGURE);    intent.setComponent(appWidget.configure);    intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);    startActivityForResult(intent, REQUEST_CREATE_APPWIDGET);  } else {    // Otherwise, finish adding the widget.  }}

有關配置的詳細討論，請參閱建立應用程式視窗小組件配置活動。
一旦應用小工具已準備就緒，下一步就是做它添加到工作區的實際工作。原來發射使用的方法稱為完全加AppWidget（）來做到這一點。
在Android4.1及更高的結合應用小工具
搭載Android 4.1增加了API，用於一個更精簡的綁定過程。這些API也有可能使一台主機綁定提供自訂UI。要使用此改進方法，您的應用程式必須申報在其清單中BIND_APPWIDGET許可權：

但是，這僅僅是第一步。在運行時，使用者必須明確授予許可權，您的應用程式，使其能夠應用小組件添加到主機。要測試你的應用程式是否有許可權新增的小工具，可以使用bindAppWidgetIdIfAllowed（）方法。如果bindAppWidgetIdIfAllowed（）返回false，您的應用程式必須顯示一個對話方塊，提示使用者授予許可權（“允許”或“總是允許”，以涵蓋所有未來的應用小工具添加）。這段代碼提供了如何顯示對話方塊的例子：

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);// This is the options bundle discussed aboveintent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

主機也必須檢查使用者是否補充說，需要配置一個應用程式組件。有關此主題的更多討論，請參閱建立應用程式視窗小組件配置活動。
主持人職責
什麼版本你定位？
您實現您的主機使用的方法應該取決於你的目標是什麼Android版本。許多本節所述的功能在3.0或更高版本進行了介紹。例如：
Android 3.0的（API等級11）介紹了小組件自動推進的行為。
Android的3.1（API等級12）引入了調整組件的能力。
搭載Android 4.0（API等級15）引入該把責任在主機上管理填充填充政策的改變。
搭載Android 4.1（API等級16）增加了一個API，允許小組件供應商，以擷取有關在其控制項執行個體被託管環境的更多詳細資料。
Android的4.2（API等級17）推出期權包和bindAppWidgetIdIfAllowed（）方法。還引入了鎖屏小組件。
如果你的目標早期裝置，參考原始啟動作為一個例子。
外掛程式開發人員可以指定使用AppWidgetProviderInfo中繼資料視窗小組件的一些配置設定。這些配置選項，在下面更詳細討論的，可以通過從與小視窗提供者關聯的AppWidgetProviderInfo對象主機進行檢索。
無論你的目標了Android版本，所有主機具有以下職責：
當添加視窗小組件，則必須按照上述分配組件ID。您還必須確保當一個小組件從主機中刪除，你可以調用deleteAppWidgetId（）來釋放小組件ID。
當添加視窗小組件，可以肯定如果存在推出配置活動，如從配置活動更新應用程式視窗小組件描述。這是許多應用小組件的必要步驟可以正確顯示前。
每一個應用程式視窗小組件指定的dps的最小寬度和高度，如AppWidgetProviderInfo定義中繼資料（採用了android：了minWidth和android：了minHeight）。確保小組件至少有這麼多的dps布局。例如，許多主機對齊柵格表徵圖和視窗小組件。在這種情況下，在預設情況下，主機應使用滿足了minWidth和了minHeight約束單元的最小數量添加的應用組件。
除了上面列出的要求，具體版本的平台引入放置在主機上新的責任功能。這些將在以下各節中描述。
Android 3.0的
Android 3.0的（API等級11）介紹了一個小工具，指定autoAdvanceViewId（）的能力。此視圖ID應指向一個可前進，如StackView或AdapterViewFlipper的一個執行個體。這表明主機應該呼籲這種觀點提前（）的間隔認為適當的主機（考慮到是否有意義推進小組件，例如，主機可能不希望，如果它提前一個小組件是另一個頁上，或如果螢幕被關閉）。
Android版3.1
Android的3.1（API等級12）引入了調整組件的能力。一個小組件可以指定它使用Android是可調整大小：在AppWidgetProviderInfo元resizeMode屬性，並說明它是否支援水平和/或垂直大小調整。在Android 4.0的（API層級14）介紹，小組件也可以指定一個機器人：minResizeWidth和/或Android：minResizeHeight。
它是主機的責任，這使該外掛程式被水平和/或垂直地調整，由外掛程式規定的。這說明它是可以調整大小可以調整任意大，但不應該比大小由Android規定值小的組件：minResizeWidth和android：minResizeHeight。有關樣本實現，請參閱AppWidgetResizeFrame中的launcher2。
Android 4.0的
搭載Android 4.0（API等級15）引入該把責任在主機上管理填充填充政策的改變。作為4.0，應用小組件不再包括自己的填充。相反，系統添加填充每個組件，基於當前螢幕的特性。這導致一個更均勻，在網格組件的一致呈現。為了協助該主機的應用程式視窗小組件，該平台提供的方法getDefaultPaddingForWidget應用程式（）。計算細胞的數量分配給widget時應用程式可以調用此方法來擷取系統定義的填充和解釋它。
搭載Android 4.1
搭載Android 4.1（API等級16）增加了一個API，允許小組件供應商，以擷取有關在其控制項執行個體被託管環境的更多詳細資料。具體地，主機暗示至約在正被顯示的視窗小組件的尺寸小視窗提供者。這是主機的責任提供這種規模的資訊。
主機通過updateAppWidgetSize提供該資訊（）。的大小指定為在DPS的最小和最大寬度/高度。一個範圍（而不是一個固定的大小）的原因是因為一個小視窗的寬度和高度可以與取向發生變化。你不希望主機必須更新其所有的旋轉組件，因為這可能會導致嚴重的系統運行緩慢。這些值應從前的外掛程式來更新被放置，所述外掛程式被調整大小的任何時間，任何時間發射膨脹用於在給定引導在第一時間（作為值不跨越啟動持續）的組件。
Android 4.2版
對於選擇在捆綁綁定時指定的Andr??oid 4.2（API等級17）增加的能力。這是指定的應用程式外掛程式選項，包括大小的理想方法，因為它給了AppWidgetProvider直接存取資料的選項在第一次更新。這可以通過使用該方法bindAppWidgetIdIfAllowed（）來實現。有關此主題的更多討論，請參閱繫結應用程式組件。
Android 4.2版還引入了鎖屏小組件。當主機在鎖定螢幕上的小組件，主機必須指定應用程式視窗小組件選項包內該資訊（AppWidgetProvider可以使用這些資訊來適當方式進行樣式設定）。要指定一個widget作為鎖屏外掛程式，使用updateAppWidgetOptions（），並包括與價值WIDGET_CATEGORY_KEYGUARD領域OPTION_APPWIDGET_HOST_CATEGORY。此選項預設為WIDGET_CATEGORY_HOME_SCREEN，所以也沒有明確要求，設定本作的主畫面主機。
請確保您的主機只增加了應用小工具，適合你的應用程式，例如，如果你的主機是主畫面，確保了android：在AppWidgetProviderInfo元widgetCategory屬性包括旗WIDGET_CATEGORY_HOME_SCREEN。同樣，對於鎖屏，確保欄位包括標誌WIDGET_CATEGORY_KEYGUARD。有關此主題的更多討論，請參閱鎖屏啟用應用程式的視窗小組件。