Udostępnianie zawartości z aplikacji — integrowanie Windows Share

Okno udostępniania systemu Windows to interfejs użytkownika dostarczany przez system, który umożliwia użytkownikom wysyłanie zawartości z Twojej aplikacji do innych aplikacji systemu Windows. W tym przewodniku wyjaśniono, jak zaimplementować kontrakt udostępniania dla spakowanych aplikacji (MSIX), progresywnych Web Apps (PWA) i rozpakowanych aplikacji Win32.

Section Co znajdziesz
Wybieranie podejścia do udostępniania Wybierz odpowiedni zestaw interfejsów API dla aplikacji UWP, klasycznych lub PWA
Implementowanie funkcji udostępniania w aplikacjach UWP DataTransferManager.GetForCurrentView i ShowShareUI
Wdrożenie udostępniania w aplikacjach PWA Integracja interfejsu API programu Web Share
Implementacja udostępniania w aplikacjach klasycznych IDataTransferManagerInteropudostępnianie poszczególnych okien dla WinUI 3, WPF, WinForms
Zdarzenia po stronie źródłowej Obserwuj wybór, ukończenie i anulowanie celu
Najlepsze rozwiązania dotyczące udostępniania Zalecenia dotyczące niezawodnego zachowania po stronie źródła

Wybieranie podejścia do udostępniania

Typ aplikacji Podejście Zestaw interfejsów API
Aplikacje platformy UWP systemu Windows Użyj DataTransferManager.GetForCurrentView i ShowShareUI Windows.ApplicationModel.DataTransfer
Aplikacje klasyczne (WinUI 3, WPF, WinForms) Użyj IDataTransferManagerInterop do udostępniania poszczególnych okien (pakietowane lub niepakietowane) środowisko wykonawcze systemu Windows poprzez współdziałanie z modelem COM
Progresywne aplikacje internetowe (PWA) Użyj interfejsu Web Share API i integracji z systemem Windows Udostępnianie w sieci Web W3C

Implementowanie funkcji Udostępnianie w aplikacjach UWP

Ważna

DataTransferManager.GetForCurrentView i ShowShareUI są obsługiwane tylko w aplikacjach platformy UWP. Aplikacje klasyczne (WinUI 3, WPF lub WinForms — pakietowane lub niepakietowane) muszą używać wzorca IDataTransferManagerInterop przedstawionego w artykule Implementowanie funkcji Udostępnianie dla aplikacji klasycznych.

1. Pobierz obiekt DataTransferManager

W inicjowaniu strony uzyskaj odwołanie do elementu DataTransferManager:

using Windows.ApplicationModel.DataTransfer;

public sealed partial class MainPage : Page
{
    public MainPage()
    {
        this.InitializeComponent();

        DataTransferManager dtm = DataTransferManager.GetForCurrentView();
        dtm.DataRequested += OnDataRequested;
    }
}

2. Wypełnianie pakietu danych

Gdy użytkownik inicjuje udział (na przykład klika przycisk Udostępnij), utwórz obiekt DataPackage z zawartością i metadanymi:

private void OnDataRequested(DataTransferManager sender, DataRequestedEventArgs args)
{
    DataRequest request = args.Request;
    DataPackage data = request.Data;

    // Set a title (required)
    data.Properties.Title = "My shared content";

    // Set content - choose one or more:
    data.SetText("Here's some text to share");

    // For URLs, use SetWebLink to enable rich link previews:
    // data.SetWebLink(new Uri("https://example.com"));

    // For files or images:
    // IStorageItem item = await StorageFile.GetFileFromPathAsync(filePath);
    // data.SetStorageItems(new[] { item });

    // Optional: add description and thumbnail
    data.Properties.Description = "A brief description";
    // data.Properties.Thumbnail = /* RandomAccessStreamReference */;
}

Wskazówka

Jeśli udostępniasz adres URL, użyj SetWebLink (lub SetApplicationLink w przypadku linków głębokich) zamiast SetText. Aplikacje docelowe mogą następnie generować zaawansowane podglądy linków i prawidłowo obsługiwać nawigację, zamiast traktować je jako zwykły tekst.

