Sửa đổi người liên hệ bằng cách sử dụng ý định

Bài học này hướng dẫn bạn cách sử dụng Intent để chèn một người liên hệ mới hoặc sửa đổi dữ liệu của một địa chỉ liên hệ. Thay vì truy cập trực tiếp vào Nhà cung cấp danh bạ, Intent sẽ khởi động ứng dụng danh bạ, ứng dụng này sẽ chạy Activity thích hợp. Đối với các thao tác sửa đổi được mô tả trong bài học này, nếu bạn gửi dữ liệu mở rộng trong Intent, dữ liệu đó sẽ được nhập vào giao diện người dùng của Activity đã khởi động.

Bạn nên sử dụng Intent để chèn hoặc cập nhật một người liên hệ, vì những lý do sau:

• Điều này giúp bạn tiết kiệm thời gian và công sức phát triển giao diện người dùng và mã của riêng mình.
• Điều này giúp tránh các lỗi do các nội dung sửa đổi không tuân thủ quy tắc của Nhà cung cấp danh bạ.
• Việc này giúp giảm số lượng quyền mà bạn cần yêu cầu. Ứng dụng của bạn không cần quyền ghi vào Nhà cung cấp danh bạ, vì ứng dụng này uỷ quyền các nội dung sửa đổi cho ứng dụng danh bạ, ứng dụng này đã có quyền đó.

Chèn một địa chỉ liên hệ mới bằng cách sử dụng ý định

Thường thì bạn muốn cho phép người dùng chèn một người liên hệ mới khi ứng dụng của bạn nhận được dữ liệu mới. Ví dụ: ứng dụng đánh giá nhà hàng có thể cho phép người dùng thêm nhà hàng làm thông tin liên hệ khi họ đánh giá nhà hàng đó. Để thực hiện việc này bằng một ý định, hãy tạo ý định bằng cách sử dụng nhiều dữ liệu nhất có thể, sau đó gửi ý định đó đến ứng dụng danh bạ.

Thao tác chèn một người liên hệ bằng ứng dụng danh bạ sẽ chèn một người liên hệ thô mới vào bảng ContactsContract.RawContacts của Trình cung cấp danh bạ. Nếu cần, ứng dụng danh bạ sẽ nhắc người dùng chọn loại tài khoản và tài khoản để sử dụng khi tạo danh bạ thô. Ứng dụng danh bạ cũng sẽ thông báo cho người dùng nếu đã có thông tin liên hệ thô. Sau đó, người dùng có thể huỷ thao tác chèn. Trong trường hợp này, hệ thống sẽ không tạo thông tin liên hệ nào. Để tìm hiểu thông tin thêm về danh bạ thô, hãy xem Trình cung cấp danh bạ Hướng dẫn về API.

Tạo ý định

Để bắt đầu, hãy tạo một đối tượng Intent mới bằng thao tác Intents.Insert.ACTION. Đặt loại MIME thành RawContacts.CONTENT_TYPE. Ví dụ:

...
// Creates a new Intent to insert a contact
val intent = Intent(ContactsContract.Intents.Insert.ACTION).apply {
    // Sets the MIME type to match the Contacts Provider
    type = ContactsContract.RawContacts.CONTENT_TYPE
}

...
// Creates a new Intent to insert a contact
Intent intent = new Intent(ContactsContract.Intents.Insert.ACTION);
// Sets the MIME type to match the Contacts Provider
intent.setType(ContactsContract.RawContacts.CONTENT_TYPE);

Nếu đã có thông tin chi tiết về người liên hệ, chẳng hạn như số điện thoại hoặc địa chỉ email, bạn có thể chèn những thông tin đó vào ý định dưới dạng dữ liệu mở rộng. Đối với giá trị khoá, hãy sử dụng hằng số thích hợp từ Intents.Insert. Ứng dụng danh bạ sẽ hiển thị dữ liệu trong màn hình chèn, cho phép người dùng chỉnh sửa và thêm dữ liệu.

private var emailAddress: EditText? = null
private var phoneNumber: EditText? = null
...
/* Assumes EditText fields in your UI contain an email address
 * and a phone number.
 *
 */
emailAddress = findViewById(R.id.email)
phoneNumber = findViewById(R.id.phone)
...
/*
 * Inserts new data into the Intent. This data is passed to the
 * contacts app's Insert screen
 */
