桌面版解决方案

    以下为融云桌面版 v1.0.0 解决方案,方案已经升级查看 v2.0.0 版本解决方案。

    架构介绍

    1. 支持 Mac、Windows、Linux

    2. 桌面版基于 Electron 开发。应用分为主进程和渲染进程。主进程通过 Node.js 的 API 跨过网页运行的沙箱实现跟操作系统底层交互。渲染进程基于 Chrominum(类 Chrome 的浏览器) 渲染界面。

      桌面版封装了主进程中既定的 功能模块,渲染进程可直接调用这些模块,开发者仅需关心渲染进程的开发,通过 HTML、CSS 和 JavaScript 技术建立跨平台的桌面版应用。

    应用

    功能模块

    模块名称 功能简介 说明
    IM SDK 与融云服务器通讯模块,较之于 Web SDK 的优势:1. 消息和会话存储在本地 2. 支持本地会话和消息的搜索 c++ 开发,编译成 Node 原生模块 后由 js 调用
    Download (下载) 文件下载
    File (文件) 文件操作,如:打开指定文件等等
    Screenshot (截图) 获取用户截屏(可编辑)的图片 c++ 开发,编译成 Node 原生模块 后由 js 调用
    System (系统) 系统操作,如清除缓存,获取当前平台等
    BrowserWindow (窗口) 窗口操作,如:最大化,最小化等等
    Upgrade (升级) 在线热更新 仅更新需要升级的模块

    API 文档

    IM SDK

    IM SDK 是用 c++ 开发的 SDK,它支持所有 Web SDK 的方法;具体请参照 Web SDK


    Download (下载)

    文件下载仅支持 http(s) 协议。

    实例

    download(file, config)

    创建下载实例

    file 参数说明:

    参数 类型 必填 说明
    url String 下载地址
    name String 文件保存后的别名

    config 参数说明:

    参数 类型 必填 说明
    timeout Number 连接超时,默认 100000 毫秒(100秒)
    retries Number 出错时重试次数,默认 10

    示例代码:

    var file = {url: 'url', name: 'name'};
    var config = (timeout: 300000, retries: 10);
    var downloader = download(file, config);
    

    实例方法

    save(name)

    保存方法,默认保存到系统下载目录。

    参数 类型 必填 说明
    name String 下载别名,默认为原文件名

    示例代码:

    downloader.save('name');  // 以下示例代码中 downloader 均指下载实例
    

    saveAs(file)

    另存为,以指定名称和指定路径

    file 参数说明:

    参数 类型 必填 说明
    name String 另存为对话框默认文件名称
    path String 另存为对话框默认路径

    示例代码:

    var file = {
      name: 'name',
      path: 'path'
    }
    downloader.saveAs(file);
    

    pause()

    暂停下载

    downloader.pause();
    

    resume()

    恢复下载

    downloader.resume();
    

    abort()

    中断下载

    downloader.abort();
    

    事件

    onReady(callback)

    下载链接初次响应事件,可获得总文件大小

    onReady 返回参数说明:

    参数 类型 说明
    total Number 文件大小
    path String 保存路径

    示例代码:

    downloader.onReady(function(data){
      console.log(data.total);
    });
    

    onProgress(callback)

    下载中

    onProgress 返回参数说明:

    参数 类型 说明
    loaded Number 已下载大小
    total Number 文件大小
    path String 保存路径

    示例代码:

    downloader.onProgress(function(data){
      console.log(data.loaded);
    });
    

    onComplete(callback)

    下载完成

    onComplete 返回参数说明:

    参数 类型 说明
    loaded Number 已下载大小
    total Number 文件大小
    path String 保存路径

    示例代码:

    downloader.onComplete(function(data){
      console.log(data.loaded);
    });
    

    onCancel(callback)

    下载取消

    onCancel 返回参数说明:

    参数 类型 说明
    loaded Number 已下载大小
    total Number 文件大小
    path String 保存路径

    示例代码:

    downloader.onCancel(function(data){
      console.log(data.loaded);
    });
    

    onTimeout(callback)

    下载超时

    onTimeout 返回参数说明:

    参数 类型 说明
    code String 错误码 "ETIMEDOUT"
    connect Boolean 超时分连接超时读取超时。connect 为 true 时为连接超时,false 为读取超时详见 Timeouts
    message String 错误信息
    stack String 错误堆栈

    示例代码:

    downloader.onTimeout(function(error){
      console.log(error.stack);
    });
    

    onError(callback)

    下载超时

    onError 返回参数说明:

    参数 类型 说明
    code String 错误码
    message String 错误信息
    stack String 错误堆栈
    description String 错误可能的原因, 参照下述常见错误码描述

    示例代码:

    downloader.onError(function(error){
      console.log(error.stack);
    });
    

    常见错误码

    • ENOTFOUND:DNS 找不到域名导致。请检查 1. 域名是否写错 2. 网络连接是否正常

    • ECONNREFUSED:这可能是因为防火墙或代理程序无法访问网络。请检查防火墙或者代理设置

    • ECONNRESET:options 加入 {originalHostHeaderName: 'Host'}。参考 如何解决 ECONNRESET 错误

    • EPIPE:低版本 nodejs 易发生此错误

    • ETIMEDOUT:连接超时


    File (文件)

    checkExist(path)

    检查文件是否存在

    path 参数说明:

    参数 类型 必填 说明
    path String 文件路径

    示例代码:

    var exist = file.checkExist('path');
    

    返回值:

    Boolean 类型,存在为 true,反之 false
    

    getFiles()

    获取粘贴板的文件(夹),支持多个文件/文件夹

    getFiles 返回值参数说明:

    参数 类型 说明
    dirList Object 文件夹数组
    fileList Object 文件数组

    dirList 对象说明:

    参数 类型 说明
    path String 文件夹路径
    size Number 文件夹大小

    fileList 对象说明:

    参数 类型 说明
    lastModified Number 最后一次更改时间
    name String 文件名称
    localPath String 本地路径
    size String 大小
    type String 文件类型

    示例代码:

    var obj = file.getFiles();
    var files = obj.fileList;
    var file = files[0];
    console.log(file.name, file.size);
    

    open(path)

    打开指定文件

    参数 类型 必填 说明
    path String 文件路径

    示例代码:

     file.open('path');
    

    openDir(path)

    打开指定文件所在文件夹,并选中文件

    参数 类型 必填 说明
    path String 文件夹路径

    示例代码:

     file.openDir('path');
    


    Screenshot (截图)

    方法

    start(callback)

    开始截图,callback 非必填

    start 返回参数说明:

    参数 类型 说明
    dataURL String dataURL
    base64 String base64 字符串
    size String 图片大小
    mime String mime 类型

    示例代码:

    // 有回调
    screenshot.start(function(data){
      console.log(data.size);
    });
    
    //无回调
    screenshot.onComplete(function(data){
      console.log(data.size);
    });
    screenshot.start();
    

    setShortcut(shortcut)

    设置截图快捷键

    shortcut 参数说明:

    参数 类型 说明
    shortcut String 快捷键字符,为空则取消快捷键;Mac:'Command+Ctrl' + shortcut;Windows:'CTRL+ALT' + shortcut

    示例代码:

    screenshot.setShortcut('S');  //实际快捷键 Mac: 'Command+Ctrl+S' Windows: 'CTRL+ALT+S'
    

    事件

    onComplete(callback)

    截屏完成后事件;如果调用截屏无法设置回调时,比如通过菜单调用截屏,页面需注册该事件以接收截屏返回数据

    onComplete 返回参数说明:

    参数 类型 说明
    dataURL String dataURL
    base64 String base64 字符串
    size String 图片大小
    mime String mime 类型

    示例代码:

    参考 start


    System (系统)

    方法

    clearCache()

    清除缓存,包括 HTTP cache、appcache、cookies、filesystem、indexdb、localstorage、shadercache、websql、serviceworkers; 参考 session.clearCache, session.clearStorageData 清除成功后跳转到主页

    示例代码:

    system.clearCache();
    

    属性

    参数 类型 说明
    deviceId String 设备id,MAC 地址
    locale String 系统语言设置参考 https://electronjs.org/docs/api/locales
    platform String 标识 Node.js 进程运行其上的操作系统平台。 例如:'darwin'、'freebsd'、'linux'、'sunos' 或 'win32'


    BrowserWindow (窗口)

    注: 为区分全局 window 对象,窗口模块名称用 BrowserWindow

    close()

    关闭窗口

    示例代码:

    browserWindow.close();
    

    focus()

    窗口获取焦点

    示例代码:

    browserWindow.focus();
    

    max()

    窗口最大化

    示例代码:

    browserWindow.max();
    

    min()

    窗口最小化

    示例代码:

    browserWindow.min();
    

    restore()

    取消窗口最大化/最小化

    示例代码:

    browserWindow.restore();
    

    setAlwaysOnTop(isOnTop)

    前置/取消前置窗口;设置窗口是否显示于其它窗口之上

    isOnTop 参数说明:

    参数 类型 说明
    isOnTop Boolean 是否前置窗口

    示例代码:

    browserWindow.setAlwaysOnTop(true);
    

    shake(config)

    振动窗口

    config 参数说明:

    参数 类型 是否必填 说明
    interval Number 振动频率,默认为 25
    time Number 振动时间,默认为 1000 毫秒

    示例代码:

    browserWindow.shake();
    

    show()

    窗口显示

    示例代码:

    browserWindow.show();
    

    showInactive()

    窗口显示但不激活

    示例代码:

    browserWindow.showInactive();
    


    Upgrade (升级)

    更新模块会获取远程模块版本信息,与本地模块逐个对比版本,如果本地模块版本较旧或者不存在,则放入下载池待下载。 下载完成后更新模块;更新模块成功前 App 可正常使用;更新成功后会自动重启升级后的 App。

    开发环境

    1. 运行环境:Nodejs 5.3.0

    2. 开发工具:Electron 1.4.15

      Electron 基于 Chromium 和 Node.js,使用 HTML、CSS 和 JavaScript 构建应用。

    3. 打包工具:electron-packager

      基于 Node.js 的命令行工具,它将基于 Electron 的应用源码打包成可执行程序,如:app(Mac)、exe(Windows) 等,并将打包后的可执行文件和相关支持文件放入待分发的文件夹中。

    4. 安装包工具:

      • Mac:electron-builder 用于建立一个可分发的 Electron 应用。

      • Windows:Inno Setup 用于建立 Windows 平台的分发应用。

    安装包制作

    • 打包:

      • macOS:

        npm run package:mac
        
      • Windows:

        npm run package:win
        
    • 制作安装包:

      • macOS:

        npm run installer:mac
        
      • Windows:打开项目文件 *.iss, 选择菜单 Build/Compile

    参考文档