[转载]Android 4.3 SDK Samples 阅读笔记之一 ContactManager - [武汉]胖大海 - 博客园

一、综述：

ContactManager是一个关于联系人管理的示例代码，共包含二个Activity，ContactManager是启动Activity，用于显示联系人列表及添加按钮；ContactAdder是添加联系人用的Activity。

在默认使用模拟器调试项目时，如果没有添加过联系人帐户，添加功能会报错。原因是Android对于联系人的管理与传统手机 不一样，Android的联系人可以与帐户关联，这个帐户可以是一个电子邮箱地址或者是Exchange的帐户。当然，与可以不与某个帐户关联，这种被称 为本地联系人。

进入Android自带的联系人管理界面，当没有任何联系人时界面如下：

其中登录帐户，就是指创建一个帐户，帐户在Android的系统设置中的帐户管理里也可以创建。在未创建帐户直接创建新联系人时界面如下：

 

在添加界面上方，即显示了“仅保存在手机中，不同步…”信息。

 

ContactManager项目中添加联系人，必须要选择所属的帐户，如果没有选择帐户，则会报错，这个错误，后文中将在改进部分中修复此问题。

二、阅读笔记：

1．ContactManager.java源码分析

该类中包含方法如下：

private void populateContactList()：显示联系人列表的方法，在OnCreate方法的最后一行调用。

private Cursor getContacts()：取得所有联系人的游标的方法，在populateContactList方法第一行调用。

protected void launchContactAdder()：显示添加联系人窗体的方法，在mAddAccountButton按钮的 onClick事件的处理程序中调用。

1.1依照相关顺序，首先解析getContacts的源码，在getContacts方法中，主要使用了managerQuery方法，返回了一个游标。

managerQuery方法接受的参数意义依次为：

Uri uri:查询目标Content Provider的唯一标识，取值ContactsContract.Contacts.CONTENT_URI代表查询联系人。

String[] projection：返回字段的名称列表，SQL查询语句中的SELECT子句以数组方式书写。

String selection：查询的条件，SQL中WHERE子句。

String[] selectionArgs：查询的条件中的参数值列表，对应替换selection中“? ”占位符。

String sortOrder：排序方式，SQL中的ORDER BY子句

返回值Cursor是一种游标对象，用于顺序读取查询结果。

1.2 populateContactList方法中，首先调用了getContacts，获得一个包含所有联系人的游标对象。

随之，构造了一个SimpleCursorAdapter的适配器对象，用于将Cursor数据源中的数据绑定到视图中显示。

SimpleCursorAdapter对象的构造方法参数意义依次为：

Context　context：ListView相关联的SimpleListItemFactory运行的上下文对象，即ListView所在的Activity对象。

int layout：用于显示Cursor中返回的每一行数据的layout。

Cursor c：数据源的游标对象。

String[] from：要显示数据的字段名称列表。

Int[] to：用于显示数据的控件的id列表。

根据源码可以得知，将使用layout下的contact_entry.xml作为游标中每一行数据显示的View，显示的字段只有一个，就是ContactsContract.Data.DISPLAY_NAME，显示数据的控件id是contactEntryText。

查看res文件夹下的layout文件夹下的contact_entry.xml可以发现，contactEntryText是一个TextView控件。

在本示例中，在managerQuery方法中的查询字段使用的是ContactsContract.Contacts.DISPLAY_NAME，而在populateContactList方法中显示字段时使用的是ContactsContract.Data.DISPLAY_NAME，两次使用的常量不同，但通过查询发现，两个常量的值都为“display_name”，可以交换使用，直接使用其值，程序也可正常运行。

1.2 launchContactAdder方法在mAddAccountButton控件的onClick事件的Listener中调用，主要作用是显示添加联系人的界面。

2.ContactAdder.java源码分析

ContactAdder类相对而言要复杂一些，本身实现了OnAccountsUpdateListener接口，这个接 口内包含一个方法onAccountsUpdated。实现了该接口的类，可以由AccountManager注册成为OnAccountsUpdate 事件的监听者，当系统中的帐户发生更新时，由AccountManager调用所有监听者的onAccountsUpdated方法。

