扩展模块 API

2020-01-17 11:03:10
孙浩
672
最后编辑:先知 于 2020-02-05 10:56:00

本文的将对扩展模块中的 API 进行介绍,如果需要了解扩展机制及扩展开发相关请参考 客户端扩展机制文档

一、API 概览

喧喧客户端扩展模块 API 由客户端提供,扩展中的 JavaScript 模块代码中可以访问这些 API 来实现丰富的功能。实际运行时可用的 API 由扩展 API 声明和服务器端授权决定。

目前扩展模块中可供使用的 API 共有 288 个。根据扩展实际拥有的权限,在扩展模块中仅能够调用拥有权限的 API。

二、按模块划分

根据扩展所属的模块不同,可以分为user、members、im、ext、notification、contextmenu、commander、components、views、utils、window、nodeModules、node、lang、env、platform几类,下面分别列出不同模块下可用的 API:

三、按等级划分

扩展 API 根据权限的不同划分为 7 个等级,等级越高的 API 拥有的权限更高,能够实现更复杂的功能。在 “基础版” 授权中客户端扩展可以使用 等级 5 及小于等级 5 下的所有 API,在 “增强版” 和 “OEM” 版本中客户端扩展可以使用所有等级的扩展 API。

下面为每个等级下的 API 清单:

  • 等级 0:扩展模块默认拥有等级为 0 的 API

  • 等级 1:能够读取当前用户自身相关信息

  • 等级 2:能够执行与当前用户自身相关其他操作并能够使用界面上的一些通用组件和对话框

  • 等级 3:能够获取会话列表、消息记录、部门和组织成员信息

  • 等级 4:能够通过 API 发送消息,对会话进行操作以及通过命令使用功能对话框

  • 等级 5:能够自定义消息卡片、右键菜单,发送本地通知并能够使用更多的内置辅助功能 API

  • 等级 6:能够使用 React 来开发应用,直接使用内置的通用组件和界面上的功能组件,主动执行功能命令

  • 等级 7:能够使用 NodeJS 内置模块,访问平台(例如 electron)提供的额外实用工具库

四、扩展 API 权限

1、扩展 API 调用鉴权机制

在扩展模块调用 API 时会实时进行权限验证,如果当前用户所使用的扩展没有对应的 API 权限则调用 API 会失败。目前扩展在运行时最终可用的权限由如下环境共同决定:

  • 客户端自身允许提供的 API 权限,一些特别定制的客户端可能只拥有有限的扩展 API 权限;
  • 当前服务器授权中允许的扩展 API 权限,不同的授权版本可能具备的权限不一样,通常更高级版的授权拥有更多权限;
  • 扩展自身在扩展描述文件中申请的权限。

2、权限定义格式

扩展 API 权限由一个列表定义(在代码中使用字符串数组),列表中每一项表示一个或一组权限,也可以用于排除部分权限,下面是可能的扩展权限定义:

  • 权限完整名称,例如user.getCurrentUser表示拥有获取当前用户信息权限;
  • 权限名称前缀,例如members表示拥有权限名称前缀为members.的所有权限,通常使用前缀来表示拥有对应模块下的所有权限;
  • @L权限等级, 例如@L2表示拥有等级为 2 或者等级小于 2 的所有权限;
  • @L权限等级!, 例如@L2!表示拥有仅等级为 2 所有权限,但没有等级小于 2 的权限;
  • -权限完整名称, 例如-members.getMember从权限清单中排除名称为members.getMember(获取成员信息)的权限;
  • -权限名称前缀, 例如-members从权限清单中排除名称前缀为members.的所有权限;

3、在描述文件中申请权限

开发扩展时,扩展需要在描述文件中申明扩展模块中所需要的权限,如果没有申明权限,则扩展模块运行时可能出错。在扩展描述文件中申明权限的格式为:

{
    "name": "xext-my-extension",
    // 使用 usesPermissions 来在一个数组中申明权限
    "usesPermissions": [
        "user",
        "members",
        "@L3",
        "nodeModules"
    ],
    // ...此处省略扩展描述文件中的其他属性
}

五、扩展 API 定义

扩展 API 定义请点击下面的按钮下载详细文档进行参考:

喧喧客户端扩展模块 API 文档.pdf

发表评论
评论通过审核后显示。
咨询电话

公司电话: 400-6689-739

客服电话: 18561939726