3. Wyświetl interfejs użytkownika udostępniania

Wywołaj okno udostępniania kliknięciem przycisku lub za pomocą polecenia menu:

private void ShareButton_Click(object sender, RoutedEventArgs e)
{
    // ShowShareUI is a static method on DataTransferManager.
    // The DataRequested handler was registered in step 1.
    DataTransferManager.ShowShareUI();
}

Implementowanie udostępniania dla progresywnych aplikacji internetowych (PWA)

Aplikacje PWA korzystają z interfejsu Web Share API konsorcjum W3C. Upewnij się, że aplikacja PWA ma wymagane właściwości manifestu do integracji z Windows:

{
  "name": "My PWA",
  "short_name": "MyPWA",
  "share_target": {
    "action": "/share",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "files": [
        {
          "name": "media",
          "accept": ["image/*"]
        }
      ]
    }
  }
}

W kodzie JavaScript aplikacji PWA użyj Web Share API:

async function shareContent() {
  if (navigator.share) {
    try {
      await navigator.share({
        title: 'Check this out',
        text: 'Great content',
        url: 'https://example.com/page'
      });
    } catch (err) {
      if (err.name !== 'AbortError') {
        console.error('Share failed:', err);
      }
    }
  }
}

Implementowanie funkcji udostępniania dla aplikacji klasycznych (WinUI 3, WPF, WinForms)

Aplikacje klasyczne — zarówno pakietowane, jak i niepakietowane — używają interfejsu IDataTransferManagerInterop do uzyskiwania dostępu do panelu Udostępnianie dla każdego okna. Dotyczy to aplikacji WinUI 3, WPF i WinForms.

1. Zadeklaruj interfejs interoperacyjny i uzyskaj obiekt DataTransferManager

using Windows.ApplicationModel.DataTransfer;

[System.Runtime.InteropServices.ComImport]
[System.Runtime.InteropServices.Guid("3A3DCD6C-3EAB-43DC-BCDE-45671CE800C8")]
[System.Runtime.InteropServices.InterfaceType(
    System.Runtime.InteropServices.ComInterfaceType.InterfaceIsIUnknown)]
interface IDataTransferManagerInterop
{
    IntPtr GetForWindow([System.Runtime.InteropServices.In] IntPtr appWindow,
        [System.Runtime.InteropServices.In] ref Guid riid);
    void ShowShareUIForWindow(IntPtr appWindow);
}

public sealed partial class MainWindow // WinUI 3 Window, WPF Window, or WinForms Form
{
    // IID of DataTransferManager, passed as the riid to GetForWindow:
    static readonly Guid _dtm_iid =
        new Guid(0xa5caee9b, 0x8708, 0x49d1, 0x8d, 0x36, 0x67, 0xd2, 0x5a, 0x8d, 0xa0, 0x0c);

    private DataTransferManager _dtm;

    // Call this from your window or form constructor (or load handler):
    private void InitializeShare()
    {
        // Retrieve the window handle (HWND) for the current window:
        //   WinUI 3:  IntPtr hWnd = WinRT.Interop.WindowNative.GetWindowHandle(this);
        //   WPF:      IntPtr hWnd = new System.Windows.Interop.WindowInteropHelper(this).Handle;
        //   WinForms: IntPtr hWnd = this.Handle;
        IntPtr hWnd = WinRT.Interop.WindowNative.GetWindowHandle(this);

        IDataTransferManagerInterop interop =
            DataTransferManager.As<IDataTransferManagerInterop>();
        _dtm = WinRT.MarshalInterface<DataTransferManager>.FromAbi(
            interop.GetForWindow(hWnd, _dtm_iid));

        _dtm.DataRequested += (sender, args) => OnDataRequested(args);
    }
}

2. Uzupełnij i wyświetl

private void OnDataRequested(DataRequestedEventArgs args)
{
    DataRequest request = args.Request;
    DataPackage data = request.Data;

    data.Properties.Title = "Share from my desktop app";
    data.SetText("Shared content");

    // For URLs:
    // data.SetWebLink(new Uri("https://example.com"));

    // For files:
    // var item = await StorageFile.GetFileFromPathAsync(filePath);
    // data.SetStorageItems(new[] { item });
}