intent.apply {
    // Inserts an email address
    putExtra(ContactsContract.Intents.Insert.EMAIL, emailAddress?.text)
    /*
     * In this example, sets the email type to be a work email.
     * You can set other email types as necessary.
     */
    putExtra(
            ContactsContract.Intents.Insert.EMAIL_TYPE,
            ContactsContract.CommonDataKinds.Email.TYPE_WORK
    )
    // Inserts a phone number
    putExtra(ContactsContract.Intents.Insert.PHONE, phoneNumber?.text)
    /*
     * In this example, sets the phone type to be a work phone.
     * You can set other phone types as necessary.
     */
    putExtra(
            ContactsContract.Intents.Insert.PHONE_TYPE,
            ContactsContract.CommonDataKinds.Phone.TYPE_WORK
    )
}

private EditText emailAddress = null;
private EditText phoneNumber = null;
...
/* Assumes EditText fields in your UI contain an email address
 * and a phone number.
 *
 */
emailAddress = (EditText) findViewById(R.id.email);
phoneNumber = (EditText) findViewById(R.id.phone);
...
/*
 * Inserts new data into the Intent. This data is passed to the
 * contacts app's Insert screen
 */
// Inserts an email address
intent.putExtra(ContactsContract.Intents.Insert.EMAIL, emailAddress.getText())
/*
 * In this example, sets the email type to be a work email.
 * You can set other email types as necessary.
 */
      .putExtra(ContactsContract.Intents.Insert.EMAIL_TYPE,
            ContactsContract.CommonDataKinds.Email.TYPE_WORK)
// Inserts a phone number
      .putExtra(ContactsContract.Intents.Insert.PHONE, phoneNumber.getText())
/*
 * In this example, sets the phone type to be a work phone.
 * You can set other phone types as necessary.
 */
      .putExtra(ContactsContract.Intents.Insert.PHONE_TYPE,
            ContactsContract.CommonDataKinds.Phone.TYPE_WORK);

Sau khi bạn tạo Intent, hãy gửi bằng cách gọi lệnh startActivity().

    /* Sends the Intent
     */
    startActivity(intent)

    /* Sends the Intent
     */
    startActivity(intent);

Cuộc gọi này sẽ mở ra một màn hình trong ứng dụng danh bạ cho phép người dùng nhập một người liên hệ mới. Chiến lược phát hành đĩa đơn loại tài khoản và tên tài khoản của người liên hệ được liệt kê ở đầu màn hình. Sau khi người dùng nhập dữ liệu và nhấp vào Xong, danh sách liên hệ của ứng dụng danh bạ sẽ xuất hiện. Người dùng quay lại ứng dụng của bạn bằng cách nhấp vào Back (Quay lại).

Chỉnh sửa một địa chỉ liên hệ hiện có bằng ý định

Việc chỉnh sửa một người liên hệ hiện có bằng Intent sẽ hữu ích nếu người dùng đã chọn người liên hệ mà bạn quan tâm. Ví dụ: một ứng dụng tìm người liên hệ có địa chỉ bưu chính nhưng thiếu mã bưu chính có thể cho phép người dùng tra cứu mã đó rồi thêm vào người liên hệ.

Để chỉnh sửa người liên hệ hiện có bằng một ý định, hãy làm theo quy trình tương tự như đang chèn một địa chỉ liên hệ. Tạo một ý định như được mô tả trong phần này Chèn một người liên hệ mới bằng cách sử dụng một ý định, nhưng thêm thông tin Contacts.CONTENT_LOOKUP_URI và loại MIME Contacts.CONTENT_ITEM_TYPE cho ý định. Nếu bạn muốn chỉnh sửa người liên hệ bằng thông tin chi tiết của mình đã có, bạn có thể đưa chúng vào dữ liệu mở rộng của ý định. Xin lưu ý rằng bạn không thể chỉnh sửa một số cột tên bằng ý định; các cột này được liệt kê trong phần tóm tắt của tài liệu tham khảo API cho lớp ContactsContract.Contacts trong tiêu đề "Cập nhật".

