Xamarin.iOS'ta Kişiler ve KişilerUI

Bu makale, Xamarin.iOS uygulamasındaki yeni Kişiler ve Kişiler kullanıcı arabirimi çerçeveleriyle çalışmayı kapsar. Bu çerçeveler, iOS'un önceki sürümlerinde kullanılan mevcut Adres Defteri ve Adres Defteri kullanıcı arabiriminin yerini alır.

iOS 9'un kullanıma sunulmasıyla birlikte Apple, Contacts iOS 8 ve ContactsUIönceki sürümler tarafından kullanılan mevcut Adres Defteri ve Adres Defteri kullanıcı arabirimi çerçevelerinin yerini alan ve adlı iki yeni çerçeve yayınladı.

İki yeni çerçeve aşağıdaki işlevleri içerir:

• Kişiler - Kullanıcının kişi listesi verilerine erişim sağlar. Çoğu uygulama yalnızca salt okunur erişim gerektirdiği için, bu çerçeve iş parçacığı güvenli, salt okunur erişim için iyileştirilmiştir.

• ContactsUI - iOS cihazlarında kişileri görüntülemek, düzenlemek, seçmek ve oluşturmak için Xamarin.iOS kullanıcı arabirimi öğeleri sağlar.

Aşağıdaki bölümlerde, bu yeni çerçevelere ve bunları bir Xamarin.iOS uygulamasında nasıl uygulayacağımıza göz atacağız.

Kişiler Çerçevesi

Kişiler Çerçevesi, kullanıcının kişi bilgilerine Xamarin.iOS erişimi sağlar. Çoğu uygulama yalnızca salt okunur erişim gerektirdiği için, bu çerçeve iş parçacığı güvenli, salt okunur erişim için iyileştirilmiştir.

Kişi Nesneleri

CNContact sınıfı, kişinin Ad, Adres veya Telefon Numaraları gibi özelliklerine iş parçacığı güvenli, salt okunur erişim sağlar. CNContact ve gibi NSDictionary işlevler birden çok salt okunur özellik koleksiyonu (adresler veya telefon numaraları gibi) içerir:

Birden çok değere (e-posta adresi veya telefon numaraları gibi) sahip olabilecek herhangi bir özellik için bunlar bir nesne dizisi NSLabeledValue olarak temsil edilir. NSLabeledValue , etiketin değeri kullanıcıya tanımladığı salt okunur bir etiket ve değer kümesinden (örneğin, Giriş veya İş e-postası) oluşan bir iş parçacığı güvenli tanımlama grubudur. Kişiler çerçevesi, uygulamanızda kullanabileceğiniz veya gereksinimleriniz için özel etiketler tanımlama seçeneğiniz olan önceden tanımlanmış etiketler (ve CNLabelPhoneNumberKey statik sınıflar aracılığıylaCNLabelKey) sunar.

Mevcut bir kişinin değerlerini ayarlaması (veya yenilerini oluşturması) gereken herhangi bir Xamarin.iOS uygulaması için sınıfın ve alt sınıflarının (gibiCNMutablePostalAddress) sürümünü kullanınNSMutableContact.

Örneğin, aşağıdaki kod yeni bir kişi oluşturur ve bu kişiyi kullanıcının kişi koleksiyonuna ekler:

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

Bu kod bir iOS 9 cihazında çalıştırılırsa, kullanıcının koleksiyonuna yeni bir kişi eklenir. Örneğin:

Kişi Biçimlendirme ve Yerelleştirme

Kişiler çerçevesi, kullanıcıya görüntülenecek içeriği biçimlendirmenize ve yerelleştirmenize yardımcı olabilecek çeşitli nesneler ve yöntemler içerir. Örneğin, aşağıdaki kod görüntülenecek kişi adını ve posta adresini doğru biçimlendiriyor:

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

Uygulamanızın kullanıcı arabiriminde görüntüleyecek olduğunuz özellik etiketleri için, Kişi çerçevesinin bu dizeleri yerelleştirme yöntemleri de vardır. Bu da uygulamanın çalıştırıldığı iOS cihazının geçerli yerel ayarını temel alır. Örneğin:

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

Mevcut Kişileri Getirme

