ภาพรวมของผู้ให้บริการปฏิทิน

ผู้ให้บริการปฏิทินคือที่เก็บข้อมูลกิจกรรมในปฏิทินของผู้ใช้ Calendar Provider API ช่วยให้คุณดำเนินการค้นหา แทรก อัปเดต และลบข้อมูลต่างๆ เช่น ปฏิทิน กิจกรรมในปฏิทิน ผู้เข้าร่วม และการช่วยเตือนได้

แอปพลิเคชันและอะแดปเตอร์การซิงค์สามารถใช้ Calendar Provider API ได้ กฎจะแตกต่างกันไปตามประเภทของโปรแกรมที่ทำการโทร เอกสารนี้เน้นที่การใช้ Calendar Provider API เป็นแอปพลิเคชันเป็นหลัก ดูการพูดคุยเกี่ยวกับความแตกต่างของอะแดปเตอร์การซิงค์ได้ที่อะแดปเตอร์การซิงค์

โดยปกติแล้ว หากต้องการอ่านหรือเขียนข้อมูลปฏิทิน ไฟล์ Manifest ของแอปพลิเคชันต้องมีการให้สิทธิ์จากผู้ใช้ที่เหมาะสมตามที่อธิบายไว้ในสิทธิ์ของผู้ใช้ เพื่อให้การดำเนินการทั่วไปง่ายขึ้น ผู้ให้บริการปฏิทินจึงมีชุด Intent ตามที่อธิบายไว้ในIntent ของปฏิทิน Intent เหล่านี้จะนำผู้ใช้ไปยังแอปพลิเคชันปฏิทินเพื่อแทรก ดู และแก้ไขกิจกรรม ผู้ใช้โต้ตอบกับแอปพลิเคชันปฏิทินแล้วกลับไปที่แอปพลิเคชันเดิม ดังนั้นแอปพลิเคชันของคุณจึงไม่จำเป็นต้องขอสิทธิ์ และไม่จำเป็นต้องมีอินเทอร์เฟซผู้ใช้เพื่อดูหรือสร้างกิจกรรม

ข้อมูลเบื้องต้น

Content Provider จะจัดเก็บข้อมูลและทำให้แอปพลิเคชันเข้าถึงข้อมูลได้ Content Provider ที่แพลตฟอร์ม Android มีให้ (รวมถึง Calendar Provider) มักจะแสดงข้อมูลเป็นชุดตารางตามโมเดลฐานข้อมูลเชิงสัมพันธ์ โดยแต่ละแถวคือระเบียน และแต่ละคอลัมน์คือข้อมูลประเภทและความหมายที่เฉพาะเจาะจง แอปพลิเคชันและอะแดปเตอร์การซิงค์จะได้รับสิทธิ์อ่าน/เขียนในตารางฐานข้อมูลที่เก็บข้อมูลปฏิทินของผู้ใช้ผ่าน Calendar Provider API

Content Provider ทุกรายจะแสดง URI สาธารณะ (รวมเป็นออบเจ็กต์ Uri) ที่ระบุชุดข้อมูลของตนโดยไม่ซ้ำกัน Content Provider ที่ควบคุมชุดข้อมูลหลายชุด (หลายตาราง) จะแสดง URI แยกต่างหากสำหรับแต่ละชุด URI ทั้งหมดสำหรับผู้ให้บริการจะขึ้นต้นด้วยสตริง "content://" ซึ่งจะระบุว่าข้อมูลได้รับการควบคุมโดย Content Provider ผู้ให้บริการปฏิทินจะกำหนดค่าคงที่สำหรับ URI ของแต่ละคลาส (ตาราง) URI เหล่านี้มีรูปแบบ <class>.CONTENT_URI เช่น Events.CONTENT_URI

รูปที่ 1 แสดงภาพโมเดลข้อมูลของผู้ให้บริการปฏิทิน โดยจะแสดงตารางหลักและช่องที่ลิงก์ตารางเหล่านั้นเข้าด้วยกัน

โมเดลข้อมูลของผู้ให้บริการปฏิทิน
รูปที่ 1 โมเดลข้อมูลของผู้ให้บริการปฏิทิน

