@nativescript/background-http

一个允许您进行后台 HTTP 上传的插件。

内容

• 安装
• 使用 @nativescript/background-http
  • 处理上传任务事件
• API
  • init()
  • session()
    • uploadFile()
    • multipartUpload()
  • 上传请求对象
  • 任务对象
    • 任务事件
• 本地测试插件
• 许可证

安装

npm install @nativescript/background-http

使用 @nativescript/background-http

要执行后台 HTTP 调用，请按照以下步骤操作

1. 初始化后台 HTTP 服务

调用 init() 函数以初始化在后台运行的 HTTP 服务。在 main.ts 文件中，在应用启动之前尽早调用该方法。

import { init } from '@nativescript/background-http';
init();

2. 上传文件

   1. 通过调用 session() 函数并传入会话的唯一标识符字符串（例如，image-upload）来创建上传会话。

   // file path and url
   var file = '/some/local/file/path/and/file/name.jpg';
   var url = 'https://some.remote.service.com/path';
   var name = file.substr(file.lastIndexOf('/') + 1);
   
   // upload configuration
   var bghttp = require('@nativescript/background-http');
   
   var session = bghttp.session('image-upload');
   var request = {
       url: url,
       method: 'POST',
       headers: {
           'Content-Type': 'application/octet-stream',
       },
       description: 'Uploading ' + name,
   };

   2. 上传文件
   • 要发起一个简单的上传请求，调用 session 的 uploadFile() 方法并传入文件路径和一个 上传请求对象

   var task = session.uploadFile(filePath, request);

   • 要发起一个 multipart/form-data 上传请求或传递额外数据，调用 multipartUpload() 方法。所有参数值都必须是字符串

   var params = [
   { name: "test", value: "value" },
   { name: "fileToUpload", filename: file, mimeType: "image/jpeg" }
   ];
   
   var task = session.multipartUpload(params, request);

为了成功上传，您应该确保以下条件得到满足

• 文件必须可以从您的应用访问。这可能需要额外的权限（例如，访问设备上的文档和文件）。
• URL 不能被操作系统阻止。Android Pie 或更高版本默认要求 TLS（HTTPS）连接，并且不会上传到不安全的（HTTP）URL。

处理上传任务事件

Both uploadFile() 和 multipartUpload() 都会启动并返回一个 任务 实例。

上传任务启动后，您可以使用以下事件来监控其进度。

有关事件对象的更多信息，请参阅 任务事件。

task.on("progress", progressHandler);
task.on("error", errorHandler);
task.on("responded", respondedHandler);
task.on("complete", completeHandler);
task.on("cancelled", cancelledHandler); // Android only

每个事件处理程序接收一个包含事件数据的单个参数。

function progressHandler(e: ProgressEventData) {

    alert("uploaded " + e.currentBytes + " / " + e.totalBytes);
}

// event arguments:
// task: Task
// responseCode: number
// error: java.lang.Exception (Android) / NSError (iOS)
// response: net.gotev.uploadservice.ServerResponse (Android) / NSHTTPURLResponse (iOS)
function errorHandler(e: ErrorEventData) {
    alert("received " + e.responseCode + " code.");
    var serverResponse = e.response;
}


// event arguments:
// task: Task
// responseCode: number
// data: string
function respondedHandler(e: ResultEventData) {
    alert("received " + e.responseCode + " code. Server sent: " + e.data);
}

// event arguments:
// task: Task
// responseCode: number
// response: net.gotev.uploadservice.ServerResponse (Android) / NSHTTPURLResponse (iOS)
function completeHandler(e: CompleteEventData) {
    alert("received " + e.responseCode + " code");
    var serverResponse = e.response;
}

// event arguments:
// task: Task
function cancelledHandler(e: EventData) {
    alert("upload cancelled");
}

API

init()

import { init } from '@nativescript/background-http';

init()

初始化 HTTP 后台服务。

session()

import { session } from '@nativescript/background-http';
session: Session = session(id: string)

通过 ID 获取或创建后台下载/上传会话。

会话对象

会话对象具有以下成员

• uploadFile(fileUri: string, options: Request): Task
• multipartUpload(params: Array<any>, options: Request): Task

这两个方法都会启动一个新的后台文件（s）上传任务。 uploadFile() 用于单个文件上传，而 multipartUpload() 用于多个文件上传。 fileUri 是要上传文件的路径。 options 参数表示 请求对象。

上传请求对象

请求对象参数具有以下属性

注意：Android通知的标题/消息可以使用以下占位符之一构建，系统将替换它们

• [upload_rate]：替换为当前的上传速率/速度
• [upload_progress]：替换为当前的上传进度
• [upload_elapsed_time]：替换为已过时间

任务对象

任务对象具有以下属性和方法，可以用来获取上传信息

EventData

所有任务事件都扩展了EventData接口。

ProgressEventData

ResultEventData

CompleteEventData

ErrorEventData

API

init()

import { init } from '@nativescript/background-http';

init()

初始化 HTTP 后台服务。

session()

import { session } from '@nativescript/background-http';

session: Session = session(id)

通过 ID 获取或创建后台下载/上传会话。

uploadFile()

session.uploadFile(filePath,requestOptions)

session对象的一个方法，用于启动后台任务，将指定的文件编码为application/x-www-form-urlencoded。

multipartUpload()

session.multipartUpload()

session对象的一个方法，用于启动后台任务，将指定的文件编码为multipart/form-data。

上传请求对象

请求对象参数具有以下属性

注意：Android通知的标题/消息可以使用以下占位符之一构建，系统将替换它们

• [upload_rate]：替换为当前的上传速率/速度
• [upload_progress]：替换为当前的上传进度
• [upload_elapsed_time]：替换为已过时间

任务对象

任务对象具有以下属性和方法。

任务事件

以下是在后台任务的不同进度状态时发出的事件

• EventData

所有以下任务事件都扩展了前面的EventData接口。

• ProgressEventData

• ResultEventData

• CompleteEventData

• ErrorEventData

本地测试插件

要测试插件，您必须有一个服务器实例来接受上传。有一些在线服务可以用于小文件上传 - 例如 http://httpbin.org/post 然而，这些不能用于大文件。插件存储库附带了一个简单的服务器，您可以在本地运行。以下是启动它的方法

cd demo-server
npm i
node server 8080

上述命令将在端口8080上启动一个服务器。请记住更新您应用中的URL以匹配服务器运行的地址/端口。

注意：如果您使用的是iOS模拟器，则应使用http://localhost:8080上传到演示服务器。如果您使用的是Android模拟器，则应使用http://10.0.2.2:8080代替。

许可证

Apache License Version 2.0