@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 按规范相对路径派生文件代理。

      参数

      • relativePath: string

        相对于当前逻辑根、使用 / 分隔的规范路径。必须是非空字符串,不能以 / 开头或结尾,不能包含空 segment、反斜杠、NUL 或其他控制字符;任一 segment 恰为 . 或 .. 都会拒绝,包括整个参数 '.'。.env、report..json 等不等于点段的普通名称可以使用。

      返回 FileHandle

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

      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