Mobile-Tutorial: Verwenden einer Adressbuch-Komponente (iOS und Android)

Aus RAD Studio
Wechseln zu: Navigation, Suche

Nach oben zu Mobile-Tutorials: Mobile Anwendungsentwicklung (iOS und Android)


Bevor Sie mit diesem Tutorial beginnen, sollten Sie die folgenden Tutorials durcharbeiten:

FireMonkey stellt für die Arbeit mit dem Adressbuch auf iOS- und Android-Geräten die Komponente TAddressBook bereit.

In diesem Tutorial wird beschrieben, wie Sie eine einfache FireMonkey-Anwendung erstellen, in der die TAddressBook-Komponente verwendet wird.

iOS Android

AddressBook Apps.png
iPhone 5

AddressBook Android.png

Android (LG - E612)


Grundlegende Funktionen der TAddressBook-Komponente

Auf mobilen Plattformen (Android und iOS) unterstützt FireMonkey die TAddressBook-Komponente, mit der Sie in Ihren Anwendungen auf das Geräte-Adressbuch zugreifen können. Diese Komponente umfasst folgende grundlegenden Funktionen:

  • Senden einer Anforderung, um auf ein Geräte-Adressbuch zuzugreifen, und Erhalten des Zugriffsstatus.
  • Zugreifen auf alle Quellen, die in dem Geräte-Adressbuch definiert sind.
  • Abrufen aller oder individueller Kontakte von der angegebenen Quelle.
  • Abrufen aller Kontakte aus der bestimmten Gruppe / den bestimmten Gruppen.
  • Bearbeiten oder Entfernen von vorhandenen Kontakten und Gruppen.
  • Erstellen neuer Kontakte.
  • Erstellen neuer Gruppen.

Erstellen einer Beispielanwendung

In diesem Abschnitt wird eine einfache Anwendung (für die Android- und iOS-Zielplattformen) erstellt, in der die Verwendung der TAddressBook-Komponente gezeigt wird. Die Anwendung demonstriert die folgenden Techniken:

  • Anfordern einer Zugriffsberechtigung für das Adressbuch.
  • Abrufen aller Kontakte von der Standard-Quelle im Geräteadressbuch.
  • Eintragen eines neuen Kontakts ins Adressbuch.
  • Entfernen eines ausgewählten Kontakts aus dem Adressbuch.

Entwerfen der Benutzeroberfläche

  1. Erstellen Sie eine neue geräteübergreifende Anwendung, indem Sie Folgendes auswählen:
    • Für Delphi: Datei > Neu > Geräteübergreifende Anwendung - Delphi > Leere Anwendung
    • Für C++: Datei > Neu > Geräteübergreifende Anwendung - C++Builder > Leere Anwendung
  2. Setzen Sie in der Projektverwaltung die Zielplattform auf Android oder iOS.
  3. Wählen Sie in der Tool-Palette die Komponenten TToolBar, TAddressBook und TListBox aus, und ziehen Sie sie in den Formular-Designer.
  4. Setzen Sie im Objektinspektor die Eigenschaft Align von TListBox auf Client.
  5. Klicken Sie im Formular-Designer mit der rechten Maustaste auf TListBox, und wählen Sie dann im Kontextmenü Eintrag hinzufügen > TSearchBox aus.
  6. Wählen Sie in der Tool-Palette die Komponente TMultiView aus, und ziehen Sie sie in den Formular-Designer.

Entwerfen der Symbolleiste und des Hauptbereichs für die Anwendung

Setzen Sie alle Steuerelemente auf die Symbolleiste und in den Hauptbereich:

  • Die Symbolleiste enthält drei Symbolschaltflächen:
    • Addre Trash.png: entfernt einen ausgewählten Kontakt aus dem Adressbuch.
    • Addr Refresh.png: aktualisiert die aktuelle Kontaktliste.
    • Addr Add.png: öffnet den Hauptbereich, um einen neuen Kontakt ins Adressbuch einzutragen.
  • Der Hauptbereich enthält ein Formular, mit dem Sie einen neuen Kontakt angeben und ins Adressbuch eintragen können.

