Qt桥元数据格式

Qt-Bridge Metadata format

Qt桥元数据格式

November 09, 2022 by Vikas Pachdha | Comments

​Vikas Pachdha，2022年11月9日|评论

Brief Overview of the metadata schema

元数据模式概述

Qt Design Studio has the capability to generate QML based UI files from a json file. Qt Design Studio expects a .metadata file for the import and the contents define the DOM and the QML item's properties in the json format. 

Qt Design Studio能够从json文件生成基于QML的UI文件。Qt Design Studio期望导入一个.metadata文件，内容以json格式定义DOM和QML项的属性。

Qt-Bridge plugins for Photoshop and Sketch generate such .metadata files. The .metadata files can be imported in the Qt Design Studio to generate QML.

Photoshop和Sketch的Qt Bridge插件生成这样的元数据文件。元数据文件可以在Qt Design Studio中导入以生成QML。

Similarly, other design tools can export the user interface in the specified metadata format to generate QML using Qt Design Studio.

类似地，其他设计工具可以以指定的元数据格式导出用户界面，以使用Qt design Studio生成QML。

The JSON format:

JSON格式：

The root object contains three sections, plugininfo, documentinfo and artboards. 

根对象包含三个部分：plugininfo、documentinfo和artboard。

• pluginInfo: This object has information about the plugin used to export the metadata.
• pluginInfo：这个对象有关于用于导出元数据的插件的信息。
• documentInfo: This object has the information about the document.  
• documentInfo：此对象包含有关文档的信息。
• artboards: This section contains the DOM and the layer properties.
• artboards：此部分包含DOM和层属性。

See the metadata JSON Schema for details.

​有关详细信息，请参见元数据JSON模式。

Plugin Info:

插件信息：

The properties defined under the "pluginInfo" object provide the information about the plugin used to export the metadata. Some properties can also change the behavior of the Asset Import in Qt Design Studio.

“pluginInfo”对象下定义的属性提供了有关用于导出元数据的插件的信息。某些属性还可以更改Qt Design Studio中资产导入的行为。

• applicationId *
• applicationName (Available in QDS version 2.1)
• applicationVersion
• extensionVersion *
• metadataVersion *
• assetNameScheme (Available in QDS version 2.1)
• coordinateSystemScheme (Available in QDS version 2.1)

* Required

*必需

Application ID

应用程序ID

The application Id of the plugin. The value should be "Generic".

插件的应用程序Id。该值应为“Generic”。

"pluginInfo": {
    "applicationId": "Generic"
  }

Application Name

应用程序名

The host application(Photoshop, Sketch, Figma etc) name. This value can be useful for logging and fixing bugs.

主机应用程序（Photoshop、Sketch、Figma等）名称。该值可用于记录和修复错误。

"pluginInfo": {
    "applicationName": "UI Maker"
  }

Application Version

应用程序版本

The host application(Photoshop, Sketch, Figma etc) version. This value can be useful for logging and fixing bugs.

主机应用程序（Photoshop、Sketch、Figma等）版本。该值可用于记录和修复错误。

"pluginInfo": {
    "applicationVersion": "21.1.1"
  }

Extension Version:

扩展版本：

The Qt Bridge plugin version. This value can be useful for logging and fixing bugs.

Qt Bridge插件版本。该值可用于记录和修复错误。

"pluginInfo": {
    "extensionVersion": "1.5.0"
  }

Metadata Version:

元数据版本：

The metadata format version. The current version is 1.1. 

元数据格式版本。当前版本为1.1。

"pluginInfo": {
    "metadataVersion": "1.1"
  }

Asset Name Scheme:

资产名称方案：

This value defines the scheme of the file names generated for assets. The possible values are:

该值定义为资源生成的文件名的方案。可能的值为：

• uuid: The UUID of the corresponding item is used as the asset file name. In this case, the asset importer will clean the file names on import. Since the UUIDs are unique, this is usually used to avoid a name clash of the generated asset files.
• uuid：相应项目的uuid用作资产文件名。在这种情况下，资产导入器将在导入时清除文件名。由于UUID是唯一的，这通常用于避免生成的资源文件的名称冲突。
• default: No renaming of the asset files is done and the files are imported as-is.
• 默认值：不重命名资源文件，文件按原样导入。

Note: undefined or incorrect value is treated as value "default"

注意：未定义或不正确的值被视为值“default”

"pluginInfo": {
    "assetNameScheme": "uuid"
  }

Coordinate System Scheme:

坐标系方案：

This value defines how the coordinated values are interpreted. The possible values are:

该值定义如何解释协调值。可能的值为：

