Powiadomienia lokalne w systemie Android

W tej sekcji przedstawiono sposób implementowania powiadomień lokalnych na platformie Xamarin.Android. Wyjaśniono w nim różne elementy interfejsu użytkownika powiadomienia systemu Android i omówiono interfejs API związane z tworzeniem i wyświetlaniem powiadomienia.

Omówienie powiadomień lokalnych

System Android udostępnia dwa obszary kontrolowane przez system do wyświetlania ikon powiadomień i informacji o powiadomieniach dla użytkownika. Po opublikowaniu powiadomienia jego ikona jest wyświetlana w obszarze powiadomień, jak pokazano na poniższym zrzucie ekranu:

Aby uzyskać szczegółowe informacje o powiadomieniu, użytkownik może otworzyć szufladę powiadomień (która rozszerza każdą ikonę powiadomienia w celu ujawnienia zawartości powiadomień) i wykonywać wszelkie akcje skojarzone z powiadomieniami. Poniższy zrzut ekranu przedstawia szufladę powiadomień odpowiadającą powyższemu obszarowi powiadomień:

Powiadomienia systemu Android używają dwóch typów układów:

• Układ podstawowy — kompaktowy, stały format prezentacji.

• Rozszerzony układ — format prezentacji, który może rozszerzyć się na większy rozmiar, aby wyświetlić więcej informacji.

Każdy z tych typów układów (i sposób ich tworzenia) wyjaśniono w poniższych sekcjach.

Uwaga

Ten przewodnik koncentruje się na interfejsach API NotificationCompat z biblioteki obsługi systemu Android. Te interfejsy API zapewnią maksymalną zgodność wsteczną z systemem Android 4.0 (poziom 14 interfejsu API).

Układ podstawowy

Wszystkie powiadomienia systemu Android są tworzone w formacie układu podstawowego, który zawiera co najmniej następujące elementy:

1. Ikona powiadomienia reprezentująca źródłową aplikację lub typ powiadomienia, jeśli aplikacja obsługuje różne typy powiadomień.

2. Tytuł powiadomienia lub nazwa nadawcy, jeśli powiadomienie jest wiadomością osobistą.

3. Komunikat powiadomienia.

4. Znacznik czasu.

Te elementy są wyświetlane jak pokazano na poniższym diagramie:

Układy podstawowe są ograniczone do 64 pikseli niezależnych od gęstości (dp) w wysokości. System Android domyślnie tworzy ten podstawowy styl powiadomień.

Opcjonalnie powiadomienia mogą wyświetlać dużą ikonę reprezentującą aplikację lub zdjęcie nadawcy. Gdy duża ikona jest używana w powiadomieniu w systemie Android 5.0 lub nowszym, mała ikona powiadomienia jest wyświetlana jako znaczek dla dużej ikony:

Począwszy od systemu Android 5.0, powiadomienia mogą być również wyświetlane na ekranie blokady:

Użytkownik może dwukrotnie nacisnąć powiadomienie ekranu blokady, aby odblokować urządzenie i przejść do aplikacji, która pochodzi z tego powiadomienia, lub szybko przesunąć, aby odrzucić powiadomienie. Aplikacje mogą ustawić poziom widoczności powiadomienia, aby kontrolować, co jest wyświetlane na ekranie blokady, a użytkownicy mogą wybrać, czy zezwolić na wyświetlanie poufnych zawartości w powiadomieniach na ekranie blokady.

System Android 5.0 wprowadził format prezentacji powiadomień o wysokim priorytcie o nazwie Heads-up. Powiadomienia z głową przesuwają się w dół od góry ekranu przez kilka sekund, a następnie cofają się do obszaru powiadomień:

Powiadomienia head-up umożliwiają interfejsowi użytkownika systemu umieszczanie ważnych informacji przed użytkownikiem bez zakłócania stanu aktualnie uruchomionej aktywności.

System Android obejmuje obsługę metadanych powiadomień, dzięki czemu powiadomienia można sortować i wyświetlać inteligentnie. Metadane powiadomień kontrolują również sposób prezentowania powiadomień na ekranie blokady i w formacie Head-up. Aplikacje mogą ustawiać następujące typy metadanych powiadomień:

• Priorytet — poziom priorytetu określa sposób i czas prezentowania powiadomień. Na przykład w systemie Android 5.0 powiadomienia o wysokim priorytcie są wyświetlane jako powiadomienia head-up.

• Widoczność — określa, ile zawartości powiadomień ma być wyświetlana po wyświetleniu powiadomienia na ekranie blokady.

• Category — informuje system, jak obsługiwać powiadomienie w różnych okolicznościach, na przykład gdy urządzenie jest w trybie Nie przeszkadzać .

Uwaga

Widoczność i kategoria zostały wprowadzone w systemie Android 5.0 i nie są dostępne we wcześniejszych wersjach systemu Android. Począwszy od systemu Android 8.0, kanały powiadomień są używane do kontrolowania sposobu prezentowania powiadomień użytkownikowi.

Rozwinięte układy

Począwszy od systemu Android 4.1, powiadomienia można skonfigurować za pomocą rozszerzonych stylów układu, które umożliwiają użytkownikowi zwiększenie wysokości powiadomienia w celu wyświetlenia większej zawartości. Na przykład w poniższym przykładzie przedstawiono rozszerzone powiadomienie o układzie w trybie zakontraktowanym:

Po rozwinięciu tego powiadomienia zostanie wyświetlony cały komunikat:

System Android obsługuje trzy rozwinięte style układu dla powiadomień o pojedynczym zdarzeniu:

• Big Text — w trybie kontraktowym wyświetla fragment pierwszego wiersza komunikatu, po którym następuje dwa kropki. W trybie rozwiniętym wyświetla cały komunikat (jak pokazano w powyższym przykładzie).

• Skrzynka odbiorcza — w trybie kontraktowym wyświetla liczbę nowych komunikatów. W trybie rozwiniętym wyświetla pierwszą wiadomość e-mail lub listę wiadomości w skrzynce odbiorczej.

• Obraz — w trybie kontraktowym wyświetla tylko tekst wiadomości. W trybie rozwiniętym wyświetla tekst i obraz.

