Kontak dan ContactsUI di Xamarin.iOS

Artikel ini membahas cara kerja dengan kerangka kerja Antarmuka Pengguna Kontak dan Kontak baru di aplikasi Xamarin.iOS. Kerangka kerja ini menggantikan UI Buku Alamat dan Buku Alamat yang ada yang digunakan di versi iOS sebelumnya.

Dengan pengenalan iOS 9, Apple telah merilis dua kerangka kerja baru, Contacts dan ContactsUI, yang menggantikan kerangka kerja UI Buku Alamat dan Buku Alamat yang ada yang digunakan oleh iOS 8 dan yang lebih lama.

Dua kerangka kerja baru berisi fungsionalitas berikut:

• Kontak - Menyediakan akses ke data daftar kontak pengguna. Karena sebagian besar aplikasi hanya memerlukan akses baca-saja, kerangka kerja ini telah dioptimalkan untuk akses utas yang aman dan baca-saja.

• ContactsUI - Menyediakan elemen UI Xamarin.iOS untuk menampilkan, mengedit, memilih, dan membuat kontak di perangkat iOS.

Di bagian berikut, kita akan melihat kerangka kerja baru ini dan cara mengimplementasikannya di aplikasi Xamarin.iOS.

Kerangka Kerja Kontak

Kerangka Kerja Kontak menyediakan akses Xamarin.iOS ke informasi kontak pengguna. Karena sebagian besar aplikasi hanya memerlukan akses baca-saja, kerangka kerja ini telah dioptimalkan untuk akses utas yang aman dan baca-saja.

Objek Kontak

Kelas ini CNContact menyediakan akses utas aman dan baca-saja ke properti kontak seperti Nama, Alamat, atau Nomor Telepon. CNContact fungsi seperti NSDictionary dan berisi beberapa kumpulan properti baca-saja (seperti alamat atau nomor telepon):

Untuk properti apa pun yang dapat memiliki beberapa nilai (seperti alamat email atau nomor telepon), properti tersebut akan diwakili sebagai array NSLabeledValue objek. NSLabeledValue adalah tuple aman utas yang terdiri dari sekumpulan label dan nilai baca-saja di mana label menentukan nilai kepada pengguna (misalnya email Rumah atau Kantor). Kerangka kerja Kontak menyediakan pilihan label yang telah ditentukan sebelumnya (melalui CNLabelKey kelas statis dan CNLabelPhoneNumberKey ) yang dapat Anda gunakan di aplikasi Anda atau Anda memiliki opsi untuk menentukan label kustom untuk kebutuhan Anda.

Untuk aplikasi Xamarin.iOS apa pun yang perlu menyesuaikan nilai kontak yang ada (atau membuat yang baru), gunakan NSMutableContact versi kelas dan sub kelasnya (seperti CNMutablePostalAddress).

Misalnya, kode berikut akan membuat kontak baru dan menambahkannya ke kumpulan kontak pengguna:

// Create a new Mutable Contact (read/write)
var contact = new CNMutableContact();

// Set standard properties
contact.GivenName = "John";
contact.FamilyName = "Appleseed";

// Add email addresses
var homeEmail = new CNLabeledValue<NSString>(CNLabelKey.Home, new NSString("john.appleseed@mac.com"));
var workEmail = new CNLabeledValue<NSString>(CNLabelKey.Work, new NSString("john.appleseed@apple.com"));
contact.EmailAddresses = new CNLabeledValue<NSString>[] { homeEmail, workEmail };

// Add phone numbers
var cellPhone = new CNLabeledValue<CNPhoneNumber>(CNLabelPhoneNumberKey.iPhone, new CNPhoneNumber("713-555-1212"));
var workPhone = new CNLabeledValue<CNPhoneNumber>("Work", new CNPhoneNumber("408-555-1212"));
contact.PhoneNumbers = new CNLabeledValue<CNPhoneNumber>[] { cellPhone, workPhone };

// Add work address
var workAddress = new CNMutablePostalAddress()
{
    Street = "1 Infinite Loop",
    City = "Cupertino",
    State = "CA",
    PostalCode = "95014"
};
contact.PostalAddresses = new CNLabeledValue<CNPostalAddress>[] { new CNLabeledValue<CNPostalAddress>(CNLabelKey.Work, workAddress) };

// Add birthday
var birthday = new NSDateComponents()
{
    Day = 1,
    Month = 4,
    Year = 1984
};
contact.Birthday = birthday;

