相对于当前逻辑根、使用 / 分隔的规范路径。必须是非空字符串,不能以
/ 开头或结尾,不能包含空 segment、反斜杠、NUL 或其他控制字符;任一 segment 恰为 . 或
.. 都会拒绝,包括整个参数 '.'。.env、report..json 等不等于点段的普通名称可以使用。
当前 SDK session 内延迟访问目标文件的冻结
FileHandle。其 kind 固定为 'file',name 是
relativePath 的末段 basename,mode 继承当前逻辑根;因此 files.sandbox.file() 返回
readwrite,从用户选择目录继续派生时则继承所选目录的 read 或 readwrite,不能通过子路径
提升权限。
HbMiniProgramSDKError
relativePath 不是字符串、为空、以 / 开头或结尾,包含连续 /、任一 . / .. 点段、
反斜杠或控制字符时,同步抛出 INVALID_PARAMS。
该方法同步校验路径并创建 lazy proxy,不检查文件是否存在或创建文件,不读取内容或元数据,不发送
bridge 请求,也不会打开系统选择器。调用本身因此不需要用户手势,不会触发 Host operation,
不会占用 pickFiles() / saveFile() 的 direct handle 配额,也不会暴露宿主真实路径。
后续 I/O 才要求在 package.json#heybox.permissions 中声明并启用 filesystem,并由 Host 开放
对应 operation:FileHandle 的 create()、remove()、
exists()、readText()、readBytes()、writeText()、writeBytes()、stat() 分别使用
file.create、file.remove、file.exists、file.readText、file.readBytes、file.writeText、
file.writeBytes、file.stat。当前运行快照缺少或未启用所需权限时分别返回 PERMISSION_NOT_IN_SNAPSHOT 或
PERMISSION_DENIED,Host 未开放具体 operation 时返回 METHOD_FORBIDDEN;这些错误在调用异步
方法时发生,不由本方法抛出。
代理只表达目标位置。exists() 可区分文件缺失或目标实际为目录;create() 可显式确保文件存在,
writeText() / writeBytes() 也可隐式创建目标文件,但不会自动创建缺失的父目录。只读父目录派生
的文件可以读取与查询,调用 create()、写入或删除会返回 FILE_ACCESS_DENIED;外部目录派生的
文件即使是 readwrite 也不能删除。
若目标是目录或需要先创建父目录,使用 files.sandbox.directory()。若要让用户选择现有的精确外部 文件,使用 files.pickFiles();若要让用户指定新的精确可写目标, 使用 files.saveFile()。
import hbSDK from '@heybox/hb-sdk'
// 构造代理时没有 I/O,且不会隐式创建 reports 目录。
const report = hbSDK.files.sandbox.file('reports/latest.json')
console.log(report.kind, report.name, report.mode)
// file, latest.json, readwrite
await hbSDK.files.sandbox.directory('reports').create({ recursive: true })
await report.writeText(JSON.stringify({ generatedAt: Date.now() }))
if (await report.exists()) {
console.log(await report.readText())
console.log((await report.stat()).size)
}
按规范相对路径派生文件代理。