宏算定义的修饰器

2019-04-19 21:29:49 NUMKIT.COM  欢迎转载,转载请注明出处

宏算算式中的修饰器用于精细控制生成的用户界面。一个用户体验较好的宏算界面的算式中,修饰器往往发挥着重要的作用。 宏算算式甚至可以不含数学算式,而仅由若干个修饰器构成。

修饰器的语法如下:

<修饰器名>{
	<属性名1>:<属性值1>;
	<属性名2>:<属性值2>;
}

大括号中允许有任意个属性名值对<属性名>:<属性值>。 每个属性名值对后跟一个分号(;),其中最后一个属性名值对后的分号是可以省略的。

例如,以下一个修饰器定义了界面的标题和说明:

option{
	title:"日期计算器";
	comment:"本计算器能计算出从特定日期向后或向前数指定天数后的日期。";
}

如果宏算算式中需要使用多个修饰器,将它们依次分别列出即可。

一个使用了若干修饰器的宏算算式例子如下:

option{title:"日期计算器";comment:"本计算器能计算出从特定日期向后或向前数指定天数后的日期。";}
input{i:"开始日期";t:"计算方式";n:"天数";}
output{o:"结束日期";}
view{i:Date;t:"<请选择>","向后数日","向前数日";n:Integer;o:Date;}
validate{alert:[t!=1 and t!=2,"请选择计算方式"][n<0,"天数不能小于0"];}
default{i:toDate(now());t:1;}

if(t==1){
	o=i+n*24*3600*1000;
}
if(t==2){
	o=i-n*24*3600*1000;
}

修饰器的语法非常灵活。 修饰器可以置于数学算式前面,也可以置于数学算式后面,也可以将一部分置于前面并将其它部分置于后面。 如果同一修饰器内出现重复属性,通常情况下,后面定义的属性将覆盖之前定义的同名属性。

修饰器列表

修饰器名用途
option控制界面的标题、备注、脚注、设置等
input控制界面中输入参数的标签及显示顺序
output控制界面中输出参数的标签及显示顺序
view控制界面中各种参数的显示方式
default控制界面中各种输入参数的默认值
validate验证用户输入的参数值是否有效
summary根据输入输出变量的值显示相应的结论文本
action根据用户的输入实时显示、隐藏、刷新输入控件
function创建自定义的可在当前宏算算式中使用的函数

属性值的类型

不同修饰器内的不同的属性可能只接受特定类型的属性值,具体可参考各修饰器的说明。这些属性值可分为以下几种:

