文件系统 -凯发app官方网站

框架概述

目录结构

native 渲染

性能与优化

小程序全局配置

acss 语法参考

小程序页面

axml

sjs 语法参考

事件系统

自定义组件

基础能力

文件系统

小程序全局 / 页面参数设置以及解析细节

分包

基础库

基础库更新日志

更新时间：2024-08-01 16:51:51

订阅更新

我的文档

设置

文件系统是支付宝小程序提供的以小程序和用户维度隔离的存储系统及相应的管理接口。

文件类型

文件主要分为两大类：

●

代码包文件：

指的是在项目目录中添加的文件。

●

本地文件：

通过调用接口本地产生，或通过网络下载到本地的文件。

其中本地文件又分为三种：

○

本地临时文件：

临时产生，随时会被回收的文件。

○

本地缓存文件：

小程序通过

调用特定接口

my.savefile

filesystemmanager.savefile

（不指定入参 filepath）

把

本地临时文件缓存后产生的文件，不能自定义目录和文件名。

○

本地用户文件：

小程序通过调用特定接口

filesystemmanager.savefile

（指定入参 filepath）把本地临时文件缓存后产生的文件，允许自定义目录和文件名。

代码包文件

适用于放置首次加载时需要的文件，由于代码包文件大小有所限制，对于内容较大或需要动态替换的文件，不推荐将该文件添加到代码包中。

访问代码包文件

访问代码包文件需要配置以下两点：

●

访问的文件路径需要从根目录开始写文件路径，不支持相对路径的写法，示例如下：

// 合法

'/source/test.json' || 'source/test.text'

// 不合法

'./source/test.json' || '../source/test.text'

●

需要在

mini.project.json

中配置要读取的小程序文件内容，示例代码如下：

示例代码

修改代码包文件

代码包内的文件无法在运行后进行动态修改或删除，若要修改代码包文件则需重新发布版本。

本地文件

本地文件指的是小程序被用户添加到手机后，以用户维度隔离，有一块独立的文件存储区域。即同一台手机，仅支持每个手机用户访问当前登录的账号下的文件，不支持访问其它用户的文件，同一账号下的不同小程序的文件也不能互相访问。

本地文件的文件路径格式为

{{协议名}}://文件路径

。支付宝客户端和小程序开发者工具（ide）的协议名均为

https

。

说明：

为了安全考虑，本地文件是支付宝分配给用户的沙盒文件，和用户文件系统隔离，小程序开发者可以通过文件管理器的接口来访问，但用户无法在手机文件系统中直接访问。

本地文件可分为本地临时文件、本地缓存文件和本地用户文件。

本地临时文件

本地临时文件只能通过调用特定接口产生，不能直接写入内容。

本地临时文件通过文件虚拟协议

https://resource

操作。

●

本地临时文件产生后，仅在当前生命周期内保证有效，重启之后不一定可用，并且一旦小程序被完全关闭就被清理，即下次冷启动小程序时不可继续使用。

●

如果需要保证在下次启动时无需下载，可通过

my.savefile

或

filesystemmanager.savefile

接口将本地临时文件转换为

本地缓存文件

或

本地用户文件

。

●

在下载文件前，可先通过

filesystemmanager.access

检查该文件是否存在，减少重复文件下载，提升用户体验。

示例代码

可产生本地临时文件的接口

接口列表持续更新中：

●

●

●

●

●

canvascontext.totempfilepath

●

my.canvastotempfilepath

●

canvas.totempfilepath

本地缓存文件

本地缓存文件只能通过调用特定接口产生，不能直接写入内容。

本地缓存文件通过文件虚拟协议

https://resource

操作。

●

本地缓存文件产生后，重启之后仍可用。

●

本地缓存文件只能通过

my.savefile

filesystemmanager.savefile

（不指定入参 filepath）接口将本地临时文件保存获得。

●

除非用户主动删除小程序，否则本地缓存文件不会被删除。

●

本地缓存文件和本地用户文件共计最大可存储 200mb，单个本地缓存文件最大可存储 30mb。

●

可通过

my.removesavedfile

删除本地缓存文件。

注意：

本地缓存文件是最初的设计，从基础库

版本开始，提供了可完全覆盖

本地缓存文件

使用场景的

本地用户文件

以及对应的管理接口

my.getfilesystemmanager

，建议使用本地用户文件。

示例代码

可产生本地缓存文件的接口

接口列表持续更新中：

●

my.savefile

●

filesystemmanager.savefile

（不指定入参 filepath）

●

my.getsavedfilelist

：返回本地缓存文件列表

本地用户文件

本地用户文件通过文件虚拟协议

https://usr

操作。

●

基础库

开始支持，为开发者提供了一个用户文件目录，开发者对此目录有完整的读写权限。通过

my.env.user_data_path

可以获取到这个目录的路径。

●

本地用户文件与本地缓存文件共计最大可存储 200mb，单个本地用户文件最大可存储 30mb。

●

可通过

filesystemmanager.unlink

删除本地用户文件。

示例代码

可产生本地用户文件的接口

接口列表持续更新中：

filesystemmanager.savefile

（指定入参 filepath）

读写权限

文件类型	读	写
代码包文件	有	无
本地临时文件	有	无
本地缓存文件	有	无
本地用户文件	有	有

示例代码

清理策略

●

本地临时文件仅支持在小程序当前生命周期内进行保存，一旦小程序被关闭就可能被清理，即下次冷启动不保证可用。

●

本地缓存文件和本地用户文件只有在代码包被清理的时才会被清理。

部份接口 / 组件支持的文件类型明细

列表持续更新中：

接口 / 组件	分类	支持的本地文件类型			备注
接口 / 组件	分类	本地临时文件	本地缓存文件	本地用户文件	备注
image 组件属性 src	多媒体	✓	✓	✓	-
my.compressimage 入参 apfilepaths	多媒体	✓	✓	✓	ios：10.2.70 开始支持本地缓存文件、本地用户文件。
my.saveimagetophotosalbum 入参 filepath	多媒体	✓	✓	✓	ios：10.2.70 开始支持本地缓存文件、本地用户文件。
my.previewimage 入参 urls	多媒体	✓	✓	✓	ios：10.2.70 开始支持本地用户文件。
my.getimageinfo 入参 src	多媒体	✓	✓	✓	10.2.70 开始支持本地缓存文件、本地用户文件。
my.savevideotophotosalbum 入参 filepath	多媒体	✓	✓	✓	10.2.70 开始支持本地缓存文件、本地用户文件。
my.opendocument 入参 filepath	文件	✓	✓	✓	●ios：10.2.60 开始支持本地缓存文件。 ●android：10.2.60 开始支持本地用户文件。
my.savefile 入参 apfilepath	文件	✓	✓	✕	-
my.getfileinfo 入参 apfilepath	文件	✓	✓	✓	-
my.removesavedfile 入参 apfilepath	文件	✕	✓	✕	-
my.getsavedfileinfo 入参 apfilepath	文件	✕	✓	✕	-
my.downloadfile 入参 filepath	网络	✓	✓	✓	10.2.80 开始支持本地临时文件、本地缓存文件、本地用户文件。
my.uploadfile 入参 filepath	网络	✓	✓	✓	10.2.80 开始支持本地缓存文件、本地用户文件。
filesystemmanager.savefile 入参 tempfilepath	文件	✓	✓	✓	-

相关问题