数字大屏 VFormula 语言定义

VFormula 语言是指数字大屏产品中的可嵌入表达式文本功能，通过使用形如 text {{ expression }} 的形式进行内容书写，从而提升功能灵活度，降低用户的使用成本。对于新用户，VFormula 语言内容均为简单文本，无需了解表达式能力，配合用户界面均可进行功能实施；对于进阶与专家用户，VFormula 语言可以使用内嵌表达式的方式提升灵活度上限，在数据分析、内容表现处理、时间处理、条件判断方面提供支持。
VFormula 语言的形态如下：

更新于 2021-12-21                        // 纯文本，内容为 "更新于 2021-12-21"
共加载{{ $table.count }}项                   // 插入表达式，内容为 "共加载3200项"
{{ FORMAT($row.measure.sales,"#,###.##") }} // 插入表达式，内容为 12,321,333.92
{{ CEIL($row.measure.sales/10000) }}万      // 插入表达式，内容为 2912 万
{{ MATCH($row.index > 3,$row.index, 4) }}   // 插入表达式，内容根据下标为 1|2|3|4

VFormula 是一门大小写敏感、表达式嵌入式的简单语法规则，整体被作为数字或文本内容，使用特定的标记插入表达式；表达式内仅支持简单的方法调用、变量使用与计算。

2.1 数据类型

2.1.1 Text 文本类型

在表达式中，使用双引号括起来的值是文本类型。

{{ "hello" }} WORLD // "hello WORLD"

2.1.2 Number 数字类型

在表达式中，独立参与计算的阿拉伯数字为数字类型，数值类型可能为包含小数点.的小数，小数参与计算位数至多有4位。

// 需要关注的是，当v-formula语句整体为一个表达式时，语句返回值为表达式返回值
{{ 12 }}       // 12
{{ 12.2 }}     // 12.2
{{ 12.3031 }}  // 12.3031
值为{{ 22.31 }} // "值为22.31"

2.1.3 Bool 真值类型

在表达式中，形为 true 或 false 的特定内容为真值类型，分别代表真与假。例如，一个属性为开关，值为真时便是开，值为假时便为关。

{{ true }} // true 真值
{{ false }} // false 假值

2.1.4 Object 对象类型

对象类型是值的合集，用来描述一个复杂结构。比如一个小狗名字叫 Aa，年龄 2 岁，小狗被我们称为对象，年龄和名字是他的属性，此时用以描述这个dog的内容是 name:"Aa", age:2; 当我们拿 dog 的 age,就会得到 2，这个动作称为 访问对象的属性。

{{ dog.age }} // 2

2.2 表达式语句

2.2.1 变量与值运算

在 VFormula 表达式中，支持变量与值参与计算，包括加减乘除四则运算、余运算、比较运算、真值运算。

{{ 12 + 2 - 22 }}   // 值计算
{{ variable + 12 }} // 变量与值计算
{{ variable + varibale }} // 变量计算
{{ variable + (12 - variable) }} // 嵌套运算优先级的四则运算
{{ variable >= 12 }} // 变量与值的比较运算

运算优先级为 / = % = * > + = - > >= = == = != = > = < = <=;
相等优先级从左至右计算，小括号()括起来的表达式提升运算优先级计算。

{{ 12 + 22 * 2 / 11 % 3 }}  // 22 * 2 -> 44 / 11 -> 4 % 3 = 1, 12 - 2 - 1 = 11;
{{ (12 + 22) * 2 / 11 % 3 }} // 12 + 22 -> 34 * 2 -> 68 / 11 -> 6.1818 % 3 -> 0.1818
{{ 12 + 22 > 22 }} // 12 + 22 -> 34 > 22 -> true

// 其中加好同时有拼接文本、拼接文本与数字的功能
{{ "€ " + money }} // "€ 1232"
{{ firstName + " " + secondName }} // "Oboo Cheng"

2.2.2 对象索引

VFormula 中对象类型包含多个可以参与计算的值，当使用这些值时使用.进行访问对象的索引，例如：

{{ variable.a.b }} // variable为 {a:{b:12}}， 则 variable.a.b 为 12；
{{ variable }} // variable为{a:1}, 但表达式最终的返回结果应当是数字或字符串，所以是非法表达式

2.2.3 方法调用

使用形如 方法名(参数)的形式来进行功能调用的形式是方法调用，能够根据传入值得到一个处理后的结果值。一个方法可以包含多个参数，参数使用,进行区分。

3.1 $Table: Object

在所有数据展示内容上存在的变量，代表当前数据内容。

3.2 $RowData : Object

在重复内容上下文中存在的变量，代表当前行的数据，结构内容为 ：

[name]:valueOfRow

举例来说，根据下列表格重复，第二项的取值内容为：

