harmony 鸿蒙文件选择器使用指导

2022-12-22
浏览 (1662)

文件选择器使用指导

文件选择器(FilePicker)是OpenHarmony中预置的系统应用，为用户提供文件选择及保存功能。具体实现可以参考FilePicker代码仓库。

应用可以通过FilePicker的两种模式实现文件选择和文件保存的功能。 - choose模式（文件选择）：当应用需要选择并上传、发送设备中的文件（包括图片、音视频等媒体资源）时，可以选择该模式。拉起FilePicker的choose模式窗口，系统将弹出弹框供用户选择具体文件。用户通过界面选择目标文件并点击“上传”按钮，应用将接收到FilePicker传回的目标文件uri。 - save模式（文件保存）：当应用需要下载保存文件（包括图片、音视频等媒体资源）时，可以选择该模式。拉起FilePicker的save模式窗口，系统将弹出弹框供用户选择保存文件的目标路径。用户通过界面选择目标路径并点击“保存”按钮，应用将接收到FilePicker传回的已保存文件uri。

开发指导

说明： FilePicker仅支持基于Stage模型开发的应用拉起。
Stage模型介绍请参考应用模型解读。

使用不同的参数调用AbilityContext.startAbilityForResult(want, options)可以拉起FilePicker不同模式的窗口。

开发者需要通过Want指定”bundleName”和”abilityName”来拉起FilePicker，具体写法可参见下方的示例代码。

同时，开发者还需要设置属性Want.parameters，来指定FilePicker拉起的模式以及文件保存的名称： - 文件选择：仅需要设置FilePicker拉起的窗口模式为'startMode': 'choose'。 - 文件保存：除了设置FilePicker拉起的窗口模式为'startMode': 'save'，还需要设置文件保存名称'saveFile'。

可以通过设置类型为StartOptions的入参options来指定弹出窗口样式，推荐设置为windowMode: 102，即自由悬浮形式窗口。

注意： 1. save模式下，用户保存路径根据保存文件名执行强校验，用户保存路径参考公共目录路径支持的文件格式。 2. 用户选择目标文件保存路径后，如存在同名文件，FilePicker将弹窗提醒用户是否覆盖原文件。

ArkTS语言示例代码如下：

// 拉起FilePicker选择文件
globalThis.context.startAbilityForResult(
    {
        bundleName: "com.ohos.filepicker",
        abilityName: "MainAbility",
        parameters: {
            'startMode': 'choose', //choose or save
        }
    },
    { windowMode: 102 }
)

// 拉起FilePicker保存文件
globalThis.context.startAbilityForResult(
    {
        bundleName: "com.ohos.filepicker",
        abilityName: "MainAbility",
        parameters: {
            'startMode': 'save', //choose or save
            'saveFile': 'test.jpg',
        }
    },
    { windowMode: 102 }
)

// FilePicker返回给startAbilityForResult的数据
let abilityResult = {
    resultCode: resultCode,
    want: {
        parameters: {
            'startMode': startMode,
            'result': result
        }
    }
}
globalThis.context.terminateSelfWithResult(abilityResult)