Poza podstawowym powiadomieniem (w dalszej części tego artykułu) wyjaśniono, jak tworzyć powiadomienia z dużym tekstem, skrzynką odbiorczą i obrazem .

Kanały powiadomień

Począwszy od systemu Android 8.0 (Oreo), możesz użyć funkcji kanałów powiadomień, aby utworzyć kanał umożliwiający dostosowywanie użytkownika dla każdego typu powiadomienia, które chcesz wyświetlić. Kanały powiadomień umożliwiają grupowanie powiadomień w taki sposób, aby wszystkie powiadomienia publikowane w kanale wykazywały takie samo zachowanie. Na przykład może istnieć kanał powiadomień przeznaczony dla powiadomień wymagających natychmiastowej uwagi oraz oddzielny kanał "cichszy" używany do obsługi komunikatów informacyjnych.

Aplikacja YouTube zainstalowana z systemem Android Oreo zawiera dwie kategorie powiadomień: Powiadomienia pobierania i Powiadomienia ogólne:

Każda z tych kategorii odpowiada kanałowi powiadomień. Aplikacja YouTube implementuje kanał powiadomień pobierania i kanał powiadomień ogólnych. Użytkownik może nacisnąć pozycję Pobierz powiadomienia, które wyświetla ekran ustawień kanału powiadomień dotyczących pobierania aplikacji:

Na tym ekranie użytkownik może zmodyfikować zachowanie kanału Powiadomień pobierania , wykonując następujące czynności:

• Ustaw poziom Ważności na Pilny, Wysoki, Średni lub Niski, który konfiguruje poziom przerw w dźwięku i wizualizacji.

• Włącz lub wyłącz kropkę powiadomienia.

• Włącz lub wyłącz światło migające.

• Pokaż lub ukryj powiadomienia na ekranie blokady.

• Zastąpi ustawienie Nie przeszkadzać .

Kanał Powiadomień ogólnych ma podobne ustawienia:

Zwróć uwagę, że nie masz absolutnej kontroli nad sposobem interakcji kanałów powiadomień z użytkownikiem — użytkownik może zmodyfikować ustawienia dowolnego kanału powiadomień na urządzeniu, jak pokazano na powyższych zrzutach ekranu. Można jednak skonfigurować wartości domyślne (jak opisano poniżej). Jak pokazano w tych przykładach, nowa funkcja kanałów powiadomień umożliwia użytkownikom precyzyjną kontrolę nad różnymi rodzajami powiadomień.

Tworzenie powiadomień

Aby utworzyć powiadomienie w systemie Android, użyj klasy NotificationCompat.Builder z pakietu NuGet Xamarin.Android.Support.v4 . Ta klasa umożliwia tworzenie i publikowanie powiadomień w starszych wersjach systemu Android. NotificationCompat.Builder omówiono również.

NotificationCompat.Builder Udostępnia metody ustawiania różnych opcji w powiadomieniu, takich jak:

• Zawartość, w tym tytuł, tekst wiadomości i ikona powiadomienia.

• Styl powiadomienia, taki jak duży tekst, skrzynka odbiorcza lub styl obrazu .

• Priorytet powiadomienia: minimalny, niski, domyślny, wysoki lub maksymalny. W systemie Android 8.0 lub nowszym priorytet jest ustawiany za pośrednictwem kanału powiadomień.

• Widoczność powiadomienia na ekranie blokady: publiczny, prywatny lub tajny.

• Metadane kategorii, które ułatwiają klasyfikowanie i filtrowanie powiadomień przez system Android.

• Opcjonalna intencja wskazująca działanie do uruchomienia po naciśnięciu powiadomienia.

• Identyfikator kanału powiadomień, na który zostanie opublikowane powiadomienie (system Android 8.0 i nowsze).

Po ustawieniu tych opcji w konstruktorze wygenerujesz obiekt powiadomień zawierający ustawienia. Aby opublikować powiadomienie, przekażesz ten obiekt powiadomienia do Menedżera powiadomień. System Android udostępnia klasę NotificationManager , która jest odpowiedzialna za publikowanie powiadomień i wyświetlanie ich użytkownikowi. Odwołanie do tej klasy można uzyskać z dowolnego kontekstu, takiego jak działanie lub usługa.

Tworzenie kanału powiadomień

Aplikacje działające w systemie Android 8.0 muszą utworzyć kanał powiadomień dla swoich powiadomień. Kanał powiadomień wymaga następujących trzech informacji:

• Ciąg identyfikatora, który jest unikatowy dla pakietu, który zidentyfikuje kanał.
• Nazwa kanału, który będzie wyświetlany użytkownikowi. Nazwa musi zawierać się między jednym i 40 znakami.
• Znaczenie kanału.

Aplikacje będą musiały sprawdzić wersję systemu Android, która jest uruchomiona. Urządzenia z wersjami starszymi niż Android 8.0 nie powinny tworzyć kanału powiadomień. Poniższa metoda to jeden z przykładów tworzenia kanału powiadomień w działaniu:

void CreateNotificationChannel()
{
    if (Build.VERSION.SdkInt < BuildVersionCodes.O)
    {
        // Notification channels are new in API 26 (and not a part of the
        // support library). There is no need to create a notification
        // channel on older versions of Android.
        return;
    }

    var channelName = Resources.GetString(Resource.String.channel_name);
    var channelDescription = GetString(Resource.String.channel_description);
    var channel = new NotificationChannel(CHANNEL_ID, channelName, NotificationImportance.Default)
                  {
                      Description = channelDescription
                  };

    var notificationManager = (NotificationManager) GetSystemService(NotificationService);
    notificationManager.CreateNotificationChannel(channel);
}

Kanał powiadomień powinien zostać utworzony za każdym razem, gdy działanie zostanie utworzone. W przypadku CreateNotificationChannel metody należy ją wywołać w OnCreate metodzie działania.

Tworzenie i publikowanie powiadomienia

Aby wygenerować powiadomienie w systemie Android, wykonaj następujące kroki:

1. Utwórz wystąpienie NotificationCompat.Builder obiektu.

