CUXML

CU: 'Can Use' or 'customUI', whatever……

CUXML 是一个专为 WPS Office JS 插件开发者设计的工具，用于处理 RibbonUI XML 文件。它可以显著简化开发流程，让你更专注于业务逻辑。

✨ 特性

• 🔄 XML 到 JavaScript 转换 - 自动将 RibbonUI XML 的回调函数配置转换为 JavaScript 代码
• 🔍 XML 合规性检查 - 全面检查 XML 文件是否符合 CustomUI 规范，详细显示错误和警告
• 👀 文件监视 - 监视 XML 文件变化，自动重新转换
• 📦 模块化 API - 提供完整的编程接口，支持同步和异步调用
• 🔌 MCP 支持 - 可作为 MCP 插件集成到 AI 工具链中
• ⚡ 转换前自动检查 - 转换前自动运行检查，提高开发效率

📦 安装

npm install -g cuxml

🚀 快速开始

命令行使用

转换 XML 文件

# 基本用法（不指定输出路径时，自动生成 {input}_temp.js）
cuxml -i ./ribbon.xml  # 输出到 ./ribbon_temp.js

# 指定输出路径
cuxml -i ./ribbon.xml -o ./ribbon.js

# 监视模式（文件变化时自动转换，默认覆盖输出文件）
cuxml -i ./ribbon.xml -w

# 非 watch 模式下覆盖已存在的输出文件
cuxml -i ./ribbon.xml -o ./ribbon.js --overwrite

# 使用默认输入路径（当前目录下的 ribbon.xml）
cuxml  # 需要在当前目录有 ribbon.xml 文件

# 注意：转换前会自动进行 XML 检查，有错误时会阻止转换

选项说明：

| 选项 | 说明 | |------|------| | -i, --input | 输入的 XML 文件路径 | | -o, --output | 输出的 JS 文件路径 | | -w, --watch | 监视文件变化并自动转换（自动覆盖） | | --overwrite | 覆盖输出文件（非 watch 模式使用） |

convert 子命令

# 基本转换
cuxml convert ./ribbon.xml

# 指定输入输出
cuxml convert ./ribbon.xml ./ribbon.js

# 监视模式
cuxml convert ./ribbon.xml ./ribbon.js -w

# 非 watch 模式下覆盖文件
cuxml convert ./ribbon.xml ./ribbon.js --overwrite

检查 XML 文件

cuxml check ./ribbon.xml

检查命令会自动显示详细的错误和警告信息，包括：

• 错误类型和位置
• 警告详情和该元素支持的所有属性（以表格形式显示）
• 支持的属性会按 4 列格式化输出，便于快速查找

查看帮助

cuxml -h
cuxml check -h
cuxml convert -h

API 使用

const cuxml = require('cuxml');

// 转换 XML 到 JavaScript
cuxml.convert('./ribbon.xml', './ribbon.js')
  .then(result => console.log(result))
  .catch(error => console.error(error));

// 同步转换
const result = cuxml.convertSync('./ribbon.xml', './ribbon.js');

// 检查 XML 文件
cuxml.check('./ribbon.xml')
  .then(result => console.log(result));

// 同步检查
const checkResult = cuxml.checkSync('./ribbon.xml');

// 检查 XML 字符串
cuxml.check('<customUI xmlns="...">...</customUI>');

// 监视文件变化
const watcher = cuxml.watch('./ribbon.xml', './ribbon.js');
// 停止监视: watcher.close();

// 格式化检查结果
const detailedResult = cuxml.checkSync('./ribbon.xml', { detailed: true });
console.log(cuxml.formatCheckResult(detailedResult));

MCP 插件

CUXML 可以作为 MCP (Model Context Protocol) 插件使用：

// 安装 MCP SDK
npm install @modelcontextprotocol/sdk

// 配置 MCP 服务器
{
  "mcpServers": {
    "cuxml": {
      "command": "node",
      "args": ["./node_modules/cuxml/src/mcp.js"]
    }
  }
}

🔧 功能说明

XML 到 JavaScript 转换

将 RibbonUI XML 文件中的回调函数配置自动转换为 JavaScript 函数代码：

• 智能解析 XML 中的回调函数属性
• 生成标准化的 JavaScript 函数模板
• 支持自动函数名处理（带 . 连接符的属性名会被截取）
• 自动处理函数名：onClick.button1 → button1

示例：

<button id="myButton" onAction="handleClick" label="点击我"/>

生成：

function handleClick(ctrl) {
    switch (ctrl.Id) {
        case "myButton":
            // TODO: 实现控件逻辑
            break;
        default:
            break;
    }
    return true;
}

XML 合规性检查

全面检查 XML 文件是否符合 CustomUI 规范：

• ✅ XML 语法规范性
• ✅ ID 唯一性检查（防止重复 ID）
• ✅ 属性冲突检测（如 label 和 getLabel 不能同时存在）
• ✅ 标签嵌套合规性
• ✅ 属性值类型验证
• ✅ 元素不支持的属性检测

检查命令会以表格形式显示该元素支持的所有属性，便于快速查找正确的属性名。

开发工作流

# 开发阶段：使用监视模式，实时更新
cuxml -i src/ribbon.xml -o gen/ribbon_callbacks.js -w

# 构建阶段：生成并验证
cuxml check src/ribbon.xml && cuxml -i src/ribbon.xml -o gen/ribbon_callbacks.js

🔗 相关资源

• Microsoft CustomUI 规范
• Simple Types 参考
• WPS Office 开发文档

📊 版本历史

v2.1.3 (2026-04-20)

功能增强

• ✨ 改进检查命令输出 - 支持的属性以表格形式显示，提高可读性
• ✨ 转换前自动检查 - 转换前自动运行 XML 检查，有错误时阻止转换
• ✨ 详细的警告信息 - 未知属性和不支持的属性会显示该元素支持的所有属性
• 📝 更新 README 文档