Tworzenie precyzyjnego linku dla miejsca docelowego

Na Androidzie precyzyjny link to link, który prowadzi bezpośrednio do określonego miejsca w aplikacji.

Komponent Nawigacja umożliwia tworzenie 2 rodzajów precyzyjnych linków: wyraźnych i domyślnych.

Tworzenie wyraźnego precyzyjnego linku

Wyraźny precyzyjny link to pojedynczy precyzyjny link, który używa PendingIntent do kierowania użytkowników do określonego miejsca w aplikacji. Możesz wyświetlić wyraźny precyzyjny link na przykład w ramach powiadomienia lub widżetu aplikacji.

Gdy użytkownik otworzy Twoją aplikację za pomocą precyzyjnego linku, stos zadań zostanie wyczyszczony i zastąpiony miejscem docelowym precyzyjnego linku. Podczas zagnieżdżania wykresów do stosu jest też dodawane miejsce docelowe z początku każdego poziomu zagnieżdżania, czyli miejsce docelowe z początku każdego elementu <navigation> w hierarchii. Oznacza to, że gdy użytkownik kliknie przycisk Wstecz w miejscu docelowym precyzyjnego linku, wróci do poprzedniego poziomu nawigacji tak, jakby wszedł do aplikacji od jej punktu wejścia.

Możesz użyć klasy NavDeepLinkBuilder do utworzenia klasy PendingIntent, jak pokazano w poniższym przykładzie. Pamiętaj, że jeśli podany kontekst nie jest obiektem Activity, konstruktor używa parametru PackageManager.getLaunchIntentForPackage() jako domyślnej aktywności do uruchomienia (jeśli jest dostępna).

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent()

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent();

Domyślnie NavDeepLinkBuilder uruchamia precyzyjny link do domyślnego Activity, który jest zadeklarowany w manifeście aplikacji. Jeśli NavHost występuje w innej aktywności, podczas tworzenia kreatora precyzyjnych linków musisz podać nazwę jego komponentu:

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(DestinationActivity::class.java)
    .createPendingIntent()

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(DestinationActivity.class)
        .createPendingIntent();

Jeśli masz ComponentName, możesz przekazać go bezpośrednio do konstruktora:

val componentName = ...

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(componentName)
    .createPendingIntent()

ComponentName componentName = ...;

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(componentName)
        .createPendingIntent();

Jeśli masz już NavController, możesz też utworzyć precyzyjny link, używając NavController.createDeepLink().

Tworzenie precyzyjnego linku typu implicit

Ukryty precyzyjny link odnosi się do określonego miejsca docelowego w aplikacji. Gdy zostanie wywołany (np. gdy użytkownik kliknie link), Android może otworzyć Twoją aplikację w odpowiednim miejscu docelowym.

Precyzyjne linki można dopasowywać na podstawie identyfikatora URI, działań związanych z intencją i typów MIME. W przypadku jednego linku głębokiego możesz określić wiele typów dopasowania, ale pamiętaj, że najpierw jest stosowany dopasowanie argumentu URI, a potem działanie i typ MIME.

Oto przykładowy precyzyjny link zawierający identyfikator URI, działanie i typ MIME:

<fragment android:id="@+id/a"
          android:name="com.example.myapplication.FragmentA"
          tools:layout="@layout/a">
        <deepLink app:uri="www.example.com"
                app:action="android.intent.action.MY_ACTION"
                app:mimeType="type/subtype"/>
</fragment>

Za pomocą Edytora nawigacji możesz też utworzyć do ukrytego miejsca docelowego domyślny precyzyjny link w ten sposób:

1. Na karcie Projekt w Edytorze nawigacji wybierz miejsce docelowe precyzyjnego linku.
2. W sekcji Linki dogłębne w panelu Atrybuty kliknij +.

