WPS JSA脚本如何向自定义工具栏添加输入框？

Question

在使用WPS JSA（JavaScript API）脚本开发时，如何向自定义工具栏添加输入框是一个常见需求。许多开发者尝试通过`UIControls.add()`方法动态创建控件，但发现仅支持按钮、下拉框等基础类型，无法直接添加文本输入框。问题核心在于WPS JSA当前API对自定义UI控件的支持有限，未提供原生的“文本框”或“输入框”控件类型。因此，开发者常面临无法捕获用户自由输入的困境。是否有变通方案（如利用对话框配合按钮触发）实现输入功能？这成为实际开发中的关键难题。

Answer 1

1. 问题背景与核心挑战

在使用WPS JSA（JavaScript API）进行脚本开发时，开发者常需通过自定义工具栏增强办公自动化能力。然而，当前WPS JSA的UIControls.add()方法仅支持按钮、下拉框等基础控件类型，未提供原生的“文本输入框”组件。这意味着无法像在传统Web前端中那样直接嵌入<input type="text">实现用户自由输入。

这一限制导致开发者在需要获取动态文本输入（如搜索关键词、配置参数、命名规则等）时陷入困境。尽管可通过下拉框预设选项，但其灵活性远不及自由输入。因此，如何绕过API限制，实现等效的输入功能，成为实际项目中的高频技术难题。

控件类型	是否支持	说明
按钮 (Button)	✅ 支持	可绑定点击事件
下拉框 (Dropdown)	✅ 支持	支持有限选项选择
文本输入框 (Textbox)	❌ 不支持	无原生API创建方式
复选框 (Checkbox)	❌ 不支持	同属缺失控件

2. 技术分析：为何无法直接添加输入框？

从架构层面看，WPS JSA的设计目标是轻量级脚本化控制文档对象模型（DOM-like），而非构建完整GUI界面。其UI系统基于Office COM控件的简化映射，仅暴露部分安全且稳定的控件接口。文本输入框涉及更复杂的焦点管理、输入验证和事件监听机制，目前尚未纳入开放API范畴。

进一步分析UIControls.add()方法的参数结构：

// 示例代码：添加一个按钮
const button = UIControls.add({
  id: "myButton",
  type: "button",
  label: "点击输入",
  onAction: function() {
    console.log("按钮被点击");
  }
});

其中type字段可选值仅包括"button"、"dropdown"，并无"textbox"或类似选项。这表明底层控件注册表中未包含输入框类控件。

3. 变通方案设计与实现路径

面对原生控件缺失，可采用“事件驱动+模态交互”的设计模式，将输入操作转移至弹出式对话框中完成。以下是三种主流变通策略：

1. 消息框输入法（prompt模拟）：利用window.prompt()或自定义对话框获取输入
2. 任务窗格嵌入HTML：通过TaskPane加载外部HTML页面，内含完整表单控件
3. 状态栏临时输入提示：结合快捷键与状态栏反馈，引导用户在文档区域输入

其中前两种最为实用，尤其适用于5年以上经验开发者关注的工程化场景。

4. 实战示例：通过按钮触发对话框实现输入捕获

以下是一个完整的JSA脚本片段，展示如何通过按钮触发Dialog来收集用户输入：

function createInputToolbar() {
  const toolbar = UIControls.add({
    id: "inputToolbar",
    type: "toolbar",
    label: "输入工具栏"
  });

  toolbar.addItem({
    id: "textInputBtn",
    type: "button",
    label: "输入文本",
    onAction: function() {
      const userInput = Dialog.show({
        title: "请输入内容",
        html: `
          <label>输入值：</label>
          <input type="text" id="userInput" />
        `,
        width: 300,
        height: 150,
        onOk: function() {
          const value = document.getElementById("userInput").value;
          Application.ActiveDocument.Content.InsertAfter(value);
        }
      });
    }
  });
}

// 注册到启动事件
OnDocumentOpen = createInputToolbar;

5. 高阶方案：集成Web技术栈的混合式UI

对于复杂输入需求（如多字段表单、实时校验），推荐使用WPS的任务窗格（TaskPane）机制，加载本地或远程HTML页面：

graph TD A[自定义工具栏按钮] --> B{点击触发} B --> C[打开TaskPane] C --> D[加载HTML表单页面] D --> E[用户填写输入框] E --> F[JS提交数据回JSA上下文] F --> G[执行文档操作]

该方案优势在于：

• 完全自由的HTML/CSS/JS控制
• 支持富文本、日期选择器、文件上传等高级控件
• 可与现有前端框架（Vue、React）集成
• 便于维护与样式统一

6. 性能与安全性考量

在实施上述方案时，资深开发者应关注以下维度：

维度	建议措施
跨域安全	避免加载外部不可信HTML，优先使用本地资源
内存泄漏	确保Dialog关闭后释放DOM引用
兼容性	测试不同WPS版本对Dialog API的支持程度
用户体验	设置合理的默认值与输入提示

此外，可通过封装通用输入函数提升代码复用性：

async function promptForText(label = "请输入：") {
  return new Promise((resolve) => {
    Dialog.show({
      title: "输入框",
      html: `<input type="text" id="tmpInput" placeholder="${label}" />`,
      onOk: () => resolve(document.getElementById("tmpInput").value),
      onCancel: () => resolve(null)
    });
  });
}

// 使用示例
UIControls.add({
  type: "button",
  label: "插入签名",
  onAction: async () => {
    const sig = await promptForText("请输入签名内容");
    if (sig) Application.ActiveDocument.Content.InsertAfter(sig);
  }
});