2. Wywołaj różne metody na obiekcie, NotificationCompat.Builder aby ustawić opcje powiadomień.

3. Wywołaj metodę Build obiektu, NotificationCompat.Builder aby utworzyć wystąpienie obiektu powiadomienia.

4. Wywołaj metodę Notify menedżera powiadomień, aby opublikować powiadomienie.

Dla każdego powiadomienia należy podać co najmniej następujące informacje:

• Mała ikona (rozmiar 24x24 dp)

• Krótki tytuł

• Tekst powiadomienia

Poniższy przykład kodu ilustruje sposób użycia NotificationCompat.Builder do generowania podstawowego powiadomienia. Zwróć uwagę, że metody obsługują tworzenie łańcuchów metod. Oznacza to, że NotificationCompat.Builder każda metoda zwraca obiekt konstruktora, dzięki czemu można użyć wyniku ostatniego wywołania metody w celu wywołania następnego wywołania metody:

// Instantiate the builder and set notification elements:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my first notification!")
    .SetSmallIcon (Resource.Drawable.ic_notification);

// Build the notification:
Notification notification = builder.Build();

// Get the notification manager:
NotificationManager notificationManager =
    GetSystemService (Context.NotificationService) as NotificationManager;

// Publish the notification:
const int notificationId = 0;
notificationManager.Notify (notificationId, notification);

W tym przykładzie nowy NotificationCompat.Builder obiekt o nazwie builder jest tworzone wystąpienie wraz z identyfikatorem kanału powiadomień, który ma być używany. Tytuł i tekst powiadomienia są ustawione, a ikona powiadomienia jest ładowana z obszaru Resources/drawable/ic_notification.png. Wywołanie metody konstruktora Build powiadomień tworzy obiekt powiadomienia z tymi ustawieniami. Następnym krokiem jest wywołanie Notify metody menedżera powiadomień. Aby zlokalizować menedżera powiadomień, wywołaj metodę GetSystemService, jak pokazano powyżej.

Metoda Notify akceptuje dwa parametry: identyfikator powiadomienia i obiekt powiadomienia. Identyfikator powiadomienia jest unikatową liczbą całkowitą, która identyfikuje powiadomienie do aplikacji. W tym przykładzie identyfikator powiadomienia jest ustawiony na zero (0); jednak w aplikacji produkcyjnej należy nadać każdemu powiadomieniu unikatowy identyfikator. Ponowne przy użyciu poprzedniej wartości identyfikatora w wywołaniu powoduje Notify zastąpienie ostatniego powiadomienia.

Gdy ten kod jest uruchamiany na urządzeniu z systemem Android 5.0, generuje ono powiadomienie podobne do następującego przykładu:

Ikona powiadomienia jest wyświetlana po lewej stronie powiadomienia — ten obraz z okręgowym "i" ma kanał alfa, dzięki czemu system Android może narysować szare okrągłe tło za nim. Możesz również podać ikonę bez kanału alfa. Aby wyświetlić obraz fotograficzny jako ikonę, zobacz Duży format ikon w dalszej części tego tematu.

Sygnatura czasowa jest ustawiana automatycznie, ale to ustawienie można zastąpić, wywołując metodę SetWhen konstruktora powiadomień. Na przykład poniższy przykład kodu ustawia znacznik czasu na bieżący czas:

builder.SetWhen (Java.Lang.JavaSystem.CurrentTimeMillis());

Włączanie dźwięku i drgań

Jeśli chcesz, aby powiadomienie również odtwarzało dźwięk, możesz wywołać metodę SetDefaults konstruktora powiadomień i przekazać flagęNotificationDefaults.Sound:

// Instantiate the notification builder and enable sound:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my first notification!")
    .SetDefaults (NotificationDefaults.Sound)
    .SetSmallIcon (Resource.Drawable.ic_notification);

To wywołanie spowoduje, że SetDefaults urządzenie będzie odtwarzać dźwięk po opublikowaniu powiadomienia. Jeśli urządzenie ma wibrować, a nie odtwarzać dźwięku, możesz przekazać NotificationDefaults.Vibrate do SetDefaults. strony Jeśli chcesz, aby urządzenie odtwarzało dźwięk i wibrować urządzenie, możesz przekazać obie flagi do :SetDefaults

builder.SetDefaults (NotificationDefaults.Sound | NotificationDefaults.Vibrate);

Jeśli włączysz dźwięk bez określenia dźwięku do odtwarzania, system Android używa domyślnego dźwięku powiadomień systemowych. Można jednak zmienić dźwięk, który będzie odtwarzany przez wywołanie metody SetSound konstruktora powiadomień. Aby na przykład odtworzyć dźwięk alarmu za pomocą powiadomienia (zamiast domyślnego dźwięku powiadomienia), możesz uzyskać identyfikator URI dźwięku alarmu z menedżera dzwonka I przekazać go do SetSound:

builder.SetSound (RingtoneManager.GetDefaultUri(RingtoneType.Alarm));

Alternatywnie możesz użyć domyślnego dźwięku dzwonka systemu dla powiadomienia:

builder.SetSound (RingtoneManager.GetDefaultUri(RingtoneType.Ringtone));

Po utworzeniu obiektu powiadomienia można ustawić właściwości powiadomień w obiekcie powiadomień (zamiast konfigurować je z wyprzedzeniem za pomocą NotificationCompat.Builder metod). Na przykład zamiast wywoływać metodę SetDefaults w celu włączenia drgań w powiadomieniu, można bezpośrednio zmodyfikować flagę bitową właściwości Defaults powiadomienia:

// Build the notification:
Notification notification = builder.Build();

// Turn on vibrate:
notification.Defaults |= NotificationDefaults.Vibrate;

Ten przykład powoduje, że urządzenie wibruje po opublikowaniu powiadomienia.

Aktualizowanie powiadomienia

Jeśli chcesz zaktualizować zawartość powiadomienia po jej opublikowaniu, możesz ponownie użyć istniejącego NotificationCompat.Builder obiektu, aby utworzyć nowy obiekt powiadomienia i opublikować to powiadomienie przy użyciu identyfikatora ostatniego powiadomienia. Na przykład:

// Update the existing notification builder content:
builder.SetContentTitle ("Updated Notification");
builder.SetContentText ("Changed to this message.");

// Build a notification object with updated content:
notification = builder.Build();

// Publish the new notification with the existing ID:
notificationManager.Notify (notificationId, notification);

W tym przykładzie istniejący NotificationCompat.Builder obiekt jest używany do tworzenia nowego obiektu powiadomień z innym tytułem i komunikatem. Nowy obiekt powiadomienia jest publikowany przy użyciu identyfikatora poprzedniego powiadomienia i aktualizuje zawartość wcześniej opublikowanego powiadomienia:

Treść poprzedniego powiadomienia jest ponownie wykorzystywana — tylko tytuł i tekst powiadomienia zmienia się, gdy powiadomienie jest wyświetlane w szufladzie powiadomień. Tekst tytułu zmienia się z "Przykładowe powiadomienie" na "Zaktualizowane powiadomienie", a tekst wiadomości zmienia się z "Hello World! To jest moje pierwsze powiadomienie!" do "Zmieniono na tę wiadomość".

Powiadomienie pozostaje widoczne do momentu wystąpienia jednej z trzech rzeczy:

• Użytkownik odrzuca powiadomienie (lub naciska pozycję Wyczyść wszystko).

• Aplikacja wykonuje wywołanie metody NotificationManager.Cancel, przekazując unikatowy identyfikator powiadomienia, który został przypisany podczas publikowania powiadomienia.

• Aplikacja wywołuje metodę NotificationManager.CancelAll.

Aby uzyskać więcej informacji na temat aktualizowania powiadomień systemu Android, zobacz Modyfikowanie powiadomienia.

Uruchamianie działania z powiadomienia

W systemie Android często powiadomienia są skojarzone z akcją — działanie uruchamiane po naciśnięciu powiadomienia. To działanie może znajdować się w innej aplikacji, a nawet w innym zadaniu. Aby dodać akcję do powiadomienia, należy utworzyć obiekt PendingIntent i skojarzyć go PendingIntent z powiadomieniem. Jest PendingIntent to specjalny typ intencji, który umożliwia aplikacji odbiorcy uruchamianie wstępnie zdefiniowanego fragmentu kodu z uprawnieniami aplikacji wysyłającej. Gdy użytkownik naciągnie powiadomienie, system Android uruchamia działanie określone przez element PendingIntent.

Poniższy fragment kodu ilustruje sposób tworzenia powiadomienia za pomocą elementu PendingIntent , które spowoduje uruchomienie działania aplikacji źródłowej: MainActivity

// Set up an intent so that tapping the notifications returns to this app:
Intent intent = new Intent (this, typeof(MainActivity));

// Create a PendingIntent; we're only using one PendingIntent (ID = 0):
const int pendingIntentId = 0;
PendingIntent pendingIntent =
    PendingIntent.GetActivity (this, pendingIntentId, intent, PendingIntentFlags.OneShot);

// Instantiate the builder and set notification elements, including pending intent:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentIntent (pendingIntent)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my first action notification!")
    .SetSmallIcon (Resource.Drawable.ic_notification);

// Build the notification:
Notification notification = builder.Build();

// Get the notification manager:
NotificationManager notificationManager =
    GetSystemService (Context.NotificationService) as NotificationManager;

// Publish the notification:
const int notificationId = 0;
notificationManager.Notify (notificationId, notification);

Ten kod jest bardzo podobny do kodu powiadomień w poprzedniej sekcji, z tą różnicą, że element PendingIntent jest dodawany do obiektu powiadomień. W tym przykładzie element PendingIntent jest skojarzony z działaniem aplikacji źródłowej przed przekazaniem jej do metody SetContentIntent konstruktora powiadomień. Flaga PendingIntentFlags.OneShot jest przekazywana do PendingIntent.GetActivity metody , PendingIntent aby była używana tylko raz. Po uruchomieniu tego kodu zostanie wyświetlone następujące powiadomienie:

Naciśnięcie tego powiadomienia spowoduje powrót użytkownika do działania źródłowego.

W aplikacji produkcyjnej aplikacja musi obsługiwać stos wstecz, gdy użytkownik naciśnie przycisk Wstecz w działaniu powiadomień (jeśli nie znasz zadań systemu Android i stosu wstecz, zobacz Zadania i Stos wsteczny). W większości przypadków przechodzenie do tyłu z działania powiadomień powinno zwrócić użytkownika z aplikacji i z powrotem do ekranu głównego. Aby zarządzać stosem zaplecza, aplikacja używa klasy TaskStackBuilder do utworzenia PendingIntent obiektu z stosem wstecznym.

Innym rzeczywistym zagadnieniem jest to, że działanie źródłowe może wymagać wysyłania danych do działania powiadomień. Na przykład powiadomienie może wskazywać, że wiadomość SMS dotarła, a działanie powiadomienia (ekran wyświetlania komunikatów) wymaga identyfikatora komunikatu w celu wyświetlenia komunikatu użytkownikowi. Działanie, które tworzy PendingIntent obiekt , może użyć metody Intent.PutExtra , aby dodać dane (na przykład ciąg) do intencji, aby te dane zostały przekazane do działania powiadomień.

Poniższy przykładowy kod ilustruje sposób użycia TaskStackBuilder do zarządzania stosem zaplecza i zawiera przykład wysyłania pojedynczego ciągu komunikatu do działania powiadomień o nazwie SecondActivity:

// Setup an intent for SecondActivity:
Intent secondIntent = new Intent (this, typeof(SecondActivity));

// Pass some information to SecondActivity:
secondIntent.PutExtra ("message", "Greetings from MainActivity!");

// Create a task stack builder to manage the back stack:
TaskStackBuilder stackBuilder = TaskStackBuilder.Create(this);

// Add all parents of SecondActivity to the stack:
stackBuilder.AddParentStack (Java.Lang.Class.FromType (typeof (SecondActivity)));

// Push the intent that starts SecondActivity onto the stack:
stackBuilder.AddNextIntent (secondIntent);