Cuối cùng, hãy gửi ý định. Để phản hồi, ứng dụng Danh bạ sẽ hiện màn hình chỉnh sửa. Khi người dùng hoàn tất chỉnh sửa và lưu nội dung chỉnh sửa, ứng dụng danh bạ sẽ hiển thị một danh bạ. Khi người dùng nhấp vào Back (Quay lại), ứng dụng của bạn sẽ hiển thị.

Tạo ý định

Để chỉnh sửa một người liên hệ, hãy gọi Intent(action) để tạo một ý định bằng thao tác ACTION_EDIT. Gọi điện setDataAndType() để đặt giá trị dữ liệu cho ý định đối với Contacts.CONTENT_LOOKUP_URI của địa chỉ liên hệ và loại MIME để Loại Contacts.CONTENT_ITEM_TYPE MIME; vì một lệnh gọi đến setType() sẽ ghi đè giá trị dữ liệu hiện tại cho Intent, bạn phải thiết lập dữ liệu và loại MIME cùng một lúc.

Để nhận Contacts.CONTENT_LOOKUP_URI của một người liên hệ, hãy gọi Contacts.getLookupUri(id, lookupkey) của người liên hệ Contacts._ID và Giá trị Contacts.LOOKUP_KEY dưới dạng đối số.

Lưu ý: Giá trị LOOKUP_KEY của một người liên hệ là giá trị nhận dạng mà bạn nên sử dụng để truy xuất người liên hệ. Mã này không thay đổi, ngay cả khi nhà cung cấp thay đổi mã hàng của người liên hệ để xử lý các hoạt động nội bộ.

Đoạn mã sau đây cho bạn biết cách tạo một ý định:

    // The Cursor that contains the Contact row
    var mCursor: Cursor? = null
    // The index of the lookup key column in the cursor
    var lookupKeyIndex: Int = 0
    // The index of the contact's _ID value
    var idIndex: Int = 0
    // The lookup key from the Cursor
    var currentLookupKey: String? = null
    // The _ID value from the Cursor
    var currentId: Long = 0
    // A content URI pointing to the contact
    var selectedContactUri: Uri? = null
    ...
    /*
     * Once the user has selected a contact to edit,
     * this gets the contact's lookup key and _ID values from the
     * cursor and creates the necessary URI.
     */
    mCursor?.apply {
        // Gets the lookup key column index
        lookupKeyIndex = getColumnIndex(ContactsContract.Contacts.LOOKUP_KEY)
        // Gets the lookup key value
        currentLookupKey = getString(lookupKeyIndex)
        // Gets the _ID column index
        idIndex = getColumnIndex(ContactsContract.Contacts._ID)
        currentId = getLong(idIndex)
        selectedContactUri = ContactsContract.Contacts.getLookupUri(currentId, mCurrentLookupKey)
    }

    // Creates a new Intent to edit a contact
    val editIntent = Intent(Intent.ACTION_EDIT).apply {
        /*
         * Sets the contact URI to edit, and the data type that the
         * Intent must match
         */
        setDataAndType(selectedContactUri, ContactsContract.Contacts.CONTENT_ITEM_TYPE)
    }

    // The Cursor that contains the Contact row
    public Cursor mCursor;
    // The index of the lookup key column in the cursor
    public int lookupKeyIndex;
    // The index of the contact's _ID value
    public int idIndex;
    // The lookup key from the Cursor
    public String currentLookupKey;
    // The _ID value from the Cursor
    public long currentId;
    // A content URI pointing to the contact
    Uri selectedContactUri;
    ...
    /*
     * Once the user has selected a contact to edit,
     * this gets the contact's lookup key and _ID values from the
     * cursor and creates the necessary URI.
     */
    // Gets the lookup key column index
    lookupKeyIndex = mCursor.getColumnIndex(ContactsContract.Contacts.LOOKUP_KEY);
    // Gets the lookup key value
    currentLookupKey = mCursor.getString(lookupKeyIndex);
    // Gets the _ID column index
    idIndex = mCursor.getColumnIndex(ContactsContract.Contacts._ID);
    currentId = mCursor.getLong(idIndex);
    selectedContactUri =
            Contacts.getLookupUri(currentId, mCurrentLookupKey);
    ...
    // Creates a new Intent to edit a contact
    Intent editIntent = new Intent(Intent.ACTION_EDIT);
    /*
     * Sets the contact URI to edit, and the data type that the
     * Intent must match
     */
    editIntent.setDataAndType(selectedContactUri, ContactsContract.Contacts.CONTENT_ITEM_TYPE);

