公式引用 V2

可以在 Vault 中创建公式来完成各种任务。Vault 使用类似 Excel™ 的公式语言，包括函数和运算符，来计算日期、文本字符串以及数字。

概念

请回顾以下概念，以熟悉 Vault 中公式的工作原理。

• 什么是公式？
• 公式在哪里使用？
• 公式的组成元素
• 运算符与函数&
• 变量与引用&

什么是公式

公式是一组用于创建期望结果的指令。例如，化学公式（两个 H 和一个 O 构成 H2O）。这并不是方程式的概念，因为氢和氧并不“等于”水，但可以用它们制造水。在某些情况下，公式是一种特殊类型的方程式，显示不同变量之间的关系。在这种情况下，公式是通过替换变量的值来进行评估（而非求解）的。

评估公式后，Vault 返回一个值或 True/False。

公式在哪里使用

公式在 Vault CDMS 中的多个地方使用：

• 数据验证规则
• 衍生条目
• 单位转换
• 视图中的衍生列
• 公式字段
• 字段默认值

公式的组成元素

公式由一个或多个表达式和参数组成。每个表达式包含值、函数、运算符、引用和变量，用于计算结果。参数是运算符或函数对表达式结果的操作。

运算符与函数&

运算符和函数是公式中的执行者。它们可以对公式中的表达式和值执行任务，以输出结果。

“运算符”和“函数”有什么区别？

