Skip to content

Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/wecom-skills/wecomcli-smartpage

wecomcli-smartpage

Verified

何时用:企业微信智能文档/智能主页/smartpage 相关诉求(含 doc.weixin.qq.com/smartpage/ 或 page.weixin.qq.com/smartpage/ 链接),或泛指「创建/写/整理文档」的企微诉求时使用;纯本地文档默认走本地工具。能力:新建/导入(.md)、读取、修改内容(整页重写/局部编辑/增删子页面)、上传附件、搭建带看板/图表的数据系统页面与信息收集表单、获取内置智能表格。

references/formula-reference.md

View on GitHub
# 公式字符串语法指南

## 概述

公式字符串是智能文档(智能主页 / smartpage)中用于动态计算和数据处理的核心能力,可用于:

- 引用数据表字段或页面控件
- 执行函数运算与四则运算
- 表单字段自动计算
- 实现复杂的业务逻辑

**重要约束**:

- 公式中优先使用语义化引用:`[页面名.控件名]`、`[表名.字段名]`、`[字段名]`(仅限当前记录上下文),避免直接使用控件id。
- 公式系统**仅支持**本目录下文档列出的函数与运算符;未列出的(如取模 `%`、三元 `?:`)一律不支持,遇到无法表达的需求应直接告知用户。
- 字符串值用**双引号**包裹(如 `"完成"`),不能用单引号。
- 函数用法以本文档为准,不要凭 Excel/JS 经验编写。

## 函数分类索引

按需求场景定位对应文档;一个需求涉及多类时,逐条查阅。

| 分类 | 适用场景 / 关键能力 | 查阅文档 |
| --- | --- | --- |
| 日期时间 | 日期构造 DATE、当前日期 NOW/TODAY、日期比较与差值、工作日计算;倒计时、工龄、截止日期判断 | [formula/datetime.md](formula/datetime.md) |
| 用户信息 | 获取当前登录用户信息;个人任务筛选、数据权限、我的待办 | [formula/user.md](formula/user.md) |
| 数学计算 | SUM、AVERAGE、MAX/MIN、COUNT/COUNTA、COUNTIF、SUMIF、ROUND 等数值计算与统计汇总;金额计算 | [formula/math.md](formula/math.md) |
| 逻辑判断 | IF、AND、OR、ISBLANK 条件判断与空值/错误处理;数据校验、状态显示、条件渲染 | [formula/logic.md](formula/logic.md) |
| 文本处理 | 文本拼接 `&`、LEFT/RIGHT 截取、SUBSTITUTE 替换、格式化、大小写;姓名规范化、日期格式化 | [formula/text.md](formula/text.md) |
| 数组列表 | FILTER 筛选、数组提取/合并/去重;数据统计、关联查询、列表处理 | [formula/arraylist.md](formula/arraylist.md) |
| 页面动作 | 打开外部链接、跳转页面、按钮点击修改数据(OPENLINK / MODIFYRECORDS / ADDRECORD) | [formula/pageblock.md](formula/pageblock.md) |
| 运算符 | 四则运算 `+-*/`、比较运算 `> < =`、文本拼接 `&`;条件筛选、数值计算 | [formula/operators.md](formula/operators.md) |
| 实用模板 | 排名、环比增长、重复标记、进度跟踪、日期提醒、工龄计算、逾期判断等开箱即用模板 | [formula/templates.md](formula/templates.md) |

## 公式语法

### 引用语法

页面公式(按钮 `formulaString`、`<formulaSpan>`、控件 `defaultValueFormula` 等)**优先使用下列三种带前缀的语义化引用形式**;禁止使用裸字段(如 `[字段名]`)。

| 引用对象 | 写法 | 说明 |
| --- | --- | --- |
| 数据表字段 | `[表名.字段名]` | 返回该字段在整张表中的值数组;`表名` 用数据表实际名称、`字段名` 用 `field.name`,不要写 `tableId`/`blockId` |
| 整张数据表 | `[表名]` | 用于配合 `.FILTER()`、`.COUNTA()` 等链式调用 |
| 页面控件 | `[页面名.控件名]` | `页面名` 是页面实际名称,`控件名` 是控件的 `title`/`name`;必须带页面名前缀 |

**示例**

```
[销售表.金额]            // 数据表字段
[订单表]                // 整张表
[学生信息页.学生姓名]     // 页面控件
```