Thêm cờ điều hướng

Trong Android 4.0 (API phiên bản 14) trở lên, sự cố trong ứng dụng danh bạ gây ra lỗi điều hướng. Khi ứng dụng của bạn gửi ý định chỉnh sửa đến ứng dụng danh bạ, đồng thời người dùng chỉnh sửa và lưu người liên hệ khi nhấp vào Quay lại, họ sẽ thấy màn hình danh bạ. Để quay lại ứng dụng của bạn, họ phải nhấp vào Gần đây rồi chọn ứng dụng của bạn.

Để giải quyết vấn đề này trong Android 4.0.3 (API phiên bản 15) trở lên, hãy thêm đoạn mã khoá dữ liệu finishActivityOnSaveCompleted cho ý định, có giá trị true. Các phiên bản Android trước Android 4.0 chấp nhận khoá này nhưng không có hiệu lực. Để đặt dữ liệu mở rộng, hãy làm như sau:

    // Sets the special extended data for navigation
    editIntent.putExtra("finishActivityOnSaveCompleted", true)

    // Sets the special extended data for navigation
    editIntent.putExtra("finishActivityOnSaveCompleted", true);

Thêm dữ liệu mở rộng khác

Để thêm dữ liệu mở rộng khác vào Intent, hãy gọi putExtra() như mong muốn. Bạn có thể thêm dữ liệu mở rộng cho các trường liên hệ phổ biến bằng cách sử dụng các khoá-giá trị được chỉ định trong Intents.Insert. Hãy nhớ rằng bạn không thể sửa đổi một số cột trong bảng ContactsContract.Contacts. Các cột này được liệt kê trong phần tóm tắt của tài liệu tham khảo API cho lớp ContactsContract.Contacts theo tiêu đề "Cập nhật".

Gửi ý định

Cuối cùng, hãy gửi ý định mà bạn đã tạo. Ví dụ:

    // Sends the Intent
    startActivity(editIntent)

    // Sends the Intent
    startActivity(editIntent);

Cho phép người dùng chọn chèn hoặc chỉnh sửa bằng cách sử dụng ý định

Bạn có thể cho phép người dùng chọn chèn người liên hệ hoặc chỉnh sửa người liên hệ hiện có bằng cách gửi Intent với thao tác ACTION_INSERT_OR_EDIT. Ví dụ: ứng dụng email khách có thể cho phép người dùng thêm địa chỉ email đến vào địa chỉ liên hệ mới hoặc thêm địa chỉ này làm địa chỉ liên hệ bổ sung của một địa chỉ liên hệ hiện tại. Đặt loại MIME cho ý định này thành Contacts.CONTENT_ITEM_TYPE! nhưng không đặt URI dữ liệu.

Khi bạn gửi ý định này, ứng dụng danh bạ sẽ hiển thị danh sách người liên hệ. Người dùng có thể chèn một người liên hệ mới hoặc chọn một người liên hệ hiện có rồi chỉnh sửa. Mọi trường dữ liệu mở rộng mà bạn thêm vào ý định sẽ điền vào màn hình xuất hiện. Bạn có thể dùng bất kỳ giá trị khoá nào được chỉ định trong Intents.Insert. Đoạn mã sau đây cho biết cách tạo và gửi ý định:

    // Creates a new Intent to insert or edit a contact
    val intentInsertEdit = Intent(Intent.ACTION_INSERT_OR_EDIT).apply {
        // Sets the MIME type
        type = ContactsContract.Contacts.CONTENT_ITEM_TYPE
    }
    // Add code here to insert extended data, if desired

    // Sends the Intent with an request ID
    startActivity(intentInsertEdit)

    // Creates a new Intent to insert or edit a contact
    Intent intentInsertEdit = new Intent(Intent.ACTION_INSERT_OR_EDIT);
    // Sets the MIME type
    intentInsertEdit.setType(ContactsContract.Contacts.CONTENT_ITEM_TYPE);
    // Add code here to insert extended data, if desired
    ...
    // Sends the Intent with an request ID
    startActivity(intentInsertEdit);