最近公司有一個需求：老闆希望能夠快速在應用中檢視各種型別的檔案📄🖼️🎶🎥，
比如文字、圖片、音訊、影片，甚至是網頁和文件，而不需要每次跳轉到系統的其他應用。
這時，我們就需要為應用整合一個檔案快速預覽的功能。
為了解決這個問題，我們選擇了 @kit.PreviewKit 模組，它提供了系統級的檔案快速預覽 API，只需幾行程式碼就能實現預覽功能。它的主要優勢在於簡單易用，幾乎不需要複雜配置就可以支援多種檔案型別，大大提高了開發效率💡。
📂 支援的檔案型別
PreviewKit支援多種檔案型別的預覽，涵蓋了常見的文字、圖片、音訊、影片等。具體支援的檔案字尾和對應的 MIME 型別如下：
文字: txt、cpp、java 等
網頁: html、htm
圖片: jpg、png、gif 等
音訊: mp3、wav 等
影片: mp4、mkv 等
文件: pdf
這些檔案型別涵蓋了企業日常中的大部分需求，無論是檢視技術文件、專案計劃，還是播放培訓影片、會議錄音，都可以透過 PreviewKit 輕鬆實現。此外，PreviewKit 的擴充套件性也非常好，未來如果需要支援更多檔案型別，可以方便地進行升級和調整。
💻 開始編碼實現檔案預覽
接下來我們直接進入編碼實現部分，看看如何透過程式碼使用 PreviewKit 來實現檔案預覽。
首先，我們需要匯入模組：
import { filePreview } from '@kit.PreviewKit';比如有這麼一個場景，使用者想要檢視一份文字檔案 1.txt ，它位於應用的 Documents 資料夾下。我們可以透過呼叫 openPreview 方法來開啟檔案預覽視窗。
import { BusinessError } from '@kit.BasicServicesKit';
import { filePreview } from '@kit.PreviewKit';
let uiContext = getContext(this); // 獲取當前的上下文環境
// 配置懸浮視窗的顯示資訊
let displayInfo: filePreview.DisplayInfo = {
x: 100,
y: 100,
width: 800,
height: 800
};
// 配置需要預覽的檔案資訊
let fileInfo: filePreview.PreviewInfo = {
title: '1.txt',
uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
mimeType: 'text/plain'
};
// 呼叫檔案預覽方法，傳入檔案資訊和懸浮視窗資訊
filePreview.openPreview(uiContext, fileInfo, displayInfo).then(() => {
console.info('Succeeded in opening preview ✅');
}).catch((err: BusinessError) => {
console.error(`Failed to open preview ❌, err.code = ${err.code}, err.message = ${err.message}`);
});📝 程式碼講解
1.上下文環境獲取:
let uiContext = getContext(this);
用於獲取當前 UI 的上下文環境。這是必需的，有了上下文環境，檔案預覽視窗才能正確地顯示。
2.懸浮視窗的顯示資訊:
DisplayInfo 包含懸浮視窗的位置和大小。可以透過 x 和 y 控制視窗在螢幕上的位置，透過 width 和 height 控制視窗大小📏。這使得我們能夠靈活地調整預覽視窗的展示效果，確保它符合使用者的使用習慣。
3.檔案資訊配置:
PreviewInfo 定義了要預覽的檔案資訊，包括檔名、URI 和 MIME 型別。如果 title 沒有填寫，系統會嘗試透過 uri 解析檔名。如果無法解析，則顯示為“未知檔案”，因此建議填寫 title 以提升使用者體驗。
4.呼叫openPreview方法:
透過 filePreview.openPreview()，傳入上下文、檔案資訊和視窗資訊，即可非同步開啟檔案預覽視窗。使用 Promise 可以方便地處理成功和失敗的回撥，從而確保應用在處理預覽請求時更加穩定，提升使用者互動體驗📈。
⚠️ 錯誤處理
當然呼叫檔案預覽介面時，非常有可能會遇到一些問題，例如引數錯誤或檔案無法訪問等。這時需要透過 catch方法捕獲錯誤並進行處理，常見的錯誤碼包括：
- 401: 輸入引數無效，可能是 URI 錯誤或 MIME 型別不正確。在這種情況下，需要檢查傳入的引數，確保資訊準確無誤。
- 801: 功能不支援，可能是裝置不支援對應檔案型別的預覽。這類錯誤通常與裝置的限制有關，可以考慮提供備用的處理方式，例如提示使用者檔案型別不支援。
進行錯誤處理，我們可以提高應用的健壯性💪，即使遇到各種邊界情況，也能夠為使用者提供清晰的錯誤提示和引導，減少使用者的困惑。
📑 多檔案預覽
有時使用者可能需要一次預覽多個檔案，比如檢視專案中的多個文件📂。在這種情況下，可以使用 openPreview(context, files, index) 方法，允許使用者在一個視窗中預覽多個檔案，從而提高檔案管理的效率。
let files: Array<filePreview.PreviewInfo> = [
{
title: '1.txt',
uri: 'file://docs/storage/Users/currentUser/Documents/1.txt',
mimeType: 'text/plain'
},
{
title: 'report.pdf',
uri: 'file://docs/storage/Users/currentUser/Documents/report.pdf',
mimeType: 'application/pdf'
}
];
filePreview.openPreview(uiContext, files, 0).then(() => {
console.info('Succeeded in opening preview ✅');
}).catch((err: BusinessError) => {
console.error(`Failed to open preview ❌, err.code = ${err.code}, err.message = ${err.message}`);
});上面的程式碼中，我們傳入了多個檔案資訊，並指定 index = 0 ，即預設開啟第一個檔案的預覽視窗。這樣，使用者可以在多個檔案之間進行切換，非常方便。
這種多檔案預覽的功能特別適用於需要同時檢視多個檔案的場景，比如稽核專案資料、檢視多份報告等，極大提升了使用者的工作效率🚀。
📌 最後小總結
透過 @kit.PreviewKit，我們可以輕鬆為應用整合檔案快速預覽功能，支援文字📄、圖片🖼️、音訊🎶、影片🎥等多種檔案型別。無論是單個檔案的預覽，還是多個檔案之間的切換，都可以透過簡單的 API 實現，為使用者提供流暢而高效的檔案檢視體驗。
總之又解決了一個老闆問題 ～安全下車～！
