高级JSON表单规范 - 第二章：输入小部件

• 下载 Input_Widget_Form - 956 B

章节

• 第 1 章：引言
• 第 2 章：输入小部件
• 第 3 章：输入列表小部件
• 第 4 章：选项小部件
• 第 5 章：选项列表小部件
• 第 6 章：捕获小部件
• 第 7 章：日期和时间小部件
• 第 8 章：高级表单功能

引言

本章介绍定义以下表单屏幕的参数

• 信息输出屏幕
• 文本输入屏幕
• 整数输入屏幕
• 数字输入屏幕

为了理解本章的其余部分，鼓励读者下载、解压缩并将输入控件表单复制到Android设备上。使用CCA Mobile应用程序填写表单，然后备份并检查填写后的表单实例文本，具体请参考此处的讨论。下面的代码块显示了一个已完成的表单实例的示例。

/*

{
"First Name": "Donkey", 
"Last Name": "Hotey", 
"Email": "donkey.hotey@mydomain.com", 
"Age": 54, 
"Fave Integer": 180, 
"Any Integer": 89, 
"Probability Rain": 0.5
}

*/

信息输出屏幕

到目前为止，表单的屏幕一直被称为输入屏幕，但这个术语并不完全准确。这是因为有一个名为信息屏幕的表单屏幕，它是一个输出屏幕。这类屏幕的主要目的是显示与整个表单相关的信息。下图描绘了一个信息屏幕的示例。

要查看上述屏幕是如何定义的，请看下面的JSON代码

/*
{
"mainScreen":  {
"screenID": "Info", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "1. Basic information.", 
"screenHint": "Please read carefully"
}], 
"screenwidgetType": "info", 
"inputRequired": false, 
"widgetSchema": "
\"Info\": {
\"type\": \"string\"
}", 
"infoDisplayArray": [
{
"localeCode": "en", 
"localeText": "1. This form is to be used in conjuction with Chapter 2 
               of this code project article."
}]
}
}
*/

信息输出屏幕有两个特定参数：screenwidgetType，设置为Info，以及infoDisplayArray。infoDisplayArray参数是一个JSON数组，包含要显示的信息文本。与本节中讨论的screenDisplayArray一样，infoDisplayArray项是一个对象，由localeCode和localeText组成，两者均为JSON string类型。显示给用户的localeText内容将基于localeCode参数的值与显示表单的设备的当前语言设置之间的匹配。请参考此处关于localeCode的讨论，以更好地理解高级JSON表单的多语言支持功能。

信息输出屏幕的inputRequired参数值必须始终设置为false。

文本输入屏幕

顾名思义，文本输入屏幕是提示用户输入文本的屏幕。可接受文本输入的格式和长度可以内置于表单定义中，如本节讨论的输入屏幕所示。

上图显示了三个文本输入屏幕中的第一个。

上图屏幕的JSON定义包含在下面的代码块中

/*
{
"mainScreen":  {
"screenID": "First Name", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "2. Please enter your first name", 
"screenHint": "Please do not leave blank."
}], 
"screenwidgetType": "textInput", 
"inputRequired": true, 
"widgetSchema": "
\"First Name\": {
\"type\": \"string\"
}"
}
}

*/

这里相关的三个参数是：screenwidgetType、inputRequired和widgetSchema。请注意，widgetSchema表示它期望一个名为First Name的JSON string。从inputRequired参数的值可以看出，此输入是强制性的。

上图显示的Last Name文本输入屏幕对预期的Last Name输入string的长度进行了限制。

/*
{
"mainScreen":  {
"screenID": "Last Name", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "3. Please enter your last name", 
"screenHint": "Please do not leave blank."
}], 
"screenwidgetType": "textInput", 
"inputRequired": true, 
"widgetSchema": "
\"Last Name\": {
\"type\": \"string\",
\"minLength\": 2,
\"maxLength\": 100
}"
}
}

*/

