日历提供程序是用户日历活动的存储区。您可以使用 Calendar Provider API,对日历、活动、参加者、提醒等执行查询、插入、更新和删除操作。
Calendar Provider API 可供应用和同步适配器使用。通过 规则因进行调用的程序类型而异。本文主要侧重于介绍如何将 Calendar Provider API 用作应用。对于 同步适配器的区别的概念,请参阅 同步适配器。
正常情况下,如要读取或写入日历数据,则应用的清单文件必须包含用户权限中所述的适当权限。为简化常见操作的执行,日历提供程序提供了一组 intent,如日历 intent 中所述。这些 intent 会将用户带入日历应用,以便执行插入事件、查看事件和编辑事件。用户与日历应用交互,然后返回原来的应用。因此,您的应用无需请求权限, 也不需要提供查看或创建事件的界面。
基础知识
内容提供程序会存储数据,并让 应用。Android 平台提供的内容提供程序(包括日历提供程序)通常以一组基于关系型数据库模型的表格形式公开数据,表格内的每一行都是一条记录,每一列都是特定类型和含义的数据。应用和同步适配器可通过 Calendar Provider API 获得对储存用户日历数据的数据库表进行读取/写入的权限。
每个 content provider 都会公开一个公开 URI(封装为
Uri
对象)作为其数据集的唯一标识符。一个 content provider,用于控制
多个数据集(多个表)会针对每个数据集公开单独的 URI。所有提供程序 URI 都以字符串“content://”开头。这个
将数据标识为受内容提供程序控制。日历
Provider 会为其每个类(表)定义 URI 常量。这些 URI 的格式为 <class>.CONTENT_URI
。例如 Events.CONTENT_URI
。
图 1 显示了日历提供程序数据模型的图形表示。它展示了 主表和链接它们的字段。
用户可拥有多个日历,并且可将不同日历与不同类型的账户(Google 日历、Exchange 等)进行关联。
CalendarContract
定义了日历和活动相关信息的数据模型。这些数据存储在以下所列的若干表中。
表(类) | 说明 |
---|---|
此表格包含 日历特定信息。此表中的每一行都包含一个日历的详细信息,例如名称、颜色、同步信息等。 | |
CalendarContract.Events |
此表包含
事件特定信息此表中的每一行都包含一个事件的相关信息,例如事件的标题、地点、开始时间、结束时间等。事件可一次性发生,也可多次重复发生。参加者
提醒和扩展属性存储在单独的表中。
它们各自都有一个 EVENT_ID ,用于引用 Events 表中的 _ID 。 |
CalendarContract.Instances |
此表储存每个事件实例的开始时间和结束时间。此表中的每一行 表示单个事件的发生实例。对于一次性事件,实例与事件为 1:1 映射。对于重复事件,系统会自动生成多个行,分别对应多个事件实例。 |
CalendarContract.Attendees |
此表包含 活动参加者(来宾)信息。每一行都表示事件的一位来宾。它指定了来宾的类型和来宾的出席响应 事件。 |
CalendarContract.Reminders |
此表包含
提醒/通知数据。每一行代表一个事件的一条提醒。一个
活动可以有多个提醒。每个活动的提醒数量上限为
指定
MAX_REMINDERS ,
该配置由同步适配器设置
拥有指定日历。提醒需指定为在事件发生前的某个时间(分钟)发出,而且其拥有一个可决定用户提醒方式的方法。 |
日历提供程序 API 设计灵活且功能强大。在 同时,提供良好的最终用户体验也很重要 以保护日历及其数据的完整性。因此,请在使用该 API 时牢记以下要点:
- 插入、更新和查看日历活动。如要直接插入、修改和读取日历提供程序中的活动,您需要拥有适当的权限。但是,如果您没有构建成熟的日历应用或同步适配器,则没有必要请求这些权限。您可以改用 Android 的日历应用支持的 Intent,将读取和写入操作转到该应用执行。使用 intent 时,您的应用会将用户转到日历应用,以便其在预填充表单中执行所需操作。完成操作后,它们将返回您的应用。 通过将应用设计为通过日历执行常见操作,您可以为用户提供一致且稳健的界面。这是推荐的方法。有关详情,请参阅日历 intent。
- 同步适配器:同步适配器可同步日历数据
用户设备上的其他服务器或数据源。在
CalendarContract.Calendars
和CalendarContract.Events
个表, 有一些列预留供同步适配器使用。 提供程序和应用不应修改这些列。事实上,它们并不是 可见,除非将其作为同步适配器进行访问。如需详细了解 同步适配器,请参阅同步适配器。
用户权限
如需读取日历数据,应用必须在其清单文件中添加 READ_CALENDAR
权限。它
必须包含 WRITE_CALENDAR
权限
删除、插入或更新日历数据:
<?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android"...> <uses-sdk android:minSdkVersion="14" /> <uses-permission android:name="android.permission.READ_CALENDAR" /> <uses-permission android:name="android.permission.WRITE_CALENDAR" /> ... </manifest>
日历表
CalendarContract.Calendars
表包含详细信息
。以下
应用和同步适配器均可写入日历列。
如需查看所支持字段的完整列表,请参阅 CalendarContract.Calendars
参考文档。
常量 | 说明 |
---|---|
NAME |
日历的名称。 |
CALENDAR_DISPLAY_NAME |
显示给用户时,该日历所使用的名称。 |
VISIBLE |
指示是否选择显示该日历的布尔值。答
值 0 表示不应将与该日历关联的活动
。值为 1 表示与该日历关联的事件应
。此值会影响 CalendarContract.Instances 表中行的生成。 |
SYNC_EVENTS |
指示是否应同步日历并使其 存储在设备上的事件值为 0 表示不同步此日历或 将其事件存储在设备上值为 1 表示同步此日历的事件 并将其事件存储在设备上。 |
包括适用于所有操作的账户类型
如果您针对 Calendars.ACCOUNT_NAME
进行查询,则还必须添加
Calendars.ACCOUNT_TYPE
。这是因为某个账号
只有在同时指定 ACCOUNT_NAME
和
ACCOUNT_TYPE
。ACCOUNT_TYPE
是与
注册账号时使用的账号验证器
AccountManager
。还有一个特殊类型的
调用了“ACCOUNT_TYPE_LOCAL
”
未关联设备账号的日历。
ACCOUNT_TYPE_LOCAL
个账号未获得
已同步。
查询日历
以下示例展示了如何获取
用户。为简单起见,在本示例中,查询操作显示在
用户界面线程(“主线程”)。实际上,这应在异步
而不是在主线程上执行有关更多讨论,请参阅
加载器。如果您并非
读取数据但对其进行修改,请参阅 AsyncQueryHandler
。
Kotlin
// Projection array. Creating indices for this array instead of doing // dynamic lookups improves performance. private val EVENT_PROJECTION: Array<String> = arrayOf( CalendarContract.Calendars._ID, // 0 CalendarContract.Calendars.ACCOUNT_NAME, // 1 CalendarContract.Calendars.CALENDAR_DISPLAY_NAME, // 2 CalendarContract.Calendars.OWNER_ACCOUNT // 3 ) // The indices for the projection array above. private const val PROJECTION_ID_INDEX: Int = 0 private const val PROJECTION_ACCOUNT_NAME_INDEX: Int = 1 private const val PROJECTION_DISPLAY_NAME_INDEX: Int = 2 private const val PROJECTION_OWNER_ACCOUNT_INDEX: Int = 3
Java
// Projection array. Creating indices for this array instead of doing // dynamic lookups improves performance. public static final String[] EVENT_PROJECTION = new String[] { Calendars._ID, // 0 Calendars.ACCOUNT_NAME, // 1 Calendars.CALENDAR_DISPLAY_NAME, // 2 Calendars.OWNER_ACCOUNT // 3 }; // The indices for the projection array above. private static final int PROJECTION_ID_INDEX = 0; private static final int PROJECTION_ACCOUNT_NAME_INDEX = 1; private static final int PROJECTION_DISPLAY_NAME_INDEX = 2; private static final int PROJECTION_OWNER_ACCOUNT_INDEX = 3;
在示例的下一部分,您需要构建查询。所选项
指定查询的条件。在此示例中,查询要查找的是
包含ACCOUNT_NAME
的日历
“hera@example.com”,ACCOUNT_TYPE
“com.example”和 OWNER_ACCOUNT
“hera@example.com”。如果您想查看用户查看过的所有日历,而不只是用户所拥有的日历,请忽略 OWNER_ACCOUNT
。查询会返回 Cursor
可用于遍历数据库返回的结果集的对象
查询。有关如何在 content provider 中使用查询的更多讨论,
请参阅内容提供程序。
Kotlin
// Run query val uri: Uri = CalendarContract.Calendars.CONTENT_URI val selection: String = "((${CalendarContract.Calendars.ACCOUNT_NAME} = ?) AND (" + "${CalendarContract.Calendars.ACCOUNT_TYPE} = ?) AND (" + "${CalendarContract.Calendars.OWNER_ACCOUNT} = ?))" val selectionArgs: Array<String> = arrayOf("hera@example.com", "com.example", "hera@example.com") val cur: Cursor = contentResolver.query(uri, EVENT_PROJECTION, selection, selectionArgs, null)
Java
// Run query Cursor cur = null; ContentResolver cr = getContentResolver(); Uri uri = Calendars.CONTENT_URI; String selection = "((" + Calendars.ACCOUNT_NAME + " = ?) AND (" + Calendars.ACCOUNT_TYPE + " = ?) AND (" + Calendars.OWNER_ACCOUNT + " = ?))"; String[] selectionArgs = new String[] {"hera@example.com", "com.example", "hera@example.com"}; // Submit the query and get a Cursor object back. cur = cr.query(uri, EVENT_PROJECTION, selection, selectionArgs, null);
以下后续部分使用游标单步调试结果集。该部分使用在示例开头设置的常量,从而返回每个字段的值。
Kotlin
// Use the cursor to step through the returned records while (cur.moveToNext()) { // Get the field values val calID: Long = cur.getLong(PROJECTION_ID_INDEX) val displayName: String = cur.getString(PROJECTION_DISPLAY_NAME_INDEX) val accountName: String = cur.getString(PROJECTION_ACCOUNT_NAME_INDEX) val ownerName: String = cur.getString(PROJECTION_OWNER_ACCOUNT_INDEX) // Do something with the values... }
Java
// Use the cursor to step through the returned records while (cur.moveToNext()) { long calID = 0; String displayName = null; String accountName = null; String ownerName = null; // Get the field values calID = cur.getLong(PROJECTION_ID_INDEX); displayName = cur.getString(PROJECTION_DISPLAY_NAME_INDEX); accountName = cur.getString(PROJECTION_ACCOUNT_NAME_INDEX); ownerName = cur.getString(PROJECTION_OWNER_ACCOUNT_INDEX); // Do something with the values... ... }
修改日历
如需执行日历更新,您可以通过 URI 追加 ID (withAppendedId()
) 或第一个选定项形式提供日历的 _ID
。选定范围应以 "_id=?"
开头,并且第一个 selectionArg
应为日历的 _ID
。您还可以通过在 URI 中对 ID 进行编码来执行更新。下例使用 (withAppendedId()
) 方法更改日历的显示名称:
Kotlin
const val DEBUG_TAG: String = "MyActivity" ... val calID: Long = 2 val values = ContentValues().apply { // The new display name for the calendar put(CalendarContract.Calendars.CALENDAR_DISPLAY_NAME, "Trevor's Calendar") } val updateUri: Uri = ContentUris.withAppendedId(CalendarContract.Calendars.CONTENT_URI, calID) val rows: Int = contentResolver.update(updateUri, values, null, null) Log.i(DEBUG_TAG, "Rows updated: $rows")
Java
private static final String DEBUG_TAG = "MyActivity"; ... long calID = 2; ContentValues values = new ContentValues(); // The new display name for the calendar values.put(Calendars.CALENDAR_DISPLAY_NAME, "Trevor's Calendar"); Uri updateUri = ContentUris.withAppendedId(Calendars.CONTENT_URI, calID); int rows = getContentResolver().update(updateUri, values, null, null); Log.i(DEBUG_TAG, "Rows updated: " + rows);
插入日历
日历被设计为主要由同步适配器进行管理,因此您只能以同步适配器的形式插入新日历。在大多数情况下
应用程序只能对日历进行表面更改,例如更改显示名称。如果应用需要创建本地日历,则可以利用 ACCOUNT_TYPE_LOCAL
的 ACCOUNT_TYPE
,以同步适配器的形式执行日历插入,进而达到目的。ACCOUNT_TYPE_LOCAL
是一种特殊的账号类型,适用于未与设备账号关联的日历。此类日历不会同步到服务器。如需了解对同步适配器的阐述,请参阅同步适配器。
事件表
CalendarContract.Events
表包含详细信息
。要添加、更新或删除事件,应用必须
将 WRITE_CALENDAR
权限添加到其
清单文件。
应用和同步都可以写入以下事件列
适配器。如需查看所支持字段的完整列表,请参阅 CalendarContract.Events
参考文档。
常量 | 说明 |
---|---|
CALENDAR_ID |
事件所属日历的 _ID 。 |
ORGANIZER |
事件组织者(所有者)的电子邮件。 |
TITLE |
事件的名称。 |
EVENT_LOCATION |
活动的举办地点。 |
DESCRIPTION |
事件的描述。 |
DTSTART |
事件开始时间,以从公元纪年开始计算的协调世界时毫秒数表示。 |
DTEND |
事件结束时间,以从公元纪年开始计算的协调世界时毫秒数表示。 |
EVENT_TIMEZONE |
事件的时区。 |
EVENT_END_TIMEZONE |
事件结束时间的时区。 |
DURATION |
活动的持续时间,采用 RFC5545 格式。
例如,值为 "PT1H" 表示事件
应持续一小时,值 "P2W" 表示
为 2 周。 |
ALL_DAY |
值为 1 表示此事件占用一整天,具体定义如下: 本地时区。值为 0 表示它是常规事件,可在一天内的任何时间开始和结束。 |
RRULE |
事件的重复规则格式。例如 "FREQ=WEEKLY;COUNT=10;WKST=SU" 。您可以
点击此处查看更多示例。 |
RDATE |
事件的重复发生日期。
您通常使用 RDATE
结合RRULE
定义一组
重复出现的次数。如需查看更详细的介绍,请参阅 RFC5545 规范。 |
AVAILABILITY |
如果将此事件计为忙碌时间,或是在可能的空闲时间 。 |
GUESTS_CAN_MODIFY |
来宾是否可修改活动。 |
GUESTS_CAN_INVITE_OTHERS |
邀请对象是否可以邀请其他邀请对象。 |
GUESTS_CAN_SEE_GUESTS |
来宾是否可查看参加者列表。 |
添加事件
当您的应用插入新事件时,我们建议您使用 INSERT
intent,如使用 intent 插入事件中所述。但是,如果你
您可以直接插入事件本部分介绍了如何执行此操作。
以下是插入新事件的规则:
- 您必须添加
CALENDAR_ID
和DTSTART
。 - 您必须添加
EVENT_TIMEZONE
。获取列表 使用getAvailableIDs()
。请注意,如果您按使用 intent 插入事件中所述通过INSERT
intent 插入事件,则此规则不适用;在该情形下,系统会提供默认时区。 - 对于非重复事件,您必须添加
DTEND
。 - 对于周期性活动,除了
RRULE
或RDATE
,您还必须添加DURATION
。请注意,如果存在以下情况,此规则不适用: 您将通过INSERT
Intent 插入事件(如使用 Intent 插入事件中所述),在该示例中, 场景,您可以将RRULE
与DTSTART
和DTEND
以及 Google 日历应用结合使用 并会自动将其转换为时长。
以下是一个插入事件的示例。此操作在界面中执行
。实际上,应在
异步线程将操作移到后台线程中。有关
信息,请参阅 AsyncQueryHandler
。
Kotlin
val calID: Long = 3 val startMillis: Long = Calendar.getInstance().run { set(2012, 9, 14, 7, 30) timeInMillis } val endMillis: Long = Calendar.getInstance().run { set(2012, 9, 14, 8, 45) timeInMillis } ... val values = ContentValues().apply { put(CalendarContract.Events.DTSTART, startMillis) put(CalendarContract.Events.DTEND, endMillis) put(CalendarContract.Events.TITLE, "Jazzercise") put(CalendarContract.Events.DESCRIPTION, "Group workout") put(CalendarContract.Events.CALENDAR_ID, calID) put(CalendarContract.Events.EVENT_TIMEZONE, "America/Los_Angeles") } val uri: Uri = contentResolver.insert(CalendarContract.Events.CONTENT_URI, values) // get the event ID that is the last element in the Uri val eventID: Long = uri.lastPathSegment.toLong() // // ... do something with event ID // //
Java
long calID = 3; long startMillis = 0; long endMillis = 0; Calendar beginTime = Calendar.getInstance(); beginTime.set(2012, 9, 14, 7, 30); startMillis = beginTime.getTimeInMillis(); Calendar endTime = Calendar.getInstance(); endTime.set(2012, 9, 14, 8, 45); endMillis = endTime.getTimeInMillis(); ... ContentResolver cr = getContentResolver(); ContentValues values = new ContentValues(); values.put(Events.DTSTART, startMillis); values.put(Events.DTEND, endMillis); values.put(Events.TITLE, "Jazzercise"); values.put(Events.DESCRIPTION, "Group workout"); values.put(Events.CALENDAR_ID, calID); values.put(Events.EVENT_TIMEZONE, "America/Los_Angeles"); Uri uri = cr.insert(Events.CONTENT_URI, values); // get the event ID that is the last element in the Uri long eventID = Long.parseLong(uri.getLastPathSegment()); // // ... do something with event ID // //
注意:请查看此示例如何捕获事件 ID。这是获取事件 ID 的最简单方法。您经常 需要使用活动 ID 来执行其他日历操作(例如添加 活动的参加者或提醒。
更新事件
当您的应用想要允许用户修改活动时,我们建议您
使用 EDIT
intent,例如
使用 intent 修改事件中所述。
不过,如有需要,您也可以直接修改事件。要执行更新
事件,您可以提供_ID
事件,可以是 URI 的附加 ID (withAppendedId()
)
或用作第一个选择项。
所选范围应以 "_id=?"
开头,并且第一个
selectionArg
应为事件的 _ID
。您可以
也可使用不含 ID 的选项进行更新以下是一个更新
事件。使用
withAppendedId()
方法:
Kotlin
val DEBUG_TAG = "MyActivity" ... val eventID: Long = 188 ... val values = ContentValues().apply { // The new title for the event put(CalendarContract.Events.TITLE, "Kickboxing") } val updateUri: Uri = ContentUris.withAppendedId(CalendarContract.Events.CONTENT_URI, eventID) val rows: Int = contentResolver.update(updateUri, values, null, null) Log.i(DEBUG_TAG, "Rows updated: $rows")
Java
private static final String DEBUG_TAG = "MyActivity"; ... long eventID = 188; ... ContentResolver cr = getContentResolver(); ContentValues values = new ContentValues(); Uri updateUri = null; // The new title for the event values.put(Events.TITLE, "Kickboxing"); updateUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); int rows = cr.update(updateUri, values, null, null); Log.i(DEBUG_TAG, "Rows updated: " + rows);
删除活动
您可以通过将事件的 _ID
作为 URI 的追加 ID,或使用标准选定范围来删除事件。如果您使用附加的 ID,则无法同时进行选择。
共有两个版本的删除:应用删除和同步适配器删除。一个
将 deleted 列设置为 1。此标志告知同步适配器该行已删除,并且应将此删除操作传播至服务器。同步适配器删除会将事件从
及其所有相关数据以下示例展示应用如何通过 _ID
删除事件:
Kotlin
val DEBUG_TAG = "MyActivity" ... val eventID: Long = 201 ... val deleteUri: Uri = ContentUris.withAppendedId(CalendarContract.Events.CONTENT_URI, eventID) val rows: Int = contentResolver.delete(deleteUri, null, null) Log.i(DEBUG_TAG, "Rows deleted: $rows")
Java
private static final String DEBUG_TAG = "MyActivity"; ... long eventID = 201; ... ContentResolver cr = getContentResolver(); Uri deleteUri = null; deleteUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); int rows = cr.delete(deleteUri, null, null); Log.i(DEBUG_TAG, "Rows deleted: " + rows);
参加者表
CalendarContract.Attendees
表的每一行都表示事件的一位参加者或来宾。调用 query()
会返回具有给定 EVENT_ID
的事件的参加者列表。这部EVENT_ID
必须与特定事件的 _ID
相匹配。
下表列出了
可写字段。插入新参加者时,您必须加入除 ATTENDEE_NAME
之外的所有字段。
常量 | 说明 |
---|---|
EVENT_ID |
事件的 ID。 |
ATTENDEE_NAME |
参加者的姓名。 |
ATTENDEE_EMAIL |
参加者的电子邮件地址。 |
ATTENDEE_RELATIONSHIP |
参加者与活动的关系。下列值之一: |
ATTENDEE_TYPE |
参加者的类型。以下任一项: |
ATTENDEE_STATUS |
参加者的出席状态。下列值之一: |
添加参加者
以下是为事件添加一位参加者的示例。请注意,EVENT_ID
是必填项:
Kotlin
val eventID: Long = 202 ... val values = ContentValues().apply { put(CalendarContract.Attendees.ATTENDEE_NAME, "Trevor") put(CalendarContract.Attendees.ATTENDEE_EMAIL, "trevor@example.com") put( CalendarContract.Attendees.ATTENDEE_RELATIONSHIP, CalendarContract.Attendees.RELATIONSHIP_ATTENDEE ) put(CalendarContract.Attendees.ATTENDEE_TYPE, CalendarContract.Attendees.TYPE_OPTIONAL) put( CalendarContract.Attendees.ATTENDEE_STATUS, CalendarContract.Attendees.ATTENDEE_STATUS_INVITED ) put(CalendarContract.Attendees.EVENT_ID, eventID) } val uri: Uri = contentResolver.insert(CalendarContract.Attendees.CONTENT_URI, values)
Java
long eventID = 202; ... ContentResolver cr = getContentResolver(); ContentValues values = new ContentValues(); values.put(Attendees.ATTENDEE_NAME, "Trevor"); values.put(Attendees.ATTENDEE_EMAIL, "trevor@example.com"); values.put(Attendees.ATTENDEE_RELATIONSHIP, Attendees.RELATIONSHIP_ATTENDEE); values.put(Attendees.ATTENDEE_TYPE, Attendees.TYPE_OPTIONAL); values.put(Attendees.ATTENDEE_STATUS, Attendees.ATTENDEE_STATUS_INVITED); values.put(Attendees.EVENT_ID, eventID); Uri uri = cr.insert(Attendees.CONTENT_URI, values);
提醒表
CalendarContract.Reminders
表的每一行
表示事件的单个提醒。调用 query()
会返回事件提醒列表,且这些事件拥有给定的 EVENT_ID
。
下表列出了提醒的可写入字段。所有这些功能都必须
。请注意,同步适配器指定它们在 CalendarContract.Calendars
表中支持的提醒类型。请参阅
ALLOWED_REMINDERS
了解详情。
常量 | 说明 |
---|---|
EVENT_ID |
事件的 ID。 |
MINUTES |
事件发生前的分钟数,应在达到该时间时发出提醒。 |
METHOD |
闹铃方法,在服务器上设置。下列值之一: |
添加提醒
下例展示如何为事件添加提醒。提醒触发 15 分钟。
Kotlin
val eventID: Long = 221 ... val values = ContentValues().apply { put(CalendarContract.Reminders.MINUTES, 15) put(CalendarContract.Reminders.EVENT_ID, eventID) put(CalendarContract.Reminders.METHOD, CalendarContract.Reminders.METHOD_ALERT) } val uri: Uri = contentResolver.insert(CalendarContract.Reminders.CONTENT_URI, values)
Java
long eventID = 221; ... ContentResolver cr = getContentResolver(); ContentValues values = new ContentValues(); values.put(Reminders.MINUTES, 15); values.put(Reminders.EVENT_ID, eventID); values.put(Reminders.METHOD, Reminders.METHOD_ALERT); Uri uri = cr.insert(Reminders.CONTENT_URI, values);
实例表
CalendarContract.Instances
表存储事件实例的开始时间和结束时间。此表中的每一行
表示单个事件的发生实例。实例表不可写入,只有
提供了一种查询事件发生次数的方法。
下表列出了一些您可以执行实例查询的字段。请注意,时区由 KEY_TIMEZONE_TYPE
和 KEY_TIMEZONE_INSTANCES
定义。
常量 | 说明 |
---|---|
BEGIN |
实例的开始时间,以协调世界时毫秒数表示。 |
END |
实例的结束时间,以协调世界时毫秒数表示。 |
END_DAY |
与日历时区相应的实例儒略历结束日。 |
END_MINUTE |
从 日历的时区。 |
EVENT_ID |
此实例的事件的 _ID 。 |
START_DAY |
日历时区实例的儒略历开始日。 |
START_MINUTE |
从午夜(相对于 日历的时区。 |
查询实例表
如需查询实例表,您需要指定查询的时间范围
URI 中。在此示例中,CalendarContract.Instances
通过其 CalendarContract.EventsColumns
接口实现获得对 TITLE
字段的访问权限。也就是说,TITLE
是通过
数据库视图,而不是通过查询原始 CalendarContract.Instances
表来实现。
Kotlin
const val DEBUG_TAG: String = "MyActivity" val INSTANCE_PROJECTION: Array<String> = arrayOf( CalendarContract.Instances.EVENT_ID, // 0 CalendarContract.Instances.BEGIN, // 1 CalendarContract.Instances.TITLE // 2 ) // The indices for the projection array above. const val PROJECTION_ID_INDEX: Int = 0 const val PROJECTION_BEGIN_INDEX: Int = 1 const val PROJECTION_TITLE_INDEX: Int = 2 // Specify the date range you want to search for recurring // event instances val startMillis: Long = Calendar.getInstance().run { set(2011, 9, 23, 8, 0) timeInMillis } val endMillis: Long = Calendar.getInstance().run { set(2011, 10, 24, 8, 0) timeInMillis } // The ID of the recurring event whose instances you are searching // for in the Instances table val selection: String = "${CalendarContract.Instances.EVENT_ID} = ?" val selectionArgs: Array<String> = arrayOf("207") // Construct the query with the desired date range. val builder: Uri.Builder = CalendarContract.Instances.CONTENT_URI.buildUpon() ContentUris.appendId(builder, startMillis) ContentUris.appendId(builder, endMillis) // Submit the query val cur: Cursor = contentResolver.query( builder.build(), INSTANCE_PROJECTION, selection, selectionArgs, null ) while (cur.moveToNext()) { // Get the field values val eventID: Long = cur.getLong(PROJECTION_ID_INDEX) val beginVal: Long = cur.getLong(PROJECTION_BEGIN_INDEX) val title: String = cur.getString(PROJECTION_TITLE_INDEX) // Do something with the values. Log.i(DEBUG_TAG, "Event: $title") val calendar = Calendar.getInstance().apply { timeInMillis = beginVal } val formatter = SimpleDateFormat("MM/dd/yyyy") Log.i(DEBUG_TAG, "Date: ${formatter.format(calendar.time)}") }
Java
private static final String DEBUG_TAG = "MyActivity"; public static final String[] INSTANCE_PROJECTION = new String[] { Instances.EVENT_ID, // 0 Instances.BEGIN, // 1 Instances.TITLE // 2 }; // The indices for the projection array above. private static final int PROJECTION_ID_INDEX = 0; private static final int PROJECTION_BEGIN_INDEX = 1; private static final int PROJECTION_TITLE_INDEX = 2; ... // Specify the date range you want to search for recurring // event instances Calendar beginTime = Calendar.getInstance(); beginTime.set(2011, 9, 23, 8, 0); long startMillis = beginTime.getTimeInMillis(); Calendar endTime = Calendar.getInstance(); endTime.set(2011, 10, 24, 8, 0); long endMillis = endTime.getTimeInMillis(); Cursor cur = null; ContentResolver cr = getContentResolver(); // The ID of the recurring event whose instances you are searching // for in the Instances table String selection = Instances.EVENT_ID + " = ?"; String[] selectionArgs = new String[] {"207"}; // Construct the query with the desired date range. Uri.Builder builder = Instances.CONTENT_URI.buildUpon(); ContentUris.appendId(builder, startMillis); ContentUris.appendId(builder, endMillis); // Submit the query cur = cr.query(builder.build(), INSTANCE_PROJECTION, selection, selectionArgs, null); while (cur.moveToNext()) { String title = null; long eventID = 0; long beginVal = 0; // Get the field values eventID = cur.getLong(PROJECTION_ID_INDEX); beginVal = cur.getLong(PROJECTION_BEGIN_INDEX); title = cur.getString(PROJECTION_TITLE_INDEX); // Do something with the values. Log.i(DEBUG_TAG, "Event: " + title); Calendar calendar = Calendar.getInstance(); calendar.setTimeInMillis(beginVal); DateFormat formatter = new SimpleDateFormat("MM/dd/yyyy"); Log.i(DEBUG_TAG, "Date: " + formatter.format(calendar.getTime())); } }
日历 Intent
您的应用不需要读取和写入日历数据的权限。它可以改用 Android 日历应用支持的 Intent,将读取和写入操作转到该应用执行。下表列出了日历提供程序支持的 Intent:
操作 | URI | 说明 | Extra |
---|---|---|---|
VIEW |
CalendarContract.CONTENT_URI 引用 URI。如需查看使用该 intent 的示例,请参阅使用 intent 查看日历数据。
|
打开日历并前往 <ms_since_epoch> 指定的时间。 |
无。 |
Events.CONTENT_URI 引用 URI。如需查看使用该 intent 的示例,请参阅使用 intent 查看日历数据。
|
查看 <event_id> 指定的事件。 |
CalendarContract.EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_END_TIME |
|
EDIT |
Events.CONTENT_URI 。
如需查看使用此 intent 的示例,请参阅使用 intent 编辑事件。
|
修改 <event_id> 指定的事件。 |
CalendarContract.EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_END_TIME |
EDIT INSERT |
Events.CONTENT_URI 。
如需查看使用此 intent 的示例,请参阅使用 intent 插入事件。
|
创建活动。 | 下表列出的任一 Extra。 |
下表列出了日历提供程序支持的 intent extra:
Intent Extra | 说明 |
---|---|
Events.TITLE |
事件的名称。 |
CalendarContract.EXTRA_EVENT_BEGIN_TIME |
事件开始时间,以从公元纪年开始计算的毫秒数表示。 |
CalendarContract.EXTRA_EVENT_END_TIME |
事件结束时间,以从公元纪年开始计算的毫秒数表示。 |
CalendarContract.EXTRA_EVENT_ALL_DAY |
一个布尔值,表示事件属于全天事件。值可以是 true 或 false 。 |
Events.EVENT_LOCATION |
事件的地点。 |
Events.DESCRIPTION |
事件描述。 |
Intent.EXTRA_EMAIL |
逗号分隔值形式的受邀者电子邮件地址列表。 |
Events.RRULE |
事件的重复发生规则。 |
Events.ACCESS_LEVEL |
事件是私人性质还是公共性质。 |
Events.AVAILABILITY |
将此事件视为忙碌时间还是可调度的空闲时间。 |
下文描述如何使用这些 Intent。
使用 Intent 插入事件
利用 INSERT
intent,您的应用可将事件插入任务转由日历应用执行。借助此方法,您的应用甚至不需要在其清单文件中包含 WRITE_CALENDAR
权限。
当用户运行使用此方法的应用时,该应用会跳转至日历,以便用户完成事件添加操作。INSERT
intent 使用额外字段来
使用日历中的活动详细信息预填充表单。用户可以
然后取消活动、根据需要编辑表单或将活动保存到他们的
日历。
以下代码段安排了一个在 2012 年 1 月 19 日上午 7:30 开始、8:30 结束的事件。请注意以下代码段内容:
- 它指定了
Events.CONTENT_URI
。 作为 URI - 它使用
CalendarContract.EXTRA_EVENT_BEGIN_TIME
和CalendarContract.EXTRA_EVENT_END_TIME
extra 字段为表单预填充事件的时间。这些时间的值必须以从公元纪年开始计算的协调世界时毫秒数表示。 - 它使用
Intent.EXTRA_EMAIL
extra 字段提供以逗号分隔的受邀者电子邮件地址列表。
Kotlin
val startMillis: Long = Calendar.getInstance().run { set(2012, 0, 19, 7, 30) timeInMillis } val endMillis: Long = Calendar.getInstance().run { set(2012, 0, 19, 8, 30) timeInMillis } val intent = Intent(Intent.ACTION_INSERT) .setData(CalendarContract.Events.CONTENT_URI) .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, startMillis) .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, endMillis) .putExtra(CalendarContract.Events.TITLE, "Yoga") .putExtra(CalendarContract.Events.DESCRIPTION, "Group class") .putExtra(CalendarContract.Events.EVENT_LOCATION, "The gym") .putExtra(CalendarContract.Events.AVAILABILITY, CalendarContract.Events.AVAILABILITY_BUSY) .putExtra(Intent.EXTRA_EMAIL, "rowan@example.com,trevor@example.com") startActivity(intent)
Java
Calendar beginTime = Calendar.getInstance(); beginTime.set(2012, 0, 19, 7, 30); Calendar endTime = Calendar.getInstance(); endTime.set(2012, 0, 19, 8, 30); Intent intent = new Intent(Intent.ACTION_INSERT) .setData(Events.CONTENT_URI) .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, beginTime.getTimeInMillis()) .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, endTime.getTimeInMillis()) .putExtra(Events.TITLE, "Yoga") .putExtra(Events.DESCRIPTION, "Group class") .putExtra(Events.EVENT_LOCATION, "The gym") .putExtra(Events.AVAILABILITY, Events.AVAILABILITY_BUSY) .putExtra(Intent.EXTRA_EMAIL, "rowan@example.com,trevor@example.com"); startActivity(intent);
使用 Intent 编辑事件
您可以直接更新事件,如更新事件中所述。但使用 EDIT
intent 可让应用
无权访问日历应用。
用户在 Google 日历中完成活动编辑后,就会返回
原始应用
下面是一个 intent 示例,它会设置新的 标题,并允许用户在日历中编辑活动。
Kotlin
val eventID: Long = 208 val uri: Uri = ContentUris.withAppendedId(CalendarContract.Events.CONTENT_URI, eventID) val intent = Intent(Intent.ACTION_EDIT) .setData(uri) .putExtra(CalendarContract.Events.TITLE, "My New Title") startActivity(intent)
Java
long eventID = 208; Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); Intent intent = new Intent(Intent.ACTION_EDIT) .setData(uri) .putExtra(Events.TITLE, "My New Title"); startActivity(intent);
使用 Intent 查看日历数据
日历提供程序提供了两种不同的 VIEW
intent 使用方式:
- 打开日历并定位到特定日期。
- 查看事件。
下例展示如何打开日历并定位到特定日期:
Kotlin
val startMillis: Long ... val builder: Uri.Builder = CalendarContract.CONTENT_URI.buildUpon() .appendPath("time") ContentUris.appendId(builder, startMillis) val intent = Intent(Intent.ACTION_VIEW) .setData(builder.build()) startActivity(intent)
Java
// A date-time specified in milliseconds since the epoch. long startMillis; ... Uri.Builder builder = CalendarContract.CONTENT_URI.buildUpon(); builder.appendPath("time"); ContentUris.appendId(builder, startMillis); Intent intent = new Intent(Intent.ACTION_VIEW) .setData(builder.build()); startActivity(intent);
下例展示如何打开事件进行查看:
Kotlin
val eventID: Long = 208 ... val uri: Uri = ContentUris.withAppendedId(CalendarContract.Events.CONTENT_URI, eventID) val intent = Intent(Intent.ACTION_VIEW).setData(uri) startActivity(intent)
Java
long eventID = 208; ... Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); Intent intent = new Intent(Intent.ACTION_VIEW) .setData(uri); startActivity(intent);
同步适配器
应用和同步适配器的方式只有细微的差别 访问日历提供程序:
- 同步适配器需要将
CALLER_IS_SYNCADAPTER
设置为true
,以指定它是同步适配器。 - 同步适配器需要提供
ACCOUNT_NAME
和ACCOUNT_TYPE
,作为 URI 中的查询参数。 - 与应用或微件相比,同步适配器拥有写入权限的列更多。
例如,应用只能修改日历的少数几种特性,
例如日历名称、显示名称、公开范围设置以及日历是否
已同步。相比之下,同步适配器不仅可访问这些列,还能访问许多其他列,例如日历颜色、时区、访问级别、地点等。不过,同步适配器仅限于
ACCOUNT_NAME
和ACCOUNT_TYPE
。
您可以利用以下辅助方法,返回与同步适配器一起使用的 URI:
Kotlin
fun asSyncAdapter(uri: Uri, account: String, accountType: String): Uri { return uri.buildUpon() .appendQueryParameter(CalendarContract.CALLER_IS_SYNCADAPTER, "true") .appendQueryParameter(CalendarContract.Calendars.ACCOUNT_NAME, account) .appendQueryParameter(CalendarContract.Calendars.ACCOUNT_TYPE, accountType).build() }
Java
static Uri asSyncAdapter(Uri uri, String account, String accountType) { return uri.buildUpon() .appendQueryParameter(android.provider.CalendarContract.CALLER_IS_SYNCADAPTER,"true") .appendQueryParameter(Calendars.ACCOUNT_NAME, account) .appendQueryParameter(Calendars.ACCOUNT_TYPE, accountType).build(); }