Wysyłanie prostych danych do innych aplikacji

Android używa intencji i powiązanych z nimi dodatków, aby umożliwić użytkownikom szybkie i łatwe udostępnianie informacji za pomocą ulubionych aplikacji.

Android udostępnia 2 sposoby udostępniania danych między aplikacjami:

• Arkusz udostępniania w Androidzie jest przeznaczony głównie do wysyłania treści poza aplikację lub bezpośrednio do innego użytkownika. Na przykład udostępnianie adresu URL znajomemu.
• Rozwiązanie do rozpoznawania intencji w Androidzie najlepiej sprawdza się w przypadku przekazywania danych do następnego etapu dobrze zdefiniowanego zadania. Na przykład otwieranie pliku PDF z poziomu aplikacji i umożliwianie użytkownikom wybrania preferowanej przeglądarki.

Podczas tworzenia intencji określasz działanie, które ma ona wykonać. Android używa działania ACTION_SENDdo wysyłania danych z jednej aktywności do drugiej, nawet w ramach różnych procesów. Musisz określić dane i ich typ. System automatycznie identyfikuje zgodne aktywności, które mogą otrzymywać dane, i wyświetla je użytkownikowi. W przypadku komponentu rozpoznawania intencji, jeśli tylko jedna aktywność może obsłużyć intencję, ta aktywność jest natychmiast uruchamiana.

Dlaczego warto korzystać z arkusza udostępniania w Androidzie

Zdecydowanie zalecamy korzystanie z arkusza udostępniania w Androidzie, aby zapewnić użytkownikom spójność w różnych aplikacjach. Nie wyświetlaj własnej listy miejsc docelowych udostępniania ani nie twórz własnych wariantów arkusza udostępniania.

Arkusz udostępniania w Androidzie umożliwia użytkownikom udostępnianie informacji odpowiedniej osobie za pomocą odpowiednich sugestii aplikacji – wszystko to jednym kliknięciem. Arkusz udostępniania może sugerować miejsca docelowe niedostępne dla rozwiązań niestandardowych i używa spójnego rankingu. Wynika to z faktu, że arkusz udostępniania może uwzględniać informacje o aktywności w aplikacji i aktywności użytkownika, które są dostępne tylko dla systemu.

Arkusz udostępniania w Androidzie ma też wiele przydatnych funkcji dla deweloperów. Możesz na przykład:

• Sprawdzanie, kiedy i gdzie użytkownicy udostępniają treści
• Dodawanie niestandardowych ChooserTarget i celów aplikacji
• Wyświetlanie podglądu treści w formacie tekstu sformatowanego od Androida 10 (poziom interfejsu API 29)
• Wykluczanie elementów docelowych pasujących do określonych nazw komponentów

Korzystanie z arkusza udostępniania w Androidzie

W przypadku wszystkich typów udostępniania utwórz intencję i ustaw jej działanie na Intent.ACTION_SEND. Aby wyświetlić arkusz udostępniania w Androidzie, wywołaj funkcję Intent.createChooser(), przekazując do niej obiekt Intent. Zwraca wersję intencji, która zawsze wyświetla arkusz udostępniania w Androidzie.

Wysyłanie treści tekstowych

Najprostszym i najczęstszym zastosowaniem arkusza udostępniania w Androidzie jest wysyłanie treści tekstowych z jednej aktywności do drugiej. Na przykład większość przeglądarek może udostępniać adres URL aktualnie wyświetlanej strony jako tekst innej aplikacji. Jest to przydatne do udostępniania artykułu lub witryny znajomym za pomocą poczty e-mail lub mediów społecznościowych. Oto przykład:

fun shareText(context: Context) {
    val sendIntent: Intent = Intent().apply {
        action = ACTION_SEND
        putExtra(Intent.EXTRA_TEXT, "This is my text to send.")
        type = "text/plain"
    }

    val shareIntent = Intent.createChooser(sendIntent, null)
    context.startActivity(shareIntent)
}
SharesheetSnippets.kt

