高级JSON表单规范 - 第六章：捕获小部件

Don Fizachi

5.00/5 (2投票s)

2016 年 7 月 18 日

LGPL3

5分钟阅读

9321

159

JSON表单规范。

下载捕获控件表单 - 899 B

章节

引言

本章介绍表单屏幕，这些屏幕统称为捕获屏幕。捕获屏幕允许用户拍照、收集签名、扫描条形码或收集位置坐标信息。

按照本文前5章的传统，强烈建议读者下载、解压缩并将捕获控件表单复制到Android设备上。读者应使用CCA-Mobile应用程序完成此表单的一个实例。表单完成后，用户应将表单备份到设备上。备份的实例应与下面代码块中的内容大致相似。

/*

{
"Any Photo":  {
"fileName": "cca_photo_06730794-a5d4-4753-bc72-d8f94da57b71.jpg"
}, 
"Car Photo":  {
"fileName": "cca_photo_d6e20a4e-e89f-46cb-b687-dd0aa57b9846.jpg"
}, 
"My Sig":  {
"fileName": "cca_signature_7a016a3a-5cb5-43fb-9e03-c9797119a98f.jpeg"
}, 
"QR Scan": "Advanced JSON Forms", 
"My Location":  {
"latitude": 51.500083, 
"longitude": -0.126182, 
"altitude": 19.097, 
"accuracy": 4.90000009536743, 
"bearing": 27.179992675781, 
"provider": "gps"
}
}

*/

图像捕获和标注屏幕

理想情况下，照片捕获屏幕应允许用户使用设备的相机捕获图像，或从设备的存储中添加照片。

上图左侧显示了一个照片表单捕获屏幕的示例，右侧显示了捕获或添加图像到表单后的同一屏幕。

下面的代码块显示了上述屏幕的JSON定义。

/*

{
"mainScreen":  {
"screenID": "Any Photo", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "1.  Take a photo of an object
", 
"screenHint": "Any object would do
"
}], 
"screenwidgetType": "photo", 
"inputRequired": true, 
"widgetSchema": "
\"Any Photo\": {
\"type\": \"object\",
\"properties\":  {
\"fileName\": {
\"type\": \"string\"
},
\"filePath\": {
\"type\": \"string\"
},
\"fileObject\": {
\"type\": \"string\"
}
},
\"required\": [\"fileName\"],
\"minProperties\": 1,
\"maxProperties\": 4,
\"additionalProperties\": false
}"
}
}
*/

读者可以在上面的代码块中看到screenwidgetType设置为photo。

对于照片捕获屏幕，widgetSchema的值是一个JSON对象，该对象至少包含三个属性：fileName、filePath和fileObject。在这三个属性中，只有fileName属性是照片屏幕输入的实例所必需或强制的。如果存在，filePathstring属性包含图像文件的统一资源标识符（URI）。此外，如果存在，fileObject属性以其base-64编码格式包含图像文件的二进制表示。

请注意，maxProperties设置为4，这表明存在第四个属性。这个第四个属性将在下一个屏幕中讨论。

代码块显示了完成的照片屏幕的JSON格式实例。

/*

{
"Any Photo":  {
"fileName": "cca_photo_06730794-a5d4-4753-bc72-d8f94da57b71.jpg"
}, 
...
}

*/

照片表单屏幕还允许图像标注，如下面的示例屏幕所示。

为了允许图像标注，在其他三个属性（filePath、fileName和fileObject）之外，还添加了一个名为annotate的第四个属性，其默认值为true，如以下代码块的widgetSchema所示。

/*

{
"mainScreen":  {
"screenID": "Car Photo", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "2. Take a photo of a car
", 
"screenHint": "Click on the photo and circle the wheels on the car
"
}], 
"screenwidgetType": "photo", 
"inputRequired": true, 
"widgetSchema": "
\"Car Photo\": {
\"type\": \"object\",
\"properties\":  {
\"fileName\": {
\"type\": \"string\"
},
\"filePath\": {
\"type\": \"string\"
},
\"fileObject\": {
\"type\": \"string\"
},
\"annotate\": {
\"type\": \"boolean\",
\"default\": true
}
},
\"required\": [\"fileName\"],
\"minProperties\": 1,
\"maxProperties\": 4,
\"additionalProperties\": false
}"
}
}
*/