So gestalten Sie die Symbolleiste für die Anwendung:

  1. Ziehen Sie drei TSpeedButton-Komponenten auf die oberen Symbolleisten.
  2. Führen Sie im Formular-Designer folgende Schritte aus:
    • Wählen Sie SpeedButton1 aus, und setzen Sie die Eigenschaften Name und StyleLookup auf btnRemove bzw. trashtoolbuttonordered.
    • Wählen Sie SpeedButton2 aus, und setzen Sie die Eigenschaften Name und StyleLookup auf btnRefresh bzw. refreshtoolbuttonordered.
    • Wählen Sie SpeedButton3 aus, und setzen Sie die Eigenschaften Name und StyleLookup auf btnAdd bzw. addtoolbuttonordered.

Nach Abschluss der obigen Schritte sollte der Formular-Designer in etwa wie der folgende Screenshot aussehen: AddressBook toolbar.png

So gestalten Sie den Hauptbereich:

  1. Wählen Sie in der Strukturansicht MultiView1 aus, und legen Sie dann im Objektinspektor die folgenden Eigenschaften fest:
    • Setzen Sie die Eigenschaft MasterButton auf btnAdd.
    • Setzen Sie die Eigenschaft Mode auf Drawer.
    • Um MultiView1 anzuzeigen, setzen Sie die Eigenschaft Visible auf True.
  2. Wählen Sie in der Tool-Palette drei TLabel-Komponenten, drei TEdit-Komponenten und zwei TButton-Komponenten aus, und ziehen Sie sie auf Multiview1.
  3. Legen Sie im Objektinspektor für die Steuerelemente, die Sie auf MultiView1 gezogen haben, die folgenden Eigenschaften fest:
    • Für Label1, Label2 und Label3: Setzen Sie die Text-Eigenschaften auf First Name, Last Name bzw. Work Mail.
    • Für Edit1, Edit2 und Edit3:
      • Setzen Sie die Name-Eigenschaft auf edtFirstName, edtLastName bzw. edtWorkMail.
      • Setzen Sie die KillFocusByReturn-Eigenschaft auf true
      • Setzen Sie die ReturnKeyType-Eigenschaft auf Go.
    • Für Button1 und Button2:
      • Setzen Sie die Text-Eigenschaft auf Add und Cancel
      • Setzen Sie die Name-Eigenschaft auf btnOK bzw. btnCancel.

Ordnen Sie die Steuerelemente des Hauptbereichs folgendermaßen an:

AddressBook Drawer.png

Abrufen der Kontaktliste

in diesem Abschnitt wird erläutert, wie die Kontaktliste von der Standardquelle in einem Geräte-Adressbuch abgerufen wird.

Definieren Sie in Ihrer Anwendung die folgenden privaten Methoden:

  • FillContactsList: erhält die Liste der Kontakte der Standardquelle in dem Geräte-Adressbuch;
  • AddListBoxItem: fügt der ListBox ein neues Element hinzu.

Ändern Sie den private-Abschnitt Ihres Anwendungscodes wie folgt:

Delphi:
private
    { Private declarations }
    procedure FillContactList;
    procedure AddListBoxItem(Contact: TAddressBookContact);
C++Builder:
private:	// User declarations
	void __fastcall FillContactsList();
        void __fastcall AddListBoxItem(TAddressBookContact *Contact);

Implementieren Sie die Methoden FillContactslist und AddListBoxItem wie folgt:

Delphi:
// Fill the contact list
procedure TForm1.FillContactList;
var
  I: Integer;
  Contacts: TAddressBookContacts;
begin
  Contacts := TAddressBookContacts.Create;
  try
    AddressBook1.AllContacts(AddressBook1.DefaultSource, Contacts);
    ListBox1.BeginUpdate;
    try
      ListBox1.Clear;
      for I := 0 to Contacts.Count - 1 do
        AddListBoxItem(Contacts.Items[I]);
    finally
      ListBox1.EndUpdate;
    end;
  finally
    Contacts.Free;
  end;
end;
// --------------------------------------------------------------------
// Add a new contact to List box
procedure TForm1.AddListBoxItem(Contact: TAddressBookContact);
var
  ListBoxItem: TListBoxItem;
begin
  try
    ListBoxItem := TListBoxItem.Create(nil);
    ListBoxItem.Text := Contact.DisplayName;
    ListBoxItem.Tag := Contact.ID;
    ListBox1.AddObject(ListBoxItem);
  finally
    ListBoxItem.Free;
  end;
