claude-office-skills/wps-core-api

全局变量

• Application / app：WPS 应用对象
• ActiveWorkbook（wb）：当前工作簿
• ActiveSheet（ws）：当前活动工作表
• Selection：当前选区

辅助函数（所有代码顶部必须定义）

function CL(c){var s="";while(c>0){c--;s=String.fromCharCode(65+(c%26))+s;c=Math.floor(c/26);}return s;}
function _n(v){return (v===null||v===undefined||isNaN(v))?0:Number(v);}
function toM(v){return _n(v)/1e6;}

---

核心 API（同步执行，非 Excel.run 模式）

读写数据

ws.Range("A1").Value2 = "文本";
ws.Range("A1:C3").Value2 = [["a","b","c"],["d","e","f"]];
var vals = ws.Range("A1:C3").Value2;
ws.Range(CL(col)+row).Value2 = 123;
ws.Range("A1").Formula = "=SUM(B1:B10)";
ws.Range("A1:Z100").ClearContents();
ws.Range("A1:Z100").ClearFormats();
ws.Range("A1:Z100").Clear();

动态区域定位（避免硬编码行数）

// End() 方向必须用数字：4=xlDown, 3=xlUp, 2=xlRight, 1=xlLeft
var lastRow = ws.Range("A1").End(4).Row;
var lastRow = ws.Range("A65536").End(3).Row;
var used = ws.UsedRange;
var lastRow = used.Row + used.Rows.Count - 1;

ws.Range("A1").Offset(1, 0).Value2 = "A2";
var r = ws.Range("A1").Resize(10, 5);
var dataRange = ws.Range("A1").CurrentRegion;

格式化

range.Font.Bold = true;
range.Font.Size = 14;
range.Font.Color = 0xFFFFFF;        // BGR 格式
range.Font.Name = "微软雅黑";
range.Font.Italic = true;
range.Interior.Color = 0x8B4513;
range.HorizontalAlignment = -4108; // -4108=居中, -4131=左, -4152=右
range.VerticalAlignment   = -4108;
range.WrapText = true;
range.ShrinkToFit = true;
range.Orientation = 90;             // 文字旋转角度
range.IndentLevel = 2;
range.NumberFormat = "#,##0.00";
range.NumberFormat = "0.00%";
range.NumberFormat = "yyyy-mm-dd";
range.NumberFormat = "#,##0.0,,"M""; // 百万M
range.Locked = false;               // 配合工作表保护

尺寸与合并

ws.Range("A:A").ColumnWidth = 15;
ws.Range("1:1").RowHeight = 30;
ws.Range("A1:P1").Merge();
ws.Range("A1:P1").UnMerge();

行列操作

ws.Range("5:5").Insert();
ws.Range("5:5").Delete();
ws.Range("3:5").Hidden = true;
ws.Range("A:C").Hidden = true;

排序（Range.Sort）

// 按 B 列升序（1=升序/xlAscending, 2=降序; Header 1=xlYes有表头）
ws.Range("A1:E100").Sort(ws.Range("B1"), 1, null, null, null, null, null, 1);

// 多列排序：B升序再C降序
ws.Range("A1:E100").Sort(ws.Range("B1"), 1, ws.Range("C1"), null, 2, null, null, 1);

查找与替换

var found = ws.Range("A:A").Find("目标值");
if (found) { var row = found.Row; }

ws.Range("A1:Z100").Replace("旧值", "新值");

复制与填充

ws.Range("A1:C10").Copy(ws.Range("E1"));
ws.Range("A1:A2").AutoFill(ws.Range("A1:A20"));
ws.Range("A1:E1").FillDown();

数据验证

ws.Range("J4:J100").Validation.Add(3, 1, 1, "选项A,选项B,选项C");

条件格式

range.FormatConditions.Delete();
var fc = range.FormatConditions.Add(1, 5, 0); // 1=xlCellValue, 5=xlGreater
fc.Interior.Color = 0x00AA00;
fc.Font.Color = 0xFFFFFF;

行列分组（财务模型折叠）

ws.Range("5:10").Group();
ws.Range("B:D").Group();
ws.Range("5:10").Ungroup();
ws.Outline.ShowLevels(1);   // 折叠到第1级
ws.Outline.ShowLevels(2);

自动筛选

ws.Range("A1:A10").AutoFilter();
ws.Range("A1").AutoFilter(2, ">1000");
ws.ShowAllData();

去重

ws.Range("A1:E100").RemoveDuplicates([1, 2], 1);

---

工作表操作

// 创建（WPS 特殊：Add() 返回 null，必须用 ActiveSheet）
wb.Sheets.Add();
var ws = wb.ActiveSheet;
ws.Name = "新工作表";

// 访问（必须用 .Item()）
var ws = wb.Sheets.Item("Sheet1");
var ws = wb.Sheets.Item(1);
var count = wb.Sheets.Count;

// 属性
ws.Visible = false;
ws.Tab.Color = 0x0055D9;   // 标签颜色 BGR
ws.Activate();

// 复制/移动/删除
ws.Copy(null, wb.Sheets.Item(wb.Sheets.Count));
Application.DisplayAlerts = false;
ws.Delete();
Application.DisplayAlerts = true;

// 保护
ws.Protect("密码");
ws.Unprotect("密码");