// Obtain the PendingIntent for launching the task constructed by
// stackbuilder. The pending intent can be used only once (one shot):
const int pendingIntentId = 0;
PendingIntent pendingIntent =
    stackBuilder.GetPendingIntent (pendingIntentId, PendingIntentFlags.OneShot);

// Instantiate the builder and set notification elements, including
// the pending intent:
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
    .SetContentIntent (pendingIntent)
    .SetContentTitle ("Sample Notification")
    .SetContentText ("Hello World! This is my second action notification!")
    .SetSmallIcon (Resource.Drawable.ic_notification);

// Build the notification:
Notification notification = builder.Build();

// Get the notification manager:
NotificationManager notificationManager =
    GetSystemService (Context.NotificationService) as NotificationManager;

// Publish the notification:
const int notificationId = 0;
notificationManager.Notify (notificationId, notification);

W tym przykładzie kodu aplikacja składa się z dwóch działań: MainActivity (który zawiera powyższy kod powiadomienia) i SecondActivity, na ekranie, który użytkownik widzi po naciśnięciu powiadomienia. Po uruchomieniu tego kodu zostanie wyświetlone proste powiadomienie (podobne do poprzedniego przykładu). Naciśnięcie powiadomienia spowoduje przejście użytkownika na SecondActivity ekran:

Komunikat ciągu (przekazany do metody intencji PutExtra ) jest pobierany SecondActivity za pośrednictwem tego wiersza kodu:

// Get the message from the intent:
string message = Intent.Extras.GetString ("message", "");

Ten pobrany komunikat "Greetings from MainActivity!", jest wyświetlany na SecondActivity ekranie, jak pokazano na powyższym zrzucie ekranu. Gdy użytkownik naciśnie przycisk Wstecz w obszarze SecondActivity, nawigacja prowadzi z aplikacji i z powrotem do ekranu poprzedzającego uruchomienie aplikacji.

Aby uzyskać więcej informacji na temat tworzenia oczekujących intencji, zobacz PendingIntent.

Poza podstawowym powiadomieniem

Powiadomienia domyślnie mają prosty format układu podstawowego w systemie Android, ale można ulepszyć ten podstawowy format, wykonując dodatkowe NotificationCompat.Builder wywołania metod. W tej sekcji dowiesz się, jak dodać do powiadomienia dużą ikonę zdjęcia. Zobaczysz przykłady tworzenia rozszerzonych powiadomień o układzie.

Duży format ikony

Powiadomienia systemu Android zwykle wyświetlają ikonę źródłowej aplikacji (po lewej stronie powiadomienia). Jednak powiadomienia mogą wyświetlać obraz lub zdjęcie ( duża ikona) zamiast standardowej małej ikony. Na przykład aplikacja do obsługi komunikatów może wyświetlić zdjęcie nadawcy, a nie ikonę aplikacji.

Oto przykład podstawowego powiadomienia systemu Android 5.0 — wyświetla tylko małą ikonę aplikacji:

Oto zrzut ekranu powiadomienia po zmodyfikowaniu go w celu wyświetlenia dużej ikony — używa ikony utworzonej na podstawie obrazu małpy kodu platformy Xamarin:

Zwróć uwagę, że gdy powiadomienie jest wyświetlane w dużym formacie ikony, mała ikona aplikacji jest wyświetlana jako znaczek w prawym dolnym rogu dużej ikony.

Aby użyć obrazu jako dużej ikony w powiadomieniu, wywołasz metodę SetLargeIcon konstruktora powiadomień i przekażesz mapę bitową obrazu. W przeciwieństwie do SetSmallIconmetody , SetLargeIcon akceptuje tylko mapę bitową. Aby przekonwertować plik obrazu na mapę bitową, należy użyć klasy BitmapFactory . Na przykład:

builder.SetLargeIcon (BitmapFactory.DecodeResource (Resources, Resource.Drawable.monkey_icon));

Ten przykładowy kod otwiera plik obrazu w folderze Resources/drawable/monkey_icon.png, konwertuje go na mapę bitową i przekazuje wynikową mapę bitową na NotificationCompat.Builder. Zazwyczaj rozdzielczość obrazu źródłowego jest większa niż mała ikona — ale nie jest znacznie większa. Obraz, który jest zbyt duży, może spowodować niepotrzebne operacje zmiany rozmiaru, które mogą opóźnić publikowanie powiadomienia.

Styl dużego tekstu

Styl big text to rozszerzony szablon układu używany do wyświetlania długich komunikatów w powiadomieniach. Podobnie jak w przypadku wszystkich powiadomień o rozszerzonym układzie, powiadomienie big text jest początkowo wyświetlane w kompaktowym formacie prezentacji:

W tym formacie wyświetlany jest tylko fragment komunikatu, zakończony dwoma kropkami. Gdy użytkownik przeciąga powiadomienie w dół, rozwija się, aby wyświetlić cały komunikat z powiadomieniem:

Ten rozszerzony format układu zawiera również tekst podsumowania w dolnej części powiadomienia. Maksymalna wysokość powiadomienia big text wynosi 256 dp.

Aby utworzyć powiadomienie big text, należy utworzyć wystąpienie NotificationCompat.Builder obiektu, tak jak wcześniej, a następnie utworzyć wystąpienie i dodać obiekt BigTextStyle do NotificationCompat.Builder obiektu. Oto przykład:

// Instantiate the Big Text style:
Notification.BigTextStyle textStyle = new Notification.BigTextStyle();

// Fill it with text:
string longTextMessage = "I went up one pair of stairs.";
longTextMessage += " / Just like me. ";
//...
textStyle.BigText (longTextMessage);

// Set the summary text:
textStyle.SetSummaryText ("The summary text goes here.");

// Plug this style into the builder:
builder.SetStyle (textStyle);

// Create the notification and publish it ...

W tym przykładzie tekst wiadomości i tekst podsumowania są przechowywane w BigTextStyle obiekcie (textStyle) przed przekazaniem go do NotificationCompat.Builder.

Styl obrazu