• global: The asset importer expects the coordinate values as global values(Scene values).
• 全局：资源导入器预期坐标值为全局值（场景值）。
• parent: The asset importer expects the coordinate values to be in the parent's coordinate system.
• parent：资产导入器希望坐标值位于父坐标系中。

Note: undefined or incorrect value is treated as value "parent"

注意：未定义或不正确的值被视为值“父级”

"pluginInfo": {
    "coordinateSystemScheme": "parent"
  }

Document Info:

文档信息：

The "documentInfo" object defines the properties of the host application document used to export the metadata. Following properties defined under the "documentInfo" object:

“documentInfo”对象定义用于导出元数据的宿主应用程序文档的属性。“documentInfo”对象下定义的以下属性：

• name: The document name *
• name：文档名称*

* Required

*必需

Artboards:

艺术板：

Each object in the "artboards" json array defines a QML component.

“artboards”json数组中的每个对象都定义了一个QML组件。

Most of the design applications defines their user interface in layers, other application has a similar concept but sometimes with different nomenclature. 

大多数设计应用程序在层中定义其用户界面，其他应用程序具有类似的概念，但有时使用不同的命名。

Each QML component in the "artboards" json array is a JSON object which defines a layer of the UI, thus "artboards" is a json array of layer objects where each layer object can compose child layers. Each property of the layer object is defined in the JSON Schema. 

“artboards”json数组中的每个QML组件都是定义UI层的json对象，因此“artboard”是层对象的json数组，每个层对象都可以组成子层。层对象的每个属性都在JSON模式中定义。

Note that a layer can either have an assetData or textDetails. A layer with assetData creates a QML object of type Image and a layer with textDetails generates QML object of type Text. A layer without any assetData or textDetails shall create a QML object of type Item. 

请注意，层可以具有assetData或textDetails。带有assetData的层创建类型为Image的QML对象，带有textDetails的层生成类型为Text的QML对象。没有任何assetData或textDetails的层应创建Item类型的QML对象。

Layer hierarchy is maintained in the QML object model.

层层次结构在QML对象模型中维护。

Most of the properties are self-explanatory. 

大多数属性是不言而喻的。

Layer object visualisation:

图层对象可视化：

Sample Metadata:

示例元数据：

example JSON 1

示例JSON 1

{
    "pluginInfo": {
        "applicationId": "Generic",
        "applicationVersion": "62",
        "extensionVersion": "1.5.1",
        "metadataVersion": "1.1"
    },
    "documentInfo": {
        "name": "shadow"
    },
    "artboards": [
        {
            "name": "Artboard",
            "x": 348,
            "y": 210,
            "width": 334,
            "height": 573,
            "metadata": {
                "qmlId": "artboard",
                "uuid": "CCF63935-D8DC-4802-B776-CA617F731D27",
                "exportType": "component",
                "qmlVisible": true,
                "opacity": 1,
                "assetData": {
                    "assetPath": "/samples/shadow/CCF63935-D8DC-4802-B776-CA617F731D27.png",
                    "assetBounds": {
                        "x": 0,
                        "y": 0,
                        "width": 334,
                        "height": 573
                    }
                }
            },
            "layerIndex": 0,
            "children": [
                {
                    "name": "rectOut",
                    "x": 82,
                    "y": 122,
                    "width": 81,
                    "height": 71,
                    "metadata": {
                        "qmlId": "rectout",
                        "uuid": "9BFFC9D2-7E85-4658-84F5-A9303C272E26",
                        "exportType": "child",
                        "qmlVisible": true,
                        "opacity": 1,
                        "assetData": {
                            "assetPath": "/samples/shadow/9BFFC9D2-7E85-4658-84F5-A9303C272E26.png",
                            "assetBounds": {
                                "x": 68,
                                "y": 112,
                                "width": 129,
                                "height": 119
                            }
                        }
                    },
                    "layerIndex": 0
                },
                {
                    "name": "text",
                    "x": 55,
                    "y": 81,
                    "width": 30,
                    "height": 21,
                    "metadata": {
                        "qmlId": "text",
                        "uuid": "FA8CF45D-DCCE-4CFD-A831-B92652AB92D9",
                        "exportType": "child",
                        "textDetails": {
                            "fontFamily": "SF Pro Text",
                            "fontSize": 17.6,
                            "kerning": -0.4244706,
                            "textColor": "#007affff",
                            "lineHeight": null,
                            "horizontalAlignment": "left",
                            "verticalAlignment": "top",
                            "fontDisplayName": "SF Pro Text Regular",
                            "contents": "text",
                            "multiline": false
                        },
                        "qmlVisible": true,
                        "opacity": 1,
                        "transformation": {
                            "rotation": 0,
                            "flippedHorizontally": false,
                            "flippedVertically": false
                        }
                    },
                    "layerIndex": 1
                }
            ]
        }
    ]
}