end;
C++Builder:
// Fill the List box with existed contact display names.
void __fastcall TForm1::FillContactsList() {
	int i;
	TAddressBookContacts *Contacts = new TAddressBookContacts(); 
	__try {
		AddressBook1->AllContacts(AddressBook1->DefaultSource(), Contacts);
		__try {
			ListBox1->BeginUpdate();
			ListBox1->Clear();
			for (i = 0; i < Contacts->Count; i++)
				AddListBoxItem(Contacts->Items[i]);

		}
		__finally {
			ListBox1->EndUpdate();
		}
	}

	__finally {
		Contacts->Free();
	}
}
// ---------------------------------------------------------------------------
// Add a new contact to List box
void __fastcall TForm1::AddListBoxItem(TAddressBookContact *Contact) {
    TListBoxItem *ListBoxItem = new TListBoxItem(ListBox1);

	__try {

		ListBoxItem->Text = Contact->DisplayName;
		ListBoxItem->Tag = Contact->ID;
		ListBox1->AddObject(ListBoxItem);
	}
	__finally {
		ListBoxItem->Free();
	}
}

Implementieren der Funktionalität der Steuerelemente

Um die Anwendungsentwicklung abzuschließen, müssen Sie Ereignisbehandlungsroutinen für alle Steuerelemente auf dem Anwendungsformular implementieren.

So implementieren Sie die OnClick-Ereignisbehandlungsroutinen für die Symbolschaltflächen:

  1. Doppelklicken Sie im Formular-Designer auf eine Symbolschaltfläche (btnRefresh oder btnRemove).
  2. Legen Sie im Quelltext-Editor für jede Schaltfläche die folgenden Ereignisbehandlungsroutinen fest:
Delphi:
//-------------------For Remove button -----------------------------------------
procedure TForm1.btnRemoveClick(Sender: TObject);
var
  ContactIndex, ContactID: Integer;
  Contact: TAddressBookContact;
begin
  ContactIndex := ListBox1.ItemIndex;
  if (ContactIndex > -1) Then
  begin
    ContactID := ListBox1.ListItems[ContactIndex].Tag;
    Contact := AddressBook1.ContactByID(ContactID);
    if Contact <> nil then
      try
        AddressBook1.RemoveContact(Contact);
        ListBox1.BeginUpdate;
        ListBox1.Items.Delete(ContactIndex);
      finally
        ListBox1.EndUpdate;
        Contact.Free;
      end;
  end;
end;
// -------------------For Refresh button---------------------------------------
procedure TForm1.btnRefreshClick(Sender: TObject);
begin
  FillContactsList;
end;
C++Builder:
//-------------------For Remove button -----------------------------------------
// Remove the contact currently selected from the List box
void __fastcall TForm1::btnRemoveClick(TObject *Sender) {
	int ContactIndex = ListBox1->ItemIndex;
	if (ContactIndex > -1) {
		int ContactID = ListBox1->ListItems[ContactIndex]->Tag;
		TAddressBookContact *Contact = AddressBook1->ContactByID(ContactID);
		if (Contact != NULL) {
			__try {
				AddressBook1->RemoveContact(Contact);
				ListBox1->BeginUpdate();
				ListBox1->Items->Delete(ContactIndex);

			}
			__finally {
				ListBox1->EndUpdate();
				Contact->Free();

			}
		}
	}
}
// --------------------------For Refresh button-------------------------------------
void __fastcall TForm1::btnRefreshClick(TObject *Sender) {
	FillContactsList();
}

