介绍桌面widgets和AppWidget框架(译)

 本文翻译自Android Developers Blog:Introducing home screen widgets and the AppWidget framework

Android 1.5 SDK一个令人兴奋的新特性是AppWidget framework,这个框架允许开发者开发widgets，这些widgets可以被用户拖到用户的桌面并且可以交互。widgets可以提供一个full-featured apps的预览，例如可以显示即将到来的日历事件，或者一首后台播放的歌曲的详细信息。

当widgets被拖到桌面上，他们被指定一个保留的空间来显示应用提供的自定义内容。用户可以通过这个widget来和你的应用交互，例如暂停或切换歌曲。如果你有一个后台服务，你可以按照你自己的schedule更新你的widget，或者使用AppWidget framework提供的一个自动的更新机制。

在更高层次上，每个widget就是一个BroadcastReceiver，他们用XML metadata来描述widget的细节。AppWidget framework通过broadcast intents和你的widget通信，例如当需要更新的时候。Widget更新使用RemoteViews被构建和发送。这个RemoteViews被包装成一个layout和特定内容来显示到桌面上。

你可以非常容易的添加widgets到你的应用中，在这篇文章里我将给一个简单的例子：写一个widget来显示Wiktionary “Word of the day.”你可以从这里获取所有的源代码，我将在这里解释Appwidget相关的代码。

首先，你需要一个XML metadata描述这个widget,包括你想在桌面上保留的区域，一个你想展示的初始的layout，和你打算何时更新。Android桌面默认使用cell-based layout,因而它会rounds你请求的尺寸为最接近的cell的尺寸。这是有点疑惑，不过这里有个公式可以帮助你：

Minimum size in dip = (Number of cells * 74dip) – 2dip

在这个例子中，我想使我们的widget占用2 cells的宽度和1 cell的高度，这意味着我应该请求的最小尺寸为146dip * 72dip。我们将要每天更新一次我们的widget，大约是每86,400,000毫秒更新一次。以下是我们的widget的XML metadata:

接下来，让我们把XML metadata捆绑到AndroidManifest的BroadcasrReicever:

最后，让我们写BroadcastReceiver的代码来处理AppWidget的请求。为了帮助widgets管理所有

broadcasr事件，有个helper class叫AppWidgetProvider，这里我们将使用这个类。其中需要注意的最重要的一件事是我们将调用一个后台服务执行定期的更新。这是因BroadcastReceivers是一个Application Not Responding(ANR) timer,这意味着如果运行时间太长，可能需要提示用户强制关闭我们的应用。制作一个web请求可能需要花费一些时间，因此我们使用服务来避免ANR timeouts.

/**

* Define a simple widget that shows the Wiktionary “Word of the day.” To build

* an update we spawn a background {@link Service} to perform the API queries.

*/

public class WordWidget extends AppWidgetProvider {

@Override

public void onUpdate(Context context, AppWidgetManager appWidgetManager,

int[] appWidgetIds) {

// To prevent any ANR timeouts, we perform the update in a service

context.startService(new Intent(context, UpdateService.class));

}

public static class UpdateService extends Service {

@Override

public void onStart(Intent intent, int startId) {

// Build the widget update for today

RemoteViews updateViews = buildUpdate(this);

// Push update for this widget to the home screen

ComponentName thisWidget = new ComponentName(this, WordWidget.class);

AppWidgetManager manager = AppWidgetManager.getInstance(this);

manager.updateAppWidget(thisWidget, updateViews);

}

/**

* Build a widget update to show the current Wiktionary

* “Word of the day.” Will block until the online API returns.

*/

public RemoteViews buildUpdate(Context context) {

// Pick out month names from resources

Resources res = context.getResources();

String[] monthNames = res.getStringArray(R.array.month_names);

// Find current month and day

Time today = new Time();

today.setToNow();

// Build today’s page title, like “Wiktionary:Word of the day/March 21″

String pageName = res.getString(R.string.template_wotd_title,

monthNames[today.month], today.monthDay);

RemoteViews updateViews = null;

String pageContent = “”;

try {

// Try querying the Wiktionary API for today’s word

SimpleWikiHelper.prepareUserAgent(context);

pageContent = SimpleWikiHelper.getPageContent(pageName, false);

} catch (ApiException e) {

Log.e(”WordWidget”, “Couldn’t contact API”, e);

} catch (ParseException e) {

Log.e(”WordWidget”, “Couldn’t parse API response”, e);

}

// Use a regular expression to parse out the word and its definition

Pattern pattern = Pattern.compile(SimpleWikiHelper.WORD_OF_DAY_REGEX);

Matcher matcher = pattern.matcher(pageContent);

if (matcher.find()) {

// Build an update that holds the updated widget contents

updateViews = new RemoteViews(context.getPackageName(), R.layout.widget_word);

String wordTitle = matcher.group(1);

updateViews.setTextViewText(R.id.word_title, wordTitle);[!--empirenews.page--]

updateViews.setTextViewText(R.id.word_type, matcher.group(2));

updateViews.setTextViewText(R.id.definition, matcher.group(3).trim());

// When user clicks on widget, launch to Wiktionary definition page

String definePage = res.getString(R.string.template_define_url,

Uri.encode(wordTitle));

Intent defineIntent = new Intent(Intent.ACTION_VIEW, Uri.parse(definePage));

PendingIntent pendingIntent = PendingIntent.getActivity(context,

0 /* no requestCode */, defineIntent, 0 /* no flags */);

updateViews.setOnClickPendingIntent(R.id.widget, pendingIntent);

} else {

// Didn’t find word of day, so show error message

updateViews = new RemoteViews(context.getPackageName(),

R.layout.widget_message);

CharSequence errorMessage = context.getText(R.string.widget_error);

updateViews.setTextViewText(R.id.message, errorMessage);

}

return updateViews;

}

@Override public IBinder onBind(Intent intent) {

// We don’t need to bind to this service

return null;

}

}

}

到这里，你已经完成了一个简单的widget，它将显示Wiktionary “Word of the day.”。当一个更新被请求时，我们读在线API将最新的数据push到widget上。AppWidget framework会按我们的需要自动更新，例如当一个新的widget添加时，或者新的一天加载新的Word of the day.”。

最后，这里给出一些建议。Widgets推荐被设计成longer-term的内容，不应该经常的被更新。超过每小时的频繁更新会快速消耗掉电量和带宽。建议尽可能的不要频繁更新，或者让你的用户自定义一个更新周期。例如有些人可能想stock ticker每15分钟更新一次，或者可能是一天更新四次。我将在我的另一篇文章giving at Google I/O讨论节省电量的一些额外的策略。

最后要提的一件比较酷的事是AppWidget framework对方向并不关心(is abstracted in both directions).这意味着你可以在两个home screen都可以包含widgets。你的widgets可以被添加到任何一个支持AppWidgetframework的home screen上。

我们已经开发了几个自己的widgets，例如Calendar和Music widgets,但是我们更希望看到你开发的widgets.