相对于当前逻辑根、使用 / 分隔的规范路径。必须是非空字符串,不能以
/ 开头或结尾,不能包含空 segment、反斜杠、NUL 或其他控制字符。. 是仅有的特例:只有
整个参数等于 '.' 时才表示当前逻辑根;./cache、cache/.、cache/../secret 等含点段路径
不会被折叠或解析,而会直接拒绝。
当前 SDK session 内延迟访问目标目录的冻结
DirectoryHandle。其 kind 固定为
'directory',name 是末段 basename(传 '.' 时为 '.'),mode 继承当前逻辑根;因此
files.sandbox.directory() 返回 readwrite,从用户选择目录继续派生时则继承所选目录的
read 或 readwrite,不能通过子路径提升权限。
HbMiniProgramSDKError
relativePath 不是字符串、为空、以 / 开头或结尾,包含连续 /、任何 . / .. 点段、
反斜杠或控制字符时,同步抛出 INVALID_PARAMS;完整参数 '.' 除外。
该方法同步校验路径并创建 lazy proxy,不检查目录是否存在或创建目录,不执行文件 I/O,不发送
bridge 请求,也不会打开系统选择器。调用本身因此不需要用户手势,不会触发 Host operation,
不会占用 picker / saveFile() 的 direct handle 配额,也不会暴露宿主真实路径。
后续 I/O 才要求在 package.json#heybox.permissions 中声明并启用 filesystem,并由 Host 开放
对应 operation:DirectoryHandle 的 create()、
exists()、list()、remove() 分别使用 directory.create、directory.exists、
directory.list、directory.remove。当前运行快照缺少或未启用所需权限时分别返回
PERMISSION_NOT_IN_SNAPSHOT 或 PERMISSION_DENIED,Host 未开放具体 operation 时返回
METHOD_FORBIDDEN;这些错误在调用异步方法时发生,不由本方法抛出。
files.sandbox.directory('.') 是沙箱根目录的逻辑代理,可用于 exists() 或 list(),但不能删除;
对它调用 remove() 会返回 FILE_ACCESS_DENIED。普通子目录代理只表达目标位置:需要确保目录
存在时调用 create(),需要观察直接子项时调用 list()。若目标是文件,使用
files.sandbox.file();若要访问用户选择的外部目录,使用
files.pickDirectory()。
import hbSDK from '@heybox/hb-sdk'
// 构造代理时没有 I/O;父目录也不会被隐式创建。
const reports = hbSDK.files.sandbox.directory('reports/2026')
console.log(reports.kind, reports.name, reports.mode)
// directory, 2026, readwrite
await reports.create({ recursive: true })
// `.` 只作为完整参数表示沙箱根;它不是可嵌入路径的点段。
const root = hbSDK.files.sandbox.directory('.')
const entries = await root.list({ limit: 100 })
console.log(entries.map(entry => entry.name))
create()、exists()、list() 与 remove()。
按规范相对路径派生目录代理。