Styl obrazu (nazywany również stylem duży obraz) to rozszerzony format powiadomień, którego można użyć do wyświetlania obrazu w treści powiadomienia. Na przykład aplikacja zrzutu ekranu lub aplikacja fotograficzna może użyć stylu powiadomień obrazów , aby udostępnić użytkownikowi powiadomienie o ostatnim przechwyconym obrazie. Należy pamiętać, że maksymalna wysokość powiadomienia o obrazie wynosi 256 dp — system Android zmieni rozmiar obrazu tak, aby mieścił się w tym maksymalnym ograniczeniu wysokości, w granicach dostępnej pamięci.

Podobnie jak wszystkie powiadomienia o rozszerzonym układzie, powiadomienia o obrazach są najpierw wyświetlane w formacie kompaktowym, który wyświetla fragment towarzyszącego tekstu wiadomości:

Gdy użytkownik przeciągnie w dół powiadomienie Obraz , rozwija się, aby wyświetlić obraz. Na przykład poniżej przedstawiono rozszerzoną wersję poprzedniego powiadomienia:

Zwróć uwagę, że gdy powiadomienie jest wyświetlane w formacie kompaktowym, wyświetla tekst powiadomienia (tekst przekazywany do metody konstruktora SetContentText powiadomień, jak pokazano wcześniej). Jednak po rozwinięciu powiadomienia w celu wyświetlenia obrazu zostanie wyświetlony tekst podsumowania powyżej obrazu.

Aby utworzyć powiadomienie o obrazie, należy utworzyć wystąpienie NotificationCompat.Builder obiektu tak jak wcześniej, a następnie utworzyć i wstawić obiekt BigPictureStyle do NotificationCompat.Builder obiektu. Na przykład:

// Instantiate the Image (Big Picture) style:
Notification.BigPictureStyle picStyle = new Notification.BigPictureStyle();

// Convert the image to a bitmap before passing it into the style:
picStyle.BigPicture (BitmapFactory.DecodeResource (Resources, Resource.Drawable.x_bldg));

// Set the summary text that will appear with the image:
picStyle.SetSummaryText ("The summary text goes here.");

// Plug this style into the builder:
builder.SetStyle (picStyle);

// Create the notification and publish it ...

SetLargeIcon Podobnie jak metoda metody , metoda NotificationCompat.BuilderBigPictureStyle BigPicture wymaga mapy bitowej obrazu, który ma być wyświetlany w treści powiadomienia. W tym przykładzie metoda BitmapFactory DecodeResource odczytuje plik obrazu znajdujący się w lokalizacji Resources/drawable/x_bldg.png i konwertuje go na mapę bitową.

Można również wyświetlać obrazy, które nie są pakowane jako zasób. Na przykład poniższy przykładowy kod ładuje obraz z lokalnej karty SD i wyświetla go w powiadomieniu Obraz :

// Using the Image (Big Picture) style:
Notification.BigPictureStyle picStyle = new Notification.BigPictureStyle();

// Read an image from the SD card, subsample to half size:
BitmapFactory.Options options = new BitmapFactory.Options();
options.InSampleSize = 2;
string imagePath = "/sdcard/Pictures/my-tshirt.jpg";
picStyle.BigPicture (BitmapFactory.DecodeFile (imagePath, options));

// Set the summary text that will appear with the image:
picStyle.SetSummaryText ("Check out my new T-Shirt!");

// Plug this style into the builder:
builder.SetStyle (picStyle);

// Create notification and publish it ...

W tym przykładzie plik obrazu znajdujący się w folderze /sdcard/Pictures/my-tshirt.jpg jest ładowany, zmieniany na połowę oryginalnego rozmiaru, a następnie konwertowany na mapę bitową do użycia w powiadomieniu:

Jeśli nie znasz z wyprzedzeniem rozmiaru pliku obrazu, dobrym pomysłem jest zawinięcie wywołania pliku BitmapFactory.DecodeFile w procedurze obsługi wyjątków — OutOfMemoryError wyjątek może zostać zgłoszony, jeśli rozmiar obrazu jest zbyt duży dla systemu Android.

Aby uzyskać więcej informacji na temat ładowania i dekodowania dużych obrazów map bitowych, zobacz Wydajne ładowanie dużych map bitowych.

Styl skrzynki odbiorczej

Format skrzynki odbiorczej to rozszerzony szablon układu przeznaczony do wyświetlania oddzielnych wierszy tekstu (takich jak podsumowanie skrzynki odbiorczej wiadomości e-mail) w treści powiadomienia. Powiadomienie w formacie skrzynki odbiorczej jest najpierw wyświetlane w formacie kompaktowym:

Gdy użytkownik przeciąga powiadomienie w dół, rozwija się, aby wyświetlić podsumowanie wiadomości e-mail, jak pokazano na poniższym zrzucie ekranu:

Aby utworzyć powiadomienie skrzynki odbiorczej, należy utworzyć NotificationCompat.Builderwystąpienie obiektu, tak jak poprzednio, i dodać obiekt InboxStyle do NotificationCompat.Builderobiektu . Oto przykład:

// Instantiate the Inbox style:
Notification.InboxStyle inboxStyle = new Notification.InboxStyle();

// Set the title and text of the notification:
builder.SetContentTitle ("5 new messages");
builder.SetContentText ("chimchim@xamarin.com");

// Generate a message summary for the body of the notification:
inboxStyle.AddLine ("Cheeta: Bananas on sale");
inboxStyle.AddLine ("George: Curious about your blog post");
inboxStyle.AddLine ("Nikko: Need a ride to Evolve?");
inboxStyle.SetSummaryText ("+2 more");

// Plug this style into the builder:
builder.SetStyle (inboxStyle);

Aby dodać nowe wiersze tekstu do treści powiadomienia, wywołaj metodę InboxStyle Addline obiektu (maksymalna wysokość powiadomienia skrzynki odbiorczej wynosi 256 dp). Należy pamiętać, że w przeciwieństwie do stylu Duży tekst styl skrzynki odbiorczej obsługuje poszczególne wiersze tekstu w treści powiadomienia.

