背景说明

协作支持二次开发，客户若有定制需求，可接入协作二次开发插件，实现定制需求。

快速上手

1.开发环境和物料准备

• 开发者工具下载地址：PC开发者工具
• 提示：若不能访问该下载地址，请联系金山侧的项目经理

2.创建本地插件配置

在本地任意目录新建一个 extensions.json 文件 注意：

1. json 里面不要写注释
2. web 插件和 node 插件配置放到同一个json文件中 path内容为插件在本地目录的路径，例如：C:/xx/xxx，路径分隔符建议用 "/" JSON 格式在线校验 https://www.json.cn/

• web插件配置示例

[
  {注意，要把注释去掉，json中不能有注释的！！！！
    "name": "xxx_web_extension", // 插件名称，要和插件工程 package.json.name 完全一致
    "entry": "entry.js", // 模块入口名
    "path": "C:/xxx/xxx/dist/", // 插件目录地址，使用绝对路径
    "type": "web" // web 插件
  }
]

• node插件配置示例

[
  {注意，要把注释去掉，json中不能有注释的！！！！
    "name": "xxx_node_extension", // 插件名称，要和插件工程 package.json.name 完全一致
    "entry": "entry.js", // 模块入口名
    "path": "C:/xxx/xxx/dist/", // 插件目录地址，使用绝对路径
    "type": "node" // node 插件
  }
]

3. 插件开发

3.1 安装插件模板工程 npm 依赖

• web插件 包管理器可以使用 yarn/npm/pnpm 任意一种，以下例子使用 yarn 举例 yarn 安装插件依赖 yarn dev 启动开发环境

• node插件 包管理器可以使用 yarn/npm/pnpm 任意一种，以下例子使用 npm 举例 yarn 安装插件依赖 yarn dev 启动开发环境

3.2 启动插件基座

使用协作开发者工具启动对应基座 选择本地插件配置文件，选择和点击启动基座程序

注意：如果启动前程序正在运行，必须先手动退出程序再通过工具重新启动

3.3 验证插件是否加载成功

• web插件 启动基座时，关注在主窗口顶部是否有弹出toast

如果有，则表示 web 插件已加载成功

• node插件 启动基座时，关注是否有展示此独立窗口

如果有，则表示 node 插件已加载成功

注意：开发node插件时，修改插件内容后，需要重启下基座才能生效

3.4 使用插件API

• 插件API调用文档可查看能力调用说明（ksxz api）
• 使用示例

import ksxz from "ksxz";

ksxz.ui.xxx();
ksxz.im.xxx();

• 插件模块入口提供 activate 函数

import ksxz from 'ksxz'

export function activate(context: ksxz.IExtensionContext) {
   // 插件逻辑全部都要在此函数中执行
   ksxz.ui.registerXXX(context)
}

• 调用插件API时，需要使用直接调用方式，不要使用解构 ksxz 对象，或者二次声明 ksxz 对象的方式

例如：

// ✅
import ksxz from "ksxz";
ksxz.ui.xxx();

// ❌
const { ui } = ksxz;
ui.xxx();

// ❌
const ksxz_other = ksxz;
ksxz_other.ui.xxx();

3.5 插件调试

使用插件开发者工具，调试对应的窗口，可以看到插件打印的log

• web 插件 web 插件通常在主窗口和活动窗口内加载，这时可以点击这个主窗口页面调试并打开chrome devtools

然后可以在 Console 面板里面找到插件内打印的日志

• node 插件 node 插件则在 electron/js2c/browser_init node.js 进程中加载，点击进行调试即可

3.6 插件构建脚本

yarn dev：插件开发和调试时使用 yarn build: 插件上线和发布使用，执行该脚本，会在根目录生成zip包，用于和基座包集成出完整的安装包

注意事项

• extensions.json 里面不能有注释，要遵循标准的 json 格式
• extensions.json 插件 name 要和 package.json 里面的 name 命名一致，且 name 必须使用 xxx_xxx 方式
• 图标命名规范：${插件name}-icon-$
• 如果需要自定义图标目录，修改webpack配置即可