Opcjonalnie możesz dodać dodatkowe informacje, np. odbiorców e-maila (EXTRA_EMAIL,EXTRA_CC,EXTRA_BCC), temat e-maila (EXTRA_SUBJECT) itp.

Uwaga: niektóre aplikacje do obsługi poczty e-mail, np. Gmail, oczekują znaku String[] w przypadku dodatków takich jak EXTRA_EMAIL i EXTRA_CC. Użyj putExtra(String, String[]) aby dodać je do intencji.

Wysyłanie treści binarnych

Udostępniaj dane binarne za pomocą działania ACTION_SEND. Ustaw odpowiedni typ MIME i umieść identyfikator URI danych w dodatkowym polu EXTRA_STREAM, jak pokazano w tym przykładzie. Jest to powszechnie używane do udostępniania obrazów, ale można go używać do udostępniania dowolnego rodzaju treści binarnych.

fun shareBinaryContent(context: Context) {
    val shareIntent: Intent = Intent().apply {
        action = ACTION_SEND
        // Example: content://com.google.android.apps.photos.contentprovider/...
        val imageUri: Uri =
            Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/1")
        putExtra(Intent.EXTRA_STREAM, imageUri)
        type = "image/jpeg"
    }
    context.startActivity(Intent.createChooser(shareIntent, null))
}
SharesheetSnippets.kt

Aplikacja odbierająca musi mieć uprawnienia dostępu do danych, na które wskazuje Uri. Możesz to zrobić na 2 sposoby:

• Przechowuj dane w swoim ContentProvider, upewniając się, że inne aplikacje mają odpowiednie uprawnienia dostępu do Twojego dostawcy. Preferowanym mechanizmem przyznawania dostępu jest używanie uprawnień do poszczególnych identyfikatorów URI, które są tymczasowe i przyznają dostęp tylko aplikacji odbierającej. Łatwym sposobem na utworzenie elementu ContentProvider takiego jak ten jest użycie klasy pomocniczej FileProvider.
• Użyj systemu MediaStore. MediaStore jest przeznaczony głównie dla typów MIME plików wideo, audio i obrazów. Jednak od Androida 3.0 (API na poziomie 11) może on też przechowywać typy inne niż multimedia. Więcej informacji znajdziesz w sekcji MediaStore.Files. Pliki można wstawiać do elementu MediaStore za pomocą funkcji scanFile(), po czym do podanego wywołania zwrotnego onScanCompleted() przekazywany jest obiekt content:// w stylu Uri odpowiedni do udostępniania. Pamiętaj, że po dodaniu do systemu MediaStore treści są dostępne dla każdej aplikacji na urządzeniu.

Używaj odpowiedniego typu MIME

Podaj najbardziej szczegółowy typ MIME dostępny dla przesyłanych danych. Na przykład podczas udostępniania zwykłego tekstu użyj text/plain. Oto kilka typowych typów MIME podczas wysyłania prostych danych na Androidzie:

Więcej informacji o typach MIME znajdziesz w oficjalnym rejestrze typów MIME IANA.

W zależności od podanego typu MIME arkusz udostępniania w Androidzie może wyświetlać podgląd treści. Niektóre funkcje w wersji przedpremierowej są dostępne tylko w przypadku określonych typów.

Udostępnianie wielu treści

Aby udostępnić wiele treści, użyj działania ACTION_SEND_MULTIPLE wraz z listą adresów URI wskazujących treści. Typ MIME zależy od rodzaju udostępnianych treści. Jeśli na przykład udostępniasz 3 obrazy JPEG, użyj typu "image/jpg". W przypadku mieszanki typów obrazów użyj symbolu "image/*", aby dopasować aktywność, która obsługuje dowolny typ obrazu. Chociaż można udostępniać różne typy plików, zdecydowanie odradzamy takie działanie, ponieważ odbiorca nie będzie wiedzieć, co ma zostać wysłane. Jeśli musisz wysłać kilka typów, użyj "*/*". To aplikacja odbierająca musi przeanalizować i przetworzyć Twoje dane. Oto przykład:

fun shareMultiple(context: Context) {
    val imageUris: ArrayList<Uri> = arrayListOf(
        Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/1"),
        Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/2")
    )

    val shareIntent = Intent().apply {
        action = Intent.ACTION_SEND_MULTIPLE
        putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris)
        type = "image/*"
    }
    context.startActivity(Intent.createChooser(shareIntent, null))
}
SharesheetSnippets.kt

Upewnij się, że podane obiekty Uri wskazują dane, do których aplikacja odbierająca ma dostęp.

Dodawanie szczegółowych treści do podglądów tekstu

Począwszy od Androida 10 (interfejs API na poziomie 29), arkusz udostępniania w Androidzie wyświetla podgląd udostępnianego tekstu. W niektórych przypadkach udostępniany tekst może być trudny do zrozumienia. Zastanów się nad udostępnieniem skomplikowanego adresu URL, np. https://www.google.com/search?ei=2rRVXcLkJajM0PEPoLy7oA4. Bardziej szczegółowy podgląd może uspokoić użytkowników, że wiedzą, co jest udostępniane.

Jeśli wyświetlasz podgląd tekstu, możesz ustawić tytuł, miniaturę lub oba te elementy. Dodaj opis do elementu Intent.EXTRA_TITLE przed wywołaniem elementu Intent.createChooser() i dodaj odpowiednią miniaturę za pomocą elementu ClipData.

Uwaga: identyfikator URI treści obrazu jest podawany z FileProvider, zwykle ze skonfigurowanego <cache-path>. Więcej informacji znajdziesz w artykule Udostępnianie plików. Upewnij się, że arkusz udostępniania ma odpowiednie uprawnienia do odczytywania obrazów, których chcesz użyć jako miniatur. Więcej informacji znajdziesz w sekcji Intent.FLAG_GRANT_READ_URI_PERMISSION.

Oto przykład:

fun richContentToTextPreviewShares(context: Context) {
    val share = Intent.createChooser(
        Intent().apply {
            action = ACTION_SEND
            putExtra(Intent.EXTRA_TEXT, "https://developer.android.com/training/sharing/")

            // (Optional) Here you're setting the title of the content
            putExtra(Intent.EXTRA_TITLE, "Introducing content previews")

            // (Optional) Here you're passing a content URI to an image to be displayed
            data =
                Uri.parse("content://com.google.android.apps.photos.contentprovider/0/1/mediakey/A123456789")
            flags = Intent.FLAG_GRANT_READ_URI_PERMISSION
        },
        null
    )
    context.startActivity(share)
}
SharesheetSnippets.kt

Podgląd wygląda mniej więcej tak:

Dodawanie działań niestandardowych do arkusza udostępniania

Zrzut ekranu z niestandardowymi działaniami na arkuszu udostępniania w Androidzie.

Na Androidzie 14 (poziom interfejsu API 34) i nowszym aplikacje mogą dodawać niestandardowe działania do arkusza udostępniania w Androidzie. Niestandardowe działania są wyświetlane jako małe ikony działań u góry arkusza udostępniania w Androidzie, a aplikacje mogą określić dowolne Intent jako działanie wywoływane po kliknięciu ikony.

Aby dodać działania niestandardowe na arkuszu udostępniania w Androidzie, najpierw utwórz element ChooserAction z elementem ChooserAction.Builder. Możesz określić PendingIntent jako działanie wywoływane po kliknięciu ikony. Utwórz tablicę zawierającą wszystkie działania niestandardowe i określ ją jako EXTRA_CHOOSER_CUSTOM_ACTIONS udostępniania Intent.

