@nativescript/firebase-storage

内容

• 简介
• 为您的应用设置和初始化 Firebase
• 创建一个默认的 Cloud Storage 存储桶
• 将 Firebase Cloud Storage SDK 添加到您的应用
• 创建一个 Firebase Storage 实例
• 创建一个文件引用
• 上传文件
• 处理任务
  • 检查上传/下载任务进度
  • 暂停和恢复任务
• 生成新的下载 URL
• 列出存储桶引用中的文件和目录
• 自定义安全规则
• 切换存储桶
• API
  • 存储类
    • android
    • ios
    • app
    • maxDownloadRetryTime
    • maxOperationRetryTime
    • maxUploadRetryTime
    • constructor()
    • useEmulator()
    • ref()
    • refFromURL()
  • 引用对象
    • android
    • ios
    • bucket
    • fullPath
    • name
    • parent
    • root
    • storage
    • child()
    • delete()
    • getDownloadURL()
    • getMetadata()
    • list()
    • listAll()
    • put()
    • putFile()
    • putString()
    • updateMetadata()
    • writeToFile()
  • 任务对象
    • android
    • ios
    • snapshot
    • on()
    • pause()
    • resume()
    • cancel()

简介

此插件允许您在 Nativescript 应用中使用原生 Firebase SDK 进行 Cloud Storage。

为您的应用设置和初始化 Firebase

要使用 Firebase Cloud Storage，您首先需要初始化 Firebase。要为 NativeScript 应用设置和初始化 Firebase，请按照 @nativescript/firebase-core 插件的文档说明操作。

创建一个默认的 Cloud Storage 存储桶

要创建一个默认的 Cloud Storage 存储桶，请按照 创建一个默认的 Cloud Storage 存储桶 的说明进行操作。

将 Firebase Cloud Storage SDK 添加到您的应用

要将 Cloud Storage SDK 添加到您的应用中，请安装并导入 @nativescript/firebase-storage 插件。

1. 在项目的根目录中运行以下命令以安装插件。

npm install @nativescript/firebase-storage

2. 要添加 Firestore SDK，导入 @nativescript/firebase-storage 插件。您应该在应用项目中只导入一次插件，最佳位置是在应用的启动文件（例如 app.ts、main.ts 等）。

创建一个 Firebase Storage 实例

要创建一个新的 Storage 实例，请在 FirebaseApp 实例上调用实例获取器，即 storage() 方法。

import { firebase } from '@nativescript/firebase-core';

const storage = firebase().storage();

默认情况下，这允许您使用在平台上安装 Firebase 时使用的默认 Firebase App 与 Firebase Storage 交互。但是，如果您想使用辅助 Firebase App，请在调用 storage 方法时传递辅助应用实例。

import { firebase } from '@nativescript/firebase-core';
import '@nativescript/firebase-storage';

// create secondary app instance
const config = new FirebaseOptions();
const secondaryApp = firebase.initializeApp(config, 'SECONDARY_APP');

const storage = firebase().storage(secondaryApp);

您可以在 Firebase 控制台 中查看您的存储桶。

创建一个文件引用

引用是对存储桶中某个文件的本地指针。这可以是已经存在的文件，也可以是尚未存在的文件。

• 要创建引用，请调用 ref 方法，并将其文件名（包括扩展名）传递给 Storage 实例。

import { firebase } from '@nativescript/firebase-core';
import '@nativescript/firebase-storage';

const reference = firebase().storage().ref('black-t-shirt-sm.png');

• 您还可以指定位于深层嵌套目录中的文件

import { firebase } from '@nativescript/firebase-core';
const reference = firebase().storage().ref('/images/t-shirts/black-t-shirt-sm.png');

上传文件

要从用户的设备直接上传文件，请按照以下步骤操作

1. 创建要上传的文件的引用。

import { firebase } from '@nativescript/firebase-core';

const reference = firebase().storage().ref('black-t-shirt-sm.png');

-2. 获取用户设备上文件的路径。例如，

import { knownfolders } from '@nativescript/core';

const pathToFile = knownFolders.documents().getFile('black-t-shirt-sm.png');
const filePath = pathToFile.path;

• 在引用上调用putFile方法，并传递本地文件的路径。

await reference.putFile(filePath);

处理任务

在上面的示例中，putFile方法返回一个Task对象，允许您挂钩到当前上传进度等信息。