3. W wyświetlonym oknie Dodaj precyzyjny link wpisz informacje o precyzyjnym linku.

   Uwaga:

   • Identyfikatory URI bez schematu są uznawane za identyfikatory http lub https. Na przykład www.google.com pasuje do http://www.google.com i https://www.google.com.
   • Zakładki parametrów ścieżki w postaci {placeholder_name} pasują do co najmniej 1 znaku. Na przykład http://www.example.com/users/{id} pasuje do http://www.example.com/users/4. Komponent Nawigacja próbuje przeanalizować wartości zastępcze i przypisać je do odpowiednich typów, dopasowując nazwy zastępcze do zdefiniowanych argumentów, które są zdefiniowane dla miejsca docelowego precyzyjnego linku. Jeśli nie zdefiniowano żadnego argumentu o tym samym imieniu, do wartości argumentu zostanie użyty domyślny typ String. Za pomocą symbolu wieloznacznego „.” możesz dopasować 0 lub więcej znaków.
   • Zakładki parametrów zapytania można używać zamiast parametrów ścieżki lub razem z nimi. Na przykład: http://www.example.com/users/{id}?myarg={myarg} pasuje do http://www.example.com/users/4?myarg=28.
   • Zakładki parametrów zapytań dla zmiennych zdefiniowanych za pomocą wartości domyślnych lub wartości dozwolonych niewymagają dopasowania. Na przykład http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} pasuje do http://www.example.com/users/4?arg2=28 lub http://www.example.com/users/4?arg1=7. Nie dotyczy to parametrów ścieżek. Na przykład http://www.example.com/users?arg1=7&arg2=28nie pasuje do powyższego wzoru, ponieważ nie podano wymaganego parametru ścieżki.
   • Nieistotne parametry zapytania nie wpływają na dopasowywanie identyfikatorów URI precyzyjnych linków. Na przykład http://www.example.com/users/{id} pasuje do http://www.example.com/users/4?extraneousParam=7, mimo że extraneousParam nie jest zdefiniowana we wzorze URI.

4. (Opcjonalnie) Zaznacz Automatyczna weryfikacja, aby wymagać od Google potwierdzenia, że jesteś właścicielem adresu URI. Więcej informacji znajdziesz w artykule Weryfikowanie linków aplikacji na Androida.

5. Kliknij Dodaj. Nad wybranym miejscem docelowym pojawi się ikona linka , aby wskazać, że to miejsce ma link głęboki.

6. Kliknij kartę Kod, aby przełączyć się na widok kodu XML. Do miejsca docelowego został dodany zagnieżdżony element <deepLink>:

   <deepLink app:uri="https://www.google.com" />
   

Aby włączyć niejawne precyzyjne linki, musisz też dodać dodatki do pliku manifest.xml aplikacji. Dodaj pojedynczy element <nav-graph> do aktywności, która wskazuje na istniejący graf nawigacyjny, jak w tym przykładzie:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapplication">

    <application ... >

        <activity name=".MainActivity" ...>
            ...

            <nav-graph android:value="@navigation/nav_graph" />

            ...

        </activity>
    </application>
</manifest>

Podczas tworzenia projektu komponent Nawigacja zastępuje element <nav-graph> wygenerowanymi elementami <intent-filter>, aby pasowały do wszystkich precyzyjnych linków w grafie nawigacji.

Gdy aktywujesz niejawny precyzyjny link, stan stosu wstecznego zależy od tego, czy niejawna Intent została uruchomiona z flagą Intent.FLAG_ACTIVITY_NEW_TASK:

• Jeśli flaga jest ustawiona, stos zadań do cofnięcia jest czyszczony i zastępowany miejscem docelowym linku głębokiego. Podobnie jak w przypadku wyraźnych precyzyjnych linków, podczas zagnieżdżania wykresów do stosu jest też dodawane miejsce docelowe początkowe z każdego poziomu zagnieżdżenia, czyli miejsce docelowe początkowe z każdego elementu <navigation> w hierarchii. Oznacza to, że gdy użytkownik naciśnie przycisk Wstecz w miejscu docelowym precyzyjnego linku, wróci do poprzedniego poziomu nawigacji tak, jakby wszedł do aplikacji od jej punktu wejścia.
• Jeśli flaga nie jest ustawiona, pozostaniesz w grupie zadań poprzedniej aplikacji, w której został wywołany domyślny precyzyjny link. W takim przypadku przycisk Wstecz wróci do poprzedniej aplikacji, a przycisk w górę uruchamia zadanie aplikacji w hierarchicznym nadrzędnym miejscu docelowym na wykresie nawigacyjnym.

Obsługa precyzyjnych linków

Zdecydowanie zalecamy, aby podczas korzystania z Nawigacji zawsze używać domyślnej wartości launchMode standard. Gdy używasz trybu uruchamiania standard, Nawigacja automatycznie obsługuje precyzyjne linki, wywołując handleDeepLink() w celu przetworzenia wszelkich jawnych lub niejawnych precyzyjnych linków w Intent. Nie dzieje się tak jednak, jeśli Activity jest ponownie używany przy użyciu alternatywnego launchMode, takiego jak singleTop. W takim przypadku musisz ręcznie wywołać funkcję handleDeepLink() w funkcji onNewIntent(), jak pokazano w tym przykładzie:

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    navController.handleDeepLink(intent)
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    navController.handleDeepLink(intent);
}

Dodatkowe materiały

Więcej informacji o nawigacji znajdziesz w tych materiałach.

Próbki

• Przykładowa implementacja podstawowych komponentów architektury Androida

Ćwiczenia z programowania

• Nawigacja – ćwiczenie programistyczne

Filmy

• Android Jetpack: zarządzanie nawigacją w interfejsie za pomocą kontrolera nawigacji (Google I/O 2018)