Możesz również użyć stylu skrzynki odbiorczej dla dowolnego powiadomienia, które musi wyświetlać poszczególne wiersze tekstu w rozszerzonym formacie. Na przykład styl powiadomień skrzynki odbiorczej może służyć do łączenia wielu oczekujących powiadomień w powiadomienie podsumowujące — można zaktualizować pojedyncze powiadomienie w stylu skrzynki odbiorczej o nowe wiersze zawartości powiadomienia (zobacz Aktualizowanie powiadomienia powyżej), a nie wygenerować ciągłego strumienia nowych, głównie podobnych powiadomień.

Konfigurowanie metadanych

NotificationCompat.Builder Zawiera metody, które można wywołać, aby ustawić metadane dotyczące powiadomienia, takie jak priorytet, widoczność i kategoria. System Android używa tych informacji — wraz z ustawieniami preferencji użytkownika — w celu określenia, jak i kiedy wyświetlać powiadomienia.

Ustawienia priorytetu

Aplikacje działające w systemie Android 7.1 i niższe muszą ustawić priorytet bezpośrednio na samym powiadomieniu. Ustawienie priorytetu powiadomienia określa dwa wyniki po opublikowaniu powiadomienia:

• Gdzie powiadomienie jest wyświetlane w odniesieniu do innych powiadomień. Na przykład powiadomienia o wysokim priorytcie są prezentowane powyżej powiadomień o niższym priorytcie w szufladzie powiadomień, niezależnie od tego, kiedy każde powiadomienie zostało opublikowane.

• Czy powiadomienie jest wyświetlane w formacie powiadomienia Head-up (Android 5.0 i nowsze). Powiadomienia o wysokim i maksymalnym priorytcie są wyświetlane jako powiadomienia head-up.

Platforma Xamarin.Android definiuje następujące wyliczenia dotyczące ustawiania priorytetu powiadomień:

• NotificationPriority.Max — powiadamia użytkownika o pilnym lub krytycznym stanie (na przykład połączenia przychodzącego, wskazówek turn-by-turn lub alertu awaryjnego). Na urządzeniach z systemem Android 5.0 lub nowszym powiadomienia o maksymalnym priorytowaniu są wyświetlane w formacie Head-up.

• NotificationPriority.High – informuje użytkownika o ważnych wydarzeniach (takich jak ważne wiadomości e-mail lub przybycie wiadomości czatu w czasie rzeczywistym). Na urządzeniach z systemem Android 5.0 lub nowszym powiadomienia o wysokim priorytcie są wyświetlane w formacie Head-up.

• NotificationPriority.Default — powiadamia użytkownika o warunkach o średnim poziomie ważności.

• NotificationPriority.Low — W przypadku niepilnych informacji, o których użytkownik musi być poinformowany (na przykład przypomnienia o aktualizacji oprogramowania lub aktualizacjach sieci społecznościowych).

• NotificationPriority.Min — Aby uzyskać podstawowe informacje, które użytkownik zauważa tylko podczas wyświetlania powiadomień (na przykład informacji o lokalizacji lub pogodzie).

Aby ustawić priorytet powiadomienia, wywołaj metodę NotificationCompat.Builder SetPriority obiektu, przekazując poziom priorytetu. Na przykład:

builder.SetPriority (NotificationPriority.High);

W poniższym przykładzie powiadomienie o wysokim priorytcie "Ważny komunikat!" pojawia się w górnej części szuflady powiadomień:

Ponieważ jest to powiadomienie o wysokim priorytcie, jest również wyświetlane jako powiadomienie Head-up powyżej bieżącego ekranu aktywności użytkownika w systemie Android 5.0:

W następnym przykładzie powiadomienie o niskim priorytcie "Myśl o dniu" jest wyświetlane w ramach powiadomienia o poziomie baterii o wyższym priorytcie:

Ponieważ powiadomienie "Myśl na dzień" jest powiadomieniem o niskim priorytcie, system Android nie będzie wyświetlał go w formacie Head-up.

Uwaga

W systemie Android 8.0 i nowszym priorytet kanału powiadomień i ustawień użytkownika określi priorytet powiadomienia.

Ustawienia widoczności

Począwszy od systemu Android 5.0, ustawienie widoczności jest dostępne do kontrolowania, ile zawartości powiadomień pojawia się na bezpiecznym ekranie blokady. Platforma Xamarin.Android definiuje następujące wyliczenia dotyczące ustawiania widoczności powiadomień:

• NotificationVisibility.Public — Pełna zawartość powiadomienia jest wyświetlana na bezpiecznym ekranie blokady.

• NotificationVisibility.Private — na bezpiecznym ekranie blokady są wyświetlane tylko istotne informacje (takie jak ikona powiadomienia i nazwa aplikacji, która ją opublikowała), ale pozostałe szczegóły powiadomienia są ukryte. Domyślnie wszystkie powiadomienia mają wartość NotificationVisibility.Private.

• NotificationVisibility.Secret — Nic nie jest wyświetlane na bezpiecznym ekranie blokady, nawet ikona powiadomienia. Zawartość powiadomienia jest dostępna tylko po odblokowaniu urządzenia przez użytkownika.

Aby ustawić widoczność powiadomienia, aplikacje wywołają SetVisibility metodę NotificationCompat.Builder obiektu, przekazując ustawienie widoczności. Na przykład to wywołanie powoduje SetVisibility wysłanie powiadomienia Private:

builder.SetVisibility (NotificationVisibility.Private);

Po opublikowaniu Private powiadomienia na bezpiecznym ekranie blokady jest wyświetlana tylko nazwa i ikona aplikacji. Zamiast komunikatu powiadomienia użytkownik widzi komunikat "Odblokuj urządzenie, aby wyświetlić to powiadomienie":

W tym przykładzie element NotificationsLab jest nazwą źródłowej aplikacji. Ta zredagowana wersja powiadomienia jest wyświetlana tylko wtedy, gdy ekran blokady jest bezpieczny (tj. zabezpieczony za pomocą numeru PIN, wzorca lub hasła) — jeśli ekran blokady nie jest bezpieczny, pełna zawartość powiadomienia jest dostępna na ekranie blokady.

Ustawienia kategorii

