网络活动API(WebActivity API)

网络活动API(WebActivity API)

• WebActivity API为应用程序提供一种 将自身活动委托给另一个应用的方法

• 活动(Web Activity)是用户想要做的事情，如选择图像，播放视频等

• 应用程序可以声明自己是活动处理者(Activity Handler)

  • 例如，当用户请求选择照片时，Gallery应用程序和已安装的第三方照片管理应用程序都可以作为候选项

  • 通常会向用户提供这样的一个选择列表。

• WebActivity接口同时暴露在Window和Worker作用域中

  • 在Window中，当想发出请求的应用程序可见时（在前台），则允许创建WebActivity

  • 在Worker中，如果声明并授予了worker-activity权限，则允许创建WebActivity

    • 否则将引发不安全的错误，WebActivity的创建将返回nullptr

启动一个活动

WebActivity的构造函数使用活动名称和可选的对象，指定其筛选器类型或其他信息，例如：

let activity = new WebActivity ( "pick" , { type : "image/ipeg" } ) ;     

在本例中，我们尝试启动一个“pick”活动，活动处理者程序(Activity Handler)应至少支持提供jpeg图像的选取。

注意，构造函数可能抛出并返回非法访问的空对象(null)。

然后，通过start()方法启动activity，如果启动了活动处理者程序(activity handler，在此即Gallery应用)并成功处理了请求，则将reolve出选取对象的promise出来。

activity.start().then(
  rv => {
    console.log("Results passed back from activity handler:")
    console.log(rv);
  },  
  err => {
    console.log(err);
  }
);

注意，一个WebActivity的实例只可启动一次，重复调用start()将被拒绝。

取消一个活动

要取消已启动的活动，请使用cancel()，并且start()挂起的承诺(pending promise)也将被拒绝(rejected)

activity.cancel();

处理一个活动

一旦用户选择了活动处理者程序(或由系统应用程序默认隐式选择)，名为activity的 SystemMessageEvent 将被派发到其服务工作程序(Service Worker)上的事件处理程序，与其他的系统消息不同，SystemMessageData 具有属性 WebActivityRequestHandler，它提供了解决(resolve)或拒绝(reject) activity.start()挂起承诺(pending promise)的方法。

注意，根据 ServiceWorkerGlobalScope[1] 的规范，活动处理程序(ActivityHandler)不会在工作线程中或者重新启动的周期内持久化。更多信息，请参阅 ServiceWorkerGlobalScope。

[1] 开发者应记住，ServiceWorker的状态不会在终止/重新启动周期中持久化，因此每个事件处理程序都应该假设它是用一个默认的全局状态调用的。

在处理名为 activity 的 systemmessage 事件时，处理程序可以使用 ServiceWorker API， Clients.openWindow() 来决定是否启动应用程序窗口以执行用户交互。或者可以直接使用 WebActivityRequestHandler.postResult() 传回结果。建议使用 postMessage() 方法在主脚本(main scripts)和服务工作脚本(service worker script)之间进行通信。

如果出现问题，请使用 WebActivityRequestHandler.postError() 发回错误消息。

WebActivityRequestHandler.source 是 WebActivityOptions 对象，表示从活动请求者处发送的信息。

• WebActivityOptions

  • 名称(name)，字符串，表示活动请求处的名称

  • 数据(data)，对象，表示从活动请求者处发送的数据

self.onsystemmessage = e => {
  try {
    let handler = e.data.webActivityRequestHandler();
    console.log("activity payload:");
    console.log(handler.source);
    let fakeResult = { images: ["a.jpeg", "b.png"], type: "favorite" };
    handler.postResult(fakeResult);
  } catch (err) {
    console.log(err);
  }
};

• WebActivityRequestHandler

  • source，WebActivityOptions对象，包含有关当前活动的信息。由启动活动的应用程序设置。

  • postResult()，发回响应并解析启动活动的应用程序的promise。

  • postError()，发回错误消息并拒绝启动活动的应用程序的promise。

用 Clients.openWindo w打开它的窗口

待定

将应用程序注册为活动处理程序

• 应用程序可将自身注册为活动处理程序，以处理一个或多个活动。

  • 需要在应用程序清单中声明活动相关信息

  • 需要在应用程序清单中设置服务工作者脚本

  • 示例如下：

设置ServiceWorker注册

"serviceworker": {
  "script_url": "script_url",
    "options": {
    "scope": "scope_of_sw",
      "update_via_cache": "value_of_update_via_cache"
  }
},

options对象是可选的，如 ServiceWorkerContainer.register() 语法中所定义，例如：

"serviceworker": {
  "script_url": "sw.js"
},

在大多数情况下，上面的例子已经足够用了。

设置Activity Handler注册

一般来说，请参考将应用程序注册为活动处理程序

活动处理程序描述的新属性和更新

• 【删除】href，指定打开的地址

  • 无需再指定href

• 【删除】disposition，指定打开的方式(window/inline)

  • 无需再指定dispotion

• 【可选】filters，过滤器

  • 同之前

• 【可选】returnValue，返回值

  • 同之前

• 【新增】【可选】allowedOrigins，允许来源

  • 数组，这是为了处理程序将其使用限制为特定用户，将筛选出其来源不在列表中的呼叫者(caller)

  • 例如，设置 "AllowedOriginates": ["http://testapp1.localhost", "http://testapp2.localhost“]

  • 仅允许从 "http://testapp1.localhost" 或 "http://testapp2.localhost" 中发出请求