下面是Car Photo表单屏幕的已完成实例。

/*

{
..., 
"Car Photo":  {
"fileName": "cca_photo_d6e20a4e-e89f-46cb-b687-dd0aa57b9846.jpg"
}, 
...
}

*/

签名板屏幕

签名捕获屏幕在点击按钮时会显示一个板，可以在上面涂写签名，如下面的图片所示。

捕获的签名将作为图像保存到设备上。由于签名以图像形式捕获，签名屏幕的定义与照片捕获屏幕类似，只有两个区别：第一个是screenwidgetType设置为signature，第二个是widgetSchema中定义的模式只允许3个属性，如下面的示例所示。

/*

{
"mainScreen":  {
"screenID": "My Sig", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "3.  Please enter you signature
", 
"screenHint": "Click on the button below to sign
"
}], 
"screenwidgetType": "signature", 
"inputRequired": true, 
"widgetSchema": "
\"My Sig\": {
\"type\": \"object\",
\"properties\":  {
\"fileName\": {
\"type\": \"string\"
},
\"filePath\": {
\"type\": \"string\"
},
\"fileObject\": {
\"type\": \"string\"
}
},
\"required\": [\"fileName\"],
\"minProperties\": 1,
\"maxProperties\": 3,
\"additionalProperties\": false
}"
}
}
*/

下面是一个已完成的签名屏幕实例的示例。

/*

{
..., 
"My Sig":  {
"fileName": "cca_signature_7a016a3a-5cb5-43fb-9e03-c9797119a98f.jpeg"
}, 
...
}

*/

代码扫描屏幕

代码扫描屏幕使用设备的数码相机扫描/读取条形码。下面的图片显示了代码扫描屏幕在扫描代码之前和之后的样子。

值得一提的是，CCA-Mobile应用程序依赖于ZXing库来实现代码扫描功能。

下面代码块显示了一个示例代码扫描屏幕的JSON定义。

/*

{
"mainScreen":  {
"screenID": "QR Scan", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "4. Click the button to scan any QR code
", 
"screenHint": "Make sure your surroundings are adequately lit.
"
}], 
"screenwidgetType": "codeScan", 
"inputRequired": true, 
"widgetSchema": "
\"QR Scan\": {
\"type\": \"string\"
}"
}
}
*/

screenwidgetType设置为codeScan，widgetSchema值是一个转义的JSON字符串模式，该模式包含扫描内容的文本。

下面是此屏幕已完成实例的示例。

/*

{
..., 
"QR Scan": "Advanced JSON Forms", 
...
}

*/

位置屏幕

位置屏幕用于读取设备的当前物理位置的经度和纬度等值。位置值可以来自设备上的嵌入式GPS芯片，从移动或WIFI网络读取，等等。下面是此类屏幕渲染的示例。

如以下代码块所示，screenwidgetType设置为location。

/*

{
"mainScreen":  {
"screenID": "My Location", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "5. Click on the button to capture your current location.
", 
"screenHint": "Make sure you can see the sky above you.
"
}], 
"screenwidgetType": "location", 
"inputRequired": true, 
"widgetSchema": "
\"My Location\": {
\"type\": \"object\",
\"properties\":  {
\"longitude\": {
\"type\": \"number\"
},
\"latitude\": {
\"type\": \"number\"
},
\"altitude\": {
\"type\": \"number\"
},
\"accuracy\": {
\"type\": \"number\",
\"maximum\": 5
},
\"bearing\": {
\"type\": \"number\",
\"default\": 0
},
\"provider\": {
\"type\": \"string\"
}
},
\"required\": [\"longitude\", \"latitude\", \"altitude\", 
\"accuracy\", \"bearing\", \"provider\"]
}"
}
}
*/

widgetSchema值是一个JSON对象的转义模式——在本例中是My Location——该对象有6个属性，即longitude、latitude、altitude、accuracy、bearing和provider。所有这些属性的值都是必需的。

请注意，accuracy属性的模式允许的最大值为5。这意味着只有accuracy值小于等于5米的定位值才被接受为该示例表单屏幕的有效输入。最大accuracy值可以根据表单设计者的要求而变化。provider属性值指示了读取位置值的来源，例如GPS、移动网络、WIFI网络等。