Począwszy od systemu Android 5.0, wstępnie zdefiniowane kategorie są dostępne do klasyfikowania i filtrowania powiadomień. Platforma Xamarin.Android udostępnia następujące wyliczenia dla tych kategorii:

• Notification.CategoryCall – Przychodzące połączenie telefoniczne.

• Notification.CategoryMessage – Przychodząca wiadomość SMS.

• Notification.CategoryAlarm — stan alarmu lub wygaśnięcie czasomierza.

• Notification.CategoryEmail — Przychodząca wiadomość e-mail.

• Notification.CategoryEvent — zdarzenie kalendarza.

• Notification.CategoryPromo – wiadomość promocyjna lub reklama.

• Notification.CategoryProgress — postęp operacji w tle.

• Notification.CategorySocial – Aktualizacja sieci społecznościowych.

• Notification.CategoryError — Niepowodzenie operacji w tle lub procesu uwierzytelniania.

• Notification.CategoryTransport — aktualizacja odtwarzania multimediów.

• Notification.CategorySystem — zarezerwowane do użycia systemu (stan systemu lub urządzenia).

• Notification.CategoryService — wskazuje, że usługa w tle jest uruchomiona.

• Notification.CategoryRecommendation — komunikat rekomendacji związany z aktualnie uruchomioną aplikacją.

• Notification.CategoryStatus — informacje o urządzeniu.

Gdy powiadomienia są sortowane, priorytet powiadomienia ma pierwszeństwo przed ustawieniem kategorii. Na przykład powiadomienie o wysokim priorytcie będzie wyświetlane jako Head-up, nawet jeśli należy do Promo kategorii. Aby ustawić kategorię powiadomienia, należy wywołać SetCategory metodę NotificationCompat.Builder obiektu, przekazując ustawienie kategorii. Na przykład:

builder.SetCategory (Notification.CategoryCall);

Funkcja Nie przeszkadzać (nowość w systemie Android 5.0) filtruje powiadomienia na podstawie kategorii. Na przykład ekran Nie przeszkadzać w Ustawienia umożliwia użytkownikowi wykluczenie powiadomień dotyczących połączeń telefonicznych i wiadomości:

Gdy użytkownik konfiguruje opcję Nie przeszkadzać , aby blokować wszystkie przerwania z wyjątkiem połączeń telefonicznych (jak pokazano na powyższym zrzucie ekranu), system Android zezwala na wysyłanie powiadomień z ustawieniem Notification.CategoryCall kategorii, które ma być prezentowane, gdy urządzenie jest w trybie Nie przeszkadzać . Należy pamiętać, że Notification.CategoryAlarm powiadomienia nigdy nie są blokowane w trybie Nie przeszkadzać .

Style powiadomień

Aby utworzyć powiadomienia w stylu Big Text, Image lub Inbox w programie NotificationCompat.Builder, aplikacja musi używać wersji zgodności tych stylów. Aby na przykład użyć stylu big text, utwórz wystąpienie NotificationCompat.BigTextstyleelementu :

NotificationCompat.BigTextStyle textStyle = new NotificationCompat.BigTextStyle();

// Plug this style into the builder:
builder.SetStyle (textStyle);

Podobnie aplikacja może używać NotificationCompat.InboxStyleNotificationCompat.BigPictureStyleodpowiednio stylów skrzynki odbiorczej i obrazu oraz dla nich.

Priorytet i kategoria powiadomień

NotificationCompat.Builder obsługuje metodę SetPriority (dostępną od systemu Android 4.1). Jednak metoda nie jest obsługiwanaSetCategory, NotificationCompat.Builder ponieważ kategorie są częścią nowego systemu metadanych powiadomień, który został wprowadzony w systemie Android 5.0.

Aby obsługiwać starsze wersje systemu Android, jeśli SetCategory nie są dostępne, kod może sprawdzić poziom interfejsu API w czasie wykonywania w celu warunkowego wywołania SetCategory , gdy poziom interfejsu API jest równy lub większy niż Android 5.0 (poziom interfejsu API 21):

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop) {
    builder.SetCategory (Notification.CategoryEmail);
}

W tym przykładzie platforma docelowa aplikacji jest ustawiona na Android 5.0, a minimalna wersja systemu Android jest ustawiona na Android 4.1 (poziom 16 interfejsu API). Ponieważ SetCategory jest dostępny na poziomie 21 interfejsu API i nowszym, ten przykładowy kod będzie wywoływany SetCategory tylko wtedy, gdy jest dostępny — nie będzie wywoływany SetCategory , gdy poziom interfejsu API jest mniejszy niż 21.

Widoczność ekranu blokady

Ponieważ system Android nie obsługuje powiadomień na ekranie blokady przed androidem 5.0 (poziom 21 interfejsu SetVisibility API), NotificationCompat.Builder nie obsługuje metody . Jak wyjaśniono powyżej, SetCategorykod może sprawdzać poziom interfejsu API w czasie wykonywania i wywoływać SetVisiblity tylko wtedy, gdy jest dostępny:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop) {
    builder.SetVisibility (Notification.Public);
}

Podsumowanie

W tym artykule wyjaśniono, jak tworzyć powiadomienia lokalne w systemie Android. Opisano w nim anatomię powiadomienia, wyjaśniono, jak używać NotificationCompat.Builder do tworzenia powiadomień, stylu powiadomień w dużych ikonach, dużych formatach tekstu, obrazu i skrzynki odbiorczej, jak ustawić ustawienia metadanych powiadomień, takie jak priorytet, widoczność i kategoria oraz jak uruchamiać działanie z powiadomienia. W tym artykule opisano również, jak te ustawienia powiadomień działają z nowymi funkcjami head-up, lock screen i Nie przeszkadzać wprowadzonymi w systemie Android 5.0. Na koniec wiesz już, jak zachować NotificationCompat.Builder zgodność powiadomień z wcześniejszymi wersjami systemu Android.

Aby uzyskać wskazówki dotyczące projektowania powiadomień dla systemu Android, zobacz Powiadomienia.

Linki powiązane

• Powiadomienia lokalne w przewodniku po systemie Android
• Powiadamianie użytkownika
• zdarzeniu
• NotificationManager
• NotificationCompat.Builder
• PendingIntent