检查上传/下载任务进度

要检查当前任务进度，可以监听任务上的state_changed事件

const task = reference.putFile(pathToFile);

task.on('state_changed', (taskSnapshot) => {
	console.log(`${taskSnapshot.bytesTransferred} transferred out of ${taskSnapshot.totalBytes}`);
});

task.then(() => {
	console.log('Image uploaded to the bucket!');
});

暂停和恢复任务

任务还提供了暂停和恢复正在进行操作的能力。要暂停任务，请调用pause方法，要恢复，请调用resume方法

const task = reference.putFile(pathToFile);

task.pause();

// Sometime later...
task.resume();

生成新的下载 URL

云存储的常见用例是将其用作全局内容分发网络（CDN）来存储您的图像。当将文件上传到存储桶时，它们不会自动通过HTTP URL可供消费。要生成新的下载URL，您需要在引用上调用getDownloadURL方法

import { firebase } from '@nativescript/firebase-core';

const url = firebase().storage().ref('images/profile-1.png').getDownloadURL();

列出存储桶引用中的文件和目录

要查看特定存储桶引用中当前文件和目录的完整列表，请在引用实例上调用list。结果被分页，如果有更多结果，可以在请求中传递分页令牌

import { firebase } from '@nativescript/firebase-core';

function listFilesAndDirectories(reference, pageToken) {
	return reference.list({ pageToken }).then((result) => {
		// Loop over each item
		result.items.forEach((ref) => {
			console.log(ref.fullPath);
		});

		if (result.nextPageToken) {
			return listFilesAndDirectories(reference, result.nextPageToken);
		}

		return Promise.resolve();
	});
}

const reference = firebase().storage().ref('images');

listFilesAndDirectories(reference).then(() => {
	console.log('Finished listing');
});

自定义安全规则

默认情况下，您的存储桶将包含规则，只允许您的项目中的认证用户访问它。但是，您可以完全自定义安全规则以满足应用程序的需求。

有关更多信息，请参阅Firebase网站上的Firebase安全规则入门文档。

切换存储桶

单个Firebase项目可以有多个存储桶。如果没有将存储桶参数传递给存储实例，则模块将使用默认存储桶。要切换存储桶，向模块提供Firebase控制台下存储 > 文件中找到的gs://存储桶URL。

import { firebase, FirebaseOptions } from '@nativescript/firebase-core';
const defaultStorageBucket = firebase().storage();
const config = new FirebaseOptions();
config.storageBucket = 'gs://my-secondary-bucket.appspot.com';
const secondaryApp = firebase.app(config, 'SECONDARY_APP');
const secondaryStorageBucket = firebase().storage(secondaryApp);

API

存储类

android

import { firebase } from '@nativescript/firebase-core';

storageAndroid: com.google.firebase.storage.FirebaseStorage = firebase().storage().android;

一个只读属性，返回底层的本地Android对象。

ios

import { firebase } from '@nativescript/firebase-core';

storageIOS: FIRStorage = firebase().storage().ios;

一个只读属性，返回底层的本地iOS对象。

app

import { firebase } from '@nativescript/firebase-core';

storageApp: FirebaseApp = firebase().storage().app;

一个只读属性，返回此Storage所属的FirebaseApp实例。

maxDownloadRetryTime

import { firebase } from '@nativescript/firebase-core';

maxDownloadRetryTime: number = firebase().storage().maxDownloadRetryTime;
// or

返回或设置在失败的情况下重试下载的最大时间，以毫秒为单位。

maxOperationRetryTime

import { firebase } from '@nativescript/firebase-core';

maxOperationRetryTime: number = firebase().storage().maxOperationRetryTime;

返回或设置在失败的情况下重试除上传或下载之外操作的最大时间，以毫秒为单位。

maxUploadRetryTime

import { firebase } from '@nativescript/firebase-core';

maxUploadRetryTime: number = firebase().storage().maxUploadRetryTime;

获取或设置在失败的情况下重试上传的最大时间，以毫秒为单位。

constructor()

import { firebase } from '@nativescript/firebase-core';

new Storage(app);

useEmulator()

import { firebase } from '@nativescript/firebase-core';

firebase().storage().useEmulator(host, port);

尝试连接到在给定主机和端口上本地运行的存储模拟器。

ref()

import { firebase } from '@nativescript/firebase-core';

reference: Reference = firebase().storage().ref(path);

