飞书项目中公式计算字段的使用指南

功能上新

计算公式字段编辑器全新升级！优化计算字段编写界面，提升公式编写体验。

功能点	新版	旧版
调整布局与样式，支持编辑器全屏放大	250px\|700px\|reset 250px\|700px\|reset	250px\|700px\|reset
公式输入支持原地搜索在公式输入区输入字段、函数名称时，在联动下方资源库进行结果查找的基础上，可原地唤起搜索结果下拉列表通过@可唤起选择器（选项/人员/团队/日期/关联工作项），且支持输入搜索	250px\|700px\|reset 250px\|700px\|reset	不支持
关联工作项可搜索，提升可读性	250px\|700px\|reset	250px\|700px\|reset
支持站外文本公式复制	公式：SUM(FILTER(${流程节点},each.${节点状态} == $option{已完成}).${节点估分}) 复制后： 250px\|700px\|reset 具体复制规则请参考复制公式	不支持
支持公式格式美化一键对公式结构进行换行和缩进	250px\|700px\|reset	不支持
支持快捷键	上键、下键、左键、右键：移动光标回车键：确认选择/换行 TAB 键：公式缩进 Ctrl+Z：取消上一步操作	不支持

介绍

度量场景复杂多变？飞书项目可自定义灵活敏捷的公式计算字段，应用于进度汇总、风险预警、资源投入计算等多种业务场景，直观查看关键指标。

功能入口

字段的添加需要管理员前往对应的工作项进行配置，具体路径为：空间配置 - 工作项管理 - 工作项（需求、缺陷等）- 字段管理 - 新建字段 - 其他 - 选择“公式计算”类型添加计算公式字段。

250px|700px|reset

学习准备

一个案例认识计算公式

在开始学习使用计算公式前，我们先来了解一个简单例子：如果我们要算一个周期，是不是首先应该有日期？这里我们假设计算距离今年春节还有多少天，也就是春节的日期减去今天的日期，再得到一个天数。简化公式为：

春节日期 - 今天日期 = 天数数数数数

那么在飞书项目计算公式中提供了一个叫 daysBetween() 的函数，来计算两个日期的天数间隔，上述公式可以这样写：

daysBetween(今天日期,春节日期) //等价春节日期 - 今天日期 = 天数数数数数

那再进一步，我们需要取得距离今年春节还有多少天工作日？人工数日期？但是有了计算公式，这个数的动作就变成了函数自动解析。

顺着上面思路，借助 workdaysBetween() 的函数，可以将两个日期中的工作日提取出来，得到“距离今年春节还有多少天工作日”的结果。

workdaysBetween(今天日期,春节日期) //等价春节日期 - 今天日期且去除非工作日的天数。。。。。

以此类推，我们要计算个数，用 COUNT()、求和用 SUM()、计算平均用 AVG()。具体使用参考函数部分，按照指定格式书写即可。

理解计算公式

再回到我们计算公式，逻辑和上述案例一致，首先要知道取什么数据，然后怎么处理这些数据，最后输出一个结果。比如直接取某个字段的值，提出时间、销售额字段。接着是怎么处理这些取得的数据，比如筛选上面取得的数据，用筛选后的数据来求和、求差、求数、求占比等等。

筛选：条件筛选数据，取属于某个节点的确认时间，获取某个需求的完成时间等；

求和：估分之和、金额之和、日期之和等；

求差：时间周期、人力之差等；

数量：需求数量、缺陷数量

平均：平均周期

占比：完成节点占比，完成缺陷占比

大小值：最大日期、最小日期

组合：两个字段值重新组合成一个新的字段

处理后的数据会输出一个值，这个值输出格式可以是数字、日期、字符串或者布尔值。最终根据我们字段配置展示在视图、详情页、节点表单上。

新建计算公式字段

添加计算字段

进入计算公式界面后，有三个区域：公式编辑区、字段与函数选择区、字段与函数示例区和输出结果设置区。

计算公式编辑区：书写计算公式的区域，可以使用类似count(filter({流程节点},each.{节点状态}=="进行中").{KEY})来表示进行中节点的数量。