fun sharesheetCustomActions(context: Context, previewText: String) {
    val sendIntent = Intent(ACTION_SEND)
        .setType("text/plain")
        .putExtra(Intent.EXTRA_TEXT, previewText)
    val shareIntent = Intent.createChooser(sendIntent, null)
    val customActions = arrayOf(
        ChooserAction.Builder(
            Icon.createWithResource(context, R.drawable.ic_logo),
            "Custom",
            PendingIntent.getBroadcast(
                context,
                1,
                Intent(Intent.ACTION_VIEW),
                PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_CANCEL_CURRENT
            )
        ).build()
    )
    shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, customActions)
    context.startActivity(shareIntent)
}
SharesheetSnippets.kt

Dodawanie niestandardowych miejsc docelowych

Arkusz udostępniania na Androidzie umożliwia określenie maksymalnie 2 obiektów ChooserTarget, które są wyświetlane przed skrótami udostępniania i celami wyboru wczytanymi z ChooserTargetServices. Możesz też określić maksymalnie 2 intencje wskazujące działania, które są wymienione przed sugestiami aplikacji:

Dodaj Intent.EXTRA_CHOOSER_TARGETS i Intent.EXTRA_INITIAL_INTENTS do intencji udostępniania po wywołaniu Intent.createChooser():

val share = Intent.createChooser(shareIntent, null).apply {
    putExtra(
        Intent.EXTRA_CHOOSER_TARGETS,
        arrayOf(chooserTargetJessica, chooserTargetSpyros)
    )
    putExtra(
        Intent.EXTRA_INITIAL_INTENTS,
        arrayOf(intentTargetNearbyShare, intentTargetMaps)
    )
}
SharesheetSnippets.kt

Korzystaj z tej funkcji z rozwagą. Każdy dodany przez Ciebie niestandardowy Intent i ChooserTarget zmniejsza liczbę sugerowaną przez system. Zwykle odradzamy dodawanie celów niestandardowych. Typowym przykładem dodania Intent.EXTRA_INITIAL_INTENTS jest udostępnienie dodatkowych działań, które użytkownicy mogą wykonać w przypadku udostępnionych treści. Na przykład użytkownik udostępnia obrazy, a Intent.EXTRA_INITIAL_INTENTS umożliwia mu wysłanie linku. Typowym przykładem dodania Intent.EXTRA_CHOOSER_TARGETS jest wyświetlanie odpowiednich osób lub urządzeń, które obsługuje Twoja aplikacja.

Wykluczanie określonych celów według komponentu

Możesz wykluczyć konkretne miejsca docelowe, podając Intent.EXTRA_EXCLUDE_COMPONENTS. Rób to tylko w przypadku usuwania miejsc docelowych, nad którymi masz kontrolę. Częstym przypadkiem użycia jest ukrywanie celów udostępniania aplikacji, gdy użytkownicy udostępniają treści z poziomu aplikacji, ponieważ prawdopodobnie chcą udostępnić je poza nią.

Dodaj Intent.EXTRA_EXCLUDE_COMPONENTS do intencji po wywołaniu funkcji Intent.createChooser():

fun excludeSpecificTargets(context: Context) {
    val share = Intent.createChooser(Intent(ACTION_SEND), null).apply {
        // Only use for components you have control over
        val excludedComponentNames =
            arrayOf(ComponentName("com.example.android", "ExampleClass"))
        putExtra(Intent.EXTRA_EXCLUDE_COMPONENTS, excludedComponentNames)
    }
    context.startActivity(share)
}
SharesheetSnippets.kt

Informacje o udostępnianiu

Warto wiedzieć, kiedy użytkownicy udostępniają treści i jakie wybierają miejsce docelowe. Arkusz udostępniania w Androidzie umożliwia uzyskanie tych informacji przez podanie ComponentName wybranych przez użytkowników za pomocą IntentSender.

Najpierw utwórz PendingIntent dla BroadcastReceiver i podaj jego IntentSender w Intent.createChooser():