Sınıfının bir örneğini CNContactStore kullanarak, kullanıcının kişi veritabanından kişi bilgilerini getirebilirsiniz. , CNContactStore veritabanından kişileri ve grupları getirmek veya güncelleştirmek için gereken tüm yöntemleri içerir. Bu yöntemler zaman uyumlu olduğundan, kullanıcı arabirimini engellememek için bunları bir arka plan iş parçacığında çalıştırmanız önerilir.

Önkoşulları (sınıfından CNContact oluşturulmuş) kullanarak, veritabanından kişileri getirirken döndürülen sonuçları filtreleyebilirsiniz. Yalnızca dizesini Appleseediçeren kişileri getirmek için aşağıdaki kodu kullanın:

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

Örneğin, getirme işlemini yalnızca kişinin GivenName ve FamilyName özellikleriyle sınırlamak için aşağıdaki kodu kullanın:

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

Son olarak, veritabanında arama yapmak ve sonuçları döndürmek için aşağıdaki kodu kullanın:

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

Bu kod yukarıdaki Kişiler Nesnesi bölümünde oluşturduğumuz örnekten sonra çalıştırıldıysa, yeni oluşturduğumuz "John Appleseed" kişisini döndürür.

Erişim Gizliliği ile İletişime Geçin

Son kullanıcılar kişi bilgilerine uygulama başına erişim izni verebildiğinden veya erişimi reddedebildiğinden, uygulamasına CNContactStoreilk kez bir çağrı yaptığınızda, uygulamanıza erişime izin vermelerini isteyen bir iletişim kutusu görüntülenir.

İzin isteği yalnızca bir kez sunulur, uygulama ilk kez çalıştırıldığında ve sonraki çalıştırmalar veya çağrılar CNContactStore kullanıcının o anda seçtiği izni kullanır.

Uygulamanızı, kullanıcının kişi veritabanına erişimi reddederek düzgün bir şekilde işlemesi için tasarlamanız gerekir.

Kısmi Kişileri Getirme

Kısmi Kişi, kişi deposundan yalnızca bazı kullanılabilir özelliklerin getirildiği kişidir. Daha önce getirilmemiş bir özelliğe erişmeye çalışırsanız, bu bir özel durumla sonuçlanır.

Örneğin veya AreKeysAvailable yöntemlerini CNContact kullanarak IsKeyAvailable belirli bir kişinin istenen özelliğe sahip olup olmadığını kolayca kontrol edebilirsiniz. Örneğin:

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

Birleşik Kişiler

Bir kullanıcının kişi veritabanındaki tek bir kişi için farklı iletişim bilgileri kaynakları olabilir (iCloud, Facebook veya Google Mail gibi). iOS ve OS X uygulamalarında, bu kişi bilgileri otomatik olarak birbirine bağlanır ve kullanıcıya tek bir Birleşik Kişi olarak görüntülenir:

Bu Birleşik Kişi, kendi benzersiz tanımlayıcısı verilecek bağlantı iletişim bilgilerinin geçici, bellek içi görünümüdür (gerekirse kişiyi yeniden oluşturmak için kullanılmalıdır). Varsayılan olarak, Kişiler çerçevesi mümkün olduğunda Birleştirilmiş Kişi döndürür.

Kişi Oluşturma ve Güncelleştirme

Yukarıdaki Kişi Nesneleri bölümünde gördüğümüz gibi, bir ve örneğini CNMutableContact kullanarak CNContactStore kullanıcının kişi veritabanına CNSaveRequestyazılan yeni kişiler oluşturursunuz:

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

, CNSaveRequest birden çok kişi ve grup değişikliğini tek bir işlemde önbelleğe almak ve bu değişiklikleri üzerinde CNContactStoretoplu olarak oluşturmak için de kullanılabilir.

Bir getirme işleminden alınan, değiştirilebilir olmayan bir kişiyi güncelleştirmek için önce değiştirip kişi deposuna geri kaydedeceğiniz değiştirilebilir bir kopya istemeniz gerekir. Örneğin:

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

Kişi Değişiklik Bildirimleri

Bir kişi her değiştirildiğinde, Kişi Deposu Varsayılan Bildirim Merkezi'ne bir CNContactStoreDidChangeNotification postalar. Önbelleğe aldıysanız veya şu anda herhangi bir kişi görüntülüyorsanız, bu nesneleri Kişi Deposu'ndan (CNContactStore) yenilemeniz gerekir.