**通用规则**

- 表名、字段名、页面名、控件名一律放在方括号 `[]` 内
- 字符串值用双引号 `""` 包裹(`"是"`、`"否"`)
- 函数名全大写(`SUM`、`FILTER`、`IF`)

## 常见错误

### 字段引用格式错误

```
// [反例] 页面公式省略表名(裸字段)
[销售额].SUM()

// [正例] 必须 [表名.字段名]
[销售表.销售额].SUM()
```

### 引号使用错误

```
// [反例] 单引号
IF([状态] = '完成', "是", "否")

// [正例] 双引号
IF([状态] = "完成", "是", "否")
```

### 括号不匹配

```
// [反例] 缺少闭合括号
IF([金额] > 1000, "大额"

// [正例]
IF([金额] > 1000, "大额", "小额")
```

### 类型不匹配

```
// [反例] 文本字段做数学加法
[员工表.姓名] + [员工表.年龄]

// [正例] 文本拼接用 &
[员工表.姓名] & " " & [员工表.年龄]
```

### FILTER / IF 多条件未包裹

多条件必须包在 `AND()` 或 `OR()` 内,不能在同一层级散写:

```
// [反例]
[任务表].FILTER([Each].[状态]="完成", [Each].[金额]>1000)

// [正例]
[任务表].FILTER(AND([Each].[状态]="完成", [Each].[金额]>1000))
```

### 人员(user)字段的特殊规则

- **筛选**:推荐用 `CONTAINTEXT`(全等比较容易因显示名差异失败);与 `USER()` 比较时可使用 `=`:

  ```
  [表.人员列].FILTER([Each].CONTAINTEXT("<英文名>(<中文名>)")).FIRST()
  [任务表].FILTER([Each].[负责人] = USER())
  ```

- **赋值**:人员字段不支持直接用文本字面值赋值。`ADDRECORD([表], [表.人员列], "人名")` 是错的;应使用 `USER()` 或通过 `FILTER` 取其他人员列的值赋值。

## 场景示例

### 示例 1:销售数据分析

```
// 总销售额
[订单表.金额].SUM()

// 平均订单金额
[订单表.金额].AVERAGE()

// 大客户订单数量(金额 > 10000)
[订单表].FILTER([Each].[金额] > 10000).[订单号].COUNTA()

// 本月订单总额
[订单表].FILTER(MONTH([Each].[日期]) = MONTH(TODAY())).[金额].SUM()

// 统计销售额大于1000的销售总和
[商品销售表.销售额].SUMIF([Each]>1000)
```

### 示例 2:任务管理

```
// 已完成任务数
[任务表].FILTER([Each].[状态] = "完成").[任务名].COUNTA()

// 我负责的任务数(负责人为人员字段)
// 方法 1:与 USER() 直接比较
[任务表].FILTER([Each].[负责人] = USER()).[任务名].COUNTA()

// 方法 2:用 CONTAINTEXT 按文本匹配(推荐,规避显示名差异)
[任务表].FILTER([Each].[负责人].CONTAINTEXT("zhangsan")).[任务名].COUNTA()

// 超期任务数
[任务表].FILTER(AND([Each].[截止日期] < TODAY(), [Each].[状态] <> "完成")).[任务名].COUNTA()

// 任务完成率
[任务表].FILTER([Each].[状态] = "完成").[任务名].COUNTA() / [任务表.任务名].COUNTA() * 100

// 项目总预算
[项目主表.预算].SUM()
```

### 示例 3:员工信息

```
// 部门人数(页面公式写法:使用完整表名前缀)
[员工表].FILTER([Each].[部门] = "研发部").[姓名].COUNTA()

// 平均工龄
[员工表.入职日期].AVERAGE()

// 全名(页面公式中需使用 [表名.字段名])
[员工表.姓] & [员工表.名]

// 工作年限(页面公式中需使用 [表名.字段名])
DATEDIF([员工表.入职日期], TODAY(), "Y")
```

### 示例 4:添加记录

```
// 配合button使用,将页面1中各种类别的数据写入各个字段
// ADDRECORD中不允许省略数据表、页面名
ADDRECORD([数据表], [数据表.字段1], [页面1.输入控件名], [数据表.字段2], "静态文本", [数据表.字段3], [页面1.公式名])
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall