8.7 发布—WinterCG 兼容性第 1 部分
了解更多

在 GitHub 上查看

@nativescript/firebase-storage ​

内容 ​

简介 ​

此插件允许您在 Nativescript 应用中使用针对 云存储 的原生 Firebase SDK。

image

设置并初始化应用的 Firebase ​

要使用 Firebase 云存储，您需要先初始化 Firebase。要为 NativeScript 应用设置并初始化 Firebase，请按照 @nativescript/firebase-core 插件文档中的说明进行操作。

创建默认的云存储桶 ​

要创建默认的云存储桶，请按照 创建默认的云存储桶 中的说明进行操作。

将 Firebase 云存储 SDK 添加到应用中 ​

要将云存储 SDK 添加到应用中，请安装并导入 @nativescript/firebase-storage 插件。

  1. 通过在项目的根目录中运行以下命令来安装插件。
cli
npm install @nativescript/firebase-storage
  1. 要添加 Firestore SDK，请导入 @nativescript/firebase-storage 插件。您应该在应用项目中导入一次插件，最理想的位置是应用引导文件（app.ts、main.ts 等）。

创建 Firebase 存储实例 ​

要创建新的存储实例，请在 FirebaseApp 实例上调用实例获取器 storage() 方法。

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

const storage = firebase().storage()

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

ts
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 Console 上查看存储桶。

创建文件引用 ​

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

  • 要创建引用，请在 Storage 实例上调用 ref 方法，并向其传递带有扩展名的文件名。
ts
import { firebase } from '@nativescript/firebase-core'
import '@nativescript/firebase-storage'

const reference = firebase().storage().ref('black-t-shirt-sm.png')
  • 您也可以指定位于深度嵌套目录中的文件。
ts
import { firebase } from '@nativescript/firebase-core'
const reference = firebase()
  .storage()
  .ref('/images/t-shirts/black-t-shirt-sm.png')

上传文件 ​

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

  1. 创建对要上传文件的引用。
ts
import { firebase } from '@nativescript/firebase-core'

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

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

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

const pathToFile = knownFolders.documents().getFile('black-t-shirt-sm.png')
const filePath = pathToFile.path
  • 在引用上调用 putFile 方法，并向其传递本地文件的路径。
ts
await reference.putFile(filePath)

处理任务 ​

上一个示例中的 putFile 方法返回一个 Task 对象，它允许您连接到诸如当前上传进度之类的信息。

检查上传/下载任务进度 ​

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

ts
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 方法。

ts
const task = reference.putFile(pathToFile)

task.pause()

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

生成新的下载 URL ​

云存储的一个常见用例是将其用作图像的全局内容交付网络 (CDN)。将文件上传到存储桶时，它们不会自动可通过 HTTP URL 使用。要生成新的下载 URL，您需要在引用上调用 getDownloadURL 方法。

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

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

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

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

ts
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 Console 的 Storage > Files 下找到的 gs:// 存储桶 URL。

ts
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 ​

Storage 类 ​

android ​

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

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

返回基础原生 Android 对象的 只读 属性。

ios ​

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

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

返回基础原生 iOS 对象的 只读 属性。

app ​

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

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

返回此 Storage 隶属的 FirebaseApp 实例的 只读 属性。

maxDownloadRetryTime ​

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

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

返回或设置在发生故障时重试下载的最大时间（以毫秒为单位）。

maxOperationRetryTime ​

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

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

返回或设置在发生故障时重试除上传或下载以外的操作的最大时间（以毫秒为单位）。

maxUploadRetryTime ​

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

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

获取或设置在发生故障时重试上传的最大时间（以毫秒为单位）。

constructor() ​

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

new Storage(app)
参数类型描述
appFirebaseApp可选：此 Storage 隶属的 FirebaseApp 实例。

useEmulator() ​

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

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

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

参数类型描述
hoststring模拟器主机。
portnumber模拟器端口。

ref() ​

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

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

创建一个新的存储 reference，如果未提供路径参数，则将其初始化在根 Firebase 存储位置，或者如果提供了路径参数，则将其初始化在给定路径上。

参数类型描述
pathstring可选：初始化引用的路径。

refFromURL() ​

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

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

创建一个新的存储 reference，从特定 URL 初始化。

参数类型描述
urlstring从其初始化引用的 URL。

引用对象 ​

android ​

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

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

ios ​

ts
referenceIOS: FIRStorageReference = reference.ios

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

bucket ​

ts
bucket: string = reference.bucket

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

fullPath ​

ts
fullPath: string = reference.fullPath

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

name ​

ts
name: string = reference.name

一个 只读 属性，返回此对象路径的短名称，它是完整路径的最后一个组件。

parent ​

ts
parent: Reference = reference.parent

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

root ​

ts
root: Reference = reference.root

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

storage ​

ts
storage: Storage = reference.storage

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

child() ​

ts
reference: Reference = reference.child(path)

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

参数类型描述
pathstring子路径。

delete() ​

ts
reference.delete()

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

getDownloadURL() ​

ts
downloadURL: string = await reference.getDownloadURL()

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

getMetadata() ​

ts
metadata: Metadata = await reference.getMetadata()

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

您可以在 此处 找到 Metadata 对象的属性。

list() ​

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

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

参数类型描述
optionsListOptions可选 : 用于配置列表操作的对象。ListOptions 属性在 list Firebase 文档上的方法中描述。

ListOptions 接口 ​

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

listAll() ​

ts
listResult: ListResult = await reference.listAll()

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

put() ​

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

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

参数类型描述
dataBlob | Uint8Array | ArrayBuffer要上传的数据。
metadataMetadata可选 : 与此上传关联的元数据。

putString() ​

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

将字符串中的字节数据上传到此引用的位置。

参数类型描述
datastring要上传的 base64 字符串。
formatStringFormat要上传的字符串的格式。
metadataMetadata可选 : 与此上传关联的元数据。

StringFormat 枚举 ​

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

putFile() ​

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

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

参数类型描述
pathstring要上传的文件的路径。
metadataMetadata可选 : 与此上传关联的元数据。

updateMetadata() ​

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

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

参数类型描述
metadataMetadata要更新的元数据。

writeToFile() ​

ts
fileWriteTask: Task = reference.writeToFile(localFilePath)

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

参数类型描述
localFilePathstring应将文件下载到的路径。

任务对象 ​

android ​

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

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

ios ​

ts
taskIOS: FIRStorageUploadTask | FIRStorageDownloadTask = task.ios;

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

snapshot ​

ts
taskSnapshot: TaskSnapshot = task.snapshot

on() ​

ts
task.on(event, nextOrObserver, error, complete)
参数类型描述
eventTaskEvent事件名称。
nextOrObserver((a: TaskSnapshot) => any) | TaskSnapshotObserver可选 : 观察者对象或在每个事件上调用的函数。
error(a: FirebaseError) => any可选 : 在错误时调用的函数。
complete() => void可选 : 在完成时调用的函数。

TaskEvent 枚举 ​

ts
enum TaskEvent {
  STATE_CHANGED = 'state_changed',
}

cancel() ​

ts
cancelled: boolean = task.cancel()

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

pause() ​

ts
paused: boolean = task.pause()

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

resume() ​

ts
resumed: boolean = task.resume()

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

License ​

Apache License Version 2.0

Next
NativeScript UI ListView