Download metadata JSON Schema

下载元数据JSON架构

Layer object:

图层对象：

The following properties define a layer object:

以下特性定义图层对象：

• name: (String) Layer's name.
• name：（字符串）层的名称。
• layerIndex: (Integral Number). Decides the stacking order *
• layerIndex：（整数）。决定堆叠顺序*
• x: (Number) X coordinate value of the generated QML item
• x: （数字）生成的QML项目的X坐标值
• y: (Number) Y coordinate value of the generated QML item
• y：（数字）生成的QML项目的y坐标值
• width: (Number) Width of the generated QML item
• width:（Number）生成的QML项目的宽度
• height : (Number) Height of the generated QML item
• height：（数字）生成的QML项目的高度
• metadata: (Object) Layer's metadata. *
• 元数据：（对象）层的元数据*

* Required

*必需

Metadata Object:

元数据对象：

This section contains the metadata properties. Some of the properties are very niche and usually used in the advanced usage of the QML generation

此部分包含元数据属性。一些属性非常小众，通常用于QML生成的高级使用

Following QML properties can be manipulated:-

可以操纵以下QML属性：-

• exportType: (String)Export Type *
• exportType:（字符串）导出类型*
• qmlId: (String) QML id to be assigned *
• qmlId：（字符串）要分配的QML id*
• uuid: (String) A unique id. *
• uuid：（字符串）唯一的id*
• assetData: (Object) Layer's exported asset details
• assetData：（对象）层导出的资产详细信息
• textDetails: (Object) When layer is a text layer. Contains text details.
• TextDetails：（对象）当层是文本层时。包含文本详细信息。
• aliases: (Array<String>)To create property aliases
• 别名：（Array＜String＞）创建属性别名
• extraImports: (Array<String>)To add QML imports
• extraImports：（数组＜字符串＞）添加QML导入
• aliasOverrides: To override the component instance's properties
• aliasOverrides：覆盖零部件实例的特性
• qmlProperties: (Array<String>) To add QML properties
• qmlProperties：（数组＜字符串＞）添加QML属性
• internalReference: (String) to create component instance [Deprecated with QDS 2.1. Use typeUuid]
• internalReference:（String）创建组件实例[QDS 2.1不推荐使用。请使用typeUuid]
• externalReference: (String) To assign custom QML type to the generated QML Item [Deprecated with QDS 2.1. Use typeName]
• externalReference:（String）将自定义QML类型分配给生成的QML项[不推荐使用QDS 2.1。使用typeName]
• annotation: (String) Contextual information about the layer. Use this to write comments.
• annotation：（字符串）关于图层的上下文信息。用它来写评论。
• typeName: (String) Explicit QML type.
• typeName：（字符串）显式QML类型。
• typeUuid: (String) The UUID of the component whose instance this item should be.
• typeUuid：（String）该项应该是其实例的组件的UUID。
• anchors: (String) To anchor the item to its parent.
• anchors：（字符串）将项锚定到其父项。

* Required

*必需

Export type:

导出类型：

The property "exportType" defines how a layer is exported. It can have the following values.

属性“exportType”定义如何导出图层。它可以具有以下值。

• Component: The layer creates a separate QML file.
• 组件：该层创建一个单独的QML文件。
• Child: The layer is composed as a child under the parent item containing the layer object.
• 子项：层作为包含层对象的父项下的子项组成。
• Merged: The asset of the layer is merged up to its parent layer. The layer object will not create any QML or asset on its own.
• 合并：层的资源被合并到其父层。图层对象不会自行创建任何QML或资源。
• Skipped: completely skips the selected layer.
• 跳过：完全跳过选定层。

Asset Data: 

资产数据：

The "assetData" object contains the details of the associated assets. Following properties can added to the "assetData" object.

“assetData”对象包含关联资产的详细信息。可以将以下属性添加到“assetData”对象。

• assetPath: (String) path of the exported asset
• assetPath：导出资源的（字符串）路径
• assetBounds: (Object) x, y, width, the height of the asset, otherwise the asset is positioned at (0, 0) inside parent
• assetBounds：（Object）x，y，width，资源的高度，否则资源位于父级内部的（0，0）
• additionalAssets: (Array<String>) extra assets to be imported for this item. E.g. Hi DPI assets.
• additionalAssets：（数组＜字符串＞）要为此项目导入的额外资产。E、 g.高DPI资产。
• referenceAsset: This asset is not a part of the UI but a reference for the designers/developers. Usually, every child layers are rasterized in this asset.
• referenceAsset：此资产不是UI的一部分，而是设计师/开发人员的参考。通常，每个子层都会在该资源中光栅化。

