1. 后端处理服务器API
1.1  数据库结构
1.2  后端处理服务器HTTP 接口
1.3. 数据包
1.3.1  数据包的基本信息
1.3.2  所有数据包
2. 后端处理服务器应用集成API
2.1  设置应用集成
2.2  API 格式和签名机制
2.3  API 定义
3. 客户端扩展机制
3.1. 扩展定义
3.1.1  扩展类型
3.1.2  扩展包目录结构
3.1.3  扩展描述文件
3.2. 扩展模块
3.2.1  主入口模块
3.2.2. 扩展模块API
3.2.2.1  扩展 API 概览
3.2.2.2  扩展 API 权限
3.2.2.3  扩展 API 定义
3.2.3  扩展实例对象
3.2.4  数据存储机制
3.2.5  自定义上下文菜单
3.2.6  自定义命令
3.2.7  自定义网址解析
3.3. 开发扩展
3.3.1  载入开发中的扩展
3.3.2  开发应用扩展
3.3.3  开发插件扩展
3.3.4  开发主题扩展
3.4  内置扩展
3.5  分发扩展
4. 会话机器人开发指南
4.1  机器人应用开发

自定义网址解析

2020-08-11 10:59:21
孙浩
5390
最后编辑:孙浩 于 2020-08-11 11:34:35
分享链接

喧喧支持将用户单独发送的网址解析为一个卡片进行显示,默认情况会尝试获取网址所指向的网页的标题和预览图作为卡片显示。通过扩展机制可以自定义网址解析卡片。使用主入口模块的urlInspectors字段可以为应用添加自定义网址解析。urlInspectors字段为一个数组,包含多个网址解析对象。

默认网址解析例子如下图所示:

message-with-url-card.png 自定义解析如下图所示:

message-with-custom-card.png

该功能需要在package.json中声明如下权限:

{
    "usePermissions": [
        "ext.urlInspectors"
    ]
}

网址解析对象

一个网址解析对象包含如下属性:

  • test:必须字段,类型为正则表达式或者回调函数function(url: string):boolean,用于判断此解析器适用于哪些网址,如果是回调函数,则回调函数第一个参数为要判断的网址,只有在回调函数返回true,才会判定为使用此解析器;
  • getUrl:可选字段,类型为回调函数function(url: string),使用此回调函数可以在解析之前进行一次转换,例如将用户发送的链接转换为免登录的链接,此回调函数应该返回转换后的链接地址,或者使用 Promise 来异步返回地址;
  • noMeta: 类型boolean,如果设置为true,则跳过内置的解析结果,即不尝试自动访问链接获取链接标题等信息;
  • provider:类型{icon: string, name: string, label: string, url: string},用于定义卡片提供方信息,默认使用扩展信息;
  • inspect:必须字段,类型为回调函数function(url: string, meta: UrlMeta, cardMeta: Object),用于返回网址解析后的卡片定义对象,其中meta和cardMeta仅在noMeta字段没有设置为true的情况下提供,分别表示内置的解析结果和内置的卡片定义对象。

卡片定义对象

网址解析对象的inspect回调函数应该返回一个卡片定义对象来告知如何呈现卡片。一个卡片定义对象包含如下属性:

  • icon:卡片图标,可以使用 Material Design Icons 图标名称或者http://或https://协议开头图片地址;
  • title:卡片标题;
  • subtitle:卡片副标题;
  • url:卡片指向的链接地址;
  • clickable:卡片可以点击并自动跳转链接的部分,可选值包括'title'(标题)、'subtitle'(副标题)、'header'(整个头部)、true(整个卡片)和false(无法点击);
  • actions:卡片操作按钮操作对象列表,通常显示在卡片底部;
  • menu:卡片菜单操作对象列表,通常显示在卡片右侧;
  • content:卡片的内容;
  • htmlContent:卡片的正文文本内容,不过最终会以 HTML 源码形式在界面进行显示;
  • contentType:卡片内容类型,包括'image'(图片)、'video'(视频) 和'normal'(普通卡片,默认类型);
  • contentUrl:当卡片类型为'image'(图片)或'video'(视频)时用于设置图片或视频的实际地址;
  • originContentType:卡片实际内容类型,例如image/png等;
  • webviewContent:是否设置卡片内容类型为 Webview(内嵌页面),如果设置为true,则将content字段理解为 Webview 设置对象。

