プロトコルバージョン 2 の仕様例

次の例の注記にご注意ください。
{
"name": "@leaf/pie-multi-radius-with-title",   
 //@Namespace/Widget package name (The namespace is the name of a widget package. A widget package cannot be published without a namespace.)
"version": "0.1.5",                            //Version number
"dependencies": {                              //Dependencies, excluding datav:/com/another datav widget
"bcore": "0.0.9",
"jquery": "2.1.4",                             //All the dependent version numbers must be locked.
"lodash": "4.6.1"
},
"datav": {                                     //DataV configuration
"cn_name": "doughnut chart with title",                   //Chinese name of a widget
"protocol": 2,                                 //Protocol version number
"type": ["regular_pie"],                       //Widget type
"view": {
    "width": 300,
    "height": 200,
    "minWidth": 100,
    "minHeight": 50
},
"icon": "",                                       //Icon URL of a widget
"apis": {                                      //Widget API. Multiple APIs are supported.
  "source": {                                  //API name
    "handler": "render",                       //Processes the widget function name returned from an API.
    "description" : "doughnut chart API",            //API description
    "fields" : {                               //Fields required by an API. Multiple fields are supported.
      "x" : {                                  //Field name
        "description" : "category",                 //Field description
        "type" : "string",                     //Field type
        "optional": true                       //Optional field
      },
      "y" : {
        "description" : "value",
        "type" : "int"
      }
    }
  }
},
"config" : {                                 //Widget configuration, which is identified by the Editor
  "paxis" : {
    "type" : "group",                        //Type:group. For more information, see <Description of the config field>.
    "name" : "label",
    "children" : {
      "dx" : {
        "type" : "text",                //Type:text. For more information, see <Description of the config field>.
        "name" : "distance from label to center",
        "default" : 220
      }
    }
  },
  "title" : {
    "type" : "group",
    "name" : "title",
    "children" : {
      "value" : {
        "hasVisibility" : "true",
        "visible" : "true",
        "type" : "text",
        "name" : "title",
        "default" : "This is title."
      },
      "font-size" : {
        "type" : "number",                 //Type:number. For more information, see <Description of the config field>.
        "name" : "font",
        "min" : 10,
        "default" : 32,
        "max" : 100
      },
      "text-align" : {
        "name" : "alignment",
        "type" : "select",                //Type:drop-down list. For more information, see <Description of the config field>.
        "options" : [
          {"name" : "left aligned", "value" : "left"},
          {"name" : "right aligned", "value" : "right"},
          {"name" : "centered", "value" : "center"}
        ],
        "default" : "center"
      },
      "color" : {
        "name" : "font color",
        "type" : "color",                  //Type:color. For more information, see <Description of the config field>.
        "default" : "#fff"
      },
      "background-color" : {
        "name" : "background",
        "type" : "color",
        "default" : "#000"
      }
    }
  }
},
"api_data":{                          //API data. Multiple APIs are supported.
  "source" : [                       //API name, which must the same as that in the apis field. The recommended data size is within 6 KB.
    {"x": "cargo", "y" : 5},
    {"x": "cargo", "y" : 22},
    {"x": "light goods", "y" : 22},
    {"x": "device", "y" : 14},
    {"x": "mineral", "y" : 15},
    {"x": "metal", "y" : 15},
    {"x": "building material", "y" : 12},
    {"x": "food", "y" : 12},
    {"x": "grain", "y" : 28}
  ],
},
"events": {                           //Global parameter (event configuration)
  "event-name": {                     //Event name               
  "description": "event description",        //Event description
    "fields": {                      //Field. Multiple fields are supported.
      "value": {                     //Field name
        "description": "value description"       //Field description
      }
    }
  }
}
}
}

設定フィールドの説明

config フィールドはウィジェットの設定項目を表します。 設定項目はウィジェットに転送することも、エディタのオプションを説明するために使用することもできます。