从上图widgetSchema参数的值来看，有效的Last Name 输入长度必须在2到100个字符之间（含）。

除了文本长度，文本输入屏幕还可以定义为，要使文本输入被视为有效，它必须符合定义的正则表达式。这是下面屏幕输入的限制条件

请注意下面代码块中widgetSchema的pattern变量中的JSON转义正则表达式。该正则表达式，即[A-Z0-9a-z._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,6}，确保输入的文本符合有效的电子邮件地址格式。

/*
{
"mainScreen":  {
"screenID": "Email", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "4. Please enter a valid email address here.", 
"screenHint": "Please do not leave blank."
}], 
"screenwidgetType": "textInput", 
"inputRequired": true, 
"widgetSchema": "
\"Email\": {
\"type\": \"string\",
\"pattern\": \"^[A-Z0-9a-z._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,6}$\"
}"
}
}

*/

整数输入屏幕

整数输入屏幕的输入可以限制在整数范围或倍数。对于整数输入屏幕，screenwidgetType始终设置为integerInput。

下面显示的输入屏幕提示用户输入整数年龄值。

从下面代码块的widgetSchema参数可以看出，Age JSON schema指定其值必须是JSON整数类型，并且必须在18到120之间（含）。

/*
{
"mainScreen":  {
"screenID": "Age", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "5. How old are you?", 
"screenHint": "This value must be between 18 and 120."
}], 
"screenwidgetType": "integerInput", 
"inputRequired": true, 
"widgetSchema": "
"Age": \\{
"type": "integer"\\,
"minimum": 18\\,
"maximum": 120
\\}"
}
}
*/

下面屏幕中的提示信息要求用户输入一个10的倍数。

上面的屏幕是一个例子，说明如何将整数输入限制为另一个整数的倍数，这里是10。下面的代码块显示了这个输入屏幕定义如何使用JSON schema规范来完成此操作。

/*
{
"mainScreen":  {
"screenID": "Fave Integer", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "6. Enter you favourite integer ending with 0", 
"screenHint": "This number must be a multiple of 10."
}], 
"screenwidgetType": "integerInput", 
"inputRequired": true, 
"widgetSchema": "
\"Fave Integer\": {
\"type\": \"integer\",
\"multipleOf\": 10
}"
}
}
*/

最后，可以允许整数输入 Assume任何值，如下面的输入屏幕和代码块所示。

/*
{
"mainScreen":  {
"screenID": "Any Integer", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "7. Enter any integer number of your choice", 
"screenHint": "Free styling ;)"
}], 
"screenwidgetType": "integerInput", 
"inputRequired": true, 
"widgetSchema": "
"Any Integer": \\{
"type": "integer"
\\}"
}
}
*/

数字输入屏幕

数字输入屏幕的结构与整数输入屏幕类似，除了screenwidgetType始终设置为numberInput。这种屏幕类型同时接受小数和整数值。

在下面的代码块中，widgetSchema参数指定Probability Rain的值必须是JSON数字类型，并且在0.1到1.0之间。请注意，上一节中显示的multipleOf关键字也适用于numberInput屏幕。

/*
{
"mainScreen":  {
"screenID": "Probability Rain", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "8. What is the probability of rain today?", 
"screenHint": "Please enter a value between 0.1 and 1.0"
}], 
"screenwidgetType": "numberInput", 
"inputRequired": true, 
"widgetSchema": "
\"Probabilty Rain\": {
\"type\": \"number\",
\"minimum\": 0.1,
\"maximum\": 1
}"
}
}

*/

下一章

在本文的下一章，即第3章，将介绍一类称为输入列表的屏幕。

看点

有兴趣的读者应该遵循这些演练中的表单设计部分，并使用这个GUI工具来了解更多关于基于多种用例场景设计表单的信息。

历史

• 2016 年 7 月 18 日：第一个版本
• 2016 年 11 月 3 日：对此工作进行了更正