ContactAdder类中实现了如下方法：

private static AuthenticatorDescription getAuthenticatorDescription(String type, AuthenticatorDescription[] dictionary)： 返回帐户的签发者的相关信息。在onAccountsUpdated方法中调用，用于读取帐户的显示数据。

private void updateAccountSelection()：将mAccountSpinner下拉列表 中当前选中的帐户信息赋给内部字段mSelectedAccount，该内部字段指示添加的联系人属于哪个帐户。此方法在mAccountSpinner 控件的OnItemSelected事件的处理方法中调用。

private void onSaveButtonClicked():处理添加按钮的单击，在mContactSaveButton按钮的onClick事件处理程序中调用。

protected void createContactEntry()：添加一个新的联系人，在onSaveButtonClicked事件中调用。

另外该类中还包括两个内部类：

AccountData：主要是帐户的显示信息，包括帐户名称，帐户的签发者的图标，签发者的名称。另外还有一个type字段，主要是type签发者的唯一识别标志，取图片和名称需要使用，并不用于显示。

AccountAdapter：用于帐户信息显示的适配器类，继承自ArrayAdapter。

在解析各个方法的代码前，先解析OnCreate方法中的内容。

在OnCreate方法中，构建了两个集合，一个为电话类型的集合，一个为Email类型的集合。在Android系统中， 一个联系人，可以有多个电话，多个Email，这些电话和Email可以标识为办公，家庭等不同类型。使用了ArrayAdapter将 mContactPhoneTypeSpinner控件和mContactEmailTypeSpinner分别与构建的两个集合关联，并使用 getTypeLabel()方法查询对应的显示名称进行显示。

而且在OnCreate方法中，构造了内部类AccountAdapter的实例，追踪构造方法，发现使用 setDropDownViewResource(R.layout.account_entry)方法，设置了下拉列表的View使用的layout， 并使用AccountAdapter将内部字段mAccounts作为mAccountSpinner控件的数据源。mAccounts是一个 AccountData类的集合，也即是帐户信息的集合。

在138行使用了 AccountManager.get(this).addOnAccountsUpdatedListener(this, null, true); 将ContactAdder注册成为OnAccountsUpdate事件的监听者。此时，会立刻调用一次 ＣContactAdder.onAccountsUpdated()方法。该方法先清除帐户信息集合，再读取所有的帐户，并根据帐户名称和签发者的相关 信息构造帐户显示信息类的集合，赋值给mAccountSpinner控件的数据源内部变量mAccounts,，并调用AccountAdapter类 的notifyDataSetChanged方法，通知Adapter更新mAccountSpinner控件的显示同步数据来源的变化。

最复杂的方法是CreateContactEntry方法，要理解该方法的代码，需要理解Android对通迅录的组织。

每个联系人属于一个帐户，首先是在该帐户下添加一个记录，获得RAW_CONTACT_ID。

然后使用RAW_CONTACT_ID添加联系人信息，添加电话信息，添加Email信息。

在帐户下添加记录时，操作的Uri为ContactsContract.RawContacts.CONTENT_URI， 返回值为RAW_CONTACT_ID,而添加联系人信息，电话信息，和Email信息时操作的是 ContactsContract.Data.CONTENT_URI,使用RAW_CONTACT_ID字段与帐户下的记录关联。

本例中使用了批量操作，故先使用以下代码构建了一个操作集合。

 

随后使用了一系列代码构建了批量操作，并添加到该集合中。构建批量操作中的第一个操作的代码如下：

 

第一个操作中为添加联系人记录，分别添加了帐户的类型和名称两个值，返回该记录的ID值。操作中使用了如下方法：

newInsert(Uri uri)方法表示，插入操作使用的Uri。

withValue(String name,Object value)方法表，要操作的字段名和其值。

build()方法表示，将其构建成为一个操作。

与构建第一个操作类似的代码构建了接下来的三个操作，分别用于添加联系人名称，电话号码，Email地址。以构建添加联系人的操作为例，其代码如下：

 