$RowData.dimension.name // "Mily"
$RowData.measure.age // 33

3.3 $Min

在重复内容上下文中存在的变量，形如 $row，但不与每行内容相关，而是持有每字段的最小值。

$min.age // 12

3.4 $Max

在重复内容上下文中存在的变量，形如 $row，但不与每行内容相关，而是持有每字段的最大值。

$max.age // 33

3.5 $Event

在有事件上下文的交互场景下存在的变量，可以携带相应的上下文信息，例如在GIS中点击省，会有：

You clicked {{ $Event.region }} // "You clicked 山东"

具体是否有$event变量，变量内容有什么，由相应组件或事件文档提供。

4.1 数字方法

4.1.1 FORMAT(source:NUMBER,format:TEXT) → Text

format 方法提供了对数字进行格式化的方法，通过传入数字与预期的格式，方法会计算出相应格式的内容。其中第二个参数是转换格式，格式为 [分位符点位 分位符标记 小数点位数]。
举例：
FORMAT(1,"3,2") → "1"
FORMAT(3233.12, "2,1") → "32,33.1"
FORMAT(2123121234, "4,") → "21,2312,1234"
FORMAT(2123121234.22123, "3,2") → "2,123,121,234.22"

4.1.2 PERCENT(source:NUMBER,format:TEXT) → Text

Percent 方法提供了将数字转换成百分比的方法，通过传入数字与预期的格式，方法会计算出相应的内容，第二个参数是转换格式，格式为 [分位符点位 分位符标记 小数点位数]。
举例：
PERCENT(1,"") →**"100%"**
PERCENT(0.093,"") →**"9.3%"**
PERCENT(12.093,"") →**"1209.3%"**
PERCENT(12.093,"3,") →**"1,209.3%"**
PERCENT(12.093,"+3,") →**"+1,209.3%"**

4.2 文本方法

4.2.1 TRIM(source:Text) → Text

TRIM 可以实现除去文本两端的空白字符。

TRIM("  Hello world  ") -> "Hello world"
TRIM(" Hello world") -> "Hello world"

4.2.2 CONCAT(source:Text,source:Text) → Text

CONCAT 可以实现按照头尾相连拼接 2 个字符串。

CONCAT("Hello","world") -> "Helloworld"
CONCAT(" ","√") -> " √"

4.2.3 LENGTH(source:Text) → Number

LENGTH 可以实现对文本求长度。

LENGTH("hello") -> 5

4.2.4 REPLACE(source:Text, from:Text, to:Text) → Text

REPLACE 可以实现将给定文本的特定部分使用给定参数进行替换，并返回操作后结果。

REPLACE("Hello world","Hello","thanks") -> "thanks world"
REPLACE("What are you doing","Me","You") -> "What are you doing"

4.3 数学方法

4.3.1 ABS(source:Number) → Number

ABS 可以实现求绝对值。

ABS(12321) -> 12321
ABS(-0) -> 0
ABS(-12.3) -> 12.3

4.3.2 POW(source:Number,exponent:Number) → Number

POW 可以计算幂值，即第一个参数的第二个参数次方。

POW(2,3) -> 8 (2^3)
POW(2,-1) -> 0.5

4.3.3 SQRT(source:Number) → Number

SQRT 可以实现开平方计算。

SQRT(4) -> 2
SQRT(3) -> 1.732

4.3.4 MIN(source1:Number,source2:Number) → Number

MIN 可以实现两值求小计算。

MIN(100,200) -> 100
MIN(200,100) -> 100

4.3.5 MAX(source1:Number,source2:Number) → Number

MAX 可以实现两值求大计算。

MAX(100,200) -> 200
MAX(200,100) -> 200

4.3.6 SIGN(source:Number) → Number

SIGN 可以实现取数的正负。

SIGN(-20.212) -> -1
SIGN(-100) -> -1
SIGN(0) -> 1
SIGN(2) -> 1

4.3.7 ROUND(source:Number) → Number

ROUND 可以实现四舍五入取整数。

ROUND(200.2) -> 200
ROUND(200.5) -> 201
ROUND(200.49) -> 200
ROUND(-200.49) -> -200
ROUND(-200.51) -> -201
ROUND(-200.5) -> -200

4.3.8 FLOOR(source:Number) → Number

FLOOR 可以实现向下取整。

FLOOR(100.2) -> 100
FLOOR(100.9) -> 100
FLOOR(-100.9) -> -101
FLOOR(-100.1) -> -101

4.3.9 CEIL(source:Number) → Number

CEIL 可以实现向上取整。

CEIL(100.1) -> 101
CEIL(100.0) -> 101
CEIL(-100.1) -> -100
CEIL(-100.9) -> -100

4.3.10 RAND() → Number

RAND 可以实现随机数生成，产出 从 0-1 之间的小数。

RAND() -> 0.3212
RAND()*100 -> 331.1
FLOOR(RAND()*10) -> 21

4.4 逻辑方法

4.4.1 **AND(condition: Bool,[ condition:Bool, ... ])**→ Bool

AND 可以实现所有参数都为真值则返回真，否则返回假。

AND(true,false) // false
AND(true,true) // true

4.4.2 **OR(condition: Bool,[ condition: Bool... ])**→ Bool

OR 可以实现所有参数中至少有一个真值则返回真，否则返回假。

OR(true,false) // true
OR(false,false) // false

4.4.3 **IF(condition: Bool,value1: any, value2: any)**→ any

IF 可以实现条件判断，第一个参数为 Bool 类型，可以为表达式的返回值；当第一个值为真时，返回第二个参数；当第一个值为假时，返回第三个参数。

4.4.4 **ISBLANK(value: any)**→ Bool

ISBLANK 可以实现 text 类型值为空文本时返回 true，否则返回 false。

ISBLANK('') // true
ISBLANK(0) // false

4.4.5 **NOT(condition: Bool)**→ Bool

NOT 可以实现非真返回 true ，否则返回 false。

NOT(true) // false
NOT(2>1) // false
NOT(NOT(true)) // true

4.4.6 **SWITCH(source:any, [case:any, value:any][])**→ any

Switch 逻辑方法，可以实现根据source值不同，在后续的匹配对中取值。最后一个参数的case为空时将作为默认匹配条件。

SWITCH(true,"[[true,1],[false,3]]") -> 1
SWITCH(false,"[[true,1],[false,3]]") -> 3
SWITCH(index,'[[1,"gold"],[2,"silver"],[3,"yellow"],["","grey"]]')

4.4.7 **MATCH(source: string, pattern:string, [mode:string])**→ Bool

MATCH 匹配方法，其中 source是目标字符串，pattern是正则表达式内容，mode是匹配模式开关。

MATCH("cn,usa,eu",'cn') -> true
MATCH("Hello",'^h','i') -> true
MATCH("404", "00$", "im") -> false

4.5 类型转换

4.5.1 NUMBER(source:any) → Number

NUMBER 可以实现将任意类型转换为数字。

NUMBER(true) -> 1
NUMBER(false) -> 0
NUMBER("123a") -> NaN
NUMBER("a123") -> NaN
NUMBER("") => 0

4.5.2 TEXT(source:any) → Text

TEXT 可以实现将任意类型转换为文本。

TEXT(true) -> "true"
TEXT(false) -> "false"
TEXT(-123.232) -> "-123.232"

4.5.3 BOOL(source:any) → Bool

BOOL 可以实现将任意类型转换为真值。

BOOL(1) -> true
BOOL(0) -> false
BOOL(-0) -> false
BOOL(-1) -> true
BOOL("") -> false
BOOL("a") -> true

4.6 日期方法

4.6.1 LOCALE_DATE(format:Text)→ Text

LOCALE_DATE 可以实现获得用户所在地时区时间， format 默认为 YYYY-MM-DD hh-mm-ss.

LOCALE_DATE() -> "2022-12-31 06:03:21"
LOCALE_DATE(`YYYY-MM-DD`) -> "2022-12-31"

4.6.2 UTC_DATE(offset:Number, format:Text)→ Text

UTC_DATE 可以实现获得当前事件的UTC某时区时间，format 默认为 YYYY-MM-DD hh-mm-ss,offset默认为0.

UTC_DATE() -> "2022-12-31 06:03:21"
UTC_DATE(0,`YYYY`) -> "2022"
UTC_DATE(8, `YYYY-MM-DD hh:mm:ss`) -> "2022-12-31 14:03:21"
UTC_DATE(-7, `YYYY-MM-DD`) -> "2022-12-30"

（1）获取到的表格数据每行的 salary 字段处理新增千分符。

{{ FORMAT($row.measure.salary,"3,") }}

（2）根据表格数据的 isMember 字段切换 VIP Tab 的展示。

{{ IF($row.measure.isMember, 1, 2) }}

（3）根据数据的正负来显示红色还是绿色。

{{ SWITCH(sign($row.measure.percent), '[[1, "red"], [-1, "green"]]') }}

（4）根据返回值语句拼接自然描述。

本次盈利水平{{
  SWITCH(ABS($row.measure.earning) > 1000, '[[true, "大幅"],[false, "小幅"]]')
}}{{
  SWITCH(SIGN($row.measure.earning), '[[1, "上升"], [-1, "下降"]]')
}}
// earning = 129302 -> 本次盈利水平大幅上升
// earning = 302 -> 本次盈利水平小幅上升
// earning = -102 -> 本次盈利水平小幅下降
// earning = -1212 -> 本次盈利水平大幅下降