Глубокие ссылки

Общие шаблоны URI для глубоких ссылок

Общий шаблон URI должен соответствовать URI целиком. Можно использовать заполнители параметров, чтобы извлекать их из полученного URI в пункте назначения.

Правила для общих шаблонов URI:

• Предполагается, что URI без схемы начинаются с http:// или https://. Поэтому uriPattern = "example.com" соответствует http://example.com и https://example.com.

• {placeholder} соответствует одному или нескольким символам (example.com/name={name} соответствует https://example.com/name=Bob). Чтобы сопоставить ноль или более символов, используйте подстановочный символ .* (example.com/name={.*} соответствует https://example.com/name=, а также любому значению name).

• Параметры для заполнителей пути обязательны при сопоставлении, а параметры для заполнителей запроса — необязательны. Например, шаблон example.com/users/{id}?arg1={arg1}&arg2={arg2}:

  • Не соответствует http://www.example.com/users?arg1=one&arg2=two, так как отсутствует обязательная часть пути (id).

  • Соответствует и http://www.example.com/users/4?arg2=two, и http://www.example.com/users/4?arg1=one.

  • Также соответствует http://www.example.com/users/4?other=random, поскольку лишние параметры запроса не влияют на сопоставление.

• Если у нескольких композируемых функций есть navDeepLink, соответствующий полученному URI, поведение не определено. Убедитесь, что шаблоны глубоких ссылок не пересекаются. Если вам нужно, чтобы несколько композируемых функций обрабатывали один и тот же шаблон глубокой ссылки, добавьте параметры пути или запроса либо используйте промежуточный пункт назначения для предсказуемой маршрутизации пользователя.

Создание шаблона URI для типа маршрута

Можно не указывать шаблон URI полностью: библиотека Navigation может автоматически создать его на основе параметров маршрута.

Чтобы воспользоваться этим подходом, определите глубокую ссылку следующим образом:

composable<PlantDetail>(
    deepLinks = listOf(
        navDeepLink<PlantDetail>(basePath = "demo://example.com/plant")
    )
) { ... }

Здесь PlantDetail — это тип маршрута, используемый для пункта назначения, а "plant" в basePath — сериализованное имя класса данных PlantDetail.

Остальная часть шаблона URI будет создана следующим образом:

• Обязательные параметры добавляются как параметры пути (пример: /{id})

• Параметры со значением по умолчанию (необязательные параметры) добавляются как параметры запроса (пример: ?name={name})

• Коллекции добавляются как параметры запроса (пример: ?items={value1}&items={value2})

• Порядок параметров соответствует порядку полей в определении маршрута.

Например, для такого типа маршрута:

@Serializable data class PlantDetail(
  val id: String,
  val name: String,
  val colors: List<String>,
  val latinName: String? = null,
)

библиотека создаёт следующий шаблон URI:

<basePath>/{id}/{name}/?colors={color1}&colors={color2}&latinName={latinName}

Пример добавления глубоких ссылок к пункту назначения

В этом примере мы назначаем несколько глубоких ссылок пункту назначения, а затем извлекаем значения параметров из полученных URI:

@Serializable @SerialName("dlscreen") data class DeepLinkScreen(val name: String)

// ...

val firstBasePath = "demo://example1.org"

NavHost(
    navController = navController,
    startDestination = FirstScreen
) {
    // ...
    
    composable<DeepLinkScreen>(
        deepLinks = listOf(
            // This composable should handle links both for demo://example1.org and demo://example2.org
            navDeepLink { uriPattern = "$firstBasePath?name={name}" },
            navDeepLink { uriPattern = "demo://example2.org/name={name}" },
            // The generated pattern only handles the parameters,
            // so we add the serial name for the route type
            navDeepLink<DeepLinkScreen>(basePath = "$firstBasePath/dlscreen"),
        )
    ) {
        // If the app receives the URI `demo://example1.org/dlscreen/Jane/`,
        // it matches the generated URI pattern (name is a required parameter and is given in the path),
        // and you can map it to the route type automatically
        val deeplink: DeepLinkScreen = backStackEntry.toRoute()
        val nameGenerated = deeplink.name
        
        // If the app receives a URI matching only a general pattern,
        // like `demo://example1.com/?name=Jane`
        // you need to parse the URI directly
        val nameGeneral = backStackEntry.arguments?.read { getStringOrNull("name") }
        
        // Composable content
    }
}

В веб-приложениях глубокие ссылки работают немного иначе: поскольку Compose Multiplatform для Web создаёт одностраничные приложения, нужно поместить все параметры шаблона URI глубокой ссылки во фрагмент URL (после символа #) и убедиться, что все параметры закодированы для URL.

Метод backStackEntry.toRoute() по-прежнему можно использовать для анализа параметров, если фрагмент URL соответствует правилам для шаблонов URI. Подробнее о доступе к URL и его анализе в веб-приложении, а также об особенностях навигации в браузере см. в разделе Поддержка навигации браузера в веб-приложениях.

composable<DeepLinkScreen>(
        deepLinks = listOf(
            // For the default Compose Multiplatform setup, localhost:8080
            // is the local dev endpoint that runs with the wasmJsBrowserDevelopmentRun Gradle task
            navDeepLink { uriPattern = "localhost:8080/#dlscreen%2F{name}" },
        )
    ) { ... }

Объявление синглтона со слушателем URI

В commonMain объявите объект-синглтон на верхнем уровне:

object ExternalUriHandler {
    // Storage for when a URI arrives before the listener is set up
    private var cached: String? = null
    
    var listener: ((uri: String) -> Unit)? = null
        set(value) {
            field = value
            if (value != null) {
                // When a listener is set and `cached` is not empty,
                // immediately invoke the listener with the cached URI
                cached?.let { value.invoke(it) }
                cached = null
            }
        }

    // When a new URI arrives, cache it.
    // If the listener is already set, invoke it and clear the cache immediately.
    fun onNewUri(uri: String) {
        cached = uri
        listener?.let {
            it.invoke(uri)
            cached = null
        }
    }
}

Реализация платформенных вызовов синглтона

Для настольной JVM и iOS необходимо явно передать URI, полученный от системы.

В jvmMain/.../main.kt разберите аргументы командной строки для каждой необходимой операционной системы и передайте полученный URI синглтону:

// Import the singleton
import org.company.app.ExternalUriHandler

fun main() {
    if(System.getProperty("os.name").indexOf("Mac") > -1) {
        Desktop.getDesktop().setOpenURIHandler { uri ->
            ExternalUriHandler.onNewUri(uri.uri.toString())
        }
    }
    else {
        ExternalUriHandler.onNewUri(args.getOrNull(0).toString())
    }

    application {
         // ...
    }
}

Для iOS добавьте в код Swift вариант application(), обрабатывающий входящие URI:

// Imports the KMP module to access the singleton
import SharedUI

func application(
    _ application: UIApplication,
    open uri: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    // Sends the full URI on to the singleton
    ExternalUriHandler.shared.onNewUri(uri: uri.absoluteString)    
        return true
    }

Настройка слушателя

Для настройки слушателя и его очистки после завершения работы композируемой функции можно использовать DisposableEffect(Unit). Например:

internal fun App(navController: NavHostController = rememberNavController()) = AppTheme {

    // The effect is produced only once, as `Unit` never changes
    DisposableEffect(Unit) {
        // Sets up the listener to call `NavController.navigate()`
        // for the composable that has a matching `navDeepLink` listed
        ExternalUriHandler.listener = { uri ->
            navController.navigate(NavUri(uri))
        }
        // Removes the listener when the composable is no longer active
        onDispose {
            ExternalUriHandler.listener = null
        }
    }

    // Reusing the example from earlier in this article
    NavHost(
        navController = navController,
        startDestination = FirstScreen
    ) {
        // ...

        composable<DeepLinkScreen>(
            deepLinks = listOf(
                navDeepLink { uriPattern = "$firstBasePath?name={name}" },
                navDeepLink { uriPattern = "demo://example2.com/name={name}" },
            )
        ) {
            // Composable content
        }
    }
}