Android korzysta z intencji i powiązanych z nimi dodatków, aby umożliwić użytkownikom szybkie i łatwe udostępnianie informacji za pomocą ulubionych aplikacji.
Android zapewnia użytkownikom 2 sposoby udostępniania danych między aplikacjami:
- Służy on przede wszystkim do wysyłania treści poza aplikację lub bezpośrednio do innego użytkownika. Dotyczy to na przykład udostępniania adresu URL znajomemu.
- Narzędzie do rozpoznawania intencji Androida najlepiej nadaje się do przekazywania danych do następnego etapu dobrze zdefiniowanego zadania. Dotyczy to na przykład otwierania pliku PDF w aplikacji i umożliwiania użytkownikom wybrania preferowanych gogli.
Podczas tworzenia intencji określa się działanie, jakie ma ona wykonać.
Android używa działania ACTION_SEND
do wysyłania danych z jednej aktywności do drugiej, nawet przez granice procesów. Musisz określić dane i ich typ. System automatycznie identyfikuje zgodne działania, które mogą otrzymywać dane, i wyświetla je użytkownikowi. Jeśli tylko jedna aktywność może obsłużyć intencję, działanie to zostanie natychmiast rozpoczęte.
Dlaczego warto korzystać z arkusza udostępniania Androida
Zdecydowanie zalecamy korzystanie z arkusza udostępniania Androida w celu zachowania spójności dla użytkowników we wszystkich aplikacjach. Nie wyświetlaj własnej listy celów udostępniania aplikacji ani nie twórz własnych odmian arkusza kalkulacyjnego.
Za pomocą arkusza udostępniania na Androidzie użytkownicy mogą dzielić się informacjami z odpowiednimi sugestiami aplikacji za pomocą jednego kliknięcia. Arkusz udostępniania może sugerować cele niedostępne dla rozwiązań niestandardowych i ma spójną pozycję w rankingu. Jest to możliwe, ponieważ arkusz kalkulacyjny może uwzględniać informacje o aktywności w aplikacjach i użytkownikach, które są dostępne tylko dla systemu.
Arkusze udostępniania na Androida mają też wiele przydatnych funkcji dla programistów. Na przykład możesz wykonać te czynności:
- Dowiedz się, kiedy użytkownicy wykonali udostępnianie i gdzie
- Dodawanie niestandardowych celów
ChooserTarget
i celów aplikacji - Udostępnianie podglądu tekstu sformatowanego od Androida 10 (poziom interfejsu API 29)
- Wykluczanie celów pasujących do konkretnych nazw komponentów
Korzystanie z arkusza udostępniania Androida
W przypadku każdego rodzaju udostępniania utwórz intencję i ustaw jej działanie na Intent.ACTION_SEND
.
Aby wyświetlić arkusz udostępniania Androida, wywołaj Intent.createChooser()
i przekaż mu obiekt Intent
.
Zwraca wersję intencji, która zawsze wyświetla arkusz udostępniania Androida.
Wysyłanie treści tekstowej
Najprostszym i najpowszechniejszym zastosowaniem arkusza udostępniania Androida jest przesyłanie treści tekstowej z jednej aktywności do drugiej. Na przykład większość przeglądarek może udostępniać URL aktualnie wyświetlanej strony innej aplikacji jako tekst. Jest to przydatne, gdy udostępniasz artykuł lub stronę znajomym w e-mailach lub w sieciach społecznościowych. Oto przykład:
Kotlin
val sendIntent: Intent = Intent().apply { action = Intent.ACTION_SEND putExtra(Intent.EXTRA_TEXT, "This is my text to send.") type = "text/plain" } val shareIntent = Intent.createChooser(sendIntent, null) startActivity(shareIntent)
Java
Intent sendIntent = new Intent(); sendIntent.setAction(Intent.ACTION_SEND); sendIntent.putExtra(Intent.EXTRA_TEXT, "This is my text to send."); sendIntent.setType("text/plain"); Intent shareIntent = Intent.createChooser(sendIntent, null); startActivity(shareIntent);
Opcjonalnie możesz dodać dodatkowe informacje, np. o odbiorcach e-maili (EXTRA_EMAIL
, EXTRA_CC
, EXTRA_BCC
), temacie e-maila (EXTRA_SUBJECT
) itp.
Uwaga: niektóre aplikacje e-mail, takie jak Gmail, mogą otrzymać String[]
w przypadku dodatków takich jak EXTRA_EMAIL
czy 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 elemencie EXTRA_STREAM
, jak pokazano w przykładzie poniżej.
Tego typu profilu używa się zwykle do udostępniania obrazów, ale można z niego korzystać do udostępniania dowolnych treści binarnych.
Kotlin
val shareIntent: Intent = Intent().apply { action = Intent.ACTION_SEND // Example: content://com.google.android.apps.photos.contentprovider/... putExtra(Intent.EXTRA_STREAM, uriToImage) type = "image/jpeg" } startActivity(Intent.createChooser(shareIntent, null))
Java
Intent shareIntent = new Intent(); shareIntent.setAction(Intent.ACTION_SEND); // Example: content://com.google.android.apps.photos.contentprovider/... shareIntent.putExtra(Intent.EXTRA_STREAM, uriToImage); shareIntent.setType("image/jpeg"); startActivity(Intent.createChooser(shareIntent, null));
Aplikacja odbierająca potrzebuje uprawnień dostępu do danych, do których wskazuje Uri
. Możesz to zrobić na 2 sposoby:
- Przechowuj dane we własnym pliku
ContentProvider
, upewniając się, że inne aplikacje mają odpowiednie uprawnienia dostępu do dostawcy. Preferowanym mechanizmem zapewniania dostępu jest użycie uprawnień powiązanych z identyfikatorem URI, które są tymczasowe i przyznają dostęp tylko aplikacji odbierającej dane. Prostym sposobem na utworzenieContentProvider
, takiego jak ten, jest użycie klasy pomocniczejFileProvider
. - Użyj systemu
MediaStore
.MediaStore
służy przede wszystkim do obsługi typów MIME plików wideo, audio i obrazów. Jednak od Androida 3.0 (poziom interfejsu API 11) może też przechowywać typy plików innych niż multimedia. Więcej informacji:MediaStore.Files
. Pliki można wstawiać do elementuMediaStore
za pomocąscanFile()
, po czym do podanego wywołania zwrotnegoonScanCompleted()
jest przekazywanyUri
w stylucontent://
odpowiedni do udostępniania. Pamiętaj, że po dodaniu treści do systemuMediaStore
są one dostępne dla każdej aplikacji na urządzeniu.
Używanie odpowiedniego typu MIME
Podaj najbardziej szczegółowy typ MIME dla wysyłanych danych. Na przykład do udostępniania zwykłego tekstu użyj text/plain
. Oto kilka typowych typów MIME używanych podczas wysyłania prostych danych w Androidzie:
Odbiorcy rejestrują się na | Nadawcy wysyłają |
---|---|
text/* |
|
`image/*` |
|
video/* |
|
Obsługiwane rozszerzenia plików | application/pdf |
Więcej informacji o typach MIME znajdziesz w oficjalnym rejestrze IANA.
W zależności od podanego typu MIME arkusz udostępniania Androida może wyświetlać podgląd treści. Niektóre funkcje podglądu są dostępne tylko w przypadku określonych typów.
Udostępnianie wielu elementów treści
Aby udostępnić wiele elementów treści, użyj działania ACTION_SEND_MULTIPLE
w połączeniu z listą identyfikatorów URI wskazujących treść. Typ MIME różni się w zależności od zbioru treści, które udostępniasz. Jeśli na przykład udostępnisz 3 obrazy JPEG, użyj typu "image/jpg"
. W przypadku różnych typów obrazów użyj funkcji "image/*"
, aby dopasować aktywność, która obsługuje obrazy dowolnego typu. Chociaż można przesyłać wiele różnych typów treści, zdecydowanie to odradzamy, ponieważ nie jest jasne dla odbiorcy, co ma być wysłane. Jeśli musisz przesłać wiele typów, użyj właściwości "*/*"
. Analizowanie i przetwarzanie danych
zależy od aplikacji odbierającej. Oto przykład:
Kotlin
val imageUris: ArrayList<Uri> = arrayListOf( // Add your image URIs here imageUri1, imageUri2 ) val shareIntent = Intent().apply { action = Intent.ACTION_SEND_MULTIPLE putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris) type = "image/*" } startActivity(Intent.createChooser(shareIntent, null))
Java
ArrayList<Uri> imageUris = new ArrayList<Uri>(); imageUris.add(imageUri1); // Add your image URIs here imageUris.add(imageUri2); Intent shareIntent = new Intent(); shareIntent.setAction(Intent.ACTION_SEND_MULTIPLE); shareIntent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, imageUris); shareIntent.setType("image/*"); startActivity(Intent.createChooser(shareIntent, null));
Upewnij się, że udostępnione obiekty Uri
wskazują dane, do których może mieć dostęp aplikacja odbierająca.
Dodawanie treści sformatowanej do podglądu tekstu
Od Androida 10 (poziom interfejsu API 29) arkusz udostępniania Androida pokazuje podgląd udostępnianego tekstu. Czasami udostępniany tekst może być trudny do zrozumienia. Rozważ udostępnienie złożonego adresu URL, np. https://www.google.com/search?ei=2rRVXcLkJajM0PEPoLy7oA4
. Bogatszy podgląd zapewni użytkownikom pewną pewność, jakie informacje są udostępniane.
Jeśli wyświetlasz podgląd tekstu, możesz ustawić tytuł, obraz miniatury lub oba te elementy. Zanim zadzwonisz pod numer Intent.createChooser()
, dodaj opis do filmu Intent.EXTRA_TITLE
i dodaj odpowiednią miniaturę w elemencie ClipData
.
Uwaga: identyfikator URI treści obrazu pochodzi z FileProvider
, zwykle ze skonfigurowanego <cache-path>
.
Więcej informacji znajdziesz w artykule Udostępnianie plików. Pamiętaj, aby przyznać w narzędziu Sharesheet uprawnienia do odczytu każdego obrazu, którego chcesz użyć jako miniatury. Więcej informacji: Intent.FLAG_GRANT_READ_URI_PERMISSION
.
Oto przykład:
Kotlin
val share = Intent.createChooser(Intent().apply { action = Intent.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 = contentUri flags = Intent.FLAG_GRANT_READ_URI_PERMISSION }, null) startActivity(share)
Java
Intent sendIntent = new Intent(Intent.ACTION_SEND); sendIntent.putExtra(Intent.EXTRA_TEXT, "https://developer.android.com/training/sharing/"); // (Optional) Here you're setting the title of the content sendIntent.putExtra(Intent.EXTRA_TITLE, "Introducing content previews"); // (Optional) Here you're passing a content URI to an image to be displayed sendIntent.setData(contentUri); sendIntent.setFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION); // Show the Sharesheet startActivity(Intent.createChooser(sendIntent, null));
Podgląd wygląda mniej więcej tak:
Dodawanie działań niestandardowych do arkusza udostępniania
Na Androidzie 14 (poziom interfejsu API 34) i nowszych aplikacje mogą dodawać działania niestandardowe do arkusza udostępniania Androida.
Działania niestandardowe są wyświetlane jako małe ikony działań u góry arkusza udostępniania na Androida, a w aplikacjach można określić dowolne Intent
jako działanie wywoływane po kliknięciu ikony.
Aby dodać działania niestandardowe do arkusza udostępniania Androida, najpierw 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 wskaż ją jako EXTRA_CHOOSER_CUSTOM_ACTIONS
udziału Intent
.
Kotlin
val sendIntent = Intent(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_custom_action), "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)
Java
Intent sendIntent = new Intent(Intent.ACTION_SEND) .setType("text.plain") .putExtra(Intent.EXTRA_TEXT, text); Intent shareIntent = Intent.createChooser(sendIntent, null); ChooserAction[] actions = new ChooserAction[]{ new ChooserAction.Builder( Icon.createWithResource(context, R.drawable.ic_custom_action), "Custom", PendingIntent.getBroadcast( context, 1, new Intent(Intent.ACTION_VIEW), PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_CANCEL_CURRENT ) ).build() }; shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, actions); context.startActivity(shareIntent);
Dodawanie celów niestandardowych
Arkusz udostępniania Androida pozwala określić maksymalnie dwa obiekty ChooserTarget
, które są wyświetlane przed skrótami udostępniania i elementami docelowymi wyboru wczytywanymi z ChooserTargetServices
. Możesz też określić maksymalnie 2 intencje wskazujące działania wymienione przed sugestiami aplikacji:
Dodaj Intent.EXTRA_CHOOSER_TARGETS
i Intent.EXTRA_INITIAL_INTENTS
do intencji udostępniania po wywołaniu Intent.createChooser()
:
Kotlin
val share = Intent.createChooser(myShareIntent, null).apply { putExtra(Intent.EXTRA_CHOOSER_TARGETS, myChooserTargetArray) putExtra(Intent.EXTRA_INITIAL_INTENTS, myInitialIntentArray) }
Java
Intent shareIntent = Intent.createChooser(sendIntent, null); share.putExtra(Intent.EXTRA_CHOOSER_TARGETS, myChooserTargetArray); share.putExtra(Intent.EXTRA_INITIAL_INTENTS, myInitialIntentArray);
Używaj tej funkcji z rozwagą. Każdy dodany niestandardowy element Intent
i ChooserTarget
zmniejsza liczbę sugerowaną przez system. Zasadniczo odradzamy dodawanie celów niestandardowych. Typowym odpowiednim przykładem dodawania właściwości Intent.EXTRA_INITIAL_INTENTS
jest podanie dodatkowych działań, które użytkownicy mogą wykonywać w odniesieniu do udostępnionych treści. Na przykład użytkownik udostępnia obrazy, a Intent.EXTRA_INITIAL_INTENTS
umożliwia mu wysłanie linku. Typowym odpowiednim przykładem zastosowania właściwości Intent.EXTRA_CHOOSER_TARGETS
jest wyświetlanie odpowiednich osób lub urządzeń dostępnych w aplikacji.
Wykluczanie określonych celów według komponentu
Możesz wykluczyć określone cele, podając Intent.EXTRA_EXCLUDE_COMPONENTS
.
Zrób to tylko po to, by usunąć cele, nad którymi masz kontrolę. Częstym przypadkiem użycia jest ukrywanie celów udostępniania w przypadku, gdy użytkownicy udostępniają treści z poziomu aplikacji, ponieważ ich intencje prawdopodobnie będą udostępniać poza aplikacją.
Dodaj użytkownika Intent.EXTRA_EXCLUDE_COMPONENTS
do intencji po połączeniu z numerem Intent.createChooser()
:
Kotlin
val share = Intent.createChooser(Intent(), null).apply { // Only use for components you have control over val excludedComponentNames = arrayOf(ComponentName("com.example.android", "ExampleClass")) putExtra(Intent.EXTRA_EXCLUDE_COMPONENTS, excludedComponentNames) }
Java
Intent shareIntent = Intent.createChooser(new Intent(), null); // Only use for components you have control over ComponentName[] excludedComponentNames = { new ComponentName("com.example.android", "ExampleClass") }; shareIntent.putExtra(Intent.EXTRA_EXCLUDE_COMPONENTS, excludedComponentNames);
Uzyskiwanie informacji o udostępnianiu
Warto wiedzieć, kiedy użytkownicy udostępniają treści i jakie ustawienia wybierają. W arkuszu udostępniania Androida możesz uzyskać te informacje, podając ComponentName
grup docelowych wybranych przez użytkowników za pomocą elementu IntentSender
.
Najpierw utwórz PendingIntent
dla BroadcastReceiver
i podaj jej IntentSender
w Intent.createChooser()
:
Kotlin
var share = Intent(Intent.ACTION_SEND) // ... val pi = PendingIntent.getBroadcast( myContext, requestCode, Intent(myContext, MyBroadcastReceiver::class.java), PendingIntent.FLAG_MUTABLE or PendingIntent.FLAG_UPDATE_CURRENT ) share = Intent.createChooser(share, null, pi.intentSender)
Java
Intent share = new Intent(ACTION_SEND); ... PendingIntent pi = PendingIntent.getBroadcast(myContext, requestCode, new Intent(myContext, MyBroadcastReceiver.class), PendingIntent.FLAG_MUTABLE | PendingIntent.FLAG_UPDATE_CURRENT); share = Intent.createChooser(share, null, pi.getIntentSender());
Odbierz wywołanie zwrotne za MyBroadcastReceiver
i sprawdź w: Intent.EXTRA_CHOSEN_COMPONENT
:
Kotlin
override fun onReceive(context: Context, intent: Intent) { ... val clickedComponent : ComponentName = intent.getParcelableExtra(EXTRA_CHOSEN_COMPONENT); }
Java
@Override public void onReceive(Context context, Intent intent) { ... ComponentName clickedComponent = intent.getParcelableExtra(EXTRA_CHOSEN_COMPONENT); }
Dodawanie działań niestandardowych do arkusza udostępniania
Na Androidzie 14 (poziom interfejsu API 34) i nowszych aplikacje mogą dodawać działania niestandardowe do arkusza udostępniania Androida.
Utwórz ChooserAction
w 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 wskaż ją jako EXTRA_CHOOSER_CUSTOM_ACTIONS
udziału Intent
.
Kotlin
val sendIntent = Intent(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_custom_action), "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)
Java
Intent sendIntent = new Intent(Intent.ACTION_SEND) .setType("text.plain") .putExtra(Intent.EXTRA_TEXT, text); Intent shareIntent = Intent.createChooser(sendIntent, null); ChooserAction[] actions = new ChooserAction[]{ new ChooserAction.Builder( Icon.createWithResource(context, R.drawable.ic_custom_action), "Custom", PendingIntent.getBroadcast( context, 1, new Intent(Intent.ACTION_VIEW), PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_CANCEL_CURRENT ) ).build() }; shareIntent.putExtra(Intent.EXTRA_CHOOSER_CUSTOM_ACTIONS, actions); context.startActivity(shareIntent);
Używanie resolvera intencji Androida
Narzędzie do rozpoznawania intencji Androida najlepiej sprawdza się podczas wysyłania danych do innej aplikacji w ramach dobrze zdefiniowanego przepływu zadań.
Aby użyć narzędzia do rozpoznawania intencji Androida, utwórz intencję i dodaj dodatkowe elementy, tak jak w przypadku wywoływania arkusza udostępniania Androida. Nie wywołuj jednak
wywołania Intent.createChooser()
.
Jeśli jest wiele zainstalowanych aplikacji z filtrami pasującymi do ACTION_SEND
i typu MIME, system wyświetla okno ujednoznacznienia nazywane narzędziem do rozpoznawania zamiarów, które pozwala użytkownikowi wybrać środowisko docelowe do udostępniania. Jeśli określona aplikacja
pasuje do siebie, jest uruchamiana.
Oto przykład użycia narzędzia do rozpoznawania intencji Androida do wysyłania tekstu:
Kotlin
val sendIntent: Intent = Intent().apply { action = Intent.ACTION_SEND putExtra(Intent.EXTRA_TEXT, "This is my text to send.") type = "text/plain" } startActivity(sendIntent)
Java
Intent sendIntent = new Intent(); sendIntent.setAction(Intent.ACTION_SEND); sendIntent.putExtra(Intent.EXTRA_TEXT, "This is my text to send."); sendIntent.setType("text/plain"); startActivity(sendIntent);
Więcej informacji
Więcej informacji o wysyłaniu danych znajdziesz w artykule o intencjach i filtrach intencji.