// 命名区域
wb.Names.Add("收入", "=财务!:");
ws.Names.Add("本表总计", ws.Range("E100"));

---

图表操作

// 必须用 Shapes.AddChart2（ChartObjects.Add 不可用）
// 类型：57=折线, 51=簇状柱形, 5=面积, 65=饼图
var shape = ws.Shapes.AddChart2(0, 57, left, top, width, height);
var chart = shape.Chart;
chart.HasTitle = true;
chart.ChartTitle.Text = "标题";
chart.SetSourceData(ws.Range("A1:C20"));

var s = chart.SeriesCollection.Item(1);
s.Name = "系列名";
s.XValues = ws.Range("A2:A20");
s.Values = ws.Range("B2:B20");

---

Application 级别

// 大批量操作前必须关闭，操作后必须恢复
Application.ScreenUpdating = false;
Application.DisplayAlerts  = false;
// ... 操作 ...
Application.ScreenUpdating = true;
Application.DisplayAlerts  = true;

// 内置工作表函数
Application.WorksheetFunction.Sum(ws.Range("B2:B100"));
Application.WorksheetFunction.Average(ws.Range("B2:B100"));
Application.WorksheetFunction.VLookup("key", ws.Range("A:B"), 2, false);
Application.WorksheetFunction.Max(ws.Range("C:C"));
Application.WorksheetFunction.CountIf(ws.Range("A:A"), ">0");

// 合并不连续区域
var union = Application.Union(ws.Range("A1:A10"), ws.Range("C1:C10"));
union.Font.Bold = true;

---

BGR 常用颜色速查

| 用途 | BGR 值 | RGB 等价 | |------|--------|---------| | 深蓝表头/品牌色 | 0x8B4513 | #13458B | | 鲜明蓝（图表主色）| 0xFF4500 | #0045FF | | 橙色强调 | 0x0055D9 | #D95500 | | 金橙色（图表柱状）| 0xE8A040 | #40A0E8 | | 浅灰背景 | 0xF0F0F0 | #F0F0F0 | | 浅蓝交替行 | 0xFFF0E0 | #E0F0FF | | 白色 | 0xFFFFFF | #FFFFFF | | 黑色 | 0x000000 | #000000 | | 红色（跌/警告）| 0x0000FF | #FF0000 | | 绿色（涨/完成）| 0x00AA00 | #00AA00 | | 橙黄（进行中）| 0x00AAFF | #FFAA00 | | 蓝色（信息）| 0xFF8800 | #0088FF |

---

❌ 不可用 API（WPS JS 宏严禁，会崩溃或报错）

| 禁用写法 | 原因 | 正确替代 | |---------|------|---------| | ws = wb.Sheets.Add() | 返回 null | wb.Sheets.Add(); ws = Application.ActiveSheet; | | ws.Cells(row, col) | VBA 语法不可用 | ws.Cells.Item(row, col) 或 ws.Range(CL(col)+row) | | ws.Rows(n) | VBA 语法不可用 | ws.Range("n:n") | | ws.Columns("A") | VBA 语法不可用 | ws.Range("A:A") | | ws.Columns("A").AutoFit() | 不可用 | 手动设 ColumnWidth | | ws.ListObjects | 不可用 | 普通 Range 模拟 | | ws.ChartObjects.Add() | 不可用 | ws.Shapes.AddChart2() | | .Borders / .BorderAround() | 直接崩溃 | 用背景色区分区域 | | wb.Sheets("名称") | 括号形式不可用 | wb.Sheets.Item("名称") | | chart.SeriesCollection(n) | 集合括号访问不可用 | chart.SeriesCollection.Item(n) | | Worksheets(1) | 集合括号访问不可用 | Worksheets.Item(1) | | End(xlDown) 字面量 | 枚举不可用 | 用数字：4=下,3=上,2=右,1=左 | | ActiveSheet（无前缀） | 全局变量不稳定 | Application.ActiveSheet | | ActiveWorkbook（无前缀） | 全局变量不稳定 | Application.ActiveWorkbook | | Range("A1").Value | 写入不可用 | 写入用 .Value2，读取用 .Value() 或 .Value2 | | [A1] = 5 | JS 解析为解构赋值 | Range("A1").Value2 = 5 | | AddChart2(-1, ...) | Style -1 返回 null | AddChart2(0, ...) | | .Cells.Clear() | 对整表操作不稳定 | .UsedRange.Clear() |

⚠️ WPS JS 宏 vs Excel VBA 关键差异

1. 颜色是 BGR 不是 RGB：0xFF0000 = 蓝色！红色是 0x0000FF
2. Sheets.Add() 返回 null，必须用 Application.ActiveSheet 获取新表
3. End() 用数字：4=xlDown, 3=xlUp, 2=xlRight, 1=xlLeft
4. 大批量写入前必须 Application.ScreenUpdating = false，否则 WPS 崩溃
5. 边框完全不可用：用深色背景+白字替代视觉分隔
6. 集合访问必须用 .Item()：Sheets.Item(1)、SeriesCollection.Item(1) 等
7. 方法调用必须加括号：.Select()、.Activate()、.Delete() 等
8. JS 严格区分大小写：Value2 不是 value2，Formula 不是 formula
9. 不支持 VBA 语法：不能用 Dim、Set、Sub/End Sub、&（字符串连接用 +）