example

示例

"metadata": { 
    "assetData": {
        "assetPath": "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7.png", 
        "assetBounds": { "x": 924, "y": 669, "width": 1014, "height": 969 }, 
        "additionalAssets": [ 
            "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7.jpg", 
            "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7@2.png", 
            "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7@2.jpg" 
        ],
        "referenceAsset" : "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7_ref.png"
    }
}

Property aliases:

属性别名：

Add "aliases" property to metadata object. "aliases" property takes an array of the properties of the respective Item for which QML aliases should be made at the component level. Primarily this is used to expose the properties of the child items, which is a requirement if the component is to be reused with the ability to override properties.  For example, add "aliases": ["text"] for the text item and the generated component will have an alias created.

将“别名”属性添加到元数据对象。“aliases”属性获取应在组件级别为其创建QML别名的各个项目的属性数组。这主要用于公开子项的属性，如果要重用具有重写属性能力的组件，这是一个要求。例如，为文本项添加“别名”：[“文本”]，生成的组件将创建一个别名。

example json and generated QML

示例json和生成的QML

example JSON 2

示例JSON 2

{
  "name": "Button",
  "x": 1774,
  "y": 36,
  "width": 160,
  "height": 70,
  "metadata": {
    "qmlId": "largeButton",
    "uuid": "5BF41D32-9220-4952-A405-A0CF85B76827",
    "exportType": "component",
    "qmlVisible": true,
    "opacity": 1,
    "assetData": {
      "assetPath": "/pop/F66E090D-2544-42CD-9CC7-B6CD46AAC5D5.png"
    }
  },
  "layerIndex": 3,
  "children": [
    {
      "name": "button",
      "x": 10,
      "y": 9,
      "width": 140,
      "height": 49,
      "metadata": {
        "qmlId": "button",
        "uuid": "9466F7DC-61D0-47F4-8CAC-4FB3D09E6386",
        "exportType": "child",
        "textDetails": {
          "fontFamily": "Helvetica Neue",
          "fontSize": 20,
          "textColor": "#000000ff",
          "lineHeight": 23,
          "horizontalAlignment": "center",
          "verticalAlignment": "center",
          "fontDisplayName": "Helvetica Neue Light",
          "contents": "button",
          "multiline": true
        },
        "aliases": [
          "text"
        ]
      },
      "layerIndex": 1
    }
  ]
}

Generated QML

生成的QML

import QtQuick 2.8

Item {
    id: largeButton
    width: 160
    height: 70
    property alias buttonText: button.text

    Image {
        id: largeButtonAsset
        x: 0
        y: 0
        source: "assets/largeButton.png"
    }

    Text {
        id: button
        x: 10
        y: 9
        width: 140
        height: 49
        color: "#ff000000"
        text: "button"
        font.pixelSize: 20
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        lineHeight: 23
        lineHeightMode: Text.FixedHeight
        wrapMode: Text.WordWrap
        font.family: "Helvetica Neue"
        font.styleName: "Light"
    }
}

QML imports:

QML导入：

Add "extraImports" property to metadata object to add QML imports to the component. "extraImports" (Array of strings) property takes an array of the import statements. The import statements are added to the Item are added to the generated QML component.

将“extraImports”属性添加到元数据对象以将QML导入添加到组件。“extraImports”（字符串数组）属性接受导入语句的数组。导入语句将添加到项目中，并添加到生成的QML组件中。

example:

示例：

"metadata": {
    "extraImports": [
    	"import myModule 1.0",
        "import QtQuick.Controls 1.4"
        ]
  }

Overrides: 

覆盖：

"aliasOverrides" metadata property is used to override the properties of the Component instance. Consider the example JSON 2 with the following metadata JSON snippet

​“aliasOverrides”元数据属性用于覆盖组件实例的属性。考虑带有以下元数据JSON片段的示例JSON 2

example JSON 3

示例JSON 3

{
  "name": "LoginButton",
  "x": 217,
  "y": 266,
  "width": 212,
  "height": 70,
  "metadata": {
    "qmlId": "loginButton",
    "uuid": "8A9AB24E-18F0-4207-8C7B-3E3442706683",
    "exportType": "child",
    "internalReference": "5BF41D32-9220-4952-A405-A0CF85B76827",
    "qmlVisible": true,
    "opacity": 1,
    "aliasOverrides": [
      {
        "name": "text",
        "value": "\"Login\"",
        "targetId": "9466F7DC-61D0-47F4-8CAC-4FB3D09E6386"
      }
    ]
  },
  "layerIndex": 1
}

