A package.json file contains configurations of a widget. This topic describes fields in a package.json file. You can configure these fields in the file to customize the style of a widget as needed.
Example of a package.json file in protocol version 2
{
"name": "@leaf/pie-multi-radius-with-title", //@Namespace/Widget name. The namespace is the name of a widget package. If you do not specify a namespace, the widget cannot be published.
"version": "0.1.5", // The version number.
"dependencies": { // The dependencies that exclude datav:/com/.
"bcore": "0.0.9",
"jquery": "2.1.4", // All dependency versions must be locked.
"lodash": "4.6.1"
},
"datav": { // The configurations of DataV.
"cn_name": "Multidimensional pie chart with a title", // The name of the widget.
"protocol": 2, // The version of the protocol.
"type": ["regular_pie"], // The type of the widget.
"supportTheme": true, // Specifies whether the widget supports theme configurations.
"view": {
"width": 300,
"height": 200,
"minWidth": 100,
"minHeight": 50
},
"icon": "", // The URL of the widget icon.
"apis": { // The widget APIs. You can add one or more APIs.
"source": { // The name of the API.
"handler": "render", // The method to handle the widget returned by the API.
"description" : "The API of a multidimensional pie chart", // The description of the API.
"fields" : { // The fields required by the API. You can add one or more fields.
"x" : { // The name of the field.
"description" : "Category", // The description of the field.
"type" : "string", // The type of the field.
"optional": true // Specifies whether the field is optional.
},
"y" : {
"description" : "Value",
"type" : "int"
}
}
}
},
"config" : { // The configuration of the widget. It consists of the UI elements that are displayed in the editor.
"paxis" : {
"type" : "group", // Specifies that the element is a group. For more information, see Description of the config field.
"name" : "Label",
"children" : {
"dx" : {
"type" : "text", // Specifies that the element is a text. For more information, see Description of the config field.
"name" : "Distance from the label to the center",
"default" : 220
}
}
},
"title" : {
"type" : "group",
"name" : "Title",
"children" : {
"value" : {
"hasVisibility" : "true",
"visible" : "true",
"type" : "text",
"name" : "Title",
"default" : "This is a title"
},
"font-size" : {
"type" : "number", // Specifies that the element is a number. For more information, see Description of the config field.
"name" : "Font",
"min" : 10,
"default" : 32,
"max" : 100
},
"text-align" : {
"name" : "Alignment",
"type" : "select", // Specifies that the element is a drop-down list. For more information, see Description of the config field.
"options" : [
{"name" : "Left", "value" : "left"},
{"name" : "Right", "value" : "right"},
{"name" : "Center", "value" : "center"}
],
"default" : "center"
},
"color" : {
"name" : "Font color",
"type" : "color", // Specifies that the element is a color. For more information, see Description of the config field.
"default" : "#fff"
},
"background-color" : {
"name" : "Background",
"type" : "color",
"default" : "#000"
}
}
}
}
},
"api_data":{ // The API data. You can add one or more pieces of data.
"source" : [ // The name of the API. It must be the same as the API name in the apis field. The size of data contained in this field cannot exceed 6 KB.
{"x": "General goods", "y" : 5},
{"x": "General goods", "y" : 22},
{"x": "Light goods", "y" : 22},
{"x": "Devices", "y" : 14},
{"x": "Mineral products", "y" : 15},
{"x": "Steel", "y" : 15},
{"x": "Building materials", "y" : 12},
{"x": "Food", "y" : 12},
{"x": "Grain", "y" : 28}
],
},
"events": { // The global event parameters.
"event-name": { // The name of the event.
"description": "Event description", // The description of the event.
"fields": { // Specifies one or more fields.
"value": { // The name of the field.
"description": "Description" // The description of the field.
}
}
}
},
"publicHandler": {
"show": {
"name": "Display",
"description": "Description",
"type": "object", // Valid values: object, array, null, and any. The value any indicates any type.
"fields": {
"data": {
"name": "Data",
"type": "array",
"children": {
...
}
}
}
}
},
}
Configuration items in the config field
The config
field contains the configuration items of a widget. These configuration items control the display of a widget and are used to present UI elements in the editor.
config
field, take note of the following requirements: - Specify the default configuration items of the widget.
- Specify the input requirements so that the editor can identify the input information.
type
in the config
field allows you to configure the type and style of a widget. The type field determines the UI elements that are displayed in the editor. You can configure the type field as needed to significantly improve the quality and user experience of a widget. For more information, see Control configuration.
apis and api_data fields
apis
fieldThe apis field defines the names of APIs in a widget and the fields required by the APIs. You can specify multiple APIs and fields."apis": { "source": { "handler": "render", "description" : "The API of a multidimensional pie chart", "fields" : { "x" : { "description" : "Category", "type" : "string", "optional": true }, "y" : { "description" : "Value", "type" : "int" } } }, "source2":{ ... } }
Field Description Required Remarks apis
The APIs of a widget. Yes A widget can provide multiple APIs. source
The name of an API. No A custom value is allowed. handler
The name of the method to process data returned by an API. Yes The method must be specified in the source code of the index.js file. description
The description of an API. No None. fields
The fields required for an API. Yes An API can contain multiple fields. fields.x
The name of a field. Yes A custom value is allowed. fields.x.description
The description of a field. No None. fields.x.type
The type of a field. No Valid values: number, string, boolean, object, and array. fields.x.optional
Specifies whether a field is optional. No A value of the BOOLEAN type is supported. true
indicates that the field is optional, andfalse
indicates that the field is required.api_data
fieldThe api_data field defines data of one or more APIs. API names in this field must be the same as those in theapis
field. The size of data contained in the api_data field cannot exceed 6 KB. For more information, see the comments."api_data":{ "source" : [ {"x": "General goods", "y" : 5}, {"x": "General goods", "y" : 22}, {"x": "Light goods", "y" : 22}, {"x": "Devices", "y" : 14}, {"x": "Mineral products", "y" : 15}, {"x": "Steel", "y" : 15}, {"x": "Building materials", "y" : 12}, {"x": "Food", "y" : 12}, {"x": "Grain", "y" : 28} ], }
Field Description Required Remarks api_data
The data of APIs. Yes A widget can contain data of one or more APIs. source
The name of an API. No The API name in this field must be the same as that in the apis
field. The size of data contained in the field cannot exceed 6 KB.
Specifications of interaction events
Interaction events of DataV are controlled by the emit
method (triggered in the widget code) and the events
field in the package.json file.
events
fieldTheevents
field is under thedatav
field and is at the same level as theconfig
field. The events field defines the name, description, and variable name of an interaction event.{ "events": { "click-me": { "description": "Click-triggered event", "fields": { "value": { "description": "Click value" } } } } }
Field Description Required Remarks click-me
The name of an event. Yes A custom value is allowed. description
The description of an event. No This field is used to describe the usage of an event. fields
The fields. Yes This field can contain the names and descriptions of multiple fields. fields.value
The name of a field. Yes A custom value is allowed. fields.value.description
The description of a field. No None. emit
methodemit
is a basic method that passes event names and data in a widget as parameters. After this method is triggered, other widgets can obtain the parameter values of the widget based on the variable name. This method is implemented in the source code of the index.js file. For more information, see the comments.render: function () { this.container.on('click', () => { this.emit('click-me', data) // data must be an object, instead of a value. The attribute name is the variable name. }) }
type field
type: ["regular_bar", ...] // One widget can belong to multiple groups. Multiple widget types are separated by underscores (_), for example, "type1_type2".
{ // The common widget types.
regular: "Regular chart",
map: "Map",
media : "Media",
network: "Network",
text: "Text",
interact: "Interaction",
material: "Material"
}
publicHandler field
The publicHandler
field defines a behavior event of DataV. Example:
"publicHandler": {
"select": {
"name": "select",
"description": "Select an option",
"type": "object",
"fields": {
"data": {
"name": "Data",
"type": "array",
"children": {
...
}
}
}
}
}
In the preceding example, a select
behavior event is registered. The index.js
file must implement the select
method. Otherwise, an error is returned if the select method is executed.
- If you do not implement the
show
,hide
, andupdateOptions
methods, DataV automatically registers and implements these methods. - You can manually implement the
updateOptions
method. If the manual operation is not performed, DataV calls therender
method to implement the updateOptions method.
Field | Description | Required | Remarks |
---|---|---|---|
name | The name of an event. | Yes | The event name is used in node-based programming configurations. |
description | The description of an event. | No | There is no limit on the number of characters in a description. |
type | The type of the first input parameter of an event. | No | Optional. The value is fixed to object. |
fields | The field. | No | None. |
fields.data.name | The name of a field. | Yes | None. |
fields.data.description | The description of a field. | No | None. |
fields.data.type | The type of a field. | Yes | Optional. Valid values: number, string, boolean, object, and array. |
fields.data.children | The subnode. | No | This field must be specified if fields.data.type is set to object or array. |
fields.data.default | The default value. | No | This field must be specified if fields.data.type is set to number, string, or boolean. |
fields.data.optional | Specifies whether a field is optional. | No | Optional. This field takes effect when fields.data.type is set to boolean. true indicates that the field is optional, and false indicates that the field is required. |