# 物料协议文件基础结构
自定义组件库需通过符合UI引擎规范的JSON配置文件（以下简称"物料协议文件"），才能在UI引擎页面设计器中正常加载、解析和使用。该文件定义了组件的元数据、属性、事件、分组等核心信息，是自定义组件与UI引擎前端页面交互的核心协议，以下为完整的配置规范及示例说明。
#### 协议基础结构
物料协议文件的根节点仅包含"data"属性，其值为对象类型，包含以下两个必选属性：
- framework：框架标识，目前仅支持"Vue"。
- materials：物料核心配置，包含组件、区块、分组等信息。
基础结构如下：
```
{
  "data": {
    "framework": "Vue",
    "materials": {}
  }
}
```
表1data属性说明 
| 属性名称                                                          | 值类型    | 说明                    |
|:---|:---|:---|
| framework                                                     | String | 物料适配的前端框架，目前仅支持"Vue"。 |
| [materials] | Object | 物料配置信息，包含组件、区块、分组等信息。 |
   
 表2materials属性说明 
| 属性名称                                                                            | 值类型                      | 说明                           |
|:---|:---|:---|
| [components](https://support.huaweicloud.com/usermanual-idme/idme_ui_0077.html) | Array\<ComponentConfig\> | 组件配置列表，每个对象对应一个自定义组件的完整配置。   |
| blocks                                                                          | Array\<Object\>          | 区块配置，当前版本无实际作用，传递空数组即可。      |
| [snippets](https://support.huaweicloud.com/usermanual-idme/idme_ui_0078.html)   | Array\<SnippetConfig\>   | 组件在物料面板的分组配置，定义组件的展示分组及初始数据。 |
   
#### 完整物料协议模板（含示例）
以下是包含"卡片测试组件"的完整物料协议模板，标注了关键配置项的说明，可直接参考适配自定义组件：
```
{
  "data": {
    "framework": "Vue", // 固定值，仅支持Vue
    "materials": {
      "components": [
        {
          "name": { // 组件多语言名称（必填）
            "zh_CN": "卡片测试组件",
            "en_US": "Card Test Component"
          },
          "component": "LscTest", // 组件标签名，需与JS导出名称一致（必填）
          "description": "这是一个测试组件，用于展示卡片的功能。", // 组件描述（可选）
          "version": "1.0.0", // 组件版本号（必填，编辑时需更新）
          "docUrl": "", // 文档地址（无则留空）
          "screenshot": "", // 组件截图（无则留空）
          "npm": { // 组件导入配置（必填，核心）
            "package": "", // npm包名（仅npm安装的组件库需配置）
            "exportName": "LscTest", // 组件导出名称，需与component一致（必填）
            "version": "1.0.0", // npm包版本（非npm包留空）
            "destructuring": true // 解构导入标识，建议固定为true
          },
          "group": "component", // 组件分组标识，需与snippets的group一致（必填）
          "category": "general", // 组件分类（自定义，可选）
          "schema": { // 组件元数据配置（必填，核心）
            "properties": [ // 属性分组配置（详见2.3）
              {
                "name": "0", // 分组唯一标识（必填）
                "label": {
                  "zh_CN": "基础属性" // 分组显示名称（必填）
                },
                "content": [ // 具体属性配置列表
                  {
                    "property": "coverImage", // 属性名，需与组件props一致（必填）
                    "label": {
                      "text": {
                        "zh_CN": "封面图片",
                        "en_US": "Cover Image"
                      }
                    },
                    "labelPosition": "top", // 标签位置，可选top/left（默认top）
                    "description": { // 属性说明（鼠标悬浮显示）
                      "zh_CN": "卡片的封面图片地址",
                      "en_US": "The URL of the card's cover image"
                    },
                    "type": "string", // 属性类型
                    "default": "", // 配置器默认值
                    "required": false, // 是否必填
                    "bindState": true, // 是否支持状态变量绑定
                    "readOnly": false, // 是否只读
                    "widget": { // 配置器组件（必填）
                      "component": "MetaInput", // 输入框配置器
                      "props": {} // 配置器属性（无则留空）
                    }
                  },
                  {
                    "property": "showButton",
                    "label": {
                      "text": {
                        "zh_CN": "是否显示按钮",
                        "en_US": "Show Button"
                      }
                    },
                    "labelPosition": "left",
                    "description": {
                      "zh_CN": "是否显示按钮",
                      "en_US": "Whether to show the button"
                    },
                    "type": "boolean",
                    "default": true,
                    "required": false,
                    "bindState": true,
                    "readOnly": false,
                    "widget": {
                      "component": "MetaSwitch", // 开关配置器（适配布尔类型）
                      "props": {}
                    }
                  }
                ]
              }
            ],
            "slots": {}, // 插槽配置，无则留空（必填）
            "events": { // 事件配置，无则留空（必填）
              "onBtnClick": { // 事件名，需以on开头+驼峰命名
                "label": {
                  "zh_CN": "按钮单击事件",
                  "en_US": "Button Click Event"
                }
              }
            }
          }
        }
      ],
      "blocks": [], // 固定空数组
      "snippets": [ // 物料面板分组配置
        {
          "group": "自定义组件", // 分组标识
          "label": {
            "zh_CN": "自定义组件" // 分组显示名称
          },
          "children": [
            {
              "name": {
                "zh_CN": "卡片测试组件",
                "en_US": "Card Test Component"
              },
              "icon": "card", // 组件图标（可选）
              "screenshot": "",
              "snippetName": "LscTest", // 需与component一致
              "schema": {}
            }
          ]
        }
      ]
    }
  }
}
```