// Save new contact
var store = new CNContactStore();
var saveRequest = new CNSaveRequest();
saveRequest.AddContact(contact, store.DefaultContainerIdentifier);

// Attempt to save changes
NSError error;
if (store.ExecuteSaveRequest(saveRequest, out error))
{
    Console.WriteLine("New contact saved");
}
else
{
    Console.WriteLine("Save error: {0}", error);
}

Jika kode ini dijalankan pada perangkat iOS 9, kontak baru akan ditambahkan ke koleksi pengguna. Contohnya:

Pemformatan dan Pelokalan Kontak

Kerangka kerja Kontak berisi beberapa objek dan metode yang dapat membantu Anda memformat dan melokalisasi konten untuk ditampilkan kepada pengguna. Misalnya, kode berikut akan memformat nama kontak dan alamat surat dengan benar untuk ditampilkan:

Console.WriteLine(CNContactFormatter.GetStringFrom(contact, CNContactFormatterStyle.FullName));
Console.WriteLine(CNPostalAddressFormatter.GetStringFrom(workAddress, CNPostalAddressFormatterStyle.MailingAddress));

Untuk label properti yang akan Anda tampilkan di UI aplikasi Anda, kerangka kerja Kontak juga memiliki metode untuk melokalisasi string tersebut. Sekali lagi, ini didasarkan pada lokal perangkat iOS saat ini yang sedang dijalankan aplikasi. Contohnya:

// Localized properties
Console.WriteLine(CNContact.LocalizeProperty(CNContactOptions.Nickname));
Console.WriteLine(CNLabeledValue<NSString>.LocalizeLabel(CNLabelKey.Home));

Mengambil Kontak yang Ada

Dengan menggunakan instans CNContactStore kelas , Anda dapat mengambil informasi kontak dari database kontak pengguna. CNContactStore berisi semua metode yang diperlukan untuk mengambil atau memperbarui kontak dan grup dari database. Karena metode ini sinkron, disarankan agar Anda menjalankannya di utas latar belakang agar tidak memblokir UI.

Dengan menggunakan predikat (dibuat dari CNContact kelas), Anda dapat memfilter hasil yang dikembalikan saat mengambil kontak dari database. Untuk mengambil hanya kontak yang berisi string Appleseed, gunakan kode berikut:

// Create predicate to locate requested contact
var predicate = CNContact.GetPredicateForContacts("Appleseed");

Misalnya, untuk membatasi pengambilan hanya ke properti GivenName dan FamilyName kontak, gunakan kode berikut:

// Define fields to be searched
var fetchKeys = new NSString[] {CNContactKey.GivenName, CNContactKey.FamilyName};

Terakhir, untuk mencari database dan mengembalikan hasilnya, gunakan kode berikut:

// Grab matching contacts
var store = new CNContactStore();
NSError error;
var contacts = store.GetUnifiedContacts(predicate, fetchKeys, out error);

Jika kode ini dijalankan setelah sampel yang kami buat di bagian Objek Kontak di atas, kode ini akan mengembalikan kontak "John Appleseed" yang baru saja kami buat.

Privasi Akses Kontak

Karena pengguna akhir dapat memberikan atau menolak akses ke informasi kontak mereka berdasarkan per aplikasi, pertama kali Anda melakukan panggilan ke CNContactStore, dialog akan disajikan meminta mereka untuk mengizinkan akses untuk aplikasi Anda.

Permintaan izin hanya akan disajikan sekali, pertama kali aplikasi dijalankan, dan eksekusi atau panggilan berikutnya ke CNContactStore akan menggunakan izin yang dipilih pengguna pada saat itu.

Anda harus merancang aplikasi Anda sehingga dengan anggun menangani pengguna yang menolak akses ke database kontak mereka.

Mengambil Kontak Parsial

Kontak Parsial adalah kontak yang hanya diambil beberapa properti yang tersedia dari penyimpanan kontak. Jika Anda mencoba mengakses properti yang sebelumnya tidak diambil, properti tersebut akan menghasilkan pengecualian.

Anda dapat dengan mudah memeriksa untuk melihat apakah kontak tertentu memiliki properti yang diinginkan dengan menggunakan IsKeyAvailable metode atau AreKeysAvailable instans CNContact . Contohnya:

// Does the contact contain the requested key?
if (!contact.IsKeyAvailable(CNContactOption.PostalAddresses)) {
    // No, re-request to pull required info
    var fetchKeys = new NSString[] {CNContactKey.GivenName, CNContactKey.FamilyName, CNContactKey.PostalAddresses};
    var store = new CNContactStore();
    NSError error;
    contact = store.GetUnifiedContact(contact.Identifier, fetchKeys, out error);
}

Kontak Terpadu

Pengguna mungkin memiliki sumber informasi kontak yang berbeda untuk satu orang di database kontak mereka (seperti iCloud, Facebook, atau Google Mail). Di aplikasi iOS dan OS X, informasi kontak ini akan secara otomatis ditautkan bersama dan ditampilkan kepada pengguna sebagai kontak terpadu tunggal:

Kontak Terpadu ini adalah tampilan sementara dalam memori dari informasi kontak tautan yang akan diberikan pengidentifikasi uniknya sendiri (yang harus digunakan untuk mengambil kembali kontak jika diperlukan). Secara default, kerangka kerja Kontak akan mengembalikan Kontak Terpadu jika memungkinkan.

Membuat dan Memperbarui Kontak

Seperti yang kita lihat di bagian Objek Kontak di atas, Anda menggunakan CNContactStore dan instans CNMutableContact untuk membuat kontak baru yang kemudian ditulis ke database kontak pengguna menggunakan CNSaveRequest :

// Create a new Mutable Contact (read/write)
var contact = new CNMutableContact();

// Set standard properties
contact.GivenName = "John";
contact.FamilyName = "Appleseed";

// Save new contact
var store = new CNContactStore();
var saveRequest = new CNSaveRequest();
saveRequest.AddContact(contact, store.DefaultContainerIdentifier);

NSError error;
if (store.ExecuteSaveRequest(saveRequest, out error)) {
    Console.WriteLine("New contact saved");
} else {
    Console.WriteLine("Save error: {0}", error);
}

Juga CNSaveRequest dapat digunakan untuk menyimpan beberapa kontak dan mengelompokkan perubahan menjadi satu operasi dan mengumpulkan modifikasi tersebut ke CNContactStore.

Untuk memperbarui kontak yang tidak dapat diubah yang diperoleh dari operasi pengambilan, Anda harus terlebih dahulu meminta salinan yang dapat diubah yang kemudian Anda ubah dan simpan kembali ke penyimpanan kontak. Contohnya:

// Get mutable copy of contact
var mutable = contact.MutableCopy() as CNMutableContact;
var newEmail = new CNLabeledValue<NSString>(CNLabelKey.Home, new NSString("john.appleseed@xamarin.com"));

// Append new email
var emails = new NSObject[mutable.EmailAddresses.Length+1];
mutable.EmailAddresses.CopyTo(emails,0);
emails[mutable.EmailAddresses.Length+1] = newEmail;
mutable.EmailAddresses = emails;

// Update contact
var store = new CNContactStore();
var saveRequest = new CNSaveRequest();
saveRequest.UpdateContact(mutable);

NSError error;
if (store.ExecuteSaveRequest(saveRequest, out error)) {
    Console.WriteLine("Contact updated.");
} else {
    Console.WriteLine("Update error: {0}", error);
}

Pemberitahuan Perubahan Kontak

Setiap kali kontak dimodifikasi, Penyimpanan Kontak memposting CNContactStoreDidChangeNotification ke Pusat Pemberitahuan Default. Jika Anda telah menyimpan cache atau saat ini menampilkan kontak apa pun, Anda harus menyegarkan objek tersebut dari Penyimpanan Kontak (CNContactStore).

Kontainer dan Grup

Kontak pengguna dapat ada baik secara lokal di perangkat pengguna atau sebagai kontak yang disinkronkan ke perangkat dari satu atau beberapa akun server (seperti Facebook atau Google). Setiap kumpulan kontak memiliki Kontainernya sendiri dan Kontak tertentu hanya dapat ada dalam satu kontainer.

Beberapa Kontainer memungkinkan Kontak diatur ke dalam satu atau beberapa Grup atau Sub-Grup. Perilaku ini tergantung pada penyimpanan backing untuk Kontainer tertentu. Misalnya, iCloud hanya memiliki satu Kontainer tetapi dapat memiliki banyak Grup (tetapi tidak ada Sub-Grup). Microsoft Exchange di sisi lain, tidak mendukung grup tetapi dapat memiliki beberapa Kontainer (satu untuk setiap Folder Exchange).

Kerangka Kerja ContactsUI

Untuk situasi di mana aplikasi Anda tidak perlu menyajikan UI kustom, Anda dapat menggunakan kerangka kerja ContactsUI untuk menyajikan elemen UI untuk menampilkan, mengedit, memilih, dan membuat kontak di aplikasi Xamarin.iOS Anda.

Dengan menggunakan kontrol bawaan Apple, Anda tidak hanya mengurangi jumlah kode yang harus Anda buat untuk mendukung Kontak di aplikasi Xamarin.iOS, tetapi Anda menyajikan antarmuka yang konsisten kepada pengguna aplikasi.

Pengontrol Tampilan Pemilih Kontak

Pengontrol Tampilan Pemilih Kontak (CNContactPickerViewController) mengelola Tampilan Pemilih Kontak standar yang memungkinkan pengguna memilih properti Kontak atau Kontak dari Database Kontak pengguna. Pengguna dapat memilih satu atau beberapa kontak (berdasarkan penggunaannya) dan Pengontrol Tampilan Pemilih Kontak tidak meminta izin sebelum menampilkan pemilih.

Sebelum memanggil CNContactPickerViewController kelas, Anda menentukan properti mana yang dapat dipilih pengguna dan menentukan predikat untuk mengontrol tampilan dan pilihan Properti Kontak.

Gunakan instans kelas yang mewarisi dari CNContactPickerDelegate untuk merespons interaksi pengguna dengan pemilih. Contohnya:

using System;
using System.Linq;
using UIKit;
using Foundation;
using Contacts;
using ContactsUI;

namespace iOS9Contacts
{
    public class ContactPickerDelegate: CNContactPickerDelegate
    {
        #region Constructors
        public ContactPickerDelegate ()
        {
        }

        public ContactPickerDelegate (IntPtr handle) : base (handle)
        {
        }
        #endregion

        #region Override Methods
        public override void ContactPickerDidCancel (CNContactPickerViewController picker)
        {
            Console.WriteLine ("User canceled picker");

        }

        public override void DidSelectContact (CNContactPickerViewController picker, CNContact contact)
        {
            Console.WriteLine ("Selected: {0}", contact);
        }

        public override void DidSelectContactProperty (CNContactPickerViewController picker, CNContactProperty contactProperty)
        {
            Console.WriteLine ("Selected Property: {0}", contactProperty);
        }
        #endregion
    }
}

Untuk mengizinkan pengguna memilih alamat email dari kontak di database mereka, Anda bisa menggunakan kode berikut:

// Create a new picker
var picker = new CNContactPickerViewController();

// Select property to pick
picker.DisplayedPropertyKeys = new NSString[] {CNContactKey.EmailAddresses};
picker.PredicateForEnablingContact = NSPredicate.FromFormat("emailAddresses.@count > 0");
picker.PredicateForSelectionOfContact = NSPredicate.FromFormat("emailAddresses.@count == 1");

// Respond to selection
picker.Delegate = new ContactPickerDelegate();

// Display picker
PresentViewController(picker,true,null);

Pengontrol Tampilan Kontak

Kelas Pengontrol Tampilan Kontak (CNContactViewController) menyediakan pengontrol untuk menyajikan Tampilan Kontak standar kepada pengguna akhir. Tampilan Kontak dapat menampilkan kontak Baru, Tidak Diketahui, atau Yang Sudah Ada dan jenisnya harus ditentukan sebelum tampilan ditampilkan dengan memanggil konstruktor statis yang benar (FromNewContact, , FromUnknownContactFromContact). Misalnya:

// Create a new contact view
var view = CNContactViewController.FromContact(contact);

// Display the view
PresentViewController(view, true, null);

Ringkasan

Artikel ini telah melihat secara rinci tentang bekerja dengan kerangka kerja Hubungi dan Hubungi UI dalam aplikasi Xamarin.iOS. Pertama, ini mencakup berbagai jenis objek yang disediakan kerangka kerja Kontak dan cara Anda menggunakannya untuk membuat kontak baru atau mengakses kontak yang ada. Ini juga memeriksa kerangka kerja Antarmuka Pengguna Kontak untuk memilih kontak yang ada dan menampilkan informasi kontak.

Link Terkait

• Yang Baru di iOS 9
• Referensi Kerangka Kerja Kontak
• Referensi Kerangka Kerja ContactsUI