wps加载项ribbon.js 与 ribbon.xml 的交互

ribbon.js 与 ribbon.xml 的交互

ribbon.js 文件是 WPS 加载项的核心逻辑文件，它通过以下方式与 ribbon.xml 进行交互：

1. 回调函数映射关系

在 [ribbon.xml]中定义的各种回调属性会直接调用 ribbon.js 中对应的函数：

xml 复制代码

onLoad="ribbon.OnAddinLoad"

onAction="ribbon.OnAction"

getEnabled="ribbon.OnGetEnabled"

getImage="ribbon.GetImage"

getVisible="ribbon.OnGetVisible"

getLabel="ribbon.OnGetLabel"

这些回调通过全局 window.ribbon 对象进行连接，在 App.vue 中设置了这个映射：

javascript 复制代码

onMounted(() => {
  window.ribbon = ribbon  // 将 ribbon.js 导出的对象挂载到 window.ribbon
})

2. 具体交互方式

初始化加载

WPS 加载插件时调用 ribbon.OnAddinLoad(ribbonUI)
保存 ribbonUI 对象用于后续刷新界面
初始化插件存储状态

用户操作响应

当用户点击按钮时，触发 OnAction 函数：

javascript 复制代码

function OnAction(control) {
    const eleId = control.Id  // 获取被点击按钮的 ID
    switch (eleId) {
        case "btnShowMsg":
            // 处理消息框按钮点击
            break;
        case "btnIsEnbable":
            // 处理启用/禁用按钮点击
            break;
        // ...其他按钮处理
    }
}

动态属性获取

WPS 会根据 XML 中的定义动态调用相关函数获取按钮状态：

GetImage(control) - 返回按钮图标路径
OnGetEnabled(control) - 返回按钮是否启用
OnGetVisible(control) - 返回按钮是否可见
OnGetLabel(control) - 返回按钮标签文本

界面刷新机制

通过 ribbonUI.InvalidateControl() 方法刷新特定控件：

javascript 复制代码

window.Application.ribbonUI.InvalidateControl("btnIsEnbable")

或者刷新所有控件：

javascript 复制代码

window.Application.ribbonUI.Invalidate()

3. 数据存储与状态管理

使用 window.Application.PluginStorage 进行状态管理：

javascript 复制代码

window.Application.PluginStorage.setItem("EnableFlag", false)
let bFlag = window.Application.PluginStorage.getItem("EnableFlag")

这允许在不同函数调用之间保持状态，实现按钮状态的动态切换。

4. 事件监听机制

通过 window.Application.ApiEvent 注册和移除事件监听器：

javascript 复制代码

window.Application.ApiEvent.AddApiEventListener('NewPresentation', 'ribbon.OnNewDocumentApiEvent')
window.Application.ApiEvent.RemoveApiEventListener('NewPresentation', 'ribbon.OnNewDocumentApiEvent')

总结

整个交互流程是：WPS 读取 ribbon.xml 定义界面结构 → 通过 window.ribbon 调用 ribbon.js 中的回调函数 → ribbon.js 处理业务逻辑并操作 WPS API → 必要时刷新界面状态。