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  # 输出到 ./ribbon_temp.js

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

检查 XML 文件

cuxml check ./ribbon.xml

# 显示详细信息
cuxml check ./ribbon.xml -v

查看帮助

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"]
    }
  }
}

📖 详细文档

完整的使用文档和技术细节请参考：CUXML Agent 文档

🔧 功能说明

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/
├── src/
│   ├── api.js          # API 模块
│   ├── checker.js      # XML 检查器
│   ├── cli.js          # CLI 工具
│   ├── converter.js    # 转换器
│   ├── mcp.js          # MCP 插件
│   ├── parser.js       # XML 解析器
│   └── templates.js    # 模板生成器
├── lib/
│   ├── simpleTypes.json        # Simple Types 配置
│   ├── clashAttributes.json    # 冲突属性配置
│   ├── StDelegate.json        # 回调函数属性配置
│   └── cbfTypes.json         # Callback 函数类型配置
├── test/              # 测试文件和示例
├── index.js           # 主入口
└── package.json

🎯 最佳实践

1. 文件组织

project/
├── src/
│   └── ribbon.xml          # RibbonUI 配置文件
├── gen/
│   └── ribbon_callbacks.js # 自动生成的回调函数
├── main.js                 # 主逻辑文件
└── package.json

2. 开发工作流

# 开发阶段：使用监视模式，实时更新
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

3. 错误处理

const cuxml = require('cuxml');

try {
  cuxml.check('./ribbon.xml');
  cuxml.convert('./ribbon.xml', './ribbon.js');
  console.log('✅ 转换成功！');
} catch (error) {
  console.error('❌ 转换失败：', error.message);
  // 处理错误
}

🔗 相关资源

• Microsoft CustomUI 规范
• Simple Types 参考
• WPS Office 开发文档
• CUXML Agent 文档 - 完整的使用文档

🤝 贡献

欢迎贡献！请随时提交 Issue 或 Pull Request。

📄 许可证

ISC

📊 版本历史

v2.0.0 (2026-02-14)

重大更新：完全重构

• ✨ 全新的模块化架构
• ✨ 完整的 API 模块（支持同步和异步）
• ✨ 统一的 CLI 命令（cuxml）
• ✨ MCP 协议支持
• ✨ 完整的 JSDoc 文档
• ✨ 改进的错误处理和日志输出
• 🔧 优化项目结构
• 🐛 修复多个已知问题

v1.0.x

• 初始版本
• 基本的 XML 转换和检查功能