Berbagi konten dari aplikasi Anda - integrasikan Windows Share

Lembar Berbagi Windows adalah UI yang disediakan sistem yang memungkinkan pengguna mengirim konten dari aplikasi Anda ke aplikasi Windows lainnya. Panduan ini menjelaskan cara menerapkan kontrak Berbagi di seluruh aplikasi paket (MSIX), Progressive Web Apps (PWAs), dan aplikasi Win32 yang tidak dikemas.

Bagian Apa yang akan Anda temukan
Pilih pendekatan berbagi Anda Pilih SET API yang tepat untuk aplikasi UWP, desktop, atau PWA
Menerapkan Berbagi untuk aplikasi UWP DataTransferManager.GetForCurrentView dan ShowShareUI
Menerapkan fitur berbagi untuk PWAs Integrasi WEB Share API
Menerapkan Berbagi untuk aplikasi desktop IDataTransferManagerInterop berbagi untuk tiap jendela pada WinUI 3, WPF, WinForms
Kejadian di sisi sumber Perhatikan pemilihan sasaran, penyelesaian, dan pembatalan
Praktik terbaik untuk Berbagi Rekomendasi untuk perilaku sisi sumber yang andal

Pilih pendekatan berbagi Anda

Jenis aplikasi Approach Kumpulan API
Aplikasi UWP Gunakan DataTransferManager.GetForCurrentView dan ShowShareUI Windows.ApplicationModel.DataTransfer (Model Aplikasi Windows untuk Transfer Data)
Aplikasi desktop (WinUI 3, WPF, WinForms) Gunakan IDataTransferManagerInterop untuk berbagi per jendela (dikemas atau tidak dikemas) Windows Runtime melalui interop COM
Aplikasi Web Progresif (PWAs) Menggunakan integrasi WEB Share API + Windows W3C Web Share

Menerapkan Berbagi untuk aplikasi UWP

Important

DataTransferManager.GetForCurrentView dan ShowShareUI hanya didukung di aplikasi UWP. Aplikasi desktop (WinUI 3, WPF, atau WinForms - dikemas atau tidak dikemas) harus menggunakan pola yang IDataTransferManagerInterop ditampilkan di Terapkan Berbagi untuk aplikasi desktop.

1. Dapatkan DataTransferManager

Dalam inisialisasi halaman Anda, peroleh referensi ke DataTransferManager:

using Windows.ApplicationModel.DataTransfer;

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

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

2. Mengisi DataPackage

Saat pengguna memulai berbagi (misalnya, mengklik tombol Bagikan), buat DataPackage dengan konten dan metadata:

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 */;
}

Tip

Saat Anda berbagi URL, gunakan SetWebLink (atau SetApplicationLink untuk tautan mendalam) alih-alih SetText. Aplikasi target kemudian dapat menghasilkan pratinjau tautan yang kaya dan menangani navigasi dengan benar, alih-alih memperlakukannya sebagai teks biasa.

3. Tampilkan UI Berbagi

Picu Lembar Berbagi dari klik tombol atau perintah 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();
}

Menerapkan fitur berbagi untuk Aplikasi Web Progresif (PWA)

PWAs menggunakan W3C Web Share API. Pastikan PWA Anda memiliki properti manifes yang diperlukan untuk diintegrasikan dengan Windows:

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

Di PWA JavaScript Anda, gunakan API Web Share:

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

Menerapkan Berbagi untuk aplikasi desktop (WinUI 3, WPF, WinForms)

Aplikasi desktop - baik dikemas atau tidak dikemas - gunakan IDataTransferManagerInterop antarmuka untuk mengakses Lembar Berbagi per jendela. Berlaku untuk aplikasi WinUI 3, WPF, dan WinForms.

1. Deklarasikan antarmuka interop dan dapatkan 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. Isi dan tampilkan

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

Untuk contoh lengkapnya, lihat sampel Sumber Berbagi WPF.

Kejadian di sisi sumber

Gunakan peristiwa ini di aplikasi sumber untuk mengamati apa yang terjadi setelah pengguna membuka Berbagi.

API Ketika diaktifkan Mengapa menggunakannya
DataTransferManager.DataRequested Pengguna memulai operasi berbagi Buat dan lampirkan DataPackage
DataTransferManager.TargetApplicationChosen Pengguna memilih aplikasi target Telemetri opsional untuk pemilihan target
DataPackage.ShareCompleted Pembagian selesai Telemetri keberhasilan opsional
DataPackage.ShareCanceled Pengguna membatalkan berbagi Telemetri untuk pembatalan opsional

Note

Contoh ini menggunakan GetForCurrentView demi singkatnya, yang berlaku untuk aplikasi UWP. Di aplikasi desktop, peroleh DataTransferManager melalui IDataTransferManagerInterop.GetForWindow, seperti yang ditunjukkan sebelumnya, lalu lampirkan event yang sama.

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 dan DataPackage.Destroyed terutama digunakan untuk alur kerja Papan Klip dan penempelan. Mereka umumnya tidak diperlukan untuk skenario Sumber berbagi.

Praktik terbaik untuk Berbagi

Gunakan daftar periksa ini untuk menjaga perilaku sisi sumber tetap dapat diprediksi.

Recommended Hindari Mengapa penting
Menggunakan SetWebLink atau SetApplicationLink untuk URL Gunakan SetText untuk URL Tautan ditampilkan dan mengarahkan dengan benar di aplikasi tujuan
Atur Title dan metadata opsional (Description, gambar mini) Mengirim konten tanpa metadata Meningkatkan kejelasan UI Berbagi dan penyajian target
Menangani TargetApplicationChosen, ShareCompleted, dan ShareCanceled jika Anda memerlukan telemetri Dengan asumsi sinyal ini berasal dari ShareOperation dalam aplikasi sumber Ini adalah sinyal sisi sumber untuk wawasan pasca-berbagi
Pastikan payload yang dibagikan tetap terfokus dan valid untuk aksi yang dipilih Mengirim payload yang tidak terkait atau terlalu besar secara default Mengurangi kegagalan dan meningkatkan tingkat keberhasilan berbagi

Konten terkait

  • Last updated on