@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...

    方法 directory

    • 按规范相对路径派生目录代理。

      参数

      • relativePath: string

        相对于当前逻辑根、使用 / 分隔的规范路径。必须是非空字符串,不能以 / 开头或结尾,不能包含空 segment、反斜杠、NUL 或其他控制字符。. 是仅有的特例:只有 整个参数等于 '.' 时才表示当前逻辑根;./cache、cache/.、cache/../secret 等含点段路径 不会被折叠或解析,而会直接拒绝。

      返回 DirectoryHandle

      当前 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))

      0.8.0

      android

      ios

      ohos

      windows

      macos

      android numeric-dot >= 1.3.396

      ios numeric-dot >= 1.3.396

      ohos none

      windows none

      macos none