字段函数选择区：选择如拉群方式、名称与业务线等字段，也可以选择如参与人员、流程节点、终止原因等对象数组；还可以手动选择计数count()、求和 sum() 等函数。

字段与函数示例区：在本区域内可以了解字段与函数的介绍与使用示例，方便快速上手使用。

计算结果显示区：根据字段输出的结果类型提示展示类型，一般有：字符串、数字、布尔、日期等。注意，字段类型一旦输出确认后，不能做变更，需要变更请重新新建一个公式计算字段。

全屏

支持点击【全屏】放大公式编辑区，点击【退出全屏】即可恢复至编辑框初始状态。

格式美化

支持一键美化格式，自动对公式结构进行换行和缩进，公式编写更具可读性和逻辑性。

250px|700px|reset

复制公式

支持站外公式复制，即按格式要求带有前缀信息的公式，可从文档、聊天框等位置，复制到【度量-计算字段编辑区】并自动匹配相关字段。

使用范围：如仅在计算字段编辑器内编写公式，无需书写前缀。如需要将公式从编辑器复制到文档，系统会自动匹配相关前缀。如需要从文档将公式复制到计算字段编辑器，公式需带有相关前缀才能最大化的复制并匹配成功。

复制格式要求：为了更好的对公式进行匹配，不同的信息需要匹配不同的前缀符号，例如字段【优先级】前需增加$，最终效果为${优先级}。