fun infoAboutSharing(context: Context, requestCode: Int) {
    var share = Intent(ACTION_SEND)
    // ...
    val pi = PendingIntent.getBroadcast(
        context, requestCode,
        Intent(context, ShareBroadcastReceiver::class.java),
        PendingIntent.FLAG_MUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
    )
    share = Intent.createChooser(share, null, pi.intentSender)
    context.startActivity(share)
}
SharesheetSnippets.kt

Odbierz wywołanie zwrotne w MyBroadcastReceiver i sprawdź w Intent.EXTRA_CHOOSER_RESULT:

override fun onReceive(context: Context?, intent: Intent) {
    val TAG = ShareBroadcastReceiver::class.simpleName
    val chooserResult: ChooserResult? = IntentCompat.getParcelableExtra(
        intent,
        Intent.EXTRA_CHOOSER_RESULT,
        ChooserResult::class.java,
    )
    chooserResult?.let {
        Log.i(TAG,
            "Share callback: isShortcut: ${it.isShortcut}, type: ${typeToString(it.type)}, componentName: ${it.selectedComponent}",
        )
    } ?: Log.i(TAG, "chooserResult is null")
}
ShareBroadcastReceiver.kt

Dodawanie działań niestandardowych do arkusza udostępniania

Na Androidzie 14 (poziom interfejsu API 34) i nowszym aplikacje mogą dodawać niestandardowe działania do arkusza udostępniania w Androidzie. Utwórz ChooserAction za pomocą ChooserAction.Builder. Możesz określić PendingIntent jako działanie wywoływane po kliknięciu ikony. Utwórz tablicę zawierającą wszystkie działania niestandardowe i określ ją jako EXTRA_CHOOSER_CUSTOM_ACTIONS udostępniania Intent.

fun customActions(context: Context, text: String) {
    val sendIntent = Intent(ACTION_SEND)
        .setType("text/plain")
        .putExtra(Intent.EXTRA_TEXT, text)
    val shareIntent = Intent.createChooser(sendIntent, null)
    val customActions = arrayOf(
        ChooserAction.Builder(
            Icon.createWithResource(context, R.drawable.ic_logo),
            "Custom",
            PendingIntent.getBroadcast(
                context,
                1,
                Intent(Intent.ACTION_VIEW),
                PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_CANCEL_CURRENT
            )
        ).build()
    )
    shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, customActions)
    context.startActivity(shareIntent)
}
SharesheetSnippets.kt

Używanie narzędzia do rozwiązywania intencji w Androidzie

Zrzut ekranu narzędzia do rozwiązywania intencji ACTION_SEND.

Rozwiązanie Android Intent Resolver najlepiej sprawdza się w przypadku wysyłania danych do innej aplikacji w ramach dobrze zdefiniowanego przepływu zadań.

Aby użyć narzędzia do rozwiązywania intencji w Androidzie, utwórz intencję i dodaj dodatkowe informacje, tak jak w przypadku wywoływania arkusza udostępniania w Androidzie. Nie dzwoń pod numer Intent.createChooser().

Jeśli jest zainstalowanych kilka aplikacji z filtrami, które pasują do ACTION_SEND i typu MIME, system wyświetla okno dialogowe z prośbą o wybór, czyli rozwiązywanie intencji, które umożliwia użytkownikowi wybranie aplikacji, do której ma zostać udostępniony plik. Jeśli pasuje tylko 1 aplikacja, zostanie ona uruchomiona.

Oto przykład użycia narzędzia do rozpoznawania intencji w Androidzie do wysyłania tekstu:

fun intentResolver(context: Context) {
    val sendIntent: Intent = Intent().apply {
        action = ACTION_SEND
        putExtra(Intent.EXTRA_TEXT, "This is my text to send.")
        type = "text/plain"
    }
    context.startActivity(sendIntent)
}
SharesheetSnippets.kt

Więcej informacji

Więcej informacji o wysyłaniu danych znajdziesz w artykule Intencje i filtry intencji.