// In your Share button handler:
private void ShareButton_Click()
{
    var hWnd = WinRT.Interop.WindowNative.GetWindowHandle(this);
    var interop = DataTransferManager.As<IDataTransferManagerInterop>();
    interop.ShowShareUIForWindow(hWnd);
}

Pełny przykład można znaleźć w przykładzie WPF Share Source.

Zdarzenia po stronie źródłowej

Użyj tych zdarzeń w aplikacjach źródłowych, aby sprawdzić, co się dzieje po otwarciu przez użytkownika panelu Udostępnianie.

API Gdy jest uruchamiany Dlaczego używać tej opcji
DataTransferManager.DataRequested Użytkownik uruchamia operację udostępniania Skompiluj i dołącz DataPackage
DataTransferManager.TargetApplicationChosen Użytkownik wybiera aplikację docelową Opcjonalna telemetria na potrzeby wyboru celu
DataPackage.ShareCompleted Udostępnianie zostało zakończone Opcjonalna telemetria powodzenia
DataPackage.ShareCanceled Użytkownik anuluje udział Opcjonalna telemetria anulowania

Note

W tym przykładzie użyto GetForCurrentView funkcji zwięzłości, która ma zastosowanie do aplikacji platformy UWP. W aplikacjach klasycznych uzyskaj element DataTransferManager za pomocą IDataTransferManagerInterop.GetForWindow , jak pokazano wcześniej, a następnie dołącz te same zdarzenia.

private void RegisterShareEvents()
{
  var dtm = DataTransferManager.GetForCurrentView();
  dtm.DataRequested += OnDataRequested;
  dtm.TargetApplicationChosen += OnTargetChosen;
}

private void OnDataRequested(DataTransferManager sender, DataRequestedEventArgs args)
{
  DataRequest request = args.Request;
  request.Data.Properties.Title = "Share from my app";
  request.Data.SetText("Hello from Windows Share");

  request.Data.ShareCompleted += OnShareCompleted;
  request.Data.ShareCanceled += OnShareCanceled;
}

private void OnTargetChosen(DataTransferManager sender, TargetApplicationChosenEventArgs args)
{
  // Optional: telemetry only
  Debug.WriteLine($"Target app: {args.ApplicationName}");
}

private void OnShareCompleted(DataPackage sender, ShareCompletedEventArgs args)
{
  Debug.WriteLine("Share completed");
}

private void OnShareCanceled(DataPackage sender, object args)
{
  Debug.WriteLine("Share canceled");
}

Note

DataPackage.OperationCompleted i DataPackage.Destroyed są przeznaczone głównie do przepływów pracy związanych ze Schowkiem i wklejaniem. Zazwyczaj nie są potrzebne w scenariuszach źródła udostępniania.

Najlepsze rozwiązania dotyczące udostępniania

Użyj tej listy kontrolnej, aby zachować przewidywalne zachowanie po stronie źródła.

Zalecane Uniknięcie Dlaczego ma to znaczenie
Użyj SetWebLink lub SetApplicationLink w przypadku adresów URL Użyj SetText dla adresów URL Linki wyświetlają się i prowadzą prawidłowo w aplikacjach docelowych
Ustaw Title i opcjonalne metadane (Description, miniatura) Wysyłanie zawartości bez metadanych Poprawia czytelność interfejsu udostępniania i wyświetlanie elementów docelowych
Obsłuż TargetApplicationChosen, ShareCompleted i ShareCanceled, jeśli potrzebujesz telemetrii Zakładając, że te sygnały pochodzą z ShareOperation aplikacji źródłowych Są to sygnały po stronie źródła na potrzeby analizy po udostępnieniu
Utrzymuj współdzielone ładunki danych w odpowiednim zakresie i zgodności z wybranym działaniem Domyślnie wysyłanie niepowiązanych lub nadmiernie załadowanych ładunków Zmniejsza liczbę niepowodzeń i poprawia współczynnik powodzenia udziału

Treści powiązane

  • Last updated on