Here the alias generated for property "text" of the Item generated from the layer with UUID "9466F7DC-61D0-47F4-8CAC-4FB3D09E6386" shall be overridden with the value "Login".  The generated QML shall be like this

此处，从UUID为“9466F7DC-61D0-47F4-8CAC-4FB3D09E6386”的层生成的项目的属性“text”生成的别名应被值“Login”覆盖。生成的QML应如下所示

LargeButton {
     id: loginButton
     x: 217
     y: 266
     width: 212
     height: 70
     buttonText: "Login"
 }

QML properties:

QML属性：

QML properties can be added explicitly to an Item. Add "qmlProperties" property to the metadata object to define the properties. "qmlProperties" expects an array of strings. 

QML属性可以显式添加到项目。将“qmlProperties”属性添加到元数据对象以定义属性。“qmlProperties”需要一个字符串数组。

example:

示例：

"metadata": {
    "qmlProperties": [
    	"color : \"#aa65cc\"",
        "width : variable_y",
        "horizontalAlignment : ENUM(Image.AlignRight)"
        ]
  }

Note: To add property of type Enumeration, wrap the value under the tag "ENUM(value)". See the example above. The color values are expected to be in AARRGGBB format.

注意：若要添加Enumeration类型的属性，请将值包装在标记“ENUM（value）”下。请参见上面的示例。颜色值应采用AARRGGBB格式。

With the aforementioned property "qmlProperties", all the QML properties can be assigned but there are some metadata object properties that can be defined to generate few QML properties easily. i.e.

通过上述属性“qmlProperties”，可以分配所有QML属性，但也可以定义一些元数据对象属性，以便轻松生成少量QML特性。即

• clip: Set item's clipping.
• clip：设置项目的剪辑。
• createAlias: To add an alias property to this item in the parent component.
• createAlias：向父组件中的此项添加别名属性。
• opacity: Add opacity value to the item
• opacity：向项目添加不透明度值
• qmlVisible: Set the item visibility.
• qmlVisible：设置项目可见性。

"metadata": {
    "clip": true,
    "qmlVisible": false,
    "createAlias": true,
    "opacity": 0.4
  }

internalReference: [Deprecated. Use typeUuid]

This property is used to create the instance of a component already defined in the metadata file. Assign the UUID of the component whose instance has to be generated.

此属性用于创建元数据文件中已定义的组件的实例。分配必须生成其实例的组件的UUID。

example

示例

"metadata": {
    "internalReference": "5BF41D32-9220-4952-A405-A0CF85B76827"
  }

externalReference: [Deprecated. Use typeName]

The type of the QML item generated can be dictated as well. "externalReference" metadata object property to define the type of the generated QML item.

也可以指定生成的QML项目的类型。“externalReference”元数据对象属性，用于定义生成的QML项的类型。

example

示例

"metadata": {
    "externalReference": "Button"
  }

typeName: [Available from QDS 2.1]

The type of the QML item generated can be dictated as well. "typeName" metadata object property to define the type of the generated QML item.

也可以指定生成的QML项目的类型。“typeName”元数据对象属性，用于定义生成的QML项的类型。

example

示例

"metadata": {
    "typeName": "Button"
  }

typeUuid: [Available from QDS 2.1]

The UUID of a component. Add the UUID of the component whose instance the generated QML should be. The Asset importer tries to find the QML Type of the target component and assigns the type to the generated QML Item.

组件的UUID。添加组件的UUID，生成的QML应该是该组件的实例。资产导入器尝试查找目标组件的QML类型，并将该类型分配给生成的QMLItem。

example

示例

"metadata": {
    "typeUuid": "5BF41D32-9220-4952-A405-A0CF85B76827"
  }

anchors: [Available from QDS 2.2]

The generated QML item can be anchored to its parent Item. The value can be a comma-separated string containing "left", "top", bottom, and "right". The position and dimension values are used to calculate the anchor margins.

生成的QML项目可以锚定到其父项目。该值可以是逗号分隔的字符串，包含“left”、“top”、“bottom”和“right”。位置和尺寸值用于计算锚定边距。

Note: The QML properties "x", "y", "width", and "height" might be irrelevant and shall be removed if the respective anchors are defined. e.g. property "x" is removed when the "left" or "right" anchor is defined. 

注：QML属性“x”、“y”、“宽度”和“高度”可能不相关，如果定义了相应的锚，则应删除。e、 g.当定义“左”或“右”锚时，属性“x”被删除。

example

示例

"metadata": {
    "anchors": "left, bottom"
  }