Kontakty a ContactsUI v Xamarin. iOS

Tento článek popisuje práci s novými architekturami uživatelského rozhraní kontaktů a kontaktů v aplikaci Xamarin. iOS. Tyto architektury nahradí stávající adresář a uživatelské rozhraní adresáře používané v předchozích verzích iOS.

Po zavedení iOS 9 vydala společnost Apple dvě nové architektury, ContactsContactsUI které nahradí stávající adresář a rozhraní uživatelského rozhraní adresáře používané systémem iOS 8 a starším.

Dvě nová rozhraní obsahují následující funkce:

• Kontakty – poskytuje přístup k datům seznamu kontaktů uživatele. Vzhledem k tomu, že většina aplikací vyžaduje jenom přístup jen pro čtení, toto rozhraní je optimalizované pro bezpečný přístup z více vláken, přístup jen pro čtení.

• ContactsUI – poskytuje prvky uživatelského rozhraní Xamarin. iOS pro zobrazení, úpravy, výběr a vytváření kontaktů na zařízeních s iOS.

V následujících částech se podíváme na tyto nové architektury a postup jejich implementace v aplikaci Xamarin. iOS.

Rozhraní kontaktů

Rozhraní kontakty nabízí přístup Xamarin. iOS k kontaktním informacím uživatele. Vzhledem k tomu, že většina aplikací vyžaduje jenom přístup jen pro čtení, toto rozhraní je optimalizované pro bezpečný přístup z více vláken, přístup jen pro čtení.

Objekty kontaktu

CNContacttřída poskytuje bezpečný přístup z více vláken, přístup jen pro čtení k vlastnostem kontaktu, jako je jméno, adresa nebo Telefon číslo. CNContact funguje jako NSDictionary a obsahuje více kolekcí vlastností jen pro čtení (například adresy nebo telefonní čísla):

U všech vlastností, které mohou mít více hodnot (například e-mailové adresy nebo telefonní čísla), budou reprezentovány jako pole NSLabeledValue objektů. NSLabeledValue je podřazená kolekce členů s vláknem, která se skládá z množiny popisků a hodnot jen pro čtení, kde popisek definuje hodnotu uživateli (například domů nebo pracovní e-mail). Rozhraní kontakty nabízí výběr předdefinovaných popisků (prostřednictvím CNLabelKeyCNLabelPhoneNumberKey statických tříd a), které můžete použít v aplikaci, nebo máte možnost definovat vlastní štítky podle svých potřeb.

Pro libovolnou aplikaci Xamarin. iOS, která potřebuje upravit hodnoty existujícího kontaktu (nebo vytvořit nové), použijte NSMutableContact verzi třídy a jejích podtříd (například CNMutablePostalAddress ).

Například následující kód vytvoří nový kontakt a přidá ho do kolekce kontaktů uživatele:

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

Pokud je tento kód spuštěný na zařízení s iOS 9, přidá se do kolekce uživatele nový kontakt. Například:

Formátování a lokalizace kontaktu

Rozhraní kontaktů obsahuje několik objektů a metod, které vám pomůžou při formátování a lokalizaci obsahu pro zobrazení uživateli. Například následující kód bude správně formátovat název kontaktů a poštovní adresu pro zobrazení:

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

Pro popisky vlastností, které se zobrazí v uživatelském rozhraní vaší aplikace, má kontaktní rozhraní metody pro lokalizaci těchto řetězců také. Tento postup je založený na aktuálním národním prostředí zařízení s iOS, ve kterém se aplikace spouští. Například:

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

Načítají se existující kontakty.

Pomocí instance CNContactStore třídy můžete načíst kontaktní informace z databáze kontaktů uživatele. CNContactStoreObsahuje všechny metody potřebné k načtení nebo aktualizaci kontaktů a skupin z databáze. Vzhledem k tomu, že tyto metody jsou synchronní, je doporučeno je spustit ve vlákně na pozadí, aby bylo možné blokování uživatelského rozhraní zabránit.

Pomocí predikátů (sestavených z CNContact třídy) můžete filtrovat výsledky vracené při načítání kontaktů z databáze. Chcete-li načíst pouze kontakty, které obsahují řetězec Appleseed , použijte následující kód:

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

Chcete-li například omezit načtení pouze na vlastnosti daného kontaktu na jméno a rodinu , použijte následující kód:

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

Nakonec, pokud chcete vyhledat databázi a vrátit výsledky, použijte následující kód:

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

Pokud byl tento kód spuštěn po ukázce, kterou jsme vytvořili v části Object Contacts výše, vrátí "Jan Appleseed", který jsme právě vytvořili.

Kontaktní údaje k ochraně osobních údajů

Vzhledem k tomu, že koncoví uživatelé můžou udělit nebo odepřít přístup ke svým kontaktním údajům na základě jednotlivých aplikací, při prvním volání do se CNContactStore zobrazí dialogové okno s výzvou, aby povolil přístup k vaší aplikaci.

Žádost o oprávnění bude prezentována pouze jednou, při prvním spuštění aplikace a následném spuštění nebo volání do nástroje CNContactStore bude používat oprávnění, které uživatel v daném čase vybral.

Měli byste navrhnout aplikaci tak, aby řádně vyplynula přístup uživatelů k své kontaktní databázi.

Načítají se částečné kontakty.

Částečný kontakt je kontaktní osoba, že z obchodu kontaktů pro se načetly jenom některé z dostupných vlastností. Pokud se pokusíte o přístup k vlastnosti, která nebyla dříve načtena, výsledkem bude výjimka.

Můžete snadno zjistit, jestli daný kontakt má požadovanou vlastnost pomocí IsKeyAvailableAreKeysAvailable metody nebo CNContact instance. Například:

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

Sjednocené kontakty

Uživatel může mít v kontaktní databázi různé zdroje kontaktní informace pro jednoho uživatele (například iCloud, Facebook nebo Google mail). V aplikacích pro iOS a OS X se tyto kontaktní údaje automaticky spojí a zobrazí se uživateli jako jediný sjednocený kontakt:

Tento Unified Contact je dočasným zobrazením v paměti kontaktních informací, které se budou předávat podle vlastního jedinečného identifikátoru (který by se měl v případě potřeby použít k opětovnému načtení kontaktu). Ve výchozím nastavení vrátí architektura kontaktů sjednocený kontakt, kdykoli je to možné.

Vytváření a aktualizace kontaktů

Jak jsme viděli v části objekty kontaktů výše, pomocí a instance a CNMutableContact vytvoříte nové kontakty, které se pak zapíší do databáze kontaktů uživatele pomocí 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);
}

CNSaveRequestLze také použít k ukládání více kontaktů a skupin změn do jediné operace a dávkování těchto změn v CNContactStore .

Pokud chcete aktualizovat neproměnlivý kontakt získaný z operace načtení, musíte nejdřív vyžádat proměnlivou kopii, kterou pak upravíte a pak ji uložíte zpátky do obchodu kontaktů. Například:

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

Oznámení o změnách kontaktů

Pokaždé, když se kontakt změní, odešle kontakt do CNContactStoreDidChangeNotification výchozího centra oznámení. Pokud máte v mezipaměti nebo aktuálně zobrazujete nějaké kontakty, budete je muset aktualizovat z obchodu kontaktů ( CNContactStore ).

Kontejnery a skupiny

Kontakty uživatele můžou existovat místně na zařízení uživatele nebo jako kontakty synchronizované se zařízením z jednoho nebo několika účtů na serveru (jako je Facebook nebo Google). Každý fond kontaktů má svůj vlastní kontejner a daný kontakt může existovat pouze v jednom kontejneru.

Některé kontejnery umožňují, aby byly kontakty uspořádány do jedné nebo více skupin nebo dílčích skupin. Toto chování závisí na záložním úložišti pro daný kontejner. Například iCloud má pouze jeden kontejner, ale může mít mnoho skupin (ale žádné podskupiny). společnost Microsoft Exchange na druhé straně nepodporuje skupiny, ale může mít více kontejnerů (jeden pro každou složku Exchange).

ContactsUI Framework

V situacích, kdy vaše aplikace nemusí prezentovat vlastní uživatelské rozhraní, můžete pomocí ContactsUI architektury prezentovat prvky uživatelského rozhraní pro zobrazení, úpravy, výběr a vytvoření kontaktů v aplikaci Xamarin. iOS.

Pomocí integrovaných ovládacích prvků společnosti Apple nesnižujete pouze množství kódu, který je třeba vytvořit pro podporu kontaktů v aplikaci Xamarin. iOS, ale pro uživatele aplikace prezentujete konzistentní rozhraní.

Kontroler zobrazení pro výběr kontaktů

Kontroler zobrazení pro výběr kontaktů ( CNContactPickerViewController ) spravuje standardní zobrazení pro výběr kontaktů, které uživateli umožňuje vybrat kontakt nebo vlastnost Contact z databáze kontaktů uživatele. Uživatel může vybrat jeden nebo více kontaktů (na základě jejího využití) a kontroler zobrazení pro výběr kontaktů nezobrazí výzvu k zadání oprávnění před zobrazením ovládacího prvku pro výběr.

Před voláním CNContactPickerViewController třídy definujete, které vlastnosti může uživatel vybrat a definovat predikáty pro řízení zobrazení a výběru vlastností kontaktu.

K CNContactPickerDelegate reakci na interakci uživatele pomocí ovládacího prvku pro výběr použijte instanci třídy, která dědí z. Například:

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

Chcete-li uživateli dovolit vybrat e-mailovou adresu z kontaktů ve své databázi, můžete použít následující kód:

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

Kontroler zobrazení kontaktů

Třída kontroleru zobrazení kontaktů ( CNContactViewController ) poskytuje kontroleru, který pro koncového uživatele nabídne standardní zobrazení kontaktu. Zobrazení kontaktů může zobrazit nové nové, neznámé nebo existující kontakty a typ musí být zadán předtím, než se zobrazení zobrazí voláním správného statického konstruktoru ( FromNewContact , FromUnknownContact , FromContact ). Příklad:

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

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

Souhrn

V tomto článku se podrobně podíváme na práci s architekturami uživatelského rozhraní kontaktů a kontaktů v aplikaci Xamarin. iOS. Nejprve se potýká různých typů objektů, které poskytuje rozhraní pro kontakty, a způsob jejich použití k vytvoření nového nebo přístupu ke stávajícím kontaktům. Také se zkontrolovala architektura uživatelského rozhraní kontaktů a vybere existující kontakty a zobrazí kontaktní informace.

Související odkazy

• Ukázka kontaktů
• Co je nového v iOSu 9
• Referenční informace k rozhraní kontaktů
• Referenční informace k rozhraní ContactsUI Framework