ผู้ใช้สามารถมีปฏิทินได้หลายรายการ และปฏิทินที่แตกต่างกันสามารถเชื่อมโยงกับบัญชีประเภทต่างๆ (Google ปฏิทิน, Exchange และอื่นๆ)

CalendarContract กำหนดโมเดลข้อมูลของปฏิทินและข้อมูลที่เกี่ยวข้องกับกิจกรรม ข้อมูลนี้จะจัดเก็บไว้ในตารางหลายตารางตามรายการต่อไปนี้

ตาราง (ชั้นเรียน) คำอธิบาย

CalendarContract.Calendars

ตารางนี้มีข้อมูลเฉพาะของปฏิทิน แต่ละแถวในตารางนี้จะมีรายละเอียดของปฏิทินเดียว เช่น ชื่อ สี และข้อมูลการซิงค์
CalendarContract.Events ตารางนี้มีข้อมูลเฉพาะเหตุการณ์ แต่ละแถวในตารางนี้มีข้อมูลสำหรับกิจกรรมเดียว เช่น ชื่อกิจกรรม สถานที่ เวลาเริ่มต้น เวลาสิ้นสุด กิจกรรมอาจเกิดขึ้นครั้งเดียวหรือเกิดขึ้นซ้ำหลายครั้งก็ได้ ระบบจะจัดเก็บผู้เข้าร่วม การช่วยเตือน และพร็อพเพอร์ตี้เพิ่มเติมไว้ในตารางแยกต่างหาก แต่ละรายการจะมี EVENT_ID ที่อ้างอิง _ID ในตารางเหตุการณ์
CalendarContract.Instances ตารางนี้จะเก็บเวลาเริ่มต้นและสิ้นสุดของการเกิดเหตุการณ์แต่ละครั้ง แต่ละแถวในตารางนี้แสดงถึงการเกิดเหตุการณ์ 1 ครั้ง สำหรับกิจกรรมที่เกิดขึ้นครั้งเดียว จะมีการแมปอินสแตนซ์กับกิจกรรมแบบ 1:1 สำหรับกิจกรรมที่เกิดซ้ำ ระบบจะสร้างแถวหลายแถวโดยอัตโนมัติซึ่งสอดคล้องกับการเกิดกิจกรรมนั้นหลายครั้ง
CalendarContract.Attendees ตารางนี้มีข้อมูลผู้เข้าร่วมกิจกรรม (ผู้เข้าร่วม) แต่ละแถวแสดงผู้เข้าร่วมกิจกรรม 1 คน โดยจะระบุประเภทของผู้เข้าร่วมและการตอบกลับการเข้าร่วมของผู้เข้าร่วมสำหรับกิจกรรม
CalendarContract.Reminders ตารางนี้มีข้อมูลการแจ้งเตือน/การเตือน แต่ละแถวแสดงการแจ้งเตือน 1 รายการสำหรับเหตุการณ์ กิจกรรมหนึ่งๆ สามารถมีการช่วยเตือนได้หลายรายการ จำนวนการช่วยเตือนสูงสุดต่อกิจกรรมจะระบุไว้ใน MAX_REMINDERS ซึ่งกำหนดโดยอะแดปเตอร์การซิงค์ที่เป็นเจ้าของปฏิทินที่ระบุ การช่วยเตือนจะระบุเป็นนาทีก่อนกิจกรรมและมีวิธีการที่กำหนดวิธีแจ้งเตือนผู้ใช้

Calendar Provider API ออกแบบมาให้มีความยืดหยุ่นและมีประสิทธิภาพ ขณะเดียวกัน คุณก็ต้องมอบประสบการณ์การใช้งานที่ดีแก่ผู้ใช้ปลายทางและปกป้องความสมบูรณ์ของปฏิทินและข้อมูลในปฏิทินด้วย ด้วยเหตุนี้ สิ่งที่ควรคำนึงถึงเมื่อใช้ API มีดังนี้

  • การแทรก การอัปเดต และการดูกิจกรรมในปฏิทิน หากต้องการแทรก แก้ไข และอ่านกิจกรรมจากผู้ให้บริการปฏิทินโดยตรง คุณต้องมีสิทธิ์ที่เหมาะสม อย่างไรก็ตาม หากคุณไม่ได้สร้างแอปพลิเคชันปฏิทินหรืออะแดปเตอร์การซิงค์แบบเต็มรูปแบบ คุณก็ไม่จำเป็นต้องขอสิทธิ์เหล่านี้ แต่คุณสามารถใช้ Intent ที่แอปพลิเคชันปฏิทินของ Android รองรับเพื่อส่งต่อการดำเนินการอ่านและเขียนไปยังแอปพลิเคชันนั้นแทนได้ เมื่อคุณใช้ Intent แอปพลิเคชันจะส่งผู้ใช้ไปยังแอปพลิเคชันปฏิทินเพื่อดำเนินการที่เลือกในแบบฟอร์มที่กรอกข้อมูลล่วงหน้า หลังจากดำเนินการเสร็จแล้ว ระบบจะส่งผู้ใช้กลับไปยังแอปพลิเคชันของคุณ การออกแบบแอปพลิเคชันให้ดำเนินการทั่วไปผ่านปฏิทินจะช่วยให้ผู้ใช้ได้รับอินเทอร์เฟซผู้ใช้ที่สอดคล้องและมีประสิทธิภาพ ซึ่งเป็นแนวทางที่แนะนำ ดูข้อมูลเพิ่มเติมได้ที่ Calendar Intents
  • อะแดปเตอร์การซิงค์ อะแดปเตอร์การซิงค์จะซิงค์ข้อมูลปฏิทินในอุปกรณ์ของผู้ใช้กับเซิร์ฟเวอร์หรือแหล่งข้อมูลอื่น ในตาราง CalendarContract.Calendars และ CalendarContract.Events มีคอลัมน์ที่สงวนไว้สำหรับอะแดปเตอร์การซิงค์เพื่อใช้งาน ผู้ให้บริการและแอปพลิเคชันไม่ควรแก้ไขข้อมูลดังกล่าว อันที่จริงแล้ว ผู้ใช้จะมองไม่เห็นบัญชีเหล่านี้เว้นแต่จะเข้าถึงในฐานะอะแดปเตอร์การซิงค์ ดูข้อมูลเพิ่มเติมเกี่ยวกับอะแดปเตอร์การซิงค์ได้ที่อะแดปเตอร์การซิงค์

สิทธิ์ของผู้ใช้

หากต้องการอ่านข้อมูลปฏิทิน แอปพลิเคชันต้องมีสิทธิ์ READ_CALENDAR ในไฟล์ Manifest โดยต้องมีสิทธิ์ 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 ได้ที่ 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...

   ...
}

แก้ไขปฏิทิน

หากต้องการอัปเดตปฏิทิน คุณสามารถระบุ _ID ของปฏิทินเป็นรหัสที่ต่อท้าย URI (withAppendedId()) หรือเป็นรายการที่เลือกรายการแรกก็ได้ การเลือกควรเริ่มต้นด้วย "_id=?" และ selectionArg แรกควรเป็น _ID ของปฏิทิน นอกจากนี้ คุณยังอัปเดตได้โดยการเข้ารหัสรหัสใน URI ตัวอย่างนี้จะเปลี่ยนชื่อที่แสดงของปฏิทินโดยใช้วิธี (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 ของ ACCOUNT_TYPE_LOCAL ACCOUNT_TYPE_LOCAL เป็นประเภทบัญชีพิเศษสำหรับปฏิทินที่ไม่ได้เชื่อมโยงกับบัญชีอุปกรณ์ ปฏิทินประเภทนี้จะไม่ซิงค์กับเซิร์ฟเวอร์ ดูการพูดคุยเกี่ยวกับอะแดปเตอร์การซิงค์ได้ที่อะแดปเตอร์การซิงค์

ตารางเหตุการณ์

ตาราง CalendarContract.Events มีรายละเอียดของแต่ละเหตุการณ์ หากต้องการเพิ่ม อัปเดต หรือลบกิจกรรม แอปพลิเคชันต้องมีสิทธิ์ WRITE_CALENDAR ในไฟล์ Manifest

คอลัมน์ Events ต่อไปนี้เขียนได้ทั้งแอปพลิเคชันและอะแดปเตอร์การซิงค์ ดูรายการช่องที่รองรับทั้งหมดได้ในข้อมูลอ้างอิง CalendarContract.Events

ค่าคงที่ คำอธิบาย
CALENDAR_ID _ID ของปฏิทินที่มีกิจกรรมอยู่
ORGANIZER อีเมลของผู้จัด (เจ้าของ) กิจกรรม
TITLE ชื่อกิจกรรม
EVENT_LOCATION สถานที่จัดกิจกรรม
DESCRIPTION คำอธิบายกิจกรรม
DTSTART เวลาที่กิจกรรมเริ่มต้นในหน่วยมิลลิวินาทีตามเวลา UTC นับตั้งแต่ Epoch
DTEND เวลาที่กิจกรรมสิ้นสุดในหน่วยมิลลิวินาที UTC นับตั้งแต่ Epoch
EVENT_TIMEZONE เขตเวลาของกิจกรรม
EVENT_END_TIMEZONE เขตเวลาสำหรับเวลาสิ้นสุดของกิจกรรม
DURATION ระยะเวลาของกิจกรรมในรูปแบบ RFC5545 ตัวอย่างเช่น ค่า "PT1H" ระบุว่ากิจกรรมควรใช้เวลา 1 ชั่วโมง และค่า "P2W" ระบุระยะเวลา 2 สัปดาห์
ALL_DAY ค่า 1 บ่งชี้ว่ากิจกรรมนี้ใช้เวลาทั้งวันตามที่กำหนดโดยเขตเวลาท้องถิ่น ค่า 0 บ่งบอกว่าเป็นกิจกรรมปกติที่อาจเริ่มต้นและสิ้นสุดเมื่อใดก็ได้ในระหว่างวัน
RRULE กฎการเกิดซ้ำสำหรับรูปแบบกิจกรรม เช่น "FREQ=WEEKLY;COUNT=10;WKST=SU" ดูตัวอย่างเพิ่มเติมได้ที่ข้อกำหนด RFC5545
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
  • สำหรับกิจกรรมที่เกิดซ้ำ คุณต้องระบุ DURATION นอกเหนือจาก RRULE หรือ RDATE โปรดทราบว่ากฎนี้จะไม่มีผลหากคุณแทรกกิจกรรมผ่าน Intent INSERT ซึ่งอธิบายไว้ในการใช้ Intent เพื่อแทรกกิจกรรม ในสถานการณ์นั้น คุณสามารถใช้ RRULE ร่วมกับ DTSTART และ DTEND แล้วแอปพลิเคชันปฏิทินจะแปลงเป็นระยะเวลาโดยอัตโนมัติ

ต่อไปนี้เป็นตัวอย่างการแทรกกิจกรรม ซึ่งจะดำเนินการในเธรด UI เพื่อความเรียบง่าย ในทางปฏิบัติ การแทรกและการอัปเดตควรทำในเทรดแบบอะซิงโครนัสเพื่อย้ายการดำเนินการไปยังเทรดเบื้องหลัง ดูข้อมูลเพิ่มเติมได้ที่ 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
//
//

หมายเหตุ: ดูวิธีที่ตัวอย่างนี้บันทึกรหัสเหตุการณ์หลังจากสร้างเหตุการณ์แล้ว ซึ่งเป็นวิธีที่ง่ายที่สุดในการรับรหัสกิจกรรม คุณมักจะต้องใช้รหัสกิจกรรมเพื่อดำเนินการอื่นๆ ในปฏิทิน เช่น เพิ่มผู้เข้าร่วมหรือการช่วยเตือนในกิจกรรม

กิจกรรมการอัปเดต

เมื่อแอปพลิเคชันของคุณต้องการอนุญาตให้ผู้ใช้แก้ไขกิจกรรม เราขอแนะนำให้ใช้ EDIT Intent ตามที่อธิบายไว้ในการใช้ Intent เพื่อแก้ไขกิจกรรม แต่หากจำเป็น คุณก็แก้ไขกิจกรรมได้โดยตรง หากต้องการอัปเดตกิจกรรม คุณสามารถระบุ _ID ของกิจกรรมเป็นรหัสที่ต่อท้าย URI (withAppendedId()) หรือเป็นรายการที่เลือกรายการแรกก็ได้ การเลือกควรเริ่มต้นด้วย "_id=?" และ selectionArg แรกควรเป็น _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 หรือใช้การเลือกมาตรฐาน หากใช้รหัสที่ต่อท้าย คุณจะเลือกไม่ได้ด้วย การลบมี 2 เวอร์ชัน ได้แก่ การลบในฐานะแอปพลิเคชันและการลบในฐานะอะแดปเตอร์การซิงค์ การลบแอปพลิเคชันจะตั้งค่าคอลัมน์ 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 แสดงถึงผู้เข้าร่วมหรือผู้เข้าร่วมกิจกรรม 1 คน การเรียกใช้ query() จะแสดงรายชื่อผู้เข้าร่วมกิจกรรมที่มี EVENT_ID ที่ระบุ EVENT_ID นี้ต้องตรงกับ _ID ของเหตุการณ์หนึ่งๆ

ตารางต่อไปนี้แสดงช่องที่เขียนได้ เมื่อแทรกผู้เข้าร่วมใหม่ คุณต้องระบุผู้เข้าร่วมทั้งหมด ยกเว้น ATTENDEE_NAME

ค่าคงที่ คำอธิบาย
EVENT_ID รหัสของกิจกรรม
ATTENDEE_NAME ชื่อของผู้เข้าร่วม
ATTENDEE_EMAIL อีเมลของผู้เข้าร่วม
ATTENDEE_RELATIONSHIP

ความสัมพันธ์ของผู้เข้าร่วมกับกิจกรรม ข้อใดข้อหนึ่งต่อไปนี้

ATTENDEE_TYPE

ประเภทของผู้เข้าร่วม ข้อใดข้อหนึ่งต่อไปนี้

ATTENDEE_STATUS

สถานะการเข้าร่วมของผู้เข้าร่วม ข้อใดข้อหนึ่งต่อไปนี้

เพิ่มผู้เข้าร่วม

ต่อไปนี้เป็นตัวอย่างการเพิ่มผู้เข้าร่วม 1 คนในกิจกรรม โปรดทราบว่าต้องระบุ 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 แสดงถึงการช่วยเตือน 1 รายการสำหรับกิจกรรม การเรียกใช้ query() จะแสดงรายการการช่วยเตือนสำหรับกิจกรรมที่มี EVENT_ID ที่ระบุ

ตารางต่อไปนี้แสดงช่องที่เขียนได้สำหรับการช่วยเตือน ต้องระบุข้อมูลทั้งหมดเมื่อแทรกการช่วยเตือนใหม่ โปรดทราบว่าอะแดปเตอร์การซิงค์จะระบุประเภทการช่วยเตือนที่รองรับในตาราง CalendarContract.Calendars ดูรายละเอียดได้ที่ ALLOWED_REMINDERS

ค่าคงที่ คำอธิบาย
EVENT_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 จะเก็บเวลาเริ่มต้นและสิ้นสุดของการเกิดเหตุการณ์ แต่ละแถวในตารางนี้แสดงถึงการเกิดเหตุการณ์ 1 ครั้ง ตารางอินสแตนซ์ไม่สามารถเขียนได้และมีไว้เพื่อค้นหาการเกิดเหตุการณ์เท่านั้น

ตารางต่อไปนี้แสดงช่องบางช่องที่คุณค้นหาอินสแตนซ์ได้ โปรดทราบว่าเขตเวลาจะกำหนดโดย KEY_TIMEZONE_TYPE และ KEY_TIMEZONE_INSTANCES

ค่าคงที่ คำอธิบาย
BEGIN เวลาเริ่มต้นของอินสแตนซ์ในหน่วยมิลลิวินาทีตามเวลา UTC
END เวลาสิ้นสุดของอินสแตนซ์ในหน่วยมิลลิวินาทีตามเวลา UTC
END_DAY วันสิ้นสุดของอินสแตนซ์ตามปฏิทินจูเลียน โดยอิงตามเขตเวลาของปฏิทิน
END_MINUTE นาทีสิ้นสุดของอินสแตนซ์ที่วัดจากเที่ยงคืนในเขตเวลาของปฏิทิน
EVENT_ID _IDของเหตุการณ์สำหรับอินสแตนซ์นี้
START_DAY วันเริ่มต้นแบบจูเลียนของอินสแตนซ์ โดยสัมพันธ์กับเขตเวลาของปฏิทิน
START_MINUTE นาทีเริ่มต้นของอินสแตนซ์ที่วัดจากเที่ยงคืน โดยสัมพันธ์กับเขตเวลาของปฏิทิน

ค้นหาตารางอินสแตนซ์

หากต้องการค้นหาตารางอินสแตนซ์ คุณต้องระบุช่วงเวลาสำหรับการค้นหาใน URI ในตัวอย่างนี้ CalendarContract.Instances จะได้รับสิทธิ์เข้าถึงช่อง TITLE ผ่านการติดตั้งใช้งานอินเทอร์เฟซ CalendarContract.EventsColumns กล่าวคือ ระบบจะแสดงผล 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 ของปฏิทิน

แอปพลิเคชันของคุณไม่จำเป็นต้องมีสิทธิ์ในการอ่านและเขียนข้อมูลปฏิทิน แต่สามารถใช้ Intent ที่แอปพลิเคชันปฏิทินของ Android รองรับเพื่อส่งต่อการดำเนินการอ่านและเขียนไปยังแอปพลิเคชันนั้นแทนได้ ตารางต่อไปนี้แสดง Intent ที่ผู้ให้บริการปฏิทินรองรับ

การทำงาน URI คำอธิบาย เพิ่มเติม

VIEW

content://com.android.calendar/time/<ms_since_epoch>

นอกจากนี้ คุณยังอ้างอิง URI ด้วย CalendarContract.CONTENT_URI ได้ด้วย ดูตัวอย่างการใช้ Intent นี้ได้ที่หัวข้อการใช้ Intent เพื่อดูข้อมูลปฏิทิน
เปิดปฏิทินตามเวลาที่ระบุโดย <ms_since_epoch> ไม่มี

VIEW

content://com.android.calendar/events/<event_id>

นอกจากนี้ คุณยังอ้างอิง URI ด้วย Events.CONTENT_URI ได้ด้วย ดูตัวอย่างการใช้ Intent นี้ได้ที่หัวข้อการใช้ Intent เพื่อดูข้อมูลปฏิทิน
ดูกิจกรรมที่ระบุโดย <event_id> CalendarContract.EXTRA_EVENT_BEGIN_TIME


CalendarContract.EXTRA_EVENT_END_TIME
EDIT

content://com.android.calendar/events/<event_id>

นอกจากนี้ คุณยังอ้างอิง URI ด้วย Events.CONTENT_URI ได้ด้วย ดูตัวอย่างการใช้ Intent นี้ได้ที่การใช้ Intent เพื่อแก้ไขเหตุการณ์
แก้ไขกิจกรรมที่ระบุโดย <event_id> CalendarContract.EXTRA_EVENT_BEGIN_TIME


CalendarContract.EXTRA_EVENT_END_TIME
EDIT

INSERT

content://com.android.calendar/events

นอกจากนี้ คุณยังอ้างอิง URI ด้วย Events.CONTENT_URI ได้ด้วย ดูตัวอย่างการใช้ Intent นี้ได้ที่การใช้ Intent เพื่อแทรกกิจกรรม
สร้างกิจกรรม รายการเสริมที่ระบุไว้ในตารางต่อไปนี้

ตารางต่อไปนี้แสดงรายการ Intent Extra ที่ผู้ให้บริการปฏิทินรองรับ

Intent Extra คำอธิบาย
Events.TITLE ชื่อเหตุการณ์
CalendarContract.EXTRA_EVENT_BEGIN_TIME เวลาเริ่มต้นของเหตุการณ์ในหน่วยมิลลิวินาทีจาก Epoch
CalendarContract.EXTRA_EVENT_END_TIME เวลาสิ้นสุดของกิจกรรมในหน่วยมิลลิวินาทีจาก Epoch
CalendarContract.EXTRA_EVENT_ALL_DAY บูลีนที่ระบุว่ากิจกรรมเป็นแบบตลอดวัน ค่าอาจเป็น true หรือ false
Events.EVENT_LOCATION ตำแหน่งของเหตุการณ์
Events.DESCRIPTION คำอธิบายกิจกรรม
Intent.EXTRA_EMAIL อีเมลของผู้ที่ต้องการเชิญเป็นรายการที่คั่นด้วยคอมมา
Events.RRULE กฎการเกิดซ้ำของกิจกรรม
Events.ACCESS_LEVEL กิจกรรมเป็นแบบส่วนตัวหรือสาธารณะ
Events.AVAILABILITY กิจกรรมนี้ถือเป็นเวลาที่ไม่ว่างหรือเป็นเวลาว่างที่สามารถกำหนดเวลาทับได้

ส่วนต่อไปนี้จะอธิบายวิธีใช้ Intent เหล่านี้

ใช้ Intent เพื่อแทรกกิจกรรม

การใช้ Intent INSERT จะช่วยให้แอปพลิเคชันของคุณส่งต่อการแทรกกิจกรรมไปยังปฏิทินได้โดยตรง ด้วยวิธีนี้ แอปพลิเคชันของคุณไม่จำเป็นต้องมีสิทธิ์ WRITE_CALENDAR รวมอยู่ในไฟล์ Manifest ด้วยซ้ำ

เมื่อผู้ใช้เรียกใช้แอปพลิเคชันที่ใช้แนวทางนี้ แอปพลิเคชันจะส่งผู้ใช้ไปยังปฏิทินเพื่อเพิ่มกิจกรรมให้เสร็จสิ้น Intent INSERT จะใช้ช่องเพิ่มเติมเพื่อป้อนข้อมูลล่วงหน้าในแบบฟอร์มพร้อมรายละเอียดของกิจกรรมในปฏิทิน จากนั้นผู้ใช้จะยกเลิกกิจกรรม แก้ไขแบบฟอร์มตามต้องการ หรือบันทึกกิจกรรมลงในปฏิทินได้

ต่อไปนี้เป็นข้อมูลโค้ดที่กำหนดเวลากิจกรรมในวันที่ 19 มกราคม 2012 ซึ่งจะเริ่มตั้งแต่เวลา 07:30 น. ถึง 08:30 น. โปรดทราบข้อมูลต่อไปนี้เกี่ยวกับข้อมูลโค้ดนี้

  • โดยจะระบุ Events.CONTENT_URI เป็น URI
  • โดยจะใช้ช่องเพิ่มเติม CalendarContract.EXTRA_EVENT_BEGIN_TIME และ CalendarContract.EXTRA_EVENT_END_TIME เพื่อป้อนข้อมูลเวลาของกิจกรรมลงในแบบฟอร์มล่วงหน้า ค่าของเวลาเหล่านี้ต้องอยู่ในหน่วยมิลลิวินาที UTC จาก Epoch
  • โดยใช้ช่อง Intent.EXTRA_EMAIL เพิ่มเติมเพื่อระบุรายการผู้ได้รับเชิญที่คั่นด้วยคอมมา ซึ่งระบุตามอีเมล

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 เพื่อแก้ไขเหตุการณ์

คุณสามารถอัปเดตกิจกรรมได้โดยตรงตามที่อธิบายไว้ในการอัปเดตกิจกรรม แต่การใช้ Intent EDIT จะช่วยให้แอปพลิเคชันที่ไม่มีสิทธิ์สามารถส่งต่อการแก้ไขกิจกรรมไปยังแอปพลิเคชันปฏิทินได้ เมื่อผู้ใช้แก้ไขกิจกรรมในปฏิทินเสร็จแล้ว ระบบจะนำผู้ใช้กลับไปยังแอปพลิเคชันเดิม

ต่อไปนี้คือตัวอย่าง 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 เพื่อดูข้อมูลปฏิทิน

ผู้ให้บริการปฏิทินมีวิธีใช้ Intent VIEW 2 วิธี ดังนี้

  • เพื่อเปิดปฏิทินในวันที่ที่ต้องการ
  • วิธีดูกิจกรรม

ตัวอย่างต่อไปนี้แสดงวิธีเปิดปฏิทินไปยังวันที่ที่ต้องการ

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();
 }