类型格式示例
关键字连续的英文字母hidden
可计算值一个不含变量的可直接计算出值的算式now()-24*60*60*1000
文本值使用引号(")引起来"文本内容"
双重文本值两个文本值使用逗号(,)隔开"重量","克"
文本值序列多个文本值使用逗号(,)隔开"美元","人民币","欧元"
映射序列(数值)[<可计算值1>,<文本值1>][<可计算值2>,<文本值2>]... [100+10,"北京"][100+21,"上海"][999,"海外"]
映射序列(条件)[<条件1>,<文本值1>][<条件2>,<文本值2>]... [c>a-b and c>0,"文本A"][d==100,"文本B"]
远程请求"get|<URL>""post|<URL>" "post|http://www.sample.com/data?id=10"

以上属性值类型说明如下:

  • 关键字 预先定义的含有特殊含义的词。
  • 可计算值 主要用于修饰器default中,将计算出的值作为输入参数的默认值。单个的数值也属于此种类型。例如0,计算出的结果为0。
  • 文本值 一个字符串。引号内可以换行。 文本内容中如果需要使用引号(")应该写作\"。 此外,换行(回车)还可以写作\n;缩进(Tab)还可以写作\t。 单个的反斜线(\)被视作转义字符,文本内容中如果需要使用反斜线(\)应该写作\\
  • 双重文本值 由主文本和扩展文本组成。在修饰器input和修饰器output中使用,可设定参数的标签和扩展标签;在修饰器function中使用,可设定函数的函数体和参数表。
  • 文本值序列 是映射序列(数值)的简写形式。只要映射序列(数值)中的数值部分是从0开始的连续整数,就可以简写为这种格式。 例如[0,"美元"][1,"人民币"][2,"欧元"]可以简写为"美元","人民币","欧元"
  • 映射序列(数值) 表示数值与文本间的映射关系。例如在修饰器view中为输入参数a设定值为[100+10,"北京"][100+21,"上海"][999,"海外"],则在生成的用户界面中,参数a以下拉框控件的方式显示。 下拉框中有“北京”、“上海”、“海外”三个选项。当用户选择“上海”并点击“确定”开始运算时,a的值为121。
  • 映射序列(条件) 表示条件与文本间的映射关系。例如在修饰器view中为输出参数d设定值为[c>a-b and c>0,"文本A"][d==100,"文本B"]。 在生成的用户界面中,用户点击“确定”运算完成后,从左到右第一个符合的条件对应的文本值会作为结果显示。即: 若满足条件c>a-b and c>0,则输出参数d在结果中显示为“文本A”;否则,若满足条件d==100,则输出参数d在结果中显示为“文本B”;若两个条件都不满足,则不会在结果中显示输出参数b。 另外,例中的第二个条件d==100,可以省略掉其中的“d==”。即[c>a-b and c>0,"文本A"][d==100,"文本B"]可以简写为[c>a-b and c>0,"文本A"][100,"文本B"]
  • 远程请求 用于修饰器option的model属性表示运算过程在远程服务器进行,或者用于修饰器view的输入参数属性表示根据远程服务器返回的数据显示为下拉框, 或者用于修饰器default中的输入参数属性表示根据远程服务器返回的数据确定默认值。

修饰器option

修饰器option控制界面的标题、备注、脚注、设置等。

支持的属性有:

  • title 设定标题。接受文本值。
  • usage(或comment) 设定说明文字,显示于界面的上部,可用于描述界面的用途和适用范围等。接受文本值,支持文本扩展。
  • footnote 设定脚注文字,显示于界面的底部,可用于注明提示信息、注意事项等。接受文本值,支持文本扩展。
  • showAnonymityFormula 设定是否显示匿名算式的计算结果。匿名算式是指未将计算结果赋值给其他参数的算式,如a+b;。 相对的,非匿名算式是指将计算结果赋值给其他参数的算式,如c=a+b;。本属性的可选值为true和false,分别表示显示和不显示。默认值为true。
  • summaryUnique 设定界面运算得到的文本结论部分是否是唯一的(参考修饰器summary)。可选值为true和false,分别表示唯一和不唯一。默认值为true。
  • summaryPosition 设定界面运算得到的文本结论部分置于数值结果之上还是之下。可选值为top和bottom,分别表示之上和之下。默认值为bottom。
  • model 设定运算模式。接受文本值。运算模式可归为两种:一种是远程请求,另一种是本地算式。 远程请求的属性值格式为"get|http://xxxx""post|http://xxxx",分别表示HTTP GET请求和HTTP POST请求。(格式中的http://xxxx指代请求地址) 本地算式的属性值为"script",表示直接使用数学算式计算得出结果,是本属性的默认值。
  • hideButtonBar 设定是否隐藏“确定”和“重置”按钮。可选值为true和false,分别表示隐藏和不隐藏。默认值为false。
  • actionInitClickOK 设定是否在打开宏算界面时自动点击“确定”按钮。可选值为true和false,分别表示自动点击和不自动点击。默认值为false。
  • actionInitHideInput 设定在打开宏算界面时初始为隐藏状态的输入参数。接受文本值。在文本值内将需要隐藏的输入参数名一一列出,各参数名间使用逗号(,)分隔。 例如属性值"a,b"表示打开宏算界面时输入参数a和输入参数b为隐藏状态。这些被隐藏的输入参数可以根据修饰器action的定义在特定条件下重新显示出来。

修饰器input

修饰器input控制界面中输入参数的标签及显示顺序。

支持的属性不固定,与宏算算式的输入参数相对应。在默认运算模式下(未设定修饰器option中的model属性为远程请求),本修饰器中可用的属性名为程序分析宏算算式确定的需要用户输入的参数名。 例如算式c=a+b;d=c*2;,程序将分析出需要用户输入的参数为a和b,则本修饰器中可用的属性名为a和b。 在远程模型模式下(设定修饰器option中的model属性为远程请求),本修饰器中的属性名可根据设计需求自由确定。

本修饰器中出现的属性名的顺序决定最终产生的界面各输入参数的排列顺序。

各属性可接受的属性值为文本值。这里的文本值可以设定两个,以逗号(,)分隔开。逗号前面的是变量的标签,逗号后面的是扩展标签。扩展标签显示于输入控件的后面,通常用于标明单位。 例如input{a:"重量","克"}表示参数a的名称为“重量”,显示在输入控件之前;单位为“克”,显示在输入控件之后。

修饰器output

修饰器output控制界面中输出参数的标签及显示顺序。

支持的属性不固定,与宏算算式的输出参数相对应。在默认运算模式下(未设定修饰器option中的model属性为远程请求),本修饰器中可用的属性名为程序分析宏算算式确定的需要用户输入的参数名和所有可能被赋值的参数名的集合。 例如算式c=a+b;d=c*2;,程序将分析出需要用户输入的参数为a和b,所有可能被赋值的参数为c和d,则本修饰器中可用的属性名为a、b、c和d。 在远程模型模式下(设定修饰器option中的model属性为远程请求),本修饰器中可用的属性名为远程服务器返回的运算结果中的所有可能的参数名的集合。

本修饰器中出现的属性名的顺序决定最终产生的计算界面各输出参数的排列顺序。

各属性可接受的属性值为文本值或关键字hidden(或hide)。这里的文本值可以设定两个,以逗号(,)分隔开。逗号前面的是变量的标签,逗号后面的是扩展标签。扩展标签显示于结果值的后面,通常用于标明单位。 例如output{c:"重量","克"}表示参数c的名称为“重量”,显示在结果值之前;单位为“克”,显示在结果值之后。当属性值被设为hidden时表示隐藏该输出参数,使其不在结果中出现。

修饰器view

修饰器view控制界面中各种参数的显示方式。

支持的属性不固定,是输入参数和输出参数的并集。关于输入参数和输出参数是如何确定的,请参考修饰器input与修饰器output的相关说明。

各属性可接受的属性值为表示显示类型的关键字、映射序列和远程请求。

其中表示显示类型的各关键字含义及示例如下:

显示类型含义显示示例示例对应的内部数值
Integer整数1010
Number浮点数8.58.5
Float浮点数(同Number)8.58.5
Time时间05:30:0019800000
Date日期2009-05-301243641600000
DateTime日期时间2009-05-30 05:30:001243661400000
String字符串文字1247285923

注意,修饰器view仅仅设置数值的显示形式。在宏算算式内部进行计算时,所有输入内容都首先被转换成数值形式。计算完成后,各输出变量会按照其显示类型由数值形式转换为显示形式。

Time、Date、DataTime是日期与时间相关的类型,它们的显示格式分别为 时:分:秒、年-月-日、年-月-日 时:分:秒。 在内部计算过程中,Time采用自当日凌晨以来的毫秒数表示,Date采用自1970年1月1日凌晨至当日凌晨间的毫秒数表示,DataTime采用自1970年1月1日凌晨以来的毫秒数表示。

在默认运算模式下(未设定修饰器option中的model属性为远程请求),String类型的输入参数在计算时会按照一个简单算法转成一个整数数值。(若用户未输入任何字符串内容,则转为整数“-1”) 一个整数数值是无法包含原始字符串的所有信息的,这意味着String类型的输入参数在参与计算时就已经丢失了原始字符串内容。 一个String类型的输出参数会在结果中显示为格式[HASH:<整数值的十六进制形式>],例如[HASH:4A5812A3]。 在远程模型模式下(设定修饰器option中的model属性为远程请求),点击“确定”按钮会将String类型的输入参数以原始字符串形式发送至远程服务器,从远程服务器返回的运算结果中的String类型的输出参数也会以原始字符串形式显示到结果中。

为输入参数设定关键字形式的显示类型,可以同时起到自动校验用户输入内容的作用。例如对于设定了显示类型为Integer的输入变量,当用户输入了整数以外的内容时,点击“确定”按钮将会弹出相关错误提示。 对于已经设定了关键字形式的显示类型的输出参数,当无法将内部数值转为相应的显示形式时,会转而显示为“Err”。

为输入参数设定映射序列(数值)作为显示类型,表示将以下拉框的方式显示该参数并根据用户的选择将映射序列中的相应的数值赋予该参数。 为输出参数设定映射序列(条件)作为显示类型,表示在生成的用户界面中,用户点击“确定”运算完成后,从左到右第一个符合的条件对应的文本值会作为结果显示。

为输入参数设定远程请求作为显示类型,表示将通过HTTP请求获取列表数据和默认选项并显示为下拉框。

若未给参数设定显示方式,则按照Number显示类型,即作为浮点数处理。

修饰器default

修饰器default控制界面中各种输入参数的默认值。

支持的属性不固定,与宏算算式的输入参数相对应。关于输入参数是如何确定的,请参考修饰器input的相关说明。

各属性可接受的属性值为可计算值、文本值和远程请求。

若设定一个可计算值,宏算界面初始显示或点击“重置”按钮后,可计算值被计算出来并根据该输入参数的显示类型(通过修饰器view设定)以相应的格式显示。 注意,当输入参数的显示类型为映射序列表示的下拉框时,应当使用一个整数值来为该输入参数指定默认值,而这个整数的含义是映射序列的序号(从0开始)。 例如,需要默认选中下拉框中的第二个选项,可以将该输入参数属性值设定为整数1。 当输入参数的显示类型为远程请求表示的下拉框时,无法通过本修饰器指定默认的选项,此时默认的选项在远程请求的响应中指定。

若设定一个文本值,当输入参数的显示类型为映射序列表示的下拉框且设定的文本值可转为整数时,其作用等效于给属性设定整数值。 当输入参数的显示类型不是下拉框时,该文本值会作为输入框的默认文本。

若设定一个远程请求值,宏算界面初始显示或点击“重置”按钮后,会根据远程服务器的响应确定默认值。

对于未在本修饰器中设定默认值的输入参数,其默认值根据其显示类型确定:

显示类型默认值
关键字Integer0
关键字Number0.0
关键字Float0.0
关键字Time00:00:00
关键字Date1970-01-01
关键字DateTime1970-01-01 00:00:00
关键字String<空>
映射序列<下拉框中的首个选项>
远程请求<下拉框中的首个选项>

修饰器validate

修饰器validate用于验证用户输入的参数值是否有效。

可以通过本修饰器设定条件来验证用户的输入,并在验证未通过时弹出错误提示信息。

支持属性alert。可接受的属性值为映射序列(条件)。映射序列中每一项的条件部分用于识别错误输入,对应的文本值是错误提示信息。 例如设定属性值为[t!=1 and t!=2,"请选择计算方式"][n<0,"天数不能小于0"] (其中输入参数t显示为一个下拉框,n显示为一个接受整数值的文本框), 当用户没有选择计算方式(此时t为0)时,点击“确定”按钮将弹出错误提示“请选择计算方式”; 当用户选择了计算方式但是输入了小于0的天数时,点击“确定”按钮将弹出错误提示“天数不能小于0”。

修饰器summary

修饰器summary可根据输入输出变量的值显示相应的结论文本。

结论是输出变量的补充,可以显示在所有输出变量的上面或下面。例如一个可以根据身高和体重计算出BMI指数的计算器,可以通过结论指出计算得到的结果是正常、过高还是过低以及相应的建议等。

支持属性content(或text)。可接受的属性值为映射序列(条件)和关键字remote。

若设定映射序列(条件)值,用户点击“确定”按钮,运算过程完成后,若映射序列中某项的条件符合,则相对应的文本部分会显示到结论文本中。 例如设定属性值为[b<18.5,"您的体重过低,需要加强营养、适度锻炼哦。"] [b<24,"恭喜!您的体重正常,请继续保持。"] [b<28,"您超重了,但还不是肥胖,建议您平衡饮食、经常锻炼。"] [1==1,"您的体重指数属于肥胖范围,建议您进行减肥。"]。在计算出的BMI指数(变量b)在不同范围时,会分别显示不同的结论文本。

默认情况下,只有从左到右第一个符合的条件对应的文本会作为结论文本显示。 可以通过设定修饰器option的summaryUnique属性为false来改变这一行为,即改变为:映射序列(条件)中所有符合的条件对应的文本值都会显示到结论文本中。

只有在远程模型模式下(设定修饰器option中的model属性为远程请求),本修饰器中的属性的值才可设定为关键字remote,即结论文本由远程服务器执行运算过程后在返回的响应中指定。

默认情况下,结论文本显示在所有输出参数的下方。可以通过设定修饰器option的summaryPosition属性为top来改变这一行为,即改变为:结论文本显示在所有输出参数的上方。

修饰器action

修饰器action可根据用户的输入实时显示、隐藏、刷新输入控件。

使用本修饰器可以实现输入界面随用户输入而自动变化。例如可实现省、市、区信息的输入:用户选择某省份后,刷新显示该省内的市列表同时隐藏区列表,用户再选择某市后,刷新显示该市内的区列表。

支持的属性不固定,与宏算算式的输入参数相对应。关于输入参数是如何确定的,请参考修饰器input的相关说明。

各属性可接受的属性值为映射序列(条件)。映射序列(条件)中的条件只能引用输入参数,不能引用输出参数,条件所对应的文本值是符合条件后应该执行的动作。

动作文本有一系列操作构成,每个操作之间用竖线(|)隔开。操作的格式类似函数调用,接受一到多个输入参数名作为参数。 例如"hideOnly(x,y,z)|reset(a,b)"表示只隐藏输入参数x、y、z(显示其他输入参数),然后重置输入参数a、b(刷新输入控件和恢复默认值)。

动作文本中支持的操作有以下这些:

操作作用
show显示指定的输入参数
hide隐藏指定的输入参数
showOnly只显示指定的输入参数
hideOnly只隐藏指定的输入参数
reset重置指定的输入参数。 如果输入参数的显示类型(修饰器view)为远程请求,则触发远程请求并根据响应刷新下拉框和设定默认值。 如果输入参数的默认类型(修饰器default)为远程请求,则触发远程请求并根据响应设定默认值。 其他情况下,直接恢复输入参数的值至其默认值。

例如,为输入参数m设置属性值[0,"showOnly(m,x,y,z)"][1==1,"hideOnly(x,y,z)|reset(a,b)"]。此时当输入参数m的值被用户改为0时,界面上只显示输入参数m、x、y、z; 当输入参数m被用户改为0以外的值时,只隐藏输入参数x、y、z(显示其他输入参数),然后重置输入参数a、b(刷新输入控件和恢复默认值)。

在本修饰器内给输入参数设置的动作,只有当用户在该输入参数对应的控件上进行操作时才可能会被触发。 触发动作引起的变化不会引起级联反应,即:若操作参数a的输入框触发了动作导致输入变量b的值变化,不会触发变量b上设置的动作。

使用本修饰器实现特定的界面规则时,常常需要在界面初始显示时就隐藏某些输入参数。修饰器option的actionInitHideInput属性可以实现此功能。 注意不要使用修饰器input来实现,其中并不支持用于隐藏参数的属性值hidden。

修饰器option中还有一个以action开头的属性actionInitClickOK,可以实现在界面初始显示时自动点击“确定”按钮。

修饰器function

修饰器function用于创建自定义的可在当前宏算算式中使用的函数。

使用本修饰器可以基于已存在的运算组件(常量、运算符、函数)创建新的自定义函数。 创建出的自定义函数与内置函数一样,几乎可以用于当前宏算算式的任何地方(属性值、条件式、数学算式)。

支持的属性不固定。属性名即是自定义函数的函数名,可在遵守命名规则的前提下自由命名。 函数名的命名规则与变量名的命名规则相同,都是:以下划线(_)或英文字母开头的连续的下划线、英文字母、数字。其中,英文字母区分大小写。 另外,此处的函数名也不能与保留字、内置的常量或函数、已定义的函数的名称冲突。 本修饰器内不允许出现重复的属性。其他修饰器内若出现重复属性,后面定义的属性将覆盖之前定义的同名属性;本修饰器内若出现重复属性,则直接报错。

各属性可接受的属性值为文本值和双重文本值。文本值或双重文本值中的主文本用于设定函数体,双重文本值中的扩展文本用于设定参数表。

例如,为输入参数avg设置属性值"(a+b)/2","a,b"即可创建一个能算出两数的平均值的函数avg。 属性值中,主文本"(a+b)/2"是函数体,扩展文本"a,b"是参数表。

当符合以下情况之一时,可以省略参数表:

  • 函数不需要参数或只有一个参数 例如:属性值"floor(random()*100)",""可简写为"floor(random()*100)", 属性值"n^3","n"可简写为"n^3"
  • 参数表是函数体中用到的所有参数的自然排序 例如:属性值"a+(b1+b2)/(b1-b2)-c","a,b1,b2,c"可简写为"a+(b1+b2)/(b1-b2)-c"

通过本修饰器创建的自定义函数是按照其出现顺序逐个注册到函数库中去的。对于任意一个自定义函数来说,前面定义的自定义函数都是可见的,而其本身和后面定义的自定义函数都是不可见的。 也就是说,只允许后面的自定义函数调用前面的自定义函数。 (本段中,“前面”的意思是指在同一宏算算式内,所有的定义顺序在它之前的自定义函数;“后面”的意思是指在同一宏算算式内,所有的定义顺序在它之后的自定义函数。)

在创建自定义函数时,为了提高可读性、实现可重用等原因,可以先从简单的函数开始逐步创建。 例如,以下修饰器先创建了用于计算二次方的函数sq,再基于它创建了用于计算矩形对角线长度的函数diag:

function{
	sq:"x^2";
	diag:"sqrt(sq(a)+sq(b))";
}

远程请求的数据格式

宏算界面支持以向远程服务器请求数据的方式处理输入参数并得到结果、生成下拉框、确定默认值。远程请求采用HTTP协议,可使用GET或POST方式。 发往服务器的数据通过HTTP请求参数传递,从服务器返回的HTTP响应为JSON格式的普通文本(text/plain)。 HTTP请求的参数由宏算界面自动生成,服务器端相关程序则需要开发者根据具体业务逻辑编写。

远程请求分为GET和POST两种方式。如果是GET请求,则宏算界面自动生成的参数会附加在开发者定义的URL后面发送。如果是POST请求,则宏算界面自动生成的参数会作为POST内容发送。 请注意避免URL中自定义的参数与宏算界面自动生成的参数间发生冲突。

宏算单页是宏算推出的包含前端宏算算式与后端服务程序以及管理平台的全套营销应用,用户已无需编写任何代码。

远程运算请求

请求参数包括:

参数说明
<各输入参数名>用于传递输入参数的值。只有可见的,且未禁用,用户按格式输入了值的输入参数才会被列入请求参数中。除了显示类型为String的输入参数按原始字符串传值外,其他输入参数均按照其显示类型被转换为数值传值。
nk_request_from用于识别请求是否是由手机宏算发出的。当请求是由手机宏算发出的时才传递此参数,传递的参数值为“c”。

请求成功的响应形如:

{"success":true,"data":{"output":{...},"summary":"..."}}

其中"output"的值是一个JSONObject,内含输出参数名值对。除了显示类型为String的输出参数应该是字符串类型外,其他输出参数均应该是数值类型。

其中"summary"的值是一个字符串,表示结论文本,支持宏算字符串扩展。

远程下拉框请求

请求参数包括:

参数说明
nk_input_var下拉框对应的输入参数名。
nk_trigger_var只在触发的action中的reset操作发出的远程请求中使用,用于表明触发action的输入参数名。
<各输入参数名>只在触发的action中的reset操作发出的远程请求中使用,用于传递当前各输入参数的值。 只有可见的,且未禁用,用户按格式输入了值的输入参数才会被列入请求参数中。除了显示类型为String的输入参数按原始字符串传值外,其他输入参数均按照其显示类型被转换为数值传值。
nk_request_from用于识别请求是否是由手机宏算发出的。当请求是由手机宏算发出的时才传递此参数,传递的参数值为“c”。

请求成功的响应形如:

{"success":true,"data":{"list":["...","..."],"value":[1.23,2.34],"select":0}}

其中"list"的值是一个JSONArray,内含一列字符串,表示下拉框的各选项显示的内容。"list"列表中至少应该含有一个项。

其中"value"的值是一个JSONArray,内含一列数值,表示下拉框的各选项对应的值,与"list"列表中的项一一对应。 "value"名值对可以被省略,其缺省值是一个与"list"的值中的项的个数相等且以0开头的整数序列。 注意,如果"value"的值序列中需要用到比较长的整数,请确保其绝对值不要超过9007199254740991,否则会在后续处理步骤中损失精度。

其中"select"的值是一个整数,表示默认被选中的下拉框选项。"select"名值对可以被省略,其缺省值是0。

远程默认值请求

请求参数包括:

参数说明
nk_input_var下拉框对应的输入参数名。
nk_trigger_var只在触发的action中的reset操作发出的远程请求中使用,用于表明触发action的输入参数名。
<各输入参数名>只在触发的action中的reset操作发出的远程请求中使用,用于传递当前各输入参数的值。 只有可见的,且未禁用,用户按格式输入了值的输入参数才会被列入请求参数中。除了显示类型为String的输入参数按原始字符串传值外,其他输入参数均按照其显示类型被转换为数值传值。
nk_request_from用于识别请求是否是由手机宏算发出的。当请求是由手机宏算发出的时才传递此参数,传递的参数值为“c”。

请求成功的响应形如:

{"success":true,"data":"..."}

其中"data"的值是一个字符串,表示输入参数的默认值。

请求失败的处理

远程运算请求若没有得到成功的响应,则宏算界面会弹出错误提示对话框。远程下拉框和远程默认值请求若没有得到成功的响应,则相应的输入控件会被禁用,同时控件内会显示“载入失败!”。

远程请求失败的原因分为若干种情况。如果是网络通讯问题或者是服务器端没有返回正确的HTTP响应,宏算界面会自动处理并显示相应错误信息。 服务器端程序检测到预料内的错误,可以以JSON格式将具体错误信息返回给客户端。如果该请求是远程运算请求,用户就可以通过弹出的错误对话框了解到具体的错误信息。

一般的请求失败的响应格式为:

{"success":false,"exception":"..."}

其中"exception"的值是一个字符串,表示错误描述信息。

因为宏算界面和服务器端程序在不同的机器上运行,而且宏算界面可能会被更新与分发多个版本,所以可能会出现宏算界面相对于服务器端程序过时的问题。 开发者可在设计远程请求URL时添加一个自定义的“版本”参数来识别这类过时的请求。对于过时的请求,可返回以下错误响应:

{"success":false,"exception":"...","outdated":true}

其中"exception"的值是一个字符串,表示关于“过时”的错误描述信息。

对于这种“过时”错误响应,即使该请求不是远程运算请求,宏算界面也会弹出错误提示对话框。

对于从手机宏算发出的远程请求(可通过“nk_request_from”参数判断)来说,响应中还可以添加“update”字段告诉客户端获取最新宏算算式的地址:

{"success":false,"exception":"...","outdated":true,"update":"http://xxxx"}

其中"exception"的值是一个字符串,表示关于“过时”的错误描述信息以及询问用户是否更新的问句。

其中"update"的值是一个字符串,表示用于获取最新宏算算式的URL。

用于获取最新宏算算式的URL的成功响应与其他远程请求的成功响应的格式类似:

{"success":true,"data":"..."}

其中"data"的值是一个字符串,表示宏算算式的完整内容。

若服务器端因为某种原因无法提供宏算算式,可以返回失败响应,其格式与其他远程请求的失败响应格式类似:

{"success":false,"exception":"..."}

其中"exception"的值是一个字符串,表示错误描述信息。

浏览器下的跨域请求

前端宏算界面以HTML页面方式显示时,远程请求将以AJAX方式发起。因为浏览器的安全限制,您可能需要将HTML文件置于Web服务器上访问才能正常发起远程请求。

如果Web服务器上的前端宏算界面和后端服务程序的URL不在同一个域内,会遇到浏览器禁止跨域请求的问题。宏算推荐使用CORS(Cross-Origin Resource Sharing)方案解决。 CORS可以让AJAX实现跨域访问,而且实现起来非常简单,只需由后端服务程序在HTTP响应中设置一个标头(Header)即可。例如要允许任意来源域访问可使用标头:

Access-Control-Allow-Origin: *

宏算单页的后端服务程序即是使用了以上标头以允许跨域访问的。