@rezti/dsh-rez-suite 0.1.49 → 0.1.51

package/templates/shared/wecomcli-smartpage/references/formula/text.md

@@ -0,0 +1,377 @@
+# 文本处理公式函数 - CHAR, CONCAT, CONCATENATE, CONTAINTEXT, FIND, LEFT, LEN, LOWER, MID, REPLACE, RIGHT, SEARCH, SPLIT, SUBSTITUTE, TEXT, TEXTJOIN, TODATE, TRIM, UPPER
+
+> 用于文本拼接、截取、替换、格式化、大小写转换等文本处理，适用于姓名格式规范化、文本拼接、日期格式化等场景。
+
+---
+
+## CHAR - 字符转换
+
+**表达式**: `CHAR(数字)`
+
+**函数说明**: 返回数字代码所对应的 Unicode 字符
+
+**参数说明**: 数字：需要转换为 Unicode 的数字
+- 10-换行符
+- 32-空白键
+- 48到57-数字0到9
+- 65到90-大写字母A到Z
+- 97到122-小写字母a到z
+
+**示例**:
+```
+CHAR(10) => \n // 换行符号
+CHAR([数据表.数字字段]) => 各行的unicode
+CHAR([页面.控件名称]) => unicode
+```
+
+---
+
+## CONCAT - 文本拼接
+
+**表达式**: `CONCAT(文本1,[文本2,...])`
+
+**函数说明**: 将多个文本拼接成单个文本。要拼接双引号，需要连续输入两个双引号。
+
+**参数说明**: 文本1：要联接的文本项。 字符串或字符串数组，后续数值是可选的
+
+**示例**:
+```
+CONCAT([姓名], "-", [年龄])=> 小明 - 28
+CONCAT("""", [产品名称], """") => "智能表格"
+注：[列名]表示引用了同一条记录中此列的单元格参与公式计算
+[姓] & [名]
+CONCAT([城市], "-", [区域])
+```
+
+---
+
+## CONCATENATE - 文本拼接
+
+**表达式**: `CONCATENATE(字符串1, [字符串2, ...])`
+
+**函数说明**: 可将两个或多个文本项连接成一个文本项。
+
+**参数说明**:
+- 文本1：必需，加入的第一个文本项
+- 文本2：可选，要加入的其他文本项
+
+**示例**:
+```
+CONCATENATE("Hello"," ","World") => "Hello World"
+```
+
+---
+
+## CONTAINTEXT - 文本包含判断
+
+**表达式**: `CONTAINTEXT(文本 ,查找文本)`
+
+**函数说明**: 判断文本中是否包含要查找的文本
+
+**参数说明**:
+- 文本：查找范围，可以是一个文本或一个字段
+- 查找文本：需要查找的文本
+
+**示例**:
+```
+CONTAINTEXT("智能表格","表格") => true
+CONTAINTEXT([描述], "重要")
+```
+
+---
+
+## FIND - 查找位置
+
+**表达式**: `FIND(查找的值, 查找范围, [起始位置])`
+
+**函数说明**: 从指定位置开始查找值，找到值在查找范围中第一次出现的位置
+
+**参数说明**:
+- 查找的值：必需，要查找的值
+- 查找范围：可以是多个值也可以是一个值
+- 开始位置：可选，默认从1开始
+
+**示例**:
+```
+FIND("花", "人面桃花相映红") => 4
+FIND("红", LIST("人","面","桃","花","相","映","红")) => 7
+FIND(1, LIST(1,2,3)) => 1
+FIND("@", [邮箱])
+```
+
+---
+
+## LEFT - 左侧截取
+
+**表达式**: `LEFT(字符串, [字符数])`
+
+**函数说明**: 从左提取字符串指定长度的子串
+
+**参数说明**:
+- 字符串：必需，包含要提取的字符的文本字符串
+- 字符数：可选，指定要由LEFT提取的字符的数量
+
+**示例**:
+```
+LEFT("人面桃花相映红", 2) =>"人面"
+LEFT([手机号], 3)        // 前3位
+```
+
+---
+
+## LEN - 长度
+
+**表达式**: `LEN(文本)`
+
+**函数说明**: 返回文本字符串中的字符个数。
+
+**参数说明**: 文本：必需，要查找其长度的文本。 空格将作为字符进行计数
+
+**示例**:
+```
+LEN("abcd") => 4
+LEN([描述])  // 获取描述文字的长度
+```
+
+---
+
+## LOWER - 小写转换
+
+**表达式**: `LOWER(文本)`
+
+**函数说明**: 将文本中的全部大写字母替换为小写字母
+
+**参数说明**: 文本：必需，要转换为小写的字符串
+
+**示例**:
+```
+LOWER("SmartSheet") => "smartsheet"
+LOWER([城市])
+```
+
+---
+
+## MID - 中间截取
+
+**表达式**: `MID(文本, 开始位置, 提取长度)`
+
+**函数说明**: 提取字符串中从指定开始位置开始的指定提取长度的字符串
+
+**参数说明**:
+- 文本：必需，包含要提取字符的文本字符串
+- 开始位置：必需，文本中要提取的第一个字符的位置。 文本中第一个字符的开始位置为 1，以此类推
+- 提取长度：必需，指定希望 MID 从文本中返回字符的个数
+
+**示例**:
+```
+MID("腾讯文档智能表格",5,4) => "智能表格"
+MID([身份证号], 7, 8)    // 提取出生日期
+```
+
+---
+
+## REPLACE - 替换
+
+**表达式**: `REPLACE(文本, 位置, 长度, 新文本)`
+
+**函数说明**: 将文本中指定位置和长度的部分文本替换为新文本
+
+**参数说明**:
+- 文本：必需。要对其局部进行替换操作的文本
+- 替代位置：必需。开始进行替换操作的位置（文本开头位置为1）
+- 字符数：必需。要在文本中替换的字符个数
+- 新文本：可选。未必需。要插入到原有文本中的文本
+
+**示例**:
+```
+REPLACE("人面桃花相映红", -5, -1, "梨") =>"人面梨花相映红"
+REPLACE([手机号], 4, 4, "****")
+```
+
+---
+
+## RIGHT - 右侧截取
+
+**表达式**: `RIGHT(字符串, [字符数])`
+
+**函数说明**: 从右提取字符串指定长度的子串
+
+**参数说明**:
+- 字符串：必需，包含要提取字符的文本字符串
+- 字符数：可选，指定希望RIGHT提取的字符数
+
+**示例**:
+```
+RIGHT("人面桃花相映红", 2) =>"映红"
+RIGHT([手机号], 4)       // 后4位
+```
+
+---
+
+## SEARCH - 查找位置
+
+**表达式**: `SEARCH(查询文本,被查询文本,[编号])`
+
+**函数说明**: 可在第二个文本字符串中查找第一个文本字符串，并返回第一个文本字符串的起始位置的编号，该编号从第二个文本字符串的第一个字符算起。
+
+**参数说明**:
+- 查询文本：必需，要查找的文本
+- 被查询文本：必需，要在其中搜索查询文本参数的值的文本
+- 编号：可选，被查询文本参数中从之开始搜索的字符编号
+
+**示例**:
+```
+SEARCH("e","Hello",1) => 2
+SEARCH("公司", [公司名称])
+```
+
+---
+
+## SPLIT - 分割
+
+**表达式**: `SPLIT(文本, 分隔符)`
+
+**函数说明**: 使用分隔符对文本进行分割
+
+**参数说明**:
+- 文本：要拆分的文本
+- 分隔符：用于拆分文本的一个或多个字符
+
+**示例**:
+```
+SPLIT("智-能-表-格","-")=> "智","能","表","格"
+SPLIT([标签], ",")
+```
+
+---
+
+## SUBSTITUTE - 文本替换
+
+**表达式**: `SUBSTITUTE(要替换部分字符的文本, 被替换文本, 替换文本, [被替换文本序号])`
+
+**函数说明**: 可在某一文本字符串中用新文本替代指定的旧文本。
+
+**参数说明**:
+- 文本：必需，包含要替换字符的旧文本单元格的文本或引用
+- 被替换文本：必需，要被替换的文本
+- 新文本：必需，用于替换旧文本的文本
+- 替换位置：可选，指定要用新文本替换的旧文本的出现位置。默认情况下，所有出现的旧文本都被替换; 但是如果指定替换位置，则仅替换指示的实例
+
+**示例**:
+```
+SUBSTITUTE("hello world","hello","Hello") => "Hello world"
+SUBSTITUTE([手机号], " ", "")  // 去除空格
+```
+
+---
+
+## TEXT - 格式化为文本
+
+**表达式**: `TEXT(数值,格式)`
+
+**函数说明**: 按指定格式将数字转为文本
+
+**参数说明**:
+- 数值：必需，要转换为文本的数值
+- 格式：必需，一个文本字符串，定义要应用于所提供值的格式
+- "YYYY/MM/DD"（年月日）
+- "YYYY" (年份全称)
+- "YY" (年份简称)
+- "MMM" (月份全称)
+- "MM" (月份数字全写)
+- "M" （月份数字）
+- "DD"（日数字全写）
+- "D"（日数字）
+- "DDDD"（星期全称）
+- "DDD"（星期简称）
+- "hh" (小时)
+- "mm" (分钟)
+- "ss" (秒钟)
+- "0.0%"（百分比）
+- "0,0" (千位分隔符)
+- "0" （数字补位符）
+- "#" （数字占位符）
+
+**示例**:
+```
+TEXT("2026-05-14", "ddd")=> 周四
+TEXT("2026-05-14", "YYYY")=> 2026
+TEXT("2026-05-14", "MM")=> 05
+TEXT("2026-05-14", "M")=> 5
+TEXT("19:30", "HH")=> 19
+TEXT("19:30", "HH:MM")=> 19:30
+TEXT("19:30:34", "HH:MM")=> 19:30
+TEXT(0.3,"0.00%")=> 30.00%
+TEXT(1.23,"##.#")=> 1.2
+TEXT(1.23,"00.0")=> 01.2
+TEXT(TODAY(), "YYYY-MM-DD")
+TEXT([金额], "#,##0.00")
+```
+
+---
+
+## TEXTJOIN - 文本连接
+
+**表达式**: `TEXTJOIN(分隔符,空白值,文本1,[文本2,...])`
+
+**函数说明**: TEXTJOIN函数将多个区域和/字符串的文本组合起来，并可以在要组合的各文本值之间插入指定的分隔符。如果分隔符是空的文本字符串，则此函数将有效连接这些区域。
+
+**参数说明**:
+- 分隔符：必需。文本字符串(空)或一个或多个用双引号括起来的字符,或对有效文本字符串的引用。如果提供了一个数字,它将被视为文本
+- 空白值：必需。如果为TRUE，则忽略空白单元格
+- 文本1：必需。要加入的文本项。文本字符串或字符串数组
+- 文本2：可选。要加入的其他文本项
+
+**示例**:
+```
+TEXTJOIN(" ",TRUE,"hello","world") => "hello world"
+TEXTJOIN(", ", TRUE, [姓名1], [姓名2], [姓名3])
+```
+
+---
+
+## TODATE - 文本转日期
+
+**表达式**: `TODATE(文本)`
+
+**函数说明**: 将文本转成日期格式
+
+**参数说明**: 文本：要转的文本值
+
+**示例**:
+```
+TODATE("2026-5-9")=> 2026/05/09
+TODATE("2026-01-01")
+```
+
+---
+
+## TRIM - 去除空格
+
+**表达式**: `TRIM(文本)`
+
+**函数说明**: 移除文本中最前和最后的空格
+
+**参数说明**: 文本：要移除空格的文本
+
+**示例**:
+```
+TRIM("  智能  表格  ")=>智能 表格
+TRIM([姓名])
+```
+
+---
+
+## UPPER - 大写转换
+
+**表达式**: `UPPER(文本)`
+
+**函数说明**: 将文本中的全部小写字母替换为大写字母
+
+**参数说明**: 文本：必需，要转换为大写的字符串
+
+**示例**:
+```
+UPPER("SmartSheet")=> "SMARTSHEET"
+UPPER([邮箱])
+```

package/templates/shared/wecomcli-smartpage/references/formula/user.md

@@ -0,0 +1,22 @@
+# 用户信息公式函数 - USER
+
+> 用于获取当前登录用户信息（头像、姓名、企业名称），适用于个人任务筛选、数据权限控制、我的待办等场景。
+
+---
+
+## USER - 当前用户
+
+USER()
+
+返回当前查看页面的用户对象。
+
+**示例**：
+
+// 筛选当前用户负责的任务
+[任务表].FILTER([Each].[负责人] = USER())
+
+// 判断是否为当前用户创建的记录
+IF([创建人] = USER(), "我创建的", "他人创建")
+
+// 获取当前用户名称（需要根据实际字段结构调整）
+[用户表].FILTER([Each].[用户] = USER()).[姓名].FIRST()

package/templates/shared/wecomcli-smartpage/references/formula-reference.md

@@ -0,0 +1,192 @@
+# 公式字符串语法指南
+
+## 概述
+
+公式字符串是智能文档（智能主页 / 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.公式名])
+```