/wps-jsa-macro

name: wps-jsa-macro
description: |
  WPS宏代码助手。告诉我你要自动化什么操作，帮你写WPS JSA宏脚本，
  批量改名、自动填表、一键汇总，重复劳动交给宏。注意WPS用的是JavaScript不是VBA。
  用于帮助用户编写WPS宏脚本。当用户提到宏、macro、自动化、批量操作时触发。
  WPS JSA macro generator - automates repetitive tasks in WPS Office.
license: MIT
user-invocable: true
argument-hint: '[操作描述]'
allowed-tools: 'Read, Grep, Glob, Bash, Write, Edit'
metadata:
  author: BWKYD
  title: WPS宏代码助手
  description_zh: 编写WPS JSA宏脚本，实现表格和文档的批量自动化操作
  tags:
    - WPS
    - JSA
    - JavaScript
    - 宏
    - 自动化
  version: 1.0.2
  license: MIT

WPS 宏生成器

生成 WPS Office **JSA（JavaScript for Applications）** 宏脚本。

> **核心原则：WPS 宏 ≠ VBA。WPS 使用 JavaScript 语法，API 虽与 VBA 相似但有重要差异。 > 绝对不要输出 VBA 代码。**

When to Use

• 用户需要在WPS中自动化重复操作
• 用户说"帮我写一个WPS宏"
• 用户需要批量处理WPS文档/表格/演示
• 用户需要在WPS表格中自动填充、计算、格式化
• 用户提到JSA、WPS脚本

When NOT to Use

• 用户明确说 Excel VBA → 提醒用户WPS不支持VBA，询问是否需要JSA版本
• 用户需要生成独立文档 → 使用 `docx-writer`
• 用户需要公文排版 → 使用 `wps-gongwen`
• 需要的是 WPS 加载项（Add-in）开发 → 这是另一个话题

JSA vs VBA 关键差异

**必须牢记这些差异，避免生成错误代码：**

| 特性 | VBA | WPS JSA | |------|-----|---------| | 语言 | Visual Basic | **JavaScript** | | 变量声明 | `Dim x As Integer` | `var x = 0` 或 `let x = 0` | | 函数定义 | `Sub / Function` | `function name()` | | 字符串连接 | `&` | `+` | | 注释 | `'` 单引号 | `//` 或 `/* */` | | 数组索引 | 从1开始 | **从0开始**（但集合类从1开始） | | 无返回值过程 | `Sub` | `function`（无区分） | | For Each | `For Each x In col` | `for (var i = 1; i <= col.Count; i++)` | | 错误处理 | `On Error` | `try...catch` | | 对象判空 | `If obj Is Nothing` | `if (obj == null \|\| obj == undefined)` | | 类型转换 | `CInt(), CStr()` | `parseInt(), String()` | | 布尔值 | `True / False` | `true / false` | | 结束语句 | `End Sub / End If` | `}` | | Set关键字 | `Set obj = ...` | 不需要，直接 `var obj = ...` |

JSA 核心 API 速查

全局对象

// 应用对象
Application              // WPS应用实例
Application.ActiveDocument  // 当前活动文档（文字）
Application.ActiveWorkbook  // 当前活动工作簿（表格）
Application.ActivePresentation // 当前活动演示

// 控制台输出（调试用）
Console.log("message")   // WPS宏编辑器控制台

// 对话框
Application.alert("消息")  // 类似 MsgBox

WPS 文字（Writer）

// 文档操作
var doc = Application.ActiveDocument
var docs = Application.Documents
docs.Open("/path/to/file.docx")
docs.Add()  // 新建文档

// 内容操作
var range = doc.Content           // 全文范围
var paras = doc.Paragraphs        // 段落集合
var para = doc.Paragraphs.Item(1) // 第1段（从1开始）
para.Range.Text                   // 段落文本
para.Range.Font.Name = "宋体"
para.Range.Font.Size = 12
para.Range.Font.Bold = true

// 查找替换
var find = doc.Content.Find
find.Text = "旧文本"
find.Replacement.Text = "新文本"
find.Execute(undefined, undefined, undefined, undefined, undefined,
             undefined, undefined, undefined, undefined, undefined, 2)
// 最后参数 2 = wdReplaceAll

// 表格
var table = doc.Tables.Item(1)
table.Cell(1, 1).Range.Text     // 第1行第1列
table.Rows.Count                // 行数
table.Columns.Count             // 列数

// 书签
var bm = doc.Bookmarks.Item("书签名")
bm.Range.Text = "填入内容"

// 保存
doc.Save()
doc.SaveAs("/path/to/new.docx")

WPS 表格（Spreadsheets）

// 工作簿和工作表
var wb = Application.ActiveWorkbook
var ws = wb.ActiveSheet
var ws2 = wb.Sheets.Item("Sheet1")  // 按名称
var ws3 = wb.Sheets.Item(1)         // 按索引（从1开始）

// 单元格操作
var cell = ws.Range("A1")
cell.Value2 = "Hello"               // 设置值（用Value2更可靠）
cell.Formula = "=SUM(B1:B10)"       // 设置公式
cell.Font.Name = "宋体"
cell.Font.Size = 11
cell.Font.Bold = true
cell.Interior.Color = 0xFFFF00      // 背景色（BGR格式）

// 范围操作
var rng = ws.Range("A1:D10")
rng.Value2                          // 返回二维数组
rng.NumberFormat = "#,##0.00"       // 数字格式
rng.HorizontalAlignment = -4108    // xlCenter
rng.Borders.LineStyle = 1          // 边框

// 行列操作
ws.Rows(1).RowHeight = 30
ws.Columns("A").ColumnWidth = 15
ws.Rows("2:5").Delete()

// 遍历（注意：Cells索引从1开始）
var lastRow = ws.Range("A1").End(-4121).Row  // xlDown = -4121
// 或用 UsedRange
var lastRow2 = ws.UsedRange.Rows.Count

for (var i = 1; i <= lastRow; i++) {
    var val = ws.Cells(i, 1).Value2
    // 处理每行数据
}

// 自动筛选
ws.Range("A1:D1").AutoFilter()
ws.Range("A1:D1").AutoFilter(1, "条件值")  // 第1列筛选

// 数据透视表（基础）
// WPS表格数据透视表API与Excel基本一致

WPS 演示（Presentation）

// 演示文稿
var ppt = Application.ActivePresentation
var slides = ppt.Slides

// 幻灯片操作
var slide = slides.Item(1)
slides.Add(2, 1)  // 在第2位添加空白幻灯片（布局1=空白）

// 形状和文本
var shape = slide.Shapes.Item(1)
shape.TextFrame.TextRange.Text = "新标题"
shape.TextFrame.TextRange.Font.Size = 28

// 添加文本框
var newShape = slide.Shapes.AddTextbox(1, 100, 100, 400, 200)
// (方向, 左, 上, 宽, 高) 单位: pt
newShape.TextFrame.TextRange.Text = "内容"

// 遍历所有幻灯片
for (var i = 1; i <= slides.Count; i++) {
    var s = slides.Item(i)
    for (var j = 1; j <= s.Shapes.Count; j++) {
        var shp = s.Shapes.Item(j)
        if (shp.HasTextFrame) {
            Console.log(shp.TextFrame.TextRange.Text)
        }
    }
}

工作流程

Step 1: 理解需求

确认：

• **操作对象**：文字/表格/演示？
• **操作内容**：具体要自动化什么？
• **触发方式**：手动运行 / 打开文档时自动执行？
• **输入输出**：需要用户输入什么？输出什么？

Step 2: 编写 JSA 脚本

遵循以下规范：

**代码规范：**

/**
 * 宏名称：功能简述
 * 作用：详细说明
 * 使用方法：在WPS中 开发工具 → 宏 → 选择此宏 → 运行
 */
function MacroName() {
    try {
        // 主逻辑

    } catch (e) {
        Application.alert("执行出错：" + e.message)
    }
}

**编码要点：** 1. 始终使用 `try...catch` 包裹主逻辑 2. 集合索引从 **1** 开始（`Sheets.Item(1)`，`Cells(1,1)`） 3. 用 `Value2` 而非 `Value` 读写单元格值 4. 用 `Application.alert()` 而非 `MsgBox` 5. 不要使用 `Set` 关键字 6. 不要使用 VBA 的 `Sub...End Sub` 语法 7. 字符串用 `+` 连接而非 `&` 8. 布尔值小写 `true/false` 9. 文件路径使用正斜杠 `/` 或双反斜杠 `\\`

Step 3: 输出脚本

将JSA脚本写入 `.js` 文件，并提供使用说明：

使用方法：
1. 打开 WPS 文档/表格/演示
2. 菜单栏 → 开发工具 → 宏编辑器（或按 Alt+F11）
3. 在编辑器中新建模块
4. 粘贴脚本代码
5. 运行（F5）或关闭编辑器后通过 开发工具→宏 运行

Step 4: 调试建议

• 用 `Console.log()` 输出中间结果到宏编辑器控制台
• 复杂操作先在小数据集上测试
• 注意WPS版本差异（部分API在旧版本中不支持）

常见宏模板

批量替换文档内容

function BatchReplace() {
    var doc = Application.ActiveDocument
    var replacements = [
        ["旧词1", "新词1"],
        ["旧词2", "新词2"]
    ]
    for (var i = 0; i < replacements.length; i++) {