前缀规则	字段示例	复制公式示例
字段增加前缀$	${优先级}	COUNTIF(${工作项id},${优先级}==$option{P0})
选项增加前缀$option	$option{P0}	COUNTIF(${工作项id},${优先级}==$option{P0})
人员增加前缀$user	$user{梦瑶}	SUM(FILTER(${流程节点},each.${节点人员}==$user{梦瑶}).${节点估分})
团队增加前缀$team	$team{PM}	SUM(FILTER(${流程节点}.${节点人员},CONTAINS(each.${所属团队},$team{运营团队})).${估分插值})
关联工作项增加前缀$related	$related{需求-关联缺陷}	COUNT(($related{需求-关联缺陷}）

数据结构

理解数据结构在计算公式中至关重要。数据结构本质对数据类型的分类，分类为数值、字符串、布尔、日期、数组以及对象类型。具体清单可以参考下方表格。

基础数据结构	数值类型	-1、789、99.99、0.000035、30%
		字符串类型	"this is a string"、"你好"、""
		布尔类型	true、false
		日期时间类型	日期：date("2022-03-03")、date("2022/3/3")、date("2/28/2021") 时间：time("2022-03-03 18:02:53")、time("2022/3/3 18:02:53" )、time("2/28/2021 18:02:53" )
		数组类型	[1,2,3,4,5,6]、[789,99.99,-1]、["P0","P1","P2","P3"]
		对象类型	{"产品经理"："飞小小"} { "产品经理":"飞小小", "身高":160, "合作方":["书大大","项目目"], "产品技能": { "沟通": 100, "逻辑": 100, } }
高级数据结构	对象数组	[{"姓名":"飞小小"}, {"姓名":"书大大"}, {"姓名":"项目目"}]
		人员	人员：对象类型，无法被构造，系统预置，可以通过函数获取，并用于入参。通过 @ 取得数据。
		字段	字段：对象类型，无法被构造，系统预置，可以通过函数获取，并用于入参。常见如流程节点、业务线等。

运算符

运算符与小时候学习数学一致，适用于数值类型的字段使用。而比较运算符适用于数字与日期之间的比较。

算术运算符	+	加：数值求和 P1+P2+...+Pn Px：数值类型 return：数值类型	1+2+3 -> 6
		-	减：数值相减，或表示数字的负值 P1-P2-...-Pn Px：数值类型 return：数值类型	1-2-3 -> -4
		*	乘：数值相乘 P1P2...*Pn Px：数值类型 return：数值类型	123 -> 6
		/	除：数值相除 P1/P2 Px：数值类型 return：数值类型	1/2/2 -> 0.25
比较运算符	<	小于：小于2个数值、日期小于比较 P1<P2 Px：数值类型/日期类型（类型相同才能对比） return：布尔类型	<2 -> true
		<=	小于等于：2 个数值、日期间大于比较 P1>P2 Px：数值类型/日期类型（类型相同才能对比） return：布尔类型	1<=1 -> true
		>	大于：2 个数值、日期间大于比较 P1>P2 Px：数值类型/日期类型（类型相同才能对比） return：布尔类型	1 > 2 -> false
		>=	大于等于：2 个数值、日期间大于等于比较 P1>=P2 P：数值类型/日期类型（类型相同才能对比） return：布尔类型	3 >= 1 -> true
		==	等于：2 个数值、日期间等于比较 P1==P2 P：数值类型/日期类型（类型相同才能对比） return：布尔类型	1 == 1 -> true
		!=	不等于：2 个数值、日期间不等于比较 P1 != P2 p：数值类型/日期类型（类型相同才能对比） return：布尔类型	1 != 2 -> true

函数

函数可以理解为封装了运算能力的合集，每个函数都有特定的功能。比如 COUNT() 计算个数，SUM() 用来求和，string() 用来转换其他类型为字符串类型等等。

统计函数	COUNT()	计数：获取数组中元素个数 count(P1) P1：数组 return：数值类型	count([1,2,3]) -> 3 count(关联缺陷)
		COUNTDISTINCT()	去重计数：获取数组中去重后的元素个数 countdistinct(P1) P1：数组 return：数值类型	countdistinct( [1,2,3] ) -> 3 countdistinct(关联缺陷)
		COUNTIF()	条件计数：按条件获取数组中元素个数 countif(P1，P2) P1：数值数组 P2：条件表达式 return：数值类型	countif(关联缺陷，each.优先级 == P0）
		COUNTDISTINCIF()	条件去重计数：按条件获取数组中去重后的元素个数- countdistictif(P1，P2) P1：数组 P2：条件表达式 return：数值类型	countdistinctif(关联缺陷，each.优先级 == P0）
		SUM()	求和：数组求和 SUM(P1) P1：数值数组，[1,2,3] return：数值类型	sum([1,2,3])
		SUMIF()	条件求和：按条件求数组总和 SUMIF(P1，P2) P1：数值数组 P2：条件表达式 return：数值类型	sumif(filter(关联缺陷, each.优先级 == "P0").估分), 需求状态 == "已完成")
		AVG()	求平均：数组求平均值 avg(P1) P1：数值数组 return：数值类型	avg([1,2,3]) avg(filter(关联缺陷, each.优先级 == "P0").时间))
		AVGIF()	条件求平均：按条件求数组平均值 avgif(P1，P2) P1：数值数组 P2：条件表达式 return：数值类型	avgif(filter(关联缺陷, each.优先级 == "P0").时间), 需求状态 == "已完成"）
		MAX()	求最大值：数组求最大值 max(P1) P1：数值数组/日期数组 return：数值/日期	max([1,2,3]) max(filter(关联缺陷, each.优先级 == "P0").估分))
		MAXIF()	求条件最大值：按条件求数组最大值 maxif(P1，P2) P1：数值数组/日期数组 P2：条件表达式 return：数值/日期	maxif(filter(关联缺陷, each.优先级 == "P0").估分), 需求状态== "已完成"）
		MIN()	求最小值：数组求最小值 min(P1) P1：数值数组/日期数组 return：数值/日期	min([1,2,3]) min(filter(关联缺陷, each.优先级 == "P0").时间))
		MINIF()	求条件最小值：按条件求数组最小值 minif(P1，P2) P1 ：数值数组/日期数组 P2：条件表达式 return：数值/日期	minif(filter(关联缺陷, each.优先级 == "P0").估分), 需求状态== "已完成"）//P0缺陷的最小估分