So implementieren Sie die OnClick-Ereignisbehandlungsroutinen für die Schaltflächen des Hauptbereichs:

  1. Wählen Sie in der Strukturansicht MultiView1 aus.
  2. Setzen Sie im Objektinspektor die Eigenschaft Visible auf True.
    Dadurch wird er Hauptbereich angezeigt.
  3. Doppelklicken Sie im Hauptbereich auf die Schaltfläche Add, und implementieren Sie dann die folgende Ereignisbehandlungsroutine:
    • Für Delphi:
     
    // --------------------------------------------------------------------
    // Add a newly created contact to Address Book
    procedure TForm1.btnOKClick(Sender: TObject);
    var
      Contact: TAddressBookContact;
      eMails: TContactEmails;
      Addresses: TContactAddresses;
    
    begin
      Contact := AddressBook1.CreateContact(AddressBook1.DefaultSource);
      try
        Contact.FirstName := edtFirstName.Text;
        Contact.LastName := edtLastName.Text;
        // Add the work mail
        eMails := TContactEmails.Create;
        try
          eMails.AddEmail(TContactEmail.TLabelKind.Work, edtWorkMail.Text);
          Contact.eMails := eMails;
        finally
          eMails.Free;
        end;
        AddressBook1.SaveContact(Contact);
        try
          ListBox1.BeginUpdate;
          AddListBoxItem(Contact);
        finally
          ListBox1.EndUpdate;
        end;
      finally
        Contact.Free;
      end;
      MultiView1.HideMaster;
    
    end;
    
    • Für C++:
    // Add a newly created contact to Address Book
    void __fastcall TForm1::btnOKClick(TObject *Sender) {
    
    	TContactEmails *eMails;
    	TAddressBookContact *Contact =
    		AddressBook1->CreateContact(AddressBook1->DefaultSource());
    
    	__try {
    
    		Contact->FirstName = edtFirstName->Text;
    		Contact->LastName = edtLastName->Text;
    		// Add the work mail
    		eMails = new TContactEmails();
    		__try {
    			eMails->AddEmail(TContactEmail::TLabelKind::Work,
    			edtWorkMail->Text);
    			Contact->EMails = eMails;
    		}
    		__finally {
    			eMails->Free();
    		}
    		AddressBook1->SaveContact(Contact);
    		__try {
    			ListBox1->BeginUpdate();
    			AddListBoxItem(Contact);
    		}
    		__finally {
    			ListBox1->EndUpdate();
    		}
    
    	}
    	__finally {
    		Contact->Free();
    	}
    	MultiView1->HideMaster();	
    }
    
  4. Doppelklicken Sie im Hauptbereich auf die Schaltfläche Cancel, und implementieren Sie dann die folgende Ereignisbehandlungsroutine:
    • Für Delphi:
     
    // Clear and close the Add New Contact form
    procedure TForm1.btnCancelClick(Sender: TObject);
    begin
      edtFirstName.Text := '';
      edtLastName.Text := '';
      edtWorkMail.Text := '';
      MultiView1.HideMaster;
    end;
    
    • Für C++:
    // Clear and close the Add New Contact form
    void __fastcall TForm1::btnCancelClick(TObject *Sender)
    {
    	edtFirstName->Text = "";
    	edtLastName->Text = "";
    	edtWorkMail->Text = "";
    	MultiView1->HideMaster();
    }
    

Beibehalten des Adressbuchs in Sync

Tools von Drittherstellern können Änderungen an einem Geräte-Adressbuch durchführen, wenn Ihre Anwendung ausgeführt wird. In diesem Fall ist es wichtig, Informationen zwischen dem Geräte-Adressbuch und der Instanz des Geräte-Adressbuchs, mit dem Ihre Anwendung direkt ausgeführt wird, zu synchronisieren. Hierfür stellt FireMonkey die Methode TAddressBook.RevertCurrentChangesAndUpdate bereit.

Zur Beibehaltung des Adressbuchs in Sync

  1. Wählen Sie im Objektinspektor AddressBook1 aus, und öffnen Sie die Registerkarte Ereignisse.
  2. Doppelklicken Sie neben OnExternalChange und implementieren Sie die folgende Ereignisbehandlungsroutine:
    • Für Delphi:
     
    procedure TForm1.AddressBook1ExternalChange(ASender: TObject);
    begin
      AddressBook1.RevertCurrentChangesAndUpdate;
      FillContactsList;
    end;
    
    • Für C++:
    void __fastcall TForm1::AddressBook1ExternalChange(TObject *ASender) {
    	AddressBook1->RevertCurrentChangesAndUpdate();
    	FillContactsList();
    }
    

Konfigurieren des Zugriffs auf das Adressbuch

Bevor Sie TAddressBook verwenden, sollte Ihre Anwendung eine Zugriffsberechtigung für das Adressbuch auf einem mobilen Zielgerät anfordern.

In diesem Abschnitt werden die Schritte zur Konfiguration Ihrer Android- und iOS-Anwendungen für den Zugriff auf das Adressbuch auf mobilen Zielgeräten beschrieben.

