文件选择器使用指导


文件选择器使用指导

文件选择器(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的数据
var abilityResult = {
    resultCode: resultCode,
    want: {
        parameters: {
            'startMode': startMode,
            'result': result
        }
    }
}
globalThis.context.terminateSelfWithResult(abilityResult)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36