所有运算符都是函数，但并非所有函数都是运算符。运算符仅返回与输入相同的数据类型，而函数则可以返回不同的数据类型。例如，考虑运算符 Add() 和函数 Value()。这两者都被视为数学函数。当将两个数字相加时，公式返回一个数字。Add(2, 2) 返回 4。当使用 Value() 函数时，输入文本，公式输出数字。Value(Right(“Veeofen 20”, 2) 返回数字 20，而不是文本字符串。

此参考中包含 Vault 当前支持的所有运算符和函数列表。

变量与引用&

可以在公式中使用变量和引用作为执行数据的占位符。当系统评估公式时，Vault 会将变量和引用替换为它们的实际执行值。每当在 Studio 中编写数据验证规则时，每次使用标识符调用数据收集条目时，都在使用变量。在 Vault 公式的上下文中，引用是指向相关对象值的变量，而不是指向对象值。例如，在使用 $site__vr.status__v 时，Vault 会将该引用替换为研究中心对象的状态值。

运算符

在构建公式时，使用以下运算符。除非另有说明，所有运算符在任何可以包含公式的地方都可用。

数学运算符

数学运算符在表达式中执行数学运算。

Add

计算两个值的和

语法

+

用途

value1 + value2

数据类型

Add 运算符接受以下数据类型：

• 数字

• 日期时间与数字（将数字解释为天数）

• 日期与数字（将数字解释为天数）

• 日期时间与时间

• 日期与间隔

• 日期时间与间隔

示例

Subtract

计算两个值的差

语法

-

用途

value1 - value2

数据类型

Subtract 运算符接受以下数据类型：

• 数字

• 日期

• 日期时间

• 日期时间与数字（将数字解释为天数）

• 日期与数字（将数字解释为天数）

• 日期与日期时间（将日期时间转换为日期）

• 日期与间隔

• 日期时间与间隔

• 时间与时间（返回分钟差）

示例

Multiply

计算两个值的乘积

语法

*

用途

value1 * value2

数据类型

Multiply 运算符接受以下数据类型：

• 数字

示例

Divide

计算两个值的商

语法

/

用途

value1 / value2

数据类型

Divide 运算符接受以下数据类型：

• 数字

示例

Remainder

计算一个值除以另一个值的余数

语法

%

用途

value1 % value2

数据类型

Remainder 运算符接受以下数据类型：

• 数字

示例

Parenthesis

优先计算括号内的表达式

语法

()

用途

(expression1)expression2

数据类型

Parenthesis 运算符接受以下数据类型：

示例

逻辑运算符

逻辑运算符在表达式中执行逻辑运算。

等于

计算两个值是否相等

语法

=

用途

value1 = value2

数据类型

等于运算符接受以下数据类型：

• 数字

• 文本

• 日期

• 日期时间

• 日期时间与日期（将日期时间转换为日期）

• 是/否

• 选项列表（两个选项列表必须都是单值选项）

• 选项列表与文本

示例

备注

• 当日期与日期时间进行比较时，Vault 会将日期时间转换为日期，并使用 Vault 的时区。

• 选项列表公式和运算符会评估值名称，而不是值标签。例如，一个选项列表 Level (level__v) 有三个值，分别命名为 study_level__v、country_level__v 和 site_level__v，标签分别为 Study、Country 和 Site。要评估选项列表的值，需使用名称定义公式，例如 level__v = "country_level__v"，而不是使用标签。

不等于

计算两个值是否不相等

语法

!=

用途

value1 != value2

数据类型

不等于运算符接受以下数据类型：

• 数字

• 文本

• 日期

• 日期时间

• 日期时间与日期（将日期时间转换为日期）

• 是/否

• 选项列表（两个选项列表必须都是单值选项）

• 选项列表与文本

示例

备注

• 当日期与日期时间进行比较时，Vault 会将日期时间转换为日期，并使用 Vault 的时区。

• 选项列表公式和运算符会评估值名称，而不是值标签。例如，一个选项列表 Level (level__v) 有三个值，分别命名为 study_level__v、country_level__v 和 site_level__v，标签分别为 Study、Country 和 Site。要评估选项列表的值，需使用名称定义公式，例如 level__v = “country_level__v”，而不是使用标签。

小于

计算一个值是否小于另一个值

语法

<

用途

value1 < value2

数据类型

小于运算符接受以下数据类型：

• 数字

• 日期

• 日期时间

• 日期与日期时间（将日期时间转换为日期）

示例

备注

• 当日期与日期时间进行比较时，Vault 会将日期时间转换为日期。

小于等于

计算一个值是否小于等于另一个值

语法

<=

用途

value1 <= value2

数据类型

小于等于运算符接受以下数据类型：

• 数字

• 日期

• 日期时间

• 日期与日期时间（将日期时间转换为日期）

示例

备注

• 当日期与日期时间进行比较时，Vault 会将日期时间转换为日期。

大于

计算一个值是否大于另一个值

语法

>

用途

value1 > value2

数据类型

大于运算符接受以下数据类型：

• 数字

• 日期

• 日期时间

• 日期与日期时间（将日期时间转换为日期）

示例

备注

• 当日期与日期时间进行比较时，Vault 会将日期时间转换为日期。

大于等于

计算一个值是否大于等于另一个值

语法

>=

用途

value1 >= value2

数据类型

大于等于运算符接受以下数据类型：

• 数字

• 日期

• 日期时间

• 日期与日期时间（将日期时间转换为日期）

示例

备注

• 当日期与日期时间进行比较时，Vault 会将日期时间转换为日期。

And

计算两个值或表达式是否均为 true

语法

&&

也可以使用 And() 来代替 &&。

用途

(expression) && (expression)

数据类型

And 运算符接受以下数据类型：

示例

Or

计算两个值或表达式中的至少一个是否为 true

语法

||

也可以使用 Or() 来代替 ||。

用途

(expression) || (expression)

数据类型

Or 运算符接受以下数据类型：

示例

文本运算符

文本运算符在表达式中执行文本操作。

连接

连接两个或多个文本字符串

语法

&

也可以使用 Concat() 来代替 &。

用途

text & text

数据类型

连接运算符接受以下数据类型：

示例

函数

在构建公式时，使用以下函数。除非另有说明，所有函数在任何可以包含公式的地方都可用。

数学函数

数学函数在表达式中执行数学运算。

Abs

计算数字的绝对值

语法

Abs()

用途

Abs(number)

示例

Average

计算提供数字的平均值

语法

Average()

用途

Average(number, number, number...)

示例

Ceiling

返回大于该值的下一个整数

语法

Ceiling()

用途

Ceiling(number)

示例

Floor

返回小于该值的下一个整数

语法

Floor()

用途

Floor(number)

示例

Max

返回集合中的最大值

语法

Max()

用途

Max(number, number...)

示例

备注

• 可以将此函数与数字、日期和日期时间数据类型一起使用。不能在单个 Max() 请求中混合数据类型。如果需要混合日期和日期时间，请使用 DateValue 将日期时间转换为日期。

Median

计算其参数的中位数。此函数接受数字数据类型的参数。

语法

Median()

用途

Median(number, number...)

示例

Min

返回集合中的最小值

语法

Min()

用途

Min(number, number...)

示例

备注

• 可以将此函数与数字、日期和日期时间数据类型一起使用。不能在单个 Min() 请求中混合数据类型。如果需要混合日期和日期时间，请使用 DateValue 将日期时间转换为日期。

Power

计算一个数的幂（指数）

语法

Power()

用途

Power(number, number)

示例

Round

将值四舍五入到定义的小数位数

语法

Round()

用途

Round(number, number of decimal places)

示例

备注

• Vault 根据小数点右侧的数字对数字进行四舍五入。如果该数字大于 5，Vault 向上四舍五入或远离零。如果该数字小于 5，Vault 向下四舍五入或朝向零。

Sqrt

返回数字的平方根

语法

Sqrt()

用途

Sqrt(number)

示例

备注

• 数字必须为正。

Sum

计算提供数字的总和

语法

Sum()

用途

Sum(number, number, number...)

示例

Value

将文本字符串作为数字返回

语法

Value()

用途

Value(text)

示例

备注

• 如果在 Value 函数中输入的文本无法解析为数字，则会收到错误提示。

逻辑函数

逻辑函数在表达式中执行逻辑运算。

And

当所有表达式都为真时，返回 true

语法

And()

也可以使用 && 来代替 And()。

用途

And(expression, expression)

示例

Case

将表达式的值与每个情况值进行比较，并返回对应的结果。如果没有值匹配，则返回最后一个参数。

语法

Case()

用途

Case(expression1, value1, result1, value2, result2, else_result)

数据类型

Case 函数接受以下数据类型：

• 数字

• 文本

• 是/否

• 选项列表

示例

备注

• 在处理选项列表字段时，例如 picklist__c，字段返回值的名称（study__v），而不是值的标签（Study）。

If

确定表达式是 true 还是 false。如果为 true，则返回给定的值；如果为 false，则返回另一个值。

语法

If()

用途

If(expression1, value1, value2)

示例

Includes

当选项列表包含与定义字符串或单值选项列表匹配的名称时，返回 true

语法

Includes()

用途

Includes(string/picklist value)

示例

备注

• Vault Platform 支持多值选项列表。对于 CDMS，使用 FindValue() 函数查找从选项列表中选定的值。

IsBlank

如果值为空，返回 true

语法

IsBlank()

用途

IsBlank(expression)

示例

IsNumber

当值为数字时，返回 true

语法

IsNumber()

用途

IsNumber(text)

示例

Not

当表达式为假时，返回 true；当表达式为真时，返回 false

语法

Not()

用途

Not(expression)

示例

Or

如果任意条件为真，则返回 true

语法

Or()

用途

Or(expression, expression)

示例

文本函数

逻辑函数在表达式中执行逻辑运算。

Concat

连接两个或多个文本字符串

语法

Concat()

也可以使用 & 来代替 Concat()。

用途

Concat(text, text...)

示例

Find

返回字符串在文本字符串中的位置

语法

Find()

用途

Find(find_text, within_text)

示例

Left

返回从文本字符串开头算起的指定数量字符

语法

Left()

用途

Left(text, number)

示例

长度

返回指定文本字符串的字符数

语法

Length()

用途

Length(text)

Lower

将指定字符串中的所有字母转换为小写

语法

Lower()

用途

Lower(text)

示例

Middle

返回两个指定位置之间的指定数量文本字符

语法

Middle()

用途

Middle(text, start_position, count)

示例

Right

返回从文本字符串末尾算起的指定数量文本字符

语法

Right()

用途

Right(text, number)

示例

Substitute

将字符串中的旧文本替换为新文本

语法

Substitute()

用途

Substitute(text, old_text, new_text)

示例

Text

根据指定格式将值转换为文本

语法

Text()

用途

Text(value, "format")

示例

备注

• d 1（某月中的第几日，1 位数）

• dd 01（某月中的第几日，2 位数）

• ddd Thu（星期几，3 个字母缩写）

• dddd Thursday（星期几，全拼）

• mm 03（月份，2 位数）

• mmm Mar（月份，3 个字母缩写）

• mmmm March（月份，全拼）

• yy 17（年份，2 位数）

• yyyy 2017（年份，4 位数）

• dd-mm-yyyy 31-03-2017

• yyyymmdd 20170331

• dd.mmm.yyyy 30.Mar.2017

• yyyy-mm-dd 2017-03-30

• mmmm yyyy March 2017

• dddd dd/mm/yy Thursday 31/03/17

Trim

删除文本字符串开头和结尾的空格和制表符

语法

Trim()

用途

Trim(text)

示例

Upper

将指定字符串中的所有字母转换为大写

语法

Upper()

用途

Upper(text)

示例

聚合函数

聚合函数在表达式中对聚合标识符的值进行操作。其中一些聚合函数也可用于任何标识符类型，但在此列出是为了提供聚合标识符可用的完整函数列表。

AllEqual

检查所有聚合标识符的值是否相等。如果值相等，则返回 true，否则返回 false。

语法

AllEqual()

用途

AllEqual(Identifier, Identifier, ...)

示例

Average

返回聚合标识符的所有值的平均值。

语法

Average()

用途

Average(Identifier), Average(Identifier, Identifier)

示例

Count

返回聚合标识符实例的数量（例如，指定重复表单的实例数量）。

语法

Count()

用途

Count(Identifier, Identifier, ...)

示例

备注

• 此函数包括空（或 null）值。如果某条目为空或标记为特意留空，它也会包含在计数中。使用 NoBlanks 函数移除所有 null 值。

CountIf

返回指定值在所有指定标识符中的出现次数。

语法

CountIf()

用途

CountIf(Value, Identifier, Identifier)

示例

FindValue

检查表达式中的标识符值中是否至少存在一个给定值。

语法

FindValue()

用途

FindValue(value, identifier)

示例

First

返回聚合标识符的第一个值（按最低序列号排序）。

语法

First()

用途

First(Identifier)

示例

GetAllMatches

返回第三个参数中的数组，这些数组的值与第二个参数中与第一个参数匹配的实例中的值相匹配。传递的两个标识符必须具有相同的值数量，因此必须使用相同的聚合路径。

语法

GetAllMatches()

用途

GetAllMatches(Value, Identifier, Identifier)

示例

备注

• 聚合路径：
  • 如果第一个标识符是 $EG[*].EV.F.IG.IT，则第二个标识符应以 $EG[*] 开头。
  • 如果第一个标识符是 $EG.EV.F[*].IG.IT，则第二个标识符应以 $EG.EV.F[*] 开头。
  • 如果第一个标识符是 $EG.EV.F.IG[*].IT，则第二个标识符应以 $EG.EV.F.IG[*] 开头。
  • 如果第一个标识符是 $EG[*].EV.F[*].IG[*].IT，则第二个标识符应以 $EG[*].EV.F[*].IG[*] 开头。
  • 如果第一个标识符是 $EG[*].EV.F[*].IG.IT，则第二个标识符应以 $EG[*].EV.F[*] 开头。
  • 如果第一个标识符是 $EG[*].EV.F.IG[*].IT，则第二个标识符应以 $EG[*].EV.F.IG[*] 开头。
  • 如果第一个标识符是 $EG.EV.F[*].IG[*].IT，则第二个标识符应以 $EG.EV.F[*].IG[*] 开头。

HasDuplicates

如果任何 2 个或更多数组的所有标识符值相等，则返回 true。如果重复项是 null 或为空值，则不返回 true。默认情况下忽略空值或 null 值。

语法

HasDuplicates()

用途

HasDuplicates(Identifier1, Identifier2, Identifier3)

示例

IsBlank

如果数组为空，则返回 true。如果数组中至少有一个值，即使该值为 null，也返回 false。

语法

IsAnyBlank()

用途

IsBlank(expression)

示例

IsAnyBlank

检查标识符中的任何值是否为空。如果有任何空值，返回 true。

语法

IsAnyBlank()

用途

IsAnyBlank(Identifier, Identifier, ...)

示例

Last

返回聚合标识符的最后一个值（按最高序列号排序）。

语法

Last()

用途

Last(Identifier)

示例

Max

返回聚合标识符中值的最大值（最高、最大）。

语法

Max()

用途

Max(Identifier), Max(Identifier, Identifier)

示例

Median

计算其参数的中位数。此函数接受数字数据类型的参数。

语法

Median()

用途

Median(number, number...)

示例

Min

返回聚合标识符中值的最小值（最低、最小）。

语法

Min()

用途

Min(Identifier), Min(Identifier, Identifier)

示例

NoBlanks

返回删除所有 null 值后的值数组，保留传递值的原始顺序。

语法

NoBlanks()

用途

NoBlanks(Identifier, Identifier, ....)

示例

Sum

返回聚合标识符值的总和。

语法

Sum()

用途

Sum(Identifier)

示例

日期和日期时间函数&

日期和日期时间函数在表达式中执行日期和日期时间的计算。

日期

从年、月、日值返回日期值

语法

Date()

用途

Date(year, month, day)

示例

DateValue

返回日期时间的日期部分

语法

DateValue()

用途

DateValue(datetime)

示例

Day

返回某月中的第几日

语法

Day()

用途

Day(date)

示例

Days

以时间间隔的形式返回指定的天数

语法

Days()

用途

Days(number)

示例

Hour

返回当前小时，范围为 0 到 23

语法

Hour()

用途

Hour()

示例

Hours

以时间间隔的形式返回指定的小时数

语法

Hours()

用途

Hours(number)

示例

备注

• 在当前版本中，此函数仅可用于定义 InWindow() 函数中的时间间隔。

• 此函数不返回日期时间或时间条目中的小时数。

• 不要使用此函数与小数点配合使用。相反，使用 Minutes() 函数与等效的分钟数，例如 Minutes(30) 代替 Hours(0.5)。

Minute

返回当前分钟，范围为 0 到 59

语法

Minute()

用途

Minute()

示例

Minutes

以时间间隔的形式返回指定的分钟数

语法

Minutes()

用途

Minutes(number)

示例

备注

• 在当前版本中，此函数仅可用于定义 InWindow() 函数中的时间间隔。

Month

返回日期中的月份

语法

Month()

用途

Month(date), Month(datetime)

示例

Months

以时间间隔的形式返回指定的月数

语法

Months()

用途

Months(number)

示例

NetWorkdays

返回两（2）个日期/日期时间之间的工作日天数。该函数支持混合使用日期和日期时间。使用日期时间时，请注意时区。此函数还接受用于周末和节假日时间表的可选参数。管理员可以通过业务管理 > 节假日时间表（Business Admin > Holiday Schedules）配置节假日。

语法

NetWorkdays()

用途

NetWorkdays(start_date/datetime, number_of_days, weekend_number, holiday_schedule)

示例

Now

返回当前日期和时间

语法

Now()

用途

Now(), Now(Timezone)

示例

备注

• Now() 不带时区参数时返回当前的 UTC 日期时间。

• 使用时区参数可以指定返回当前日期时间的时区。请参阅输入格式列表。

• 要返回研究中心时区的当前日期，可以使用 DateValue(Now(), @Site.timezone__v)。

Second

返回当前秒数，范围为 0 到 59

语法

Second()

用途

Second()

示例

StartOfDay

返回在指定时区当天开始的 UTC 日期时间

语法

StartOfDay()

用途

StartOfDay(day, "Timezone")

示例

Time

根据指定的小时、分钟和秒数返回时间

语法

Time()

用途

Time(hour, minute, second)

示例

Today

返回用户的当前日期。可以使用可选参数“timezone”返回特定时区的当前日期。

语法

Today()

用途

Today(), Today("timezone")

示例

Weekday

根据日期或日期时间返回星期几，结果为 1 到 7 的数字

语法

Weekday()

用途

Weekday(date), Weekday(datetime)

示例

Workday

返回一个日期，该日期是排除周末和可选节假日后的未来几天。此函数还接受用于周末和节假日时间表的可选参数。管理员可以通过业务管理 > 节假日时间表（Business Admin > Holiday Schedules）配置节假日。

语法

Workday()

用途

Workday(start_date/datetime, number_of_days, weekend_number, holiday_schedule)

示例

Year

返回指定日期或日期时间的年份。如果未提供日期或日期时间，则返回当前年份。

语法

Year()

用途

Year(date)

示例

Years

以时间间隔的形式返回指定的年数

语法

Years()

用途

Years(number)

示例

MaxDate

将日期的未知部分替换为可能的最大值

语法

MaxDate()

用途

MaxDate(unknown date), MaxDate(unknown date, timezone)

示例

备注

• 使用 MaxDate() 包装带有未知部分的日期用于表达式。

• 对不带未知部分的日期使用 MaxDate()，只返回原始日期。

• 使用时区参数可以指定返回当前日期的时区。请参阅输入格式列表。

MinDate

将日期的未知部分替换为可能的最小值

语法

MinDate()

用途

MinDate(unknown date), , MinDate(unknown date, timezone)

示例

备注

• 使用 MinDate() 包装带有未知部分的日期用于表达式。

• 对不带未知部分的日期使用 MinDate()，只返回原始日期。

• 使用时区参数可以指定返回当前日期的时区。请参阅输入格式列表。

MaxDateTime

将日期时间的未知部分替换为可能的最大值

语法

MaxDateTime()

用途

MaxDateTime(unknown date), MaxDateTime(unknown date, timezone)

示例

备注

• 对不带未知部分的日期时间使用 MaxDateTime()，只返回原始日期时间。

• 对于未知时间，Vault 返回小时数 23，分钟数 59，即 23:59。

• MaxDateTime() 不应单独用作设置某个条目值的函数，因为转换为 UTC 时间以获取标准化值会影响此函数。相反，应该使用此函数来执行需要已知日期时间进行评估的计算和比较。

• 使用时区参数可以指定返回当前日期时间的时区。请参阅输入格式列表。

MinDateTime

将日期时间的未知部分替换为可能的最小值

语法

MinDateTime()

用途

MinDateTime(unknown date), MinDateTime(unknown date, timezone)

示例

备注

• 对不带未知部分的日期时间使用 MinDateTime()，只返回原始日期时间。

• 对于未知时间，Vault 返回小时数 00，分钟数 00，即 00:00。

• MinDateTime() 不应单独用作设置某个条目值的函数，因为转换为 UTC 时间以获取标准化值会影响此函数。相反，应该使用此函数来执行需要已知日期时间进行评估的计算和比较。

• 使用时区参数可以指定返回当前日期时间的时区。请参阅输入格式列表。

InWindow

如果日期在指定的时间窗内（基于参考日期），则返回 true

语法

InWindow()

用途

InWindow(date, date, interval, interval, boolean, boolean)

数据类型

InWindow 函数接受以下数据类型：

• 日期

• 日期时间

• 时间

示例

备注

• 只能比较相同数据类型的对象（日期与日期比较，日期时间与日期时间比较，时间与时间比较）。

• 时间间隔可以使用以下函数定义：Minutes()、Hours()、Days()、Months()、Years()。

• 两个布尔参数用于指示是否包含整体时间窗的下限（第一个参数）和上限（第二个参数）。true 表示排除边界时间，false 表示包含边界时间。

SiteDateTime

根据研究中心时区，自动从日期条目和时间条目创建日期时间

语法

SiteDateTime()

用途

SiteDateTime(date, time)

数据类型

SiteDateTime 函数接受以下数据类型：

• 日期

• 时间

示例

SiteDateValue

返回日期时间条目中的日期，并自动转换为研究中心时区

语法

SiteDateValue()

用途

SiteDateValue(datetime)

数据类型

SiteDateValue 函数接受以下数据类型：

• 日期时间

示例

备注

• 当日期部分未知时，MinDateTime 和 MaxDateTime 不支持此函数。

弃用函数

以下函数在新表达式语法中不再可用。

连接

连接两个或多个文本字符串。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

Concatenate(text, text)

替代函数

Concat()&

DateAdd

返回一个日期，该日期基于从起始日期（date）的偏移（interval）。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

DateAdd(date, interval)

替代函数

date + number and date + interval

DateDiff

返回两个日期之间的天数差。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

DateDiff(end, start)

替代函数

date - date

DateTimeAdd

返回一个日期时间值，该日期时间基于从起始日期时间（datetime）的偏移（interval）。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

DateTimeAdd(datetime, interval)

替代函数

dateTime + number and dateTime + interval

DateTimeDiff

返回两个日期时间值之间的天数、小时数和分钟数差。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

DateTimeDiff(end, start)

替代函数

dateTime - dateTime

IfBlank

如果第一个参数为空，则返回第二个参数。如果不为空，则返回第一个参数。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

IfBlank(expression, expression)

替代函数

If(IsBlank())

IfNull

如果第一个参数为 null，则返回第二个参数。如果不为 null，则返回第一个参数。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

IfNull(expression, expression)

替代函数

If(IsBlank())

IsNull

当值为 null 时，返回 true。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

IsNull(expression, expression)

替代函数

If(IsBlank())

NumberEquals

如果两个数字参数相等，则返回 true。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

NumberEquals(number, number)

替代函数

=

PicklistEquals

将选项列表值的基础标签与现有全局选项列表值的基础标签进行比较，并返回 true 或 false。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

PicklistEquals(<picklist_field>, picklist_value__v)

替代函数

=

TextEquals

如果两个文本字符串相等，则返回 true。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

TextEquals(text, text)

替代函数

=

TimeDiff

返回两个时间之间的分钟差。此函数将结束时间（end）与起始时间（start）相减。此函数仅适用于使用 Expression Engine V1 的研究。请参阅使用 V2 时的替代函数。

语法

TimeDiff(end, start)

替代函数

Time - Time

日期格式

可用的日期格式列于下表：

数字格式

可用的数字格式列于下表：

系统变量

系统变量是系统定义用于存储值的动态对象，供一个或多个 Vault 应用程序引用。它们是动态的，因为它们的值会根据使用上下文变化。例如，@User 是一个系统变量，指向当前登录用户的配置文件，并允许访问多个属性，如用户的状态或电子邮件。

Vault Platform 系统变量

在当前版本中，Vault EDC 支持一个 Vault Platform 系统变量 @User。在编写规则时，可以引用此变量。

@User

引用当前登录的用户

示例属性

• @User.name__v：返回当前用户的姓名

• @User.status__v：返回当前用户的状态

• @User.email__v：返回当前用户的电子邮件

• @User.securityProfile__v：返回当前用户的安全配置文件

• @User.language__v：返回当前用户的语言

• @User.timezone__v：返回当前用户的时区

示例用法

Vault EDC 系统变量

EDC 有多个特定的系统变量，可在编写规则时使用。这些变量允许快速访问研究或病例手册层次结构中的对象。

以下对象和字段可在 Vault EDC 中用于系统变量：

研究

以下字段在研究（study__v）对象中可用于系统引用和变量：

Study Country（研究国家/地区）

以下字段在研究国家/地区（study_country__v）对象中可用于系统引用和变量：

研究中心

以下字段在研究中心（site__v）对象中可用于系统引用和变量：

备注

• 对于研究中心，name__v 返回该研究中心记录的研究中心编号字段值。研究中心编号是 name__v 字段的标签。

病例手册

以下字段在病例手册（casebook__v）对象中可用于系统引用和变量：

事件组

以下字段在事件组（event_group__v）对象中可用于系统引用和变量：

事件

以下字段在事件（event__v）对象中可用于系统引用和变量：

备注

• 在引用事件日期时，请始终定义事件。不要使用 @Event.event_date__v。对于完全限定的标识符，请使用 $EG.EVENT.event_date__v。

表单

以下字段在表单（form__v）对象中可用于系统引用和变量：

备注

• 使用 $EG.EVENT.FORM.intentionally_left_blank 作为完全限定标识符的示例格式。

• 在 24R2 版本中，in_progress_post_submit__v 表单状态的标签从“提交后进行中”（In Progress Post Submit）更改为“编辑中”（In Edit）。变量未更改，仍然是 in_progress_post_submit__v。

条目

以下字段在条目（item__v）对象中可用于系统引用和变量：

备注

• 不要对日期数据类型的条目使用 value__v。默认情况下，日期类型条目在任何计算中使用 value_normalized__v，强制使用 value__v 会导致执行错误。

• 使用 $EG.EVENT.FORM.IG.ITEM.change_reason__v 作为完全限定标识符的示例格式。

• 数学函数可以用于单位条目类型。

• Vault 自动将单位条目的标识符值转换为标准单位。例如，@Form.IG.UNITITEM.value_translated__v。可以使用 {{@Form.IG.UNITITEM.value__v}} 返回无单位的数值。

请注意，部分定义的路径也支持规则表达式。例如，@EventGroup.EVENT.field__v、@EventGroup.EVENT.FORM.field__v、@EventGroup.EVENT.FORM.IG.ITEM.field__v、@Event.FORM.field__v、@Event.FORM.IG.ITEM.field__v。

系统引用

在 Vault 公式的上下文中，引用是指向相关对象值的变量，而不是指向对象值。例如，在使用 $study__vr.phase__v 时，Vault 会将该引用替换为与当前研究中心关联的研究对象的阶段值。

Vault Platform 系统引用

以下系统引用可作为 Vault Platform 的一部分使用，因此可以在应用程序中提供公式的任何地方使用这些引用：

对象到相关对象

允许公式访问与当前上下文对象相关的对象的属性。

用途

relationship__vr.name__vr

示例

principal_investigator__vr.research_and_focus_areas__v = "Macular Degeneration"

如果当前研究中心（对象）的主要研究者在黄斑变性方面有研究重点，则返回 True。

Vault EDC 系统引用

以下系统引用作为 Vault EDC 的一部分提供，因此只能在 EDC（数据验证规则、单位转换等）接受公式的应用程序区域中使用。

EDC 研究层次结构中的对象遵循以下顺序：

研究 → 研究中心 → 病例手册 → 事件组 → 事件 → 表单 → 条目组 → 条目

EDC 表达式可以引用研究层次结构中的多个不同对象及其属性。要引用这些对象，它们在研究层次结构中的访问路径必须使用特定语法编写。

每个引用必须以 $ 符号或 @ 符号开头，并且对象和属性之间必须用句点（.）分隔。

以下对象和字段可在 Vault EDC 中用于系统引用与变量：&

研究

以下字段在研究（study__v）对象中可用于系统引用和变量：

Study Country（研究国家/地区）

以下字段在研究国家/地区（study_country__v）对象中可用于系统引用和变量：

研究中心

以下字段在研究中心（site__v）对象中可用于系统引用和变量：

备注

• 对于研究中心，name__v 返回该研究中心记录的研究中心编号字段值。研究中心编号是 name__v 字段的标签。

病例手册

以下字段在病例手册（casebook__v）对象中可用于系统引用和变量：

事件组

以下字段在事件组（event_group__v）对象中可用于系统引用和变量：

事件

以下字段在事件（event__v）对象中可用于系统引用和变量：

备注

• 在引用事件日期时，请始终定义事件。不要使用 @Event.event_date__v。对于完全限定的标识符，请使用 $EG.EVENT.event_date__v。

表单

以下字段在表单（form__v）对象中可用于系统引用和变量：

备注

• 使用 $EG.EVENT.FORM.intentionally_left_blank 作为完全限定标识符的示例格式。

• 在 24R2 版本中，in_progress_post_submit__v 表单状态的标签从“提交后进行中”（In Progress Post Submit）更改为“编辑中”（In Edit）。变量未更改，仍然是 in_progress_post_submit__v。

条目

以下字段在条目（item__v）对象中可用于系统引用和变量：

备注

• 不要对日期数据类型的条目使用 value__v。默认情况下，日期类型条目在任何计算中使用 value_normalized__v，强制使用 value__v 会导致执行错误。

• 使用 $EG.EVENT.FORM.IG.ITEM.change_reason__v 作为完全限定标识符的示例格式。

• 数学函数可以用于单位条目类型。

• Vault 自动将单位条目的标识符值转换为标准单位。例如，@Form.IG.UNITITEM.value_translated__v。可以使用 {{@Form.IG.UNITITEM.value__v}} 返回无单位的数值。

示例

例如，要访问研究结束时生命体征收集的日期，可使用以下表达式（具体取决于研究在 EDC Studio 中的构建方式和对象的名称）：

$End_of_Study.End_of_Study_Visit.Vital_Signs.General_Information.Date.value__v

该引用访问的是研究结束时生命体征收集的日期（日期条目在生命体征表单的常规信息条目组中，位于研究结束访视事件中，属于研究结束事件）。

还可以访问其他级别的属性，例如事件或表单：

$Cohort_A.Visit_1.event_date__v

该引用访问的是队列 A 事件组中的第一次访视（访视 1 事件）的事件日期。

定义简短路径

指定访问表达式中所有对象的完整路径可能很长且繁琐，因此您可能希望使用 #define 语句定义简短路径，以引用表达式中经常使用的表单或条目组（或任何其他对象）。

可以在 #define 语句中同时使用系统引用和系统变量。

定义简短路径的语法是：

#define vitals_info “$End_of_Study.Vital_Signs.General_Information”

然后可以使用对象 vitals_info 访问相关对象和属性。

上一节中的示例：

$End_of_Study.End_of_Study_Visit.Vital_Signs.General_Information.Date.value__v

可以简化为：

vitals_info.Date.value__v

构建公式

可以使用的公式编辑器功能，该功能能否使用取决于在 Vault 中使用公式的具体位置。关于特定功能区域的公式详细信息，请参阅：

• 在 Studio 中创建规则
• 定义默认单位与转换&
• 创建视图

有效字段与数据类型&

定义公式时，请确保公式中的运算符、函数、字段和值与字段的数据类型匹配。例如，不能在公式中使用日期字段来更新文本字段，除非使用文本函数进行转换。

Vault 会在公式中自动转换以下数据类型：

• 对象引用 → 文本
• 选项列表 → 文本（在对象上的公式字段或字段默认值中除外）
• 日期时间 → 日期（在对象上的公式字段或字段默认值中除外）

Vault 提供一些可用于转换数据类型的函数：

• 日期 → 文本： Text(date, format)
• 数字 → 时间间隔：Days(number)、Months(number)、Years(number)、Hours(number)、Minutes(number)
• 文本 → 数字：Value(text)

标识符

构建用于规则或视图的公式时，可以使用标识符来引用研究数据，例如引用表单上的某个条目。

可以按层次结构定义标识符，直到唯一为止，并用句点（.）分隔标识符：

$Event_group.Event.Form.Item_group.Item

然后再可以使用条目对象上的字段来引用收集的值：

$Event_group.Event.Form.Item_group.Item.value__v

在 Studio 规则编辑器中，Vault 可以在您输入时尝试自动完成标识符、变量、运算符和函数。按下 Ctrl + 空格键可查看下拉列表中的自动完成选项。如果在开始键入标识符之前按下 Ctrl + 空格键，Vault 会在下拉列表中列出所有有效标识符。

如果在多个地方使用设计定义，例如，如果在多个表单中使用某个条目，可以使用 @ 指定要涵盖该定义的所有实例。

例如，要在多个表单中评估某个条目，可以使用 @Form.Item_group.Item。可以在事件组、事件和表单级别使用此功能。

在禁用和设置条目值规则中，只能使用 @Form 标识符（不能使用 @EventGroup、@Event 或 @ItemGroup）。

#Define 语句

可以使用 #define 语句为标识符定义变量，这样就不必每次在公式中引用标识符时还重新编写它们。

例如，要为舒张压（Diastolic Blood Pressure）条目定义简化名称：

#define diastolic @Form.Vitals.Diastolic_blood_pressure.value__v

现在，每次在公式中使用 diastolic 时，Vault 会自动将其读取为 #define 语句中的标识符。

• 将 #define 语句放在公式的顶部，每行一个。
• 必须在每个公式中都包含 #define 语句。这些变量是在规则的上下文中定义的，因此无法跨多个规则使用单个 #define 语句。

注释

可以使用注释在公式中做备注。例如，可能希望添加简短的表达式说明，以便日后提醒自己如何使用。

要在公式中添加注释，请在公式顶部（第一行）输入注释文本，并将其用 /* 和 */ 括起来。

/* This is a comment.*/

公式指南

编写公式时，请遵循以下指南：

• 小数点使用句点，而不考虑 Vault 区域设置。
• 公式的最大表达式长度为 1,500 个字符。
• 当公式包含多个表达式时，请使用括号 () 将表达式括起来。
• Vault CDMS 将数字视为浮点数，并在公式评估结束时对其进行解析。

函数

在公式表达式中添加函数时，请遵循以下指南：

• 函数名称区分大小写。
• 函数可以有一个或多个参数。不同函数允许不同数量的参数。
• Vault 从左到右处理公式。对于嵌套函数，Vault 先从左到右处理子函数，然后再处理父函数。

运算符

在公式表达式中添加运算符时，请遵循以下指南：

• 标准的运算顺序适用：乘法和除法优先于加法和减法，除非使用括号进行分组覆盖。
• 可以使用数学运算来添加数字和数字类型的字段。
• 不能在数学运算中使用日期类型字段。使用上述的各种日期函数。

布尔字段

编写引用“是/否”类型对象字段或布尔类型条目（复选框）的公式时，使用 true 表示“是”，使用 false 表示“否”（未勾选的复选框）。

空值处理

这决定了 Vault 在公式中处理空字段值的方式：

• 作为零：Vault 将空值替换为零，以继续完成公式计算。
• 作为空：Vault 将空值视为 null，导致整个表达式返回 null/空值。

示例

此示例展示不同的空值处理选项对此公式结果的影响：

公式：

NUM1 + NUM2 

错误处理

任何语法错误都必须在创建或更新规则之前解决。操作从条件字段中点击移出时，如果公式语法不正确，Vault 会显示“表达式无效”（Expression is invalid）。以下是常见的语法错误：

• 返回的数据类型不匹配。例如，如果返回类型为日期，但表达式返回一个数字，那么将收到错误。
• 公式缺少结束括号，或者括号不匹配。
• 函数中参数的数量不正确。例如，在 if(expression, value 1, value 2) 函数中使用了三个参数。
• 函数具有不正确的参数值。

迁移（V1 到 V2）

Enhanced Vault Formulas 在使用公式的应用平台区域中自动可用，可供立即使用。

对于 EDC 特定的公式使用（规则和视图），必须在每个研究中启用 Enhanced Vault Formulas。

在 19R1 版本（2019 年 4 月发布）之前创建的研究无法升级到增强型公式语言。此类研究必须继续使用 V1 公式语言（请参阅此处的参考）来处理其规则和派生列映射。

如何为研究启用 Enhanced Vault Formulas

要在研究中启用 Enhanced Vault Formulas，需要：

1. 验证研究中没有使用 V1 公式语言的任何公式。
2. 导航到管理 > 业务管理（Admin > Business Admin）中的研究配置（Study Configuration）对象。
3. 找到研究并点击打开它。
4. 单击编辑。
5. 在 Expression Engine 版本字段中，输入 2。
6. 点击保存。

您的研究现在正在使用增强型公式语言。

将现有设计移动到启用 Enhanced Vault Formulas 的新研究中

还可以选择创建一个新研究（新研究默认启用 Enhanced Vault Formulas），并将现有设计导入该新研究中。Vault 会导入系统管理的规则（必填、范围和未来日期验证检查）以及单位转换（自动将 value__v 替换为 $value__v），但不导入自定义规则或派生列公式。

1. 导出研究设计。详情请见此处。
2. 创建新研究。
3. 将研究设计导入新研究中。详情请见此处。
4. Vault 会删除任何自定义规则和派生列公式，然后导入研究。

现在可以使用 Enhanced Vault Formulas 为规则、派生列和单位转换创建新的公式表达式。

其他资源

另有一些包含具体用例信息的帮助主题，详细说明了如何使用公式：

• 在 Studio 中创建规则
• 定义默认单位与转换&
• 创建视图