快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-firebase-storage` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-firebase-storage
npx cap sync

导入

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

快速入门

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

await FirebaseStorage.deleteFile({ path: 'mountains.png' });

示例：getDownloadUrl

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

const result = await FirebaseStorage.getDownloadUrl({ path: 'mountains.png' });
console.log(result);

示例：getMetadata

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

const result = await FirebaseStorage.getMetadata({ path: 'mountains.png' });
console.log(result);

常见坑点

• 原生同步：运行 npx cap sync 在插件升级后。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

API 概览

deleteFile

删除文件。

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

await FirebaseStorage.deleteFile({ path: 'mountains.png' });

getDownloadUrl

获取文件的下载链接。

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

const result = await FirebaseStorage.getDownloadUrl({ path: 'mountains.png' });
console.log(result);

getMetadata

获取文件的元数据。

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

const result = await FirebaseStorage.getMetadata({ path: 'mountains.png' });
console.log(result);

listFiles

列出目录中的文件。

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

const result = await FirebaseStorage.listFiles({ path: 'path/to/file' });
// The result holds sensitive values: use it without logging it.

updateMetadata

更新文件的元数据。

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

await FirebaseStorage.updateMetadata({
  path: 'path/to/file',
  metadata: {},
});

uploadFile

上传文件。

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

const result = await FirebaseStorage.uploadFile({ path: 'mountains.png' }, (event, error) => {
  console.log(event);
});
console.log(result);

useEmulator

配置您的 App 以连接 Cloud Storage 模拟器。

在 Android 上，必须允许明文流量。在 Capacitor 配置中：

{
  server: {
    cleartext: true
  }
}

明文流量不适用于生产环境。

import { FirebaseStorage } from '@capgo/capacitor-firebase-storage';

await FirebaseStorage.useEmulator({ host: "127.0.0.1" });

类型参考

DeleteFileOptions

export interface DeleteFileOptions {
  /**
   * The full path to the file to delete, including the file name.
   *
   * @since 5.3.0
   * @example 'mountains.png'
   * @example 'images/mountains.png'
   */
  path: string;
}

GetDownloadUrlOptions

export interface GetDownloadUrlOptions {
  /**
   * The full path to the file to get the download url for, including the file name.
   *
   * @since 5.3.0
   * @example 'mountains.png'
   * @example 'images/mountains.png'
   */
  path: string;
}

GetDownloadUrlResult

export interface GetDownloadUrlResult {
  /**
   * The download url for the file.
   *
   * @since 5.3.0
   */
  downloadUrl: string;
}

GetMetadataOptions

export interface GetMetadataOptions {
  /**
   * The full path to the file to get the metadata for, including the file name.
   *
   * @since 5.3.0
   * @example 'mountains.png'
   * @example 'images/mountains.png'
   */
  path: string;
}

GetMetadataResult

export interface GetMetadataResult {
  /**
   * The bucket this file is contained in.
   *
   * @since 5.3.0
   */
  bucket: string;
  /**
   * The timestamp at which the file was created in milliseconds since the epoch.
   *
   * @since 5.3.0
   * @example 1697304435933
   */
  createdAt?: number;
  /**
   * The object's generation.
   *
   * @since 5.3.0
   * @see https://cloud.google.com/storage/docs/metadata#generation-number
   */
  generation: string;
  /**
   * The md5 hash of the file.
   *
   * @since 5.3.0
   */
  md5Hash?: string;
  /**
   * The object's metadata generation.
   *
   * @since 5.3.0
   * @see https://cloud.google.com/storage/docs/metadata#generation-number
   */
  metadataGeneration: string;
  /**
   * The short name of this file, which is the last component of the full path.
   *
   * @since 5.3.0
   * @example 'mountains.png'
   */
  name?: string;
  /**
   * The full path to the file, including the file name.
   *
   * @since 5.3.0
   * @example 'images/mountains.png'
   */
  path?: string;
  /**
   * The size of the file in bytes.
   *
   * @since 5.3.0
   */
  size: number;
  /**
   * The timestamp at which the file was last updated in milliseconds since the epoch.
   *
   * @since 5.3.0
   * @example 1697304435933
   */
  updatedAt: number;
  /**
   * Served as the `Cache-Control` header on object download.
   *
   * @since 6.1.0
   */
  cacheControl?: string;
  /**
   * Served as the `Content-Disposition` header on object download.
   *
   * @since 6.1.0
   */
  contentDisposition?: string;
  /**
   * Served as the `Content-Encoding` header on object download.
   *
   * @since 6.1.0
   */
  contentEncoding?: string;
  /**
   * Served as the `Content-Language` header on object download.
   *
   * @since 6.1.0
   */
  contentLanguage?: string;
  /**
   * Served as the `Content-Type` header on object download.
   *
   * @since 6.1.0
   */
  contentType?: string;
  /**
   * Additional user-defined custom metadata.
   *
   * @since 6.1.0
   */
  customMetadata?: { [key: string]: string };
}

ListFilesOptions

export interface ListFilesOptions {
  /**
   * The full path to the directory to list files for.
   *
   * @since 5.3.0
   */
  path: string;
  /**
   * The maximum number of results to return.
   *
   * @since 5.3.0
   * @default 1000
   */
  maxResults?: number;
  /**
   * The page token, returned by a previous call to this method.
   * If provided, listing is resumed from the previous position.
   *
   * @since 5.3.0
   */
  pageToken?: string;
}

ListFilesResult

export interface ListFilesResult {
  /**
   * The list of files in the directory.
   *
   * @since 5.3.0
   */
  items: StorageReference[];
  /**
   * If set, there might be more results for this list.
   * Use this token to resume the list.
   *
   * @since 5.3.0
   */
  nextPageToken?: string;
}

UpdateMetadataOptions

export interface UpdateMetadataOptions {
  /**
   * The full path to the file to update the metadata for, including the file name.
   *
   * @since 5.3.0
   */
  path: string;
  /**
   * The metadata to update.
   *
   * @since 5.3.0
   */
  metadata: SettableMetadata;
}

UploadFileOptions

export interface UploadFileOptions {
  /**
   * The data to upload.
   *
   * Only available for Web.
   *
   * @since 5.3.0
   */
  blob?: Blob;
  /**
   * The full path where data should be uploaded, including the file name.
   *
   * @since 5.3.0
   * @example 'mountains.png'
   * @example 'images/mountains.png'
   */
  path: string;
  /**
   * The uri to the file to upload.
   *
   * Only available for Android and iOS.
   *
   * @since 5.3.0
   * @example 'content://com.google.android.apps.photos.contentprovider/-1/1/content://media/external/images/media/1000000214/ORIGINAL/NONE/image/.png/mountains'
   * @example 'file:///var/mobile/Containers/Data/Application/E397A70D-67E4-4258-236E-W1D9E12111D4/Library/Caches/092F8464-DE60-40B3-8A23-EB83160D9F9F/mountains.png'
   */
  uri?: string;
  /**
   * The metadata to set for the file.
   *
   * @since 5.4.0
   */
  metadata?: UploadMetadata;
}

UploadFileCallback

export type UploadFileCallback = (event: UploadFileCallbackEvent | null, error: any) => void;

CallbackId

export type CallbackId = string;

UseEmulatorOptions

export interface UseEmulatorOptions {
  /**
   * The emulator host without any port or scheme.
   *
   * Note when using a Android Emulator device: 10.0.2.2 is the special IP address to connect to the 'localhost' of the host computer.
   *
   * @since 6.1.0
   * @example "127.0.0.1"
   */
  host: string;
  /**
   * The emulator port.
   *
   * @since 6.1.0
   * @default 9199
   * @example 9199
   */
  port?: number;
}

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 要规划存储和文件处理，请将其与 @capgo/capacitor-data-storage-sqlite 关于 @capgo/capacitor-data-storage-sqlite 中的实现细节， 使用 @capgo/capacitor-data-storage-sqlite 关于使用 @capgo/capacitor-data-storage-sqlite 的原生能力， @capgo/capacitor-file 关于 @capgo/capacitor-file 中的实现细节， 使用 @capgo/capacitor-file 用于“使用 @capgo/capacitor-file”中的原生能力，以及 @capgo/capacitor-uploader 了解 @capgo/capacitor-uploader. 的实现细节