添加了联系人的名称操作使用了withValueBackReference方法。此方法中第一个参数表示添加记录的字段名，第二个参数表示了使用批量操作中下,标为0的操作的返回值也就是添加联系人记录的操作，其返回值即是联系人的记录Id。

添加电话号码和邮件地址，只是字段不同而已。

最后使用 getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);执行了批量操 作。getContentResolver方法用于获取ContentResolver对象，该对象是执行操作的执行者，applyBatch方法用于执 行批量的操作，第一个参数是有该操作权限对象的进程名称，第二个参数是要执行的操作集合。

三、改进源码

3.1 错误排除

首先要做的改进是，允许在没有帐户的情况下增加联系人。

在添加联系人的批量操作中的第一个，会使用mSelectedAccount中存储的对象的getType()和 getName方法分别获取选中的帐户的类型和名称，如果系统中没有帐户，mSelectedAccount的值将为null,所以在使用前判定 mSelectedAccount是否为null.

将代码：

 

修改为：

 

在没有帐户被选中的情况下，添加记录时，帐户的类型和名称都使用null值，这样添加的联系人记录就是仅本地存储，不与任何帐户关联的。

在操作中加入AGGREGATION_MODE字段，设其值为AGGREGATION_MODE_DISABLED，主要目的是阻止同名联系人的电话和Email等资料自动合并处理。

另外，还需要注释掉使用到mSelectedAccount的语句。

 

3.2 新版本的建议做法

在本示例代码中，可以发现ManagerQuery方法与SimpleCursorAdapter类的构造方法被标识为过时的方法。

在新版本的SDK的Document中建议使用CursorLoader类来替代ManagerQuery方法。CursorLoader类会创建一个用于游标的Loader类，该类由LoaderManager对象管理。需要实现三个方法：

onCreateLoader(int id,Bundle args):该方法在LoaderManager对象创建Loader时使用。

onLoadFinished(Loader<T> arg0,T arg1)：该方法在Loader读取数据完成后调用。

onLoaderReset(Loader<T> arg0):该方法在Loader重置时调用。

重写的populateContactList2方法代码如下：

 

本示例代码中构建了populateContactList2方法，替换了原代码中的populateContactList和getContacts方法。

注意与原来代码的区别，依然是构造了一个SimpleCursorAdapter对象，只是将其中的第三个参数Cursor 设为null值。主要原因是代码中使用CursorLoader去管理Cursor，不是直接在代码中构造Cursort，故在创建 SimpleCursorAdapter对象时无法传入Cursor对象。

接下来使用getLoaderManager取得了当前Activity的LoaderManager对象，调用该对象的initLoader方法，初始化一个Loader对象。

intiLoader方法有三个参数：第一个参数为int id，是一个标识符，用于LoaderManager实例区分不 同的Loader；第二个参数为Bundle args，用于向Loader中传入数据，第三个参数是LoaderCallBack<T>接 口的实现类。由参数类型LoaderCallBack<T>可以看出这是一个回调类，主要用于LoaderManager管理该Loader 对象时三个方法，在上文中已经介绍过。同时该接口为一个泛型接口，可以用于管理不同类型的Loader。本例中用于管理Cursor对象，故传入值为 LoaderCallBack<Cursor>。

在LoaderCallBack<Cursor>的onCreateLoader中创建了一个 CursorLoader类的实例返回，CursorLoader类是Loader<Cursor>的实现。在onLoadFinished 方法中使用如下代码将CursorLoader加载完成后获得的Cursor对象置入SimpleCursorAdapter对象。

 

在onLoaderReset方法中使用如下代码，将未加载完成的Cursor对象从SimpleCursorAdapter对象中卸载。

 

为了配合上述代码，将原先在populateContactList方法中声明的SimpleCursorAdapter对象声明放入类中。由于CursorLoader是在Android 3.0中加入的新类型，故需要将程序的最低SDK需求设为3.0，即将minSdkVersion的值改为11。

 最后将onCreate中的两处对populateContactList方法的调用改为populateContactList2方法调用。

至此，ContactManager类的改造完成，使用了新的SDK的实现方式，并修复了无帐户时添加联系人的错误。

改造后的项目源码下载地址：http://files.cnblogs.com/PandaHi/ContactManager.rar