如何分享檔案 (HTML)

發行項
12/11/2015

[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App，請參閱最新文件 ]

使用者通常會想要和其他人或應用程式分享檔案。使用分享功能，您的應用程式可以輕易支援各種工作，包括使用電子郵件傳送檔案給同事，分享家人出遊的照片。

支援分享檔案這類功能時，您需要考慮您的應用程式何時可以準備好檔案。大部分的情況下，您的應用程式可能已經準備好要分享的檔案。如果是這樣，那麼這個主題中的步驟就正好是您需要的。如果您的應用程式在檔案準備就緒前需要執行其他工作，例如將檔案從一種格式轉換為另一種，那麼您需要參閱我們的如何支援提取作業主題。該主題示範如何使用委派函式讓目標應用程式從您的應用程式提取要分享的內容，而不是要求您的應用程式發送內容。

您必須知道的事

技術

Windows.ApplicationModel.DataTransfer

先決條件

您應該熟悉 Visual Studio 以及相關範本。
您應該熟悉 JavaScript。
您必須了解如何取得檔案和其他資料，例如使用 FileOpenPicker。您可以在使用檔案選擇器存取檔案中了解詳細資訊。

指示

步驟 1: 建立按鈕處理常式函式，讓使用者選擇影像檔

下列按鈕處理常式程式碼可讓使用者挑選影像檔。這個快速入門的後續步驟都會用到這個檔案。

注意

下列程式碼使用 pickSingleFileAsync。在 Windows Phone 8.1 應該改用 pickSingleFileAndContinue。

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

步驟 2: 將您的應用程式設定成分享來源

DataTransferManager 物件是任何分享作業的主起點。新增一個要在使用者想要叫用分享時引發的 DataRequested 事件處理常式。在 Windows 市集應用程式中，當使用者叫用 [分享] 常用鍵時，就會自動引發這個事件。如果您開發的是 Windows Phone 應用程式，則沒有內建的分享常用鍵，所以您需要新增控制項，讓使用者可以輕觸並觸發處理常式。

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareStorageItemsHandler);

剩餘的是實作 shareStorageItemsHandler 函式的步驟。

步驟 3: 取得 DataRequest 物件

發生 datarequested 事件後，應用程式會收到 DataRequest 物件。這個物件有一個 DataPackage，您可以用它來提供使用者想分享的內容。

var request = e.request;

步驟 4: 設定標題和描述屬性

request.data.properties.title = "Share StorageItems Example";
request.data.properties.description = "Demonstrates how to share files.";

步驟 5: 將檔案新增到 DataPackage

若要將檔案新增到 DataPackage，請使用 setStorageItems 方法。

request.data.setStorageItems([imageFile]);

備註

根據預設，setStorageItems 會提供 storageItems 的唯讀"複製"項目來與目標應用程式進行分享。在呼叫 setStorageItems 之後，您在個別的儲存項目上設定的任何新屬性將不會反映在複製的項目上。這就是為什麼必須確定要分享的檔案已經準備就緒，才能將檔案新增到 DataPackage。

此外，如果您希望目標應用程式擁有讀/寫 storageItems 的能力，可使用 setStorageItems 方法的超載版本指定唯讀或讀/寫。例如，要求目標執行「貼上時刪除」操作的來源應用程式會指定讀/寫，讓目標可以在複製來源檔案後刪除它們。

如果您的應用程式需要使用非同步作業來準備影像或縮圖，則需要使用延遲模式。我們會在如何在 DataRequested 處理常式中進行非同步呼叫中示範該怎麼做。

如果您的應用程式需要較長的時間 (超過 200 毫秒) 來準備檔案，您必須使用委派函式來分享影像。我們會在如何支援提取作業中教您如何完成。如果您決定使用委派函式，那麼新增檔案前，需要設定 DataPackage 上的 FileTypes 屬性。

完整範例

這裡是一個函式範例，它為使用者設定一些要分享的檔案。如需更完整的範例，請參閱我們的程式碼庫範例。

var imageFile = null;
function pickImageFile() {
    var picker = new Windows.Storage.Pickers.FileOpenPicker();
    picker.fileTypeFilter.replaceAll([".jpg", ".bmp", ".gif", ".png"]);
    picker.pickSingleFileAsync().done(function (file) {
        imageFile = file;
    });
}

function shareStorageItemsHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share StorageItems Example";
    request.data.properties.description = "Demonstrates how to share files.";
    request.data.setStorageItems([imageFile]);
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
            // This app is newly launched; register it as a share source.
            var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
            dataTransferManager.addEventListener("datarequested", shareStorageItemsHandler);
            // Setup the button handler to pick image file
            document.getElementById("chooseImageButton").addEventListener("click", pickImageFile, false);
        } else {
            // TODO: This app was reactivated from suspension.
            // Restore the app state here.
        }
        args.setPromise(WinJS.UI.processAll());
    }
};