config フィールドを設定するには、次の要件を満たす必要があります。

  • ウィジェットのデフォルト設定を含める必要があります。
  • エディタが識別できるように、入力仕様を明確に記述する必要があります。
  • 設定アイテムの handler フィールド
    • config の設定アイテムの handler を設定した場合、設定アイテムが変更されると、構成アイテムとこの構成アイテムに含まれるアイテムの両方が指定されたハンドラ内のカスタム関数に転送されます。

    • この構成アイテムの変更は、デフォルトのレンダリング機能には転送されません。 この設定アイテムをレンダリングまたは他の関数で使用するには、カスタム関数で設定と "this.config" を組み合わせます。

      "config": {
      "example": {
        "type": "group",
        "name": "chart property",
        "handler": "updateBar",            //Custom function name
        "children": {
          "_innerRadius": {
            "type": "number",
            "name": "inner radius",
            "default": 0.4,
            "range": [
              0,
              1
            ]
          }
        }
      }
      }
  • 設定アイテムの type フィールド
    タイプに応じて異なるエディタ UI が表示されます。 適切な種類と設定項目を使用することで、ウィジェットの品質とユーザーエクスペリエンスを向上させることができます。
    説明
    group 設定アイテムグループ。複数の設定アイテムを含めることができます。 同じ種類の要素を同じグループに配置することをお勧めします。
    text テキスト
    number
    select ドロップダウンリスト
    search コンボボックス
    color
    multicolor グラデーションカラー (グラデーションカラーとして単色または複数の色を選択できます。)
    image イメージ
    array 配列 (配列は複数の系列とカラーサイクルに使用されます。)
    hidden 非表示の設定項目 (エディタは非表示の設定項目を設定しません。)
    boolean ブール値
    radio チェックボックス
    percent 数値
    imageSelect 装飾的な要素
    • type:group
      "margin": {
      "type" : "group",                                                
      "name" : "label",                           
      "children" : {    
      }
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      children グループ内の要素 必須ではない このフィールドにデータが含まれていない場合、グループは空です。
    • type:text
      {
      "type" : "text",                                                
      "name" : "title",                           
      "default": "This is title."
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト表示値 必須ではない このフィールドにデータが含まれていない場合、表示値は空です。
    • type:number
      {
      "type" : "number",                                                
      "name" : "font size",                        
      "default": 22,
      "min": 10,            
      "max": 55,
      "range": [10, 55],
      "range": {
      "min" : 10,
      "max" : 55
      }
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト表示値 N/A このフィールドにデータが含まれていない場合は、 16 が表示されます。
      min 最小値 必須ではない "min"、"range [0]" および "range.min" のいずれかのフィールドが設定されていれば、最小値は正常に設定されています。 "min"、"range [0]" および "range.min" の各フィールドが設定されていない場合、"type" の値は "text" に設定され、プログラムを正しく実行することができません。
      max 最大値 必須ではない "min"、"range [1]" および "range.max" のいずれかのフィールドが設定されていれば、最大値は正常に設定されています。 "min"、"range [1]" および "range.max" の各フィールドが設定されていない場合、"type" の値は "text" に設定され、プログラムを正しく実行することができません。
      range 値の範囲 必須ではない このフィールドは、配列 ( [10, 55] など) またはオブジェクト ({min: 10, max:55} など) にすることができます。 "range"、min および max フィールドが設定されていない場合、"type" の値は "text" に設定され、プログラムが正しく実行されていることを保証できません。
      フィールドに最大値または最小値がある場合は、スライダーが UI に表示されます。
    • type:select
      {
      "name" : "alignment",
      "type" : "select", 
      "options" : [
       {"name" : "left aligned", "value" : "left"},
       {"name" : "right aligned", "value" : "right"},
       {"name" : "centered", "value" : "center"}
       ],
      "default" : "center"
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト表示値 必須ではない このフィールドにデータが含まれていない場合は、options [0]が表示されています。
      options ドロップダウンリストのオプション 必須 このフィールドは配列です (例: [{name: '' ,value: ''}])。 このフィールドが設定されていない場合、"type" の値は "text" に設定されます。
    • type:search
      {
      "name": "font",
      "type": "search",
      "default": "Microsoft Yahei",
      "range": [
      {
        "Microsoft Yahei": "Microsoft Yahei"
      },
      {
        "SimSun": "SimSun"
      },
      {
        "SimHei": "SimHei"
      },
      {
        "LiSu": "LiSu"
      },
      {
        "YouYuan": "YouYuan"
      },
      "tahoma",
      "arial",
      "sans-serif"
      ],
      "description": "Select a font that is already installed on your system. If your system does not have this font, the default font is used for the title."
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト表示値 必須ではない このフィールドにデータが含まれていない場合は、 options [0]が表示されています。
      range ドロップダウンリストのオプション 必須 このフィールドは、次のいずれかの形式になります。[{name: '' ,value: ''}] (配列)、[{key: value}]および[value]です。 このフィールドが設定されていない場合、"type" の値は "text" に設定されます。
    • type:color
      {
      "name" : "font color",
      "type" : "color", 
      "default" : "#fff"
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト表示値 必須ではない このフィールドにデータが含まれていない場合は、#000 が表示されています。
    • type:multicolor
      {
      "name" : "gradient color",
      "type" : "multicolor", 
      "default" : {
      "style": "single",
      "value": "#ccc",
      "from": "#000",
      "to": "#fff",
      "angle": 0
      }
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト表示値 必須 style の値は single または double で、value の値は single です。 from to および angle のフィールドの値は、"style" フィールドが "double" に設定されている場合は、グラデーションの範囲を示します。
      stylesingle に設定されている場合、次の実際のデータが表示されます。
      {
      "style": "single",
      "value": "#xxx"
      }
      styledouble に設定されている場合は、以下の実際のデータ値が表示されます。
      {
      "style": "double",
      "from": "#xxx",
      "to": "#xxx",
      "angle": 90
      }
    • type:image
      {
      "name" : "background image",
      "type" : "image",
      "default": "http://datav.oss-cn-hangzhou.aliyuncs.com/uploads/images/c4ba3c6518c1997f4baa612a600c3fbe.png"
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト表示値 必須ではない このフィールドにデータが含まれていない場合、画像は表示されません。
      画像がローカルの静的ファイルの場合は、そのファイルをウィジェットの "resources" ディレクトリに配置します。たとえば、 ./resources/xxxx.png のようにします。
    • type:array
      {
      "name" : "series",
      "type" : "array",
      "default": [{"name": "series 1", value: "arrival"},{"name": "series 2", value: "departure"}]
      "child": {
      "name" : "series<%=i+1%>",
      "type" : "object",
      "child": {
        "name": {
          "name" : "series value",
          "type" : "text",
          "default": "series"
        },
        "value": {
          "name" : "series name",
          "type" : "text",
          "default": ""
        }
      }
      }
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト値 必須 オブジェクト配列です。 オブジェクトのプロパティは、child フィールドで指定されたフィールド名と同じである必要があります。
      child オブジェクト名 必須 type フィールドはオブジェクトに設定する必要があります。
      child オブジェクトプロパティ 必須 child フィールドは、オブジェクトプロパティとデフォルト値を定義するために使用されます。
      シリーズの default 値はオブジェクト配列でなければなりません。 配列内のオブジェクトのプロパティは child で定義し、オブジェクトプロパティの表示名型、およびデフォルト値を設定する必要があります。
    • type:hidden
      {
      "type" : "hidden",
      "name": "value",
      "default": 22
      }
      フィールド名 説明 要否 備考
      type 必須 エディタはこのフィールドを設定しません。
      name 表示名 必須 N/A
      default デフォルト値 必須ではない 値はデフォルトでは表示されませんが、関数に転送されます。
    • type:boolean
      {
      "type" : "boolean",
      "name" : "display",
      "default": true
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト値 必須ではない このフィールドにデータが含まれていない場合は、false が表示されます。
    • type:radio
      {
        "name":"font weight",
        "type":"radio",
        "default":1,
        "list":[  
          {  
            "name":"normal",
            "value":1
          },
          {  
            "name":"bold",
            "value":2
          }
        ]
       }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      list ドロップダウンリスト 必須 name および value フィールドを含むオブジェクト配列です。
      default デフォルト値 必須ではない このフィールドが設定されていない場合、デフォルト値は空です。
    • type:percent
      "percent": {
      "type": "percent",
      "name": "numerical value",
      "default": 20
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 N/A
      default デフォルト値 必須ではない このフィールドにデータが含まれていない場合、デフォルト値は空です。
    • type: imageSelect
      "imageSelect": 
      {
      "name": "decorative element",
      "type": "imageSelect",
      "default": "gif1",
      "range": [
      {
      "name": "gif1",
      "value": "gif1",
      "url": "https://img.alicdn.com/tps/TB1tFMtPXXXXXXyXpXXXXXXXXXX-1920-1080.gif"
      },
      {
      "name": "gif2",
      "value": "gif2",
      "url": "https://img.alicdn.com/tps/TB1Pg3pPXXXXXcxXpXXXXXXXXXX-1920-1080.gif"
      }
      ]
      }
      フィールド名 説明 要否 備考
      type 必須 N/A
      name 表示名 必須 このフィールドにデータが含まれていない場合は、表示名としてキー ( margin など) が使用されます。
      default デフォルト値 必須ではない このフィールドにデータが含まれていない場合は、"options [0]" が表示されます。
      range ドロップダウンリストのオプション 必須 このフィールドは配列です。たとえば、 [{name:'',value: '',url: ''}] のようになります。

カスタム設定アイテムの表示と非表示

このセクションでは、 show の使用して、カスタム設定アイテムを表示または非表示にする方法について説明します。
{
"xAxis": {
    "type": "group",
    "name": "x-axis",
    "children": {
        "show": { //Displays a check box on the right side of the x-axis. This check box does not determine whether a similar property is displayed.
             "type": "boolean",
             "name": "display",
             "default": true
        },
        "color": {
            "type": "color",
            "name": "color",
            "default": "#ccc",
            "show": [            //Determines whether to display a property.
                ["show", "$eq", true]     //Condition under which the color is displayed: The color is displayed only when the show filed of a similar property is set to true.
            ]
        }
    }
}
}

"apis" と "api_data" のフィールド

  • apis フィールド
    このフィールドは、ウィジェット API の名前とその API が必要とするフィールドを定義します。 複数の API とフィールドがサポートされています。 詳しくは、前の例の注記をご参照ください。
    "apis": {                               //Widget API. Multiple APIs are supported.
    "source": {                             //API name
    "handler": "render",                     //Processes the widget function name returned from an API.
    "description" : "doughnut chart API",          //API description
    "fields" : {                             //Fields required by an API. Multiple fields are supported.
     "x" : {                                 //Field name
       "description" : "category",                 //Field description
       "type" : "string",                     //Field type
       "optional": true                       //Optional field
     },
     "y" : {
       "description" : "value",
       "type" : "int"
     }
    }
    },
    "source2":{
          ...                                     //API 2
    }
    }
  • api_data フィールド
    このフィールドは API データを定義します。 複数の API がサポートされています。 API 名は apis と同じである必要があります。 推奨データサイズは 6 KB 以内です。 詳しくは、前の例の注記をご参照ください。
    "api_data":{                          //API data. Multiple APIs are supported.
      "source" : [                       //API name, which must the same as that in the apis field. The recommended data size is within 6 KB.
        {"x": "cargo", "y" : 5},
        {"x": "cargo", "y" : 22},
        {"x": "light goods", "y" : 22},
        {"x": "device", "y" : 14},
        {"x": "mineral", "y" : 15},
        {"x": "metal", "y" : 15},
        {"x": "building material", "y" : 12},
        {"x": "food", "y" : 12},
        {"x": "grain", "y" : 28}
      ],
    },

イベント仕様

DataV のウィジェットインタラクションは、"emit" と "events" の記述を通して実装されています。 "emit" は、イベントの説明 ("package.json" のイベントの説明) に従って起動されます。

  • events の説明
    "events" フィールドは config のように、"datav" フィールドに含まれます。 "events" フィールドはインタラクションイベント名、イベントの説明および変数名を定義します。 詳しくは、前の例の注記をご参照ください。
    package.json
    {
    "events": {                 
        "click-me": {                //custom event name
            "description": "click to trigger an event",             //Event description field
            "fields": {            //Multiple variables and corresponding description can be defined.
                "value": {         //Field name, which can be customized as needed
                    "description": "callback value" 
                }
            }
        }
    }
    }
  • "emit" をトリガーする
    "emit" は、ウィジェットのイベント名と必要なデータをパラメーターとしてスローできる基本関数です。 このようにして、他のウィジェットは変数名に従ってパラメータ値を取得できます。 詳しくは、前の例の注記をご参照ください。
    index.js
    render: function () {
        this.container.on('click', () => {
            this.emit('click-me', data)            // The value of data must be an object and cannot be a value. The property name is the variable name.
        })
    }

"type" フィールド

type はウィジェットの種類を定義します。 詳しくは、前の例の注記をご参照ください。
type: ["regular_bar", ...]  //A widget can belong to different groups. Multiple widget types are separated using underscores (_), for example, "type1_type2".
    { // Common widget type
      regular: "basic chart",
      map: "map", 
      figure: 'indicator', 
      network: "networks", 
      text: "text", 
      decorate: "supporting graphics"
    }