逻辑函数	AND() 可简写为：&&	判读全部参数值是否均为真 and(P1，P2，...) P：条件表达式 return：布尔类型	filter(关联缺陷, each.优先级 == "P0" && 状态== "已完成")
		OR() 可简写为：\|\|	判读全部参数值是否任一为真 or(P1，P2，...) P：条件表达式 return：布尔类型	filter(关联缺陷, each.优先级 == "P0" \|\| 状态== "已完成")
		IF()	根据提供的条件参数，条件计算结果为 TRUE 时，返回一个值；条件计算结果为 FALSE 时，返回另一个值 if(P1，P2，P3) P1：条件表达式 P2：基础数据类型，为真时的返回值，可以为null或计算公式返回值 P3：基础数据类型，为假时的返回值，可以为null或计算公式返回值 return：基础数据类型	if(sum(filter({流程节点},match(each.{名称},"开发")).{节点估分}) > 50,"大需求","小需求")
		NOT()	对提供的参数值求反 not(P1) P1：布尔，包括计算结果为 TRUE 或 FALSE 的任何或表达式 return：布尔	not(优先级 == P0）
比较函数	valid() VALID()	判断字段是否有效 valid(P1) P1：字段 return：布尔	valid(优先级）
比较函数		empty()	判断字段是否为空（如果无效则会判断为false） empty(P1) P1：字段 return：布尔	empty(优先级）
数值类操作运算	round()	按指定位数进行四舍五入的取值 round(P1，P2) P1：数值类型 //源数据 P2：数值类型位数 return：数值类型 P2 省略则默认为0（保留整数）	round(2.15，0) -> 2
		ceil()	保持位数不变，舍弃小数值，向上取整展示 ceil(P) P：数值类型 return：数值类型	ceil(2.15) -> 3.00 ceil(-1.3) -> -1.0
		floor()	保持位数不变，舍弃小数值，向下取整展示 floor(P) P：数值类型 return：数值类型	floor(2.15) -> 2.00 floor(-1.3) -> -2.0
		sqrt()	开根号 sqrt(P) P：数值类型(正数) return：数值类型	sqrt(16) -> 4 sqrt(-16) -> N/A
日期函数	workdaysBetween()	计算日期范围包含的工作日天数 workdaysBetween(P1，P2) P1：日期类型 P2：日期类型 return：数值类型	workdaysBetween(date("2022-3-20")，date("2022-3-27")) //输出结果 5
		daysBetween()	计算日期范围包含的自然日天数 daysBetween(P1，P2) P1：日期类型 P2：日期类型 return：数值类型	daysBetween(date("2021-1-1")，date("2021-1-10")) //输出结果 9
		date_add()	计算日期增减计算后的返回值 date_add(P1，P2，P3) P1：日期类型(date) P2：数值类型 P3：字符串类型，可选 day、week、bi-week、month、bi-month、quarter、year return：日期类型（date）	date_add(预计开始时间，-10)
		getYear()	提取日期所在年 getYear(P) P：日期类型 return：数值类型	getyear(today()) -> 2022
	getMonth()	提取日期所在月份 getMonth(P) P：日期类型 return：数值类型	GETMONTH(TODAY()) ->11
	getWeekOfYear()	提取日期所在周（今天第几周） getWeekOfYear(P) P：日期类型 return：数值类型	GETWEEKOFYEAR(TODAY()) ->45
字符串操作	join()	字符串元素拼接 join([P1,P2,...],"P") Px：字符串 P：字符串作为拼接符，例如 - 作为拼接符 return：字符串类型（string）	join([{名称},{当前状态}],"-") // "计算字段-开发中"
		match()	字符串匹配 match(P1,P2) p：字符串类型 return：布尔类型	match({名称},"开发") // 匹配 iOS 开发、前端开发
		length()	计算字符串的字符个数 length(p) p：字符串类型 return：数值类型	length({终止原因}.{原因}) // 20
容器操作函数	. each.	点语法 P1.P2.P3.. P:数据结构中的数据类型构成，在 filter 中，流程节点, each.名称=xxx，这里 each 等价流程节点	filter({流程节点},each.{名称}=="埋点设计" \|\| each.{名称}=="AB方案设计").{节点估分}
		filter()	筛取对象数组值 filter() P1：对象数组