Kapsayıcılar ve Gruplar

Kullanıcının kişileri kullanıcının cihazında yerel olarak veya bir veya daha fazla sunucu hesabından (Facebook veya Google gibi) cihazla eşitlenmiş kişiler olarak bulunabilir. Her kişi havuzunun kendi Kapsayıcısı vardır ve belirli bir Kişi yalnızca bir kapsayıcıda bulunabilir.

Bazı Kapsayıcılar, Kişilerin bir veya daha fazla Grup veya Alt Grup halinde düzenlenmesini sağlar. Bu davranış, belirli bir Kapsayıcı için yedekleme deposuna bağlıdır. Örneğin, iCloud yalnızca bir Kapsayıcıya sahiptir ancak çok sayıda Gruba sahip olabilir (ancak Alt Grup yok). Öte yandan, Microsoft Exchange grupları desteklemez, ancak birden çok Kapsayıcıya (her Exchange Klasörü için bir kapsayıcı) sahip olabilir.

ContactsUI Çerçevesi

Uygulamanızın özel bir kullanıcı arabirimi sunması gerekmediği durumlarda, KişilerUI çerçevesini kullanarak Xamarin.iOS uygulamanızda kişileri görüntülemek, düzenlemek, seçmek ve oluşturmak üzere kullanıcı arabirimi öğeleri sunabilirsiniz.

Apple'ın yerleşik denetimlerini kullanarak Xamarin.iOS uygulamanızdaki Kişileri desteklemek için oluşturmanız gereken kod miktarını azaltmakla kalmaz, aynı zamanda uygulamanın kullanıcılarına tutarlı bir arabirim sunarsınız.

Kişi Seçici Görünüm Denetleyicisi

Kişi Seçici Görünüm Denetleyicisi (CNContactPickerViewController), kullanıcının Kişi Veritabanından bir Kişi veya Kişi özelliği seçmesine olanak tanıyan standart Kişi Seçici Görünümü'nü yönetir. Kullanıcı bir veya daha fazla kişi seçebilir (kullanımına bağlı olarak) ve Kişi Seçici Görünüm Denetleyicisi seçiciyi görüntülemeden önce izin istemez.

sınıfını CNContactPickerViewController çağırmadan önce, kullanıcının hangi özellikleri seçebileceğini ve Kişi Özellikleri'nin görüntülenmesini ve seçilmesini denetlemek için hangi önkoşulları tanımlayabileceğini tanımlarsınız.

Kullanıcının seçiciyle etkileşimine yanıt vermek için öğesini CNContactPickerDelegate devralan sınıfın bir örneğini kullanın. Örneğin:

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
    }
}

Kullanıcının veritabanındaki kişilerden bir e-posta adresi seçmesine izin vermek için aşağıdaki kodu kullanabilirsiniz:

// 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);

Kişi Görünümü Denetleyicisi

Kişi Görünümü Denetleyicisi (CNContactViewController) sınıfı, son kullanıcıya standart bir Kişi Görünümü sunmak için bir denetleyici sağlar. Kişi görünümü yeni Yeni, Bilinmeyen veya Var olan kişileri görüntüleyebilir ve doğru statik oluşturucu (FromNewContact, FromUnknownContact, FromContact) çağrılarak görünüm görüntülenmeden önce türü belirtilmelidir. Örneğin:

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

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

Özet

Bu makalede, Xamarin.iOS uygulamasında Kişi ve kişi kullanıcı arabirimi çerçeveleriyle çalışma konusuna ayrıntılı bir bakış verilmiştir. İlk olarak, Kişi çerçevesinin sağladığı farklı nesne türlerini ve bunları yeni kişiler oluşturmak veya var olan kişilere erişmek için nasıl kullandığınız ele alınmıştır. Ayrıca, mevcut kişileri seçmek ve kişi bilgilerini görüntülemek için Kişi Kullanıcı Arabirimi çerçevesini inceledi.

İlişkili Bağlantılar

• iOS 9'daki Yenilikler
• Kişiler Çerçevesi Başvurusu
• ContactsUI Framework Başvurusu