So fordern Sie eine Zugriffsberechtigung für das Adressbuch an:

  1. Wählen Sie im Objektinspektor Form1 aus, und öffnen Sie die Registerkarte Ereignisse.
  2. Doppelklicken Sie neben onShow, und implementieren Sie dann die folgende Ereignisbehandlungsroutine:
    • Für Delphi:
     
    procedure TForm1.FormShow(Sender: TObject);
    begin
      // Display this information box while loading the contacts
      if AddressBook1.Supported then
      begin
        TDialogService.ShowMessage('Loading contacts...');
        AddressBook1.RequestPermission;
      end
      else
        ShowMessage('This platform does not support the Address Book service');
    
    end;
    
    • Für C++:
    void __fastcall TForm1::FormShow(TObject *Sender) {
    	if (AddressBook1->Supported()) {
    		// Display this information box while loading the contacts
    		TDialogService::ShowMessage("Loading contacts...");
    		AddressBook1->RequestPermission();
    	}
    	else {
    		TDialogService::ShowMessage
    			("This platform does not support the Address Book service.");
    	}
    }
    

    Hinweis Um die TDialogService.ShowMessage-Methode zu verwenden, stellen Sie sicher, dass Ihr Quelltext die folgenden Instruktionen enthält:

    Delphi:
    uses
      FMX.DialogService;
    
    C++:
    #include <FMX.DialogService.hpp>
    
  3. Wählen Sie im Objektinspektor AddressBook1 aus, und öffnen Sie die Registerkarte Ereignisse.
  4. Doppelklicken Sie neben OnPermissionRequest, und implementieren Sie dann die folgende Ereignisbehandlungsroutine:
    • Für Delphi:
     
    procedure TForm1.AddressBook1PermissionRequest(ASender: TObject;
      const AMessage: string; const AAccessGranted: Boolean);
    begin
     if AAccessGranted then
       Begin
          FillContactlist;     
       End
                       else
          ShowMessage('You cannot access Address Book. Reason: ' + AMessage);
    
    
    end;
    
    • Für C++:
    void __fastcall TForm1::AddressBook1PermissionRequest(TObject *ASender,
    	const UnicodeString AMessage, const bool AAccessGranted) {
    
    	if (AAccessGranted) {
    		FillContactsList();
    
    	}
    	else {
    		ShowMessage("You cannot access Address Book. Reason: " + AMessage);
    	}
    }
    

Konfigurieren von Android-Anwendungen für den Zugriff auf das Adressbuch

Vor dem Ausführen von Android-Anwendungen, die die TAddressBook-Komponente verwenden, müssen Sie einige Berechtigungen für Ihr Projekt konfigurieren.

So konfigurieren Sie Berechtigungen:

  1. Wählen Sie in der RAD Studio-IDE Projekt > Optionen > Verwendet Berechtigungen aus.
  2. Aktivieren Sie die folgenden Berechtigungen:
    • Konten abrufen
    • Kontakte lesen
    • Kontakte lesen

Ausführen der Beispielanwendung

Gehen Sie folgendermaßen vor, um diese Anwendung auszuführen:

  1. Wählen Sie in der Projektverwaltung die Zielplattform aus (Android und iOS werden unterstützt).

    Wichtig: Vor dem Ausführen dieser Anwendung auf Android-Geräten müssen Sie die Schritte unter Konfigurieren von Android-Anwendungen für den Zugriff auf das Adressbuch abgeschlossen haben.

  2. Drücken Sie Umschalt+Strg+F9, um die Anwendung ohne Debugger auszuführen.

Mit den folgenden Szenarien können Sie Ihre Anwendung testen:

So tragen Sie einen neuen Kontakt ins Adressbuch ein:

  1. Tippen Sie in der Symbolleiste der Anwendung auf Addr Add.png.
    Dadurch wird der Hauptbereich geöffnet.
  2. Geben Sie im Hauptbereich in die Textfelder First name, Last name und Work mail die entsprechenden Informationen ein. Tippen Sie anschließend auf Add, um den gerade erstellten Kontakt ins Adressbuch einzutragen.

    Add Contact iOS.png



So löschen Sie einen Kontakt:

  1. Tippen Sie in der Kontaktliste auf den Kontakt, den Sie löschen möchten.
  2. Tippen Sie in der Symbolleiste der Anwendung auf Addre Trash.png
    Achtung! Dadurch wird der Kontakt aus dem Geräte-Adressbuch entfernt, ohne dass dies angezeigt wird!

    Remove Contact iOS.png

Siehe auch

Codebeispiele