chrome.fileBrowserHandler

Description

使用 chrome.fileBrowserHandler API 扩展 Chrome 操作系统文件浏览器。例如，您可以使用此 API 使用户能够将文件上传到您的网站。

Permissions

fileBrowserHandler

Availability

Foreground only

当用户按 Alt+Shift+M 或连接外部存储设备（例如 SD 卡、USB 密钥、外部驱动器或数码相机）时，Chrome 操作系统文件浏览器就会出现。除了显示外部设备上的文件外，文件浏览器还可以显示用户之前保存到系统中的文件。

当用户选择一个或多个文件时，文件浏览器会添加代表这些文件的有效处理程序的按钮。例如，在以下屏幕截图中，选择带有“.png”后缀的文件会导致用户可以单击“保存到图库”按钮。

# Manifest

您必须在扩展清单（extension manifest）中声明“fileBrowserHandler”权限，并且必须使用“file_browser_handlers”字段将扩展注册为至少一种文件类型的处理程序。您还应该提供一个 16x16 的图标以显示在按钮上。例如：

{
  "name": "My extension",
  ...
  "file_browser_handlers": [
    {
      "id": "upload",
      "default_title": "Save to Gallery", // What the button will display
      "file_filters": [
        "filesystem:*.jpg",  // To match all files, use "filesystem:*.*"
        "filesystem:*.jpeg",
        "filesystem:*.png"
      ]
    }
  ],
  "permissions" : [
    "fileBrowserHandler"
  ],
  "icons": {
    "16": "icon16.png",
    "48": "icon48.png",
    "128": "icon128.png"
  },
  ...
}

注意：您可以为“default_title”的值指定特定于语言环境的字符串。有关详细信息，请参阅国际化 (i18n)Internationalization (i18n)。

# Implementing a file browser handler(实现文件浏览器处理程序)

要使用此 API，您必须实现一个函数来处理 chrome.fileBrowserHandler 的 onExecute 事件。只要用户单击代表您的文件浏览器处理程序的按钮，就会调用您的函数。在您的函数中，使用文件系统 API（File System API ）来访问文件内容。下面是一个例子：

chrome.fileBrowserHandler.onExecute.addListener(async (id, details) => {
  if (id !== 'upload') {
    return;  // check if you have multiple file_browser_handlers
  }

  for (const entry of detail.entries) {
    // the FileSystemFileEntry doesn't have a Promise API, wrap in one
    const file = await new Promise((resolve, reject) => {
      entry.file(resolve, reject);
    });
    const buffer = await file.arrayBuffer();
    // do something with buffer
  }
});

您的事件处理程序传递了两个参数：

• id

  清单文件中的“id”值。如果您的扩展实现了多个处理程序，您可以检查 id 值以查看触发了哪个处理程序。

• details

  描述事件的对象。您可以从该对象的条目entries字段中获取用户选择的一个或多个文件，该对象是一个 FileSystemFileEntry 对象数组。

Summary

• Types

  FileHandlerExecuteEventDetails

• Methods

  selectFile

• Events

  onExecute

Types

FileHandlerExecuteEventDetails

fileBrowserHandler.onExecute 事件的事件详细信息负载。

PROPERTIES

• entries

  any[]

  表示作为此操作目标文件的条目实例数组（在 ChromeOS 文件浏览器中选择）。

• tab_id

  number optional

  引发此事件的选项卡的 ID。标签 ID 在浏览器会话中是唯一的。

Methods

selectFile

chrome.fileBrowserHandler.selectFile(
  selectionParams: object,
  callback?: function,
)

Promise

提示用户选择应保存文件的文件路径。选择文件后，调用方将授予使用该文件所需的文件访问权限（读取、写入和创建）。该文件实际上不会在函数调用期间创建，因此函数调用者在使用它之前必须确保它的存在。必须使用用户手势调用该函数。

PARAMETERS

• selectionParams

  object

  选择文件时将使用的参数。

  • allowedFileExtensions

    string[] optional

    所选文件可以具有的文件扩展名列表。该列表还用于指定要在选择文件对话框中显示的文件。具有所列扩展名的文件仅显示在对话框中。扩展不应包含前导“.”。示例：['jpg', 'png']

  • suggestedName

    string

    文件的建议名称。

• callback

  function optional

  The callback parameter looks like:

  (result: object) => void

  • result

    object

    方法的结果。

    • entry

      object optional

      选定的文件条目(entry)。如果尚未选择文件，它将为空。

    • success

      boolean

      文件是否被选中。

RETURNS

• Promise<object>

  Pending

  这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

Events

onExecute

chrome.fileBrowserHandler.onExecute.addListener(
  callback: function,
)

从 ChromeOS 文件浏览器执行文件系统操作时触发。

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (id: string, details: FileHandlerExecuteEventDetails) => void

  • id

    string

  • details

    FileHandlerExecuteEventDetails

By.一粒技术服务.