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)、读取、修改内容(整页重写/局部编辑/增删子页面)、上传附件、搭建带看板/图表的数据系统页面与信息收集表单、获取内置智能表格。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.5 KB |
| references/data-driven-pages.md | markdown | 4.1 KB |
| references/formula-reference.md | markdown | 6.9 KB |
| references/formula/arraylist.md | markdown | 10.7 KB |
| references/formula/datetime.md | markdown | 7.5 KB |
| references/formula/logic.md | markdown | 7.3 KB |
| references/formula/math.md | markdown | 8.5 KB |
| references/formula/operators.md | markdown | 4.8 KB |
| references/formula/pageblock.md | markdown | 3.4 KB |
| references/formula/templates.md | markdown | 11.9 KB |
| references/formula/text.md | markdown | 9.3 KB |
| references/formula/user.md | markdown | 607 B |
| references/mdx-syntax.md | markdown | 27.4 KB |
| references/smartpage-edit.md | markdown | 28.8 KB |
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.公式名])
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |