Wysyłanie prostych danych do innych aplikacji

Android wykorzystuje intencje i powiązane z nimi dodatki, aby umożliwić użytkownikom szybkie i łatwe udostępnianie informacji w ulubionych aplikacjach.

Android umożliwia użytkownikom udostępnianie danych między aplikacjami na 2 sposoby:

• Arkusz udostępniania na Androida służy przede wszystkim do wysyłania treści poza aplikację lub bezpośrednio do innego użytkownika. na przykład przez udostępnienie adresu URL znajomemu.
• Rozpoznawanie intencji w Androidzie najlepiej nadaje się do przekazywania danych do następnego etapu dobrze zdefiniowanego zadania. Dotyczy to na przykład otwierania pliku PDF z aplikacji i umożliwiania użytkownikom wyboru preferowanej gogli.

Podczas tworzenia intencji określasz działanie, które ma ona wykonać. Android używa działania ACTION_SEND do wysyłania danych z jednej aktywności do drugiej, nawet poza granicami procesów. Musisz określić dane i ich typ. System automatycznie rozpoznaje zgodne działania, które mogą otrzymywać dane, i wyświetla je użytkownikowi. Jeśli w przypadku resolvera intencji tylko jedno działanie może obsłużyć intencję, rozpocznie się ono natychmiast.

Dlaczego warto korzystać z arkusza udostępniania Androida

Zdecydowanie zalecamy korzystanie z arkusza udostępniania Androida, aby zapewnić użytkownikom spójność między aplikacjami. Nie wyświetlaj listy docelowych udostępniania swojej aplikacji ani nie twórz własnych odmian arkusza udostępniania.

Android Sharesheet pozwala użytkownikom jednym kliknięciem udostępniać informacje odpowiednim osobom wraz z sugestiami aplikacji. Arkusz udostępniania może sugerować cele niedostępne dla rozwiązań niestandardowych i stosuje spójny ranking. Dzieje się tak, ponieważ arkusz udostępniania może uwzględniać informacje o aktywności użytkowników i aplikacji, które są dostępne tylko dla systemu.

Arkusz udostępniania Androida ma też wiele przydatnych funkcji dla programistów. Na przykład możesz:

• Dowiedz się, kiedy i gdzie użytkownicy udostępnią coś
• Dodawanie niestandardowego celu ChooserTarget i celów aplikacji
• Wyświetlanie podglądu sformatowanego tekstu już w Androidzie 10 (poziom API 29)
• Wyklucz cele pasujące 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 Androida, wywołaj Intent.createChooser() i przekaż go jako obiekt Intent. Zwraca wersję intencji, w której zawsze wyświetla się arkusz udostępniania Androida.

Wyślij treść tekstową

Najprostszym i najpowszechniejszym zastosowaniem arkusza udostępniania Androida jest przesyłanie treści tekstowych z jednej aktywności do drugiej. Na przykład większość przeglądarek może udostępniać innym aplikacjom adres URL wyświetlanej strony w postaci tekstu. Przydaje się to, gdy chcesz udostępnić artykuł lub stronę znajomym przez e-mail albo w sieci społecznościowej. Oto przykład:

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)

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ć dodatki zawierające więcej informacji, takich jak odbiorcy e-maila (EXTRA_EMAIL, EXTRA_CC, EXTRA_BCC), temat e-maila (EXTRA_SUBJECT itp.).

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

Wysyłaj treści binarne

Udostępnij dane binarne za pomocą działania ACTION_SEND. Ustaw odpowiedni typ MIME i umieść dane w dodatkowym EXTRA_STREAM jako identyfikator URI, jak pokazano w przykładzie poniżej. Zwykle jest stosowany do udostępniania obrazu, ale można go też stosować do udostępniania dowolnych treści binarnych.

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))

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, na które wskazuje Uri. Możesz to zrobić na 2 sposoby:

• Przechowuj dane w swoim zasobniku ContentProvider, aby mieć pewność, że inne aplikacje mają odpowiednie uprawnienia dostępu do Twojego dostawcy. Preferowanym mechanizmem przyznawania dostępu jest używanie uprawnień na podstawie identyfikatora URI, które są tymczasowe i dają dostęp tylko do aplikacji odbierającej. Prostym sposobem na utworzenie tego typu obiektu ContentProvider jest użycie klasy pomocniczej FileProvider.
• Użyj systemu MediaStore. MediaStore dotyczy głównie typów MIME plików wideo, audio i graficznych. Jednak już od Androida 3.0 (poziom interfejsu API 11) można w nim zapisywać typy inne niż multimedia. Więcej informacji: MediaStore.Files. Pliki można wstawiać do MediaStore za pomocą polecenia scanFile(). Następnie do podanego wywołania zwrotnego onScanCompleted() przekazywana jest kreacja Uri w stylu content://, która nadaje się do udostępniania. Pamiętaj, że po dodaniu do systemu MediaStore treść jest dostępna dla każdej aplikacji na urządzeniu.

Używanie odpowiedniego typu MIME

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

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

W zależności od wybranego typu MIME w arkuszu udostępniania Androida może pojawić się podgląd treści. Niektóre funkcje w wersji testowej są dostępne tylko w przypadku określonych typów.

Udostępnianie wielu elementów treści

Aby udostępnić wiele treści, użyj działania ACTION_SEND_MULTIPLE wraz z listą identyfikatorów URI wskazujących te treści. Typ MIME zależy od kombinacji udostępnianych treści. Jeśli na przykład udostępniasz 3 obrazy JPEG, użyj typu "image/jpg". W przypadku kombinacji typów obrazów użyj właściwości "image/*", aby dopasować działanie, które obsługuje dowolny typ obrazu. Chociaż można udostępniać różne rodzaje wiadomości, zdecydowanie to odradzamy, ponieważ odbiorca nie do końca wie, co ma wysłać. Jeśli chcesz przesłać kilka rodzajów danych, użyj "*/*". Analizowanie i przetwarzanie danych zależy od aplikacji odbierającej. Oto przykład:

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))

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 podane obiekty Uri wskazują dane, do których aplikacja odbierająca ma dostęp.

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

Począwszy od Androida 10 (poziom interfejsu API 29) arkusz udostępniania Androida pokazuje podgląd udostępnianego tekstu. W niektórych przypadkach udostępniany tekst może być trudny do zrozumienia. Warto udostępnić złożony adres URL, np. https://www.google.com/search?ei=2rRVXcLkJajM0PEPoLy7oA4. Bogatszy podgląd pozwoli użytkownikom zorientować się, co są udostępniane.

Jeśli wyświetlasz podgląd tekstu, możesz ustawić tytuł, obraz miniatury lub oba te elementy. Dodaj opis do Intent.EXTRA_TITLE przed nawiązaniem połączenia Intent.createChooser() oraz dodaj odpowiednią miniaturę za pomocą ClipData.

Uwaga: identyfikator URI zawartości obrazu jest dostarczany z FileProvider, zwykle ze skonfigurowanego identyfikatora <cache-path>. Więcej informacji znajdziesz w artykule Udostępnianie plików. Pamiętaj, aby przyznać arkuszowi udostępniania uprawnienia do odczytu dowolnego obrazu, którego chcesz użyć jako miniatury. Więcej informacji znajdziesz tutaj: Intent.FLAG_GRANT_READ_URI_PERMISSION.

Oto przykład:

 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)

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

Zrzut ekranu pokazujący działania niestandardowe w arkuszu udostępniania Androida.

Na Androidzie 14 (poziom interfejsu API 34) i nowszym 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 Androida. Aplikacje mogą określać dowolny Intent jako działanie wywoływane po kliknięciu ikony.

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

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)

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);

Dodaj cele niestandardowe

Arkusz udostępniania Androida pozwala określić maksymalnie 2 obiekty ChooserTarget, które będą wyświetlane przed skrótami udostępniania i celami selektora ładowanymi 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 funkcji Intent.createChooser():

val share = Intent.createChooser(myShareIntent, null).apply {
    putExtra(Intent.EXTRA_CHOOSER_TARGETS, myChooserTargetArray)
    putExtra(Intent.EXTRA_INITIAL_INTENTS, myInitialIntentArray)
}

Intent shareIntent = Intent.createChooser(sendIntent, null);
share.putExtra(Intent.EXTRA_CHOOSER_TARGETS, myChooserTargetArray);
share.putExtra(Intent.EXTRA_INITIAL_INTENTS, myInitialIntentArray);

Używaj tej funkcji ostrożnie. Dodanie niestandardowych wartości Intent i ChooserTarget zmniejsza liczbę sugerowaną przez system. Zasadniczo odradzamy dodawanie celów niestandardowych. Typowym przykładem dodawania właściwości Intent.EXTRA_INITIAL_INTENTS jest udostępnienie użytkownikom dodatkowych działań, które mogą wykonywać w przypadku udostępnionych treści. Na przykład użytkownik udostępnia obrazy, a usługa Intent.EXTRA_INITIAL_INTENTS umożliwia mu wysłanie linku. Typowym przykładem dodawania właściwości Intent.EXTRA_CHOOSER_TARGETS jest wyświetlanie odpowiednich osób lub urządzeń dostępnych w aplikacji.

Wyklucz konkretne cele według komponentu

Możesz wykluczyć określone cele, podając Intent.EXTRA_EXCLUDE_COMPONENTS. Pozwala to usuwać cele, nad którymi masz kontrolę. Typowym przypadkiem użycia jest ukrywanie celów udostępniania, gdy użytkownicy udostępniają treści z poziomu aplikacji, ponieważ istnieje duże prawdopodobieństwo, że będą oni udostępniać je poza nią.

Dodaj element Intent.EXTRA_EXCLUDE_COMPONENTS do intencji po wywołaniu usługi Intent.createChooser():

  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)
  }

  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);

Informacje o udostępnianiu

Warto wiedzieć, kiedy użytkownicy udostępniają treści i jakie cele wybierają. Aby uzyskać te informacje, możesz użyć arkusza udostępniania Androida, podając ComponentName wybranych przez użytkowników celów za pomocą pola IntentSender.

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

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)

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 połączenie zwrotne w MyBroadcastReceiver i sprawdź w Intent.EXTRA_CHOSEN_COMPONENT:

override fun onReceive(context: Context, intent: Intent) {
  ...
  val clickedComponent : ComponentName = intent.getParcelableExtra(EXTRA_CHOSEN_COMPONENT);
}

@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 nowszym aplikacje mogą dodawać działania niestandardowe do arkusza udostępniania Androida. Utwórz ChooserAction z: ChooserAction.Builder. Możesz określić PendingIntent jako działanie wywoływane po kliknięciu ikony. Utwórz tablicę zawierającą wszystkie Twoje działania niestandardowe i określ ją jako EXTRA_CHOOSER_CUSTOM_ACTIONS udziału Intent.

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)

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żyj resolvera intencji Androida

Zrzut ekranu przedstawiający resolver intencji ACTION_SEND.

Rozpoznawanie intencji w Androidzie najlepiej sprawdza się podczas wysyłania danych do innej aplikacji w ramach dobrze zdefiniowanego przepływu zadań.

Aby użyć resolvera Androida, utwórz intencję i dodaj elementy dodatkowe, tak jak w przypadku wywoływania arkusza udostępniania Androida. Nie dzwonij jednak pod Intent.createChooser().

Jeśli masz kilka zainstalowanych aplikacji z filtrami, które pasują do filtra ACTION_SEND i typu MIME, system wyświetla okno ujednoznacznienia nazywane mechanizmem rozpoznawania intencji, który umożliwia użytkownikowi wybranie elementu docelowego, któremu ma zostać udostępniona treść. W przypadku dopasowania pojedyncza aplikacja jest uruchamiana.

Oto przykład użycia resolvera intencji w Androidzie do wysyłania tekstu:

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

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 Intencje i filtry intencji.