操作对象定义

卡片定义对象中的actions和menu字段都为一个操作对象数组,每一个操作对象包含如下属性:

  • icon:操作图标,可以使用 Material Design Icons 图标名称或者http://或https://协议开头图片地址;
  • label:操作名称;
  • btnClass:操作按钮元素类名,包括'primary'、'success'、'danger'、'warning'、'info'、'important'、'sepcial',不同的类名获得不同的颜色外观;
  • click:点击操作按钮时的回调函数;
  • url:点击操作按钮时打开的链接。

在操作对象中click和url属性只能设置其中一个。

Webview 内嵌页面设置对象

当webviewContent设置为true时会将链接以内嵌页面的形式作为卡片内容显示,此时可以通过content字段对象来设置 Webview 各项功能。Webview 设置对象属性包括:

  • className:类型为string,添加到元素上的类名;
  • onLoadingChange:类型为回调函数function(isLoading: boolean),当 Webview 开始加载或加载完成时会调用此回调函数,参数isLoading用于指示是否正在加载;
  • onPageTitleUpdated:类型为回调函数function(title: string, explicitSet: boolean),当页面标题变更时会调用此函数,回调函数参数title为当前标题(变更后),回调函数参数explicitSet如果为true表示此标题是页面确切设置的标题(而不是临时或着缺省标题);
  • src:类型为string,表示要加载的页面地址;
  • insertCss:类型为string,表示要注入要页面上的 CSS 样式代码;
  • executeJavaScript:类型为string,表示要在页面上执行的 JavaScript 代码;
  • onExecuteJavaScript:类型为回调函数,表示执行executeJavaScript字段指定的 JavaScript 代码完成后的回调函数;
  • onNavigate:类型为回调函数function(url: string, event: Event),表示页面导航到其他地址时的回调函数,函数参数url表示要导航的地址,event表示导航事件对象;
  • onDomReady:类型为回调函数,当页面 DOM 树加载就绪时调用;
  • injectForm:类型为 JSON 字符串,表示页面表单注入对象;
  • useMobileAgent:类型为boolean,如果为true表示 Webview 的 userAgent 设置为模拟移动设备类型;
  • hideBeforeDOMReady:类型为boolean,如果为true表示在页面 DOM 数加载完成之前隐藏页面;
  • style:要为 Webview 元素设置的 CSS 样式对象;
  • type:Webview 类型,可选值包括'webview'(使用 Electron 内置的 webview 对象)、'iframe'(使用 <iframe>元素) 或'auto'(自动使用类型)。

Webview 内嵌页面设置对象中的injectForm可以用来将值注入到页面表单域上。该字段为一个对象,对象的属性名称为要注入的表单域名称,属性对应的值为要设置的值。

自定义网址解析卡片的例子

下面的例子将禅道公开服务器网址都解析为内嵌 Webview 卡片形式:

module.exports = {
    // 在扩展内定义网址解析
    urlInspectors: [
        {
            // test 函数用于判断一个url是否要进行特殊卡片渲染
            test: url => {
                const urlObj = new URL(url)
                const urlHost = urlObj.host;
                return ['.5upm.com', 'pms.zentao.net', 'demo.zentao.net', 'pro.demo.zentao.net', '.zentaopm.com', 'test.zentao.net'].some(x => urlHost.endsWith(x));
            },
            // 用于忽略系统内置的方式
            noMeta: true,
            // 用于决定最终url渲染的卡片配置
            inspect: (url) => {
                const cardMeta = {};
                cardMeta.title = null;
                cardMeta.webviewContent = true;
                cardMeta.icon = false;
                cardMeta.content = {
                    // url iframe 地址
                    src: url,
                    // iframe 高度和宽度设置
                    style: {height: '400px', width: '550px'},
                    // type 为 iframe 和 webview 方式则直接在卡片内加载页面
                    type: 'iframe'
                };
                return cardMeta;
            }
        },
        // 如果要定义多个网址解析,则可以在数组中继续添加更多的网址解析对象
    ]
}

该例子需要在package.json中声明如下权限:

{
    "usePermissions": [
        "ext.urlInspectors"
    ]
}
发表评论
叁 加 肆 =
评论通过审核后显示。