如何接收檔案 (HTML)
[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App,請參閱 最新文件 ]
分享檔案與較簡單的資料類型 (如文字) 相比需要較多準備。分享檔案時,您需要考慮處理檔案的時間。
如果您認為應用程式需要時間來處理使用者想要分享的檔案,開始處理檔案前請務必呼叫 reportStarted。此方法可確保系統讓您的應用程式保持運作直到完成處理。應用程式完成處理後,請呼叫 reportCompleted 以完成分享作業。若要深入了解,請參閱快速入門:接收分享的內容中的"報告延伸的分享狀態"。
您必須知道的事
技術
先決條件
- 您應該熟悉 Visual Studio 以及相關範本。
- 您應該熟悉 JavaScript。
指示
步驟 1: 支援分享協定。
您的應用程式可以接收分享的內容之前,必須先宣告它支援分享協定。這個協定會讓系統知道您的應用程式能夠接收內容。如果您使用 Microsoft Visual Studio 範本建立應用程式,以下是支援共用目標合約的方式:
- 開啟資訊清單檔案 (package.appxmanifest)。
- 開啟 [宣告] 索引標籤。
- 從 [可用宣告]**** 清單中選擇 [共用目標]。
- 按一下 [加入]****,在應用程式新增共用目標合約的支援。
步驟 2: 指定應用程式支援的檔案類型。
在應用程式資訊清單中指定副檔名,即可指定應用程式支援的檔案類型:
- 開啟資訊清單檔案。
- 在 [資料格式] 區段中,按一下 [加入新的]****。
- 輸入副檔名,如 ".txt" (不要加上引號)。
- 對於任何其他的檔案類型重複上述步驟。
前面的步驟會將下段文字新增到資訊清單中:
<Extensions>
<Extension Category="windows.shareTarget">
<ShareTarget>
<SupportedFileTypes>
<FileType>.txt</FileType>
</ShareTarget>
</Extension>
</Extensions>
注意 您不需要在 [資料格式] 區段中指定 StorageItems。它的支援是在資訊清單的 SupportedFileTypes 區段中指定的。如果您的應用程式支援所有的檔案類型,可以核取 [支援任何檔案類型] 在資訊清單中指定它們。
注意 當您的應用程式依據共用目標合約啟用時,您可以指定不同的進入點。若要這樣做,請修改套件資訊清單中 [共用目標] 宣告中 [應用程式]**** 設定區段中 [起始頁] 項目。也強烈建議您在該頁面使用專門處理啟用的另一個 JavaScript 檔案。如需範例,請查看分享內容目標應用程式範例。
步驟 3: 新增事件處理常式來偵測應用程式何時啟用。
當使用者選取您的應用程式來分享內容時,系統會啟用您的應用程式。因為啟用的方法很多,所以您需要新增程式碼以偵測發生啟用的原因。您可以檢查 kind 屬性的值來這樣做。
app.onactivated = function (args) {
if (args.detail.kind === activation.ActivationKind.launch) {
// The application has been launched. Initialize as appropriate.
} else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
...
}
};
步驟 4: 取得 ShareOperation 物件。
ShareOperation 物件包含應用程式所需的全部資料,讓應用程式取得使用者想分享的內容。
shareOperation = args.detail.shareOperation;
步驟 5: 快速地從啟用的事件處理常式傳回。
activated 事件處理常式必須快速傳回。將來自於 activated 事件處理常式的非同步事件排入佇列,這樣啟用的事件傳回之後就會開始處理分享資料。
WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });
剩餘的步驟是實作 shareReady
函式。
步驟 6: 檢查 DataPackageView 是否包含 StorageItems。
ShareOperation 物件包含一個 DataPackageView 物件。這個物件是 DataPackage 物件 (來源應用程式用來建立資料) 的唯讀版本。使用此物件來查看要分享的內容是否包含 StorageItems。
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
// Data being shared contains one or more StorageItem. Code to process the StorageItems goes here.
}
檢查 DataPackage 是否包含您有興趣的資料格式是很好的做法,即使您的應用程式僅支援一種格式。 這樣會讓應用程式以後可以輕鬆地支援其他資料格式。
步驟 7: 處理檔案。
若要取得檔案,請呼叫 DataPackageView.GetStorageItemsAsync 方法。
shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
var fileList = "";
for (var i = 0; i < storageItems.size; i++) {
fileList += storageItems.getAt(i).name;
if (i < storageItems.size - 1) {
fileList += ", ";
}
}
// In this example, we only display the file names. To do this, you need
// a <div> element with an id of "output" in your HTML page.
// In your app, replace this with whatever is appropriate for your scenario.
document.getElementById("output").innerText = "Files: " + fileList;
});
注意
處理檔案可能需要時間。請不要強迫使用者等候應用程式完成載入和處理資料,這是很重要的。在 Windows 8.1 上,您可以呼叫 reportStarted 方法,讓系統得知您的應用程式已開始處理分享的內容。系統會讓您的應用程式保持運作,直到呼叫 reportCompleted 為止—即使使用者關閉應用程式返回來源應用程式也是一樣。如需詳細資訊,請參閱快速入門:接收分享的內容中的<報告延伸的分享狀態>。
步驟 8: 呼叫 reportCompleted。
在您的應用程式成功完成分享內容後,請呼叫 reportCompleted。呼叫這個方法之後,系統會關閉您的應用程式。
shareOperation.reportCompleted();
備註
請查看我們的分享內容目標應用程式範例中的程式碼範例,了解應用程式接收分享之文字的整個端對端經驗。
完整範例
var shareOperation = null;
function shareReady(args) {
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
var fileList = "";
for (var i = 0; i < storageItems.size; i++) {
fileList += storageItems.getAt(i).name;
if (i < storageItems.size - 1) {
fileList += ", ";
}
}
// In this example, we only display the file names. To do this, you need
// a <div> element with an id of "output" in your HTML page.
// In your app, replace this with whatever is appropriate for your scenario.
document.getElementById("output").innerText = "Files: " + fileList;
});
}
}
app.onactivated = function (args) {
if (args.detail.kind === activation.ActivationKind.launch) {
// The app has been launched.
args.setPromise(WinJS.UI.processAll());
} else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
// This app was activated for the Share contract.
args.setPromise(WinJS.UI.processAll());
// We receive the ShareOperation object as part of the eventArgs.
shareOperation = args.detail.shareOperation;
// We queue an asychronous event so that working with the ShareOperation
// object does not block or delay the return of the activation handler.
WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });
}
};
相關主題
Windows.ApplicationModel.DataTransfer