创建一个新的存储引用，如果未提供路径参数，则初始化在根Firebase Storage位置，如果提供路径参数，则初始化在给定的路径。

refFromURL()

import { firebase } from '@nativescript/firebase-core';

reference: Reference = firebase().storage().refFromURL(url);

从特定URL初始化一个新的存储引用。

引用对象

android

referenceAndroid: com.google.firebase.storage.StorageReference = reference.android;

一个只读属性，返回Android的底层本地StorageReference对象。

ios

referenceIOS: FIRStorageReference = reference.ios;

一个只读属性，返回iOS的底层本地StorageReference对象。

bucket

bucket: string = reference.bucket;

一个只读属性，返回包含此引用对象的存储桶的名称。

fullPath

fullPath: string = reference.fullPath;

一个只读属性，返回此对象的完整路径，不包括Google Cloud Storage存储桶。

name

name: string = reference.name;

一个只读属性，返回此对象路径的简称，即完整路径的最后一个组件。

parent

parent: Reference = reference.parent;

一个只读属性，返回当前引用的父引用的引用，如果当前引用是根，则为null。

root

root: Reference = reference.root;

一个只读属性，返回当前引用存储桶的根的引用。

storage

storage: Storage = reference.storage;

一个只读属性，返回与引用相关联的 存储 实例。

child()

reference: Reference = reference.child(path);

返回当前引用的相对路径的引用。有关更多信息，请参阅 Firebase 网站上的 child。

delete()

reference.delete();

删除当前引用位置的对象。

getDownloadURL()

downloadURL: string = await reference.getDownloadURL();

异步检索具有可撤销令牌的长期下载 URL。有关更多信息，请参阅 Firebase 网站上的 getDownloadUrl。

getMetadata()

metadata: Metadata = await reference.getMetadata();

异步检索与当前引用位置的对象相关联的元数据。有关此方法的更多描述，请参阅 Firebase 网站上的 getMetadata。

可以在 此处 找到元数据对象的属性。

list()

listResult: ListResult = await reference.list(options);

返回此 StorageReference 下的项（文件）和前缀（文件夹）。

列表选项接口

interface ListOptions {
	maxResults: undefined | number;
	pageToken: undefined | string;
}

listAll()

listResult: ListResult = await reference.listAll();

异步返回此 StorageReference 下的所有项（文件）和前缀（文件夹）的列表。有关更多信息，请参阅 Firebase 网站上的 listAll。

put()

task: Task = reference.put(data, metadata);

将数据上传到此引用的位置。有关更多信息，请参阅 Firebase 网站上的 putBytes。

putString()

stringTask: Task = reference.putString(data, format, metadata);

将字符串数据以字节形式从字符串上传到此引用的位置。

StringFormat 枚举

enum StringFormat {
	RAW = 'raw',
	BASE64 = 'base64',
	BASE64URL = 'base64url',
	DATA_URL = 'data_url',
}

putFile()

fileTask: Task = reference.putFile(path, metadata);

将文件上传到此引用的位置。

updateMetadata()

updatedMetadata: FullMetadata = await reference.updateMetadata(metadata);

更新与此引用相关联的指定元数据。有关更多信息，请参阅 Firebase 网站上的 updateMetadata。

writeToFile()

fileWriteTask: Task = reference.writeToFile(localFilePath);

将此引用位置的对象下载到指定的系统文件路径。有关更多信息，请参阅 Firebase 网站上的 writeToFile。

任务对象

android

taskAndroid: com.google.firebase.storage.FileDownloadTask.TaskSnapshot | com.google.firebase.storage.UploadTask.TaskSnapshot = task.android;

一个只读属性，返回原生 Android 对象。

ios

taskIOS: FIRStorageUploadTask | FIRStorageDownloadTask = task.ios;

一个只读属性，返回原生 iOS 对象。

snapshot

taskSnapshot: TaskSnapshot = task.snapshot;

on()

task.on(event, nextOrObserver, error, complete);

任务事件枚举

enum TaskEvent {
	STATE_CHANGED = 'state_changed',
}

cancel()

cancelled: boolean = task.cancel();

取消当前上传或下载任务。

pause()

paused: boolean = task.pause();

暂停当前上传或下载任务。

resume()

resumed: boolean = task.resume();

恢复当前上传或下载任务。

许可证

Apache 许可证版本 2.0