清单定义

注意：本页描述的是5.14版本中引入的当前元数据格式（《am-package》，版本《1》）。关于旧格式——目前仍受支持——请参阅此处。

概述

包清单或元数据文件 info.yaml 是一个遵循相同规则的YAML文件，规则与应用程序管理器中使用的所有其他YAML文件相同。

虽然应用程序管理器可以支持其他文件格式，例如XML，但目前唯一实现的元数据加载器是基于YAML的。

所有包和它们包含的应用程序都由一个单一的 info.yaml 文件描述，位于包的根目录中。

包清单

以下是一个功能齐全的 info.yaml 文件示例，同时也展示了如何在 YAML 1.1 文档中混合经典 YAML 和 JSON 风格。

%YAML 1.1
---
formatVersion: 1
formatType: am-package
---
id: 'com.pelagicore.radio'
icon: 'FM-Radio.png'
name:
  en: "FM Radio"
  de: "UKW-Rundfunk"

version: '1.2.1-alpha3'

applications:
- id: com.pelagicore.radio.app
  code: "radio.qml"

  runtime: qml
  runtimeParameters: { loadDummyData: true }

  capabilities:
  - cameraAccess
  - locationAccess

info.yaml 文件头（第一个 YAML 文档）内的字段如下所示

字段名称	类型	描述
`formatVersion`	int	必需。目前始终为 1。
`formatType`	string	必需。始终为 am-package。

info.yaml 清单数据（第二个 YAML 文档）内的字段如下所示

字段名称	类型	描述
`id`	string	包的唯一标识符，作为长度不超过 150 个字符的字符串表示。该 ID 可用于在 PackageManager QML 类型中查找有关包的信息。由于此 ID 用于文件系统中，因此只能允许一小部分可打印的 ASCII 字符：0-9、a-z、A-Z 以及 !#$%&'`^~_+-=.,;()[]{} 中的任何一个。如果您正在构建一个包含第三方应用程序的更大系统，那么长期使用反向DNS表示法作为包 ID 是一个好的做法，以帮助您长时间跟踪您的 ID。PackageManager::validateDnsName 帮助函数可以帮助您在系统 UI 中强制实施此策略。
`icon`	string	必需。图标的文件名。文件必须位于与 info.yaml 相同的目录中，可以是 Qt 支持的任何图像格式。
`name`	object	必需。一个包含语言（`string`）到显示名称（`string`）映射的对象。语言标识符需要遵循标准 POSIX 位置定义。有关更多信息，请参阅 QLocale。至少需要有一个映射存在。但是，提供英文（`en`）映射至少作为后备是一个好的做法。
`description`	object	一个包含语言（`string`）到描述名称（`string`）映射的可选对象。此字段使用与 name 字段相同的语法。
`categories`	list<string>	应与该包关联的分类名称列表。这主要用于自动商店上传以及将包的应用程序或意图显示在系统 UI 中的一组固定分类中。
`version`	string	包的版本字符串。
`applications`	list	必需。此包中包含的应用程序列表。必须至少定义一个应用程序。
`intents`	list	此包中应用程序提供的目标列表。

应用程序列表中每个项目使用的字段如下所示

字段名称	类型	描述
`id`	string	应用程序的唯一标识符，表示为字符串，最大长度为150个字符。此ID可以用于在ApplicationModel QML 类型中查找有关应用程序的信息。由于此ID用于文件系统，因此仅允许使用可打印的ASCII字符子集：`0-9`、`a-z`、`A-Z`以及任何!#$%&'`^~_+-=.,;()[]{}字符。如果您正在构建包含第三方应用程序的更大系统，则使用反向DNS表示法为应用程序ID是一种好的做法，这有助于长期跟踪您的ID。辅助函数ApplicationInstaller::validateDnsName可以帮助您从系统UI中强制执行此策略。
`代码`	string	必需。主可执行文件 - 由`runtime`解释。
`runtime`	string	必需。一个运行时ID，引用运行时插件。目前支持`qml`、`qml-inprocess`和`native`。对于QML运行时，`code`字段需要指向主QML文件，该文件应具有一个ApplicationManagerWindow作为根项。对于本地运行时，`code`字段可以指向任意可执行文件，该文件通过QProcess::start执行。应用程序管理器将以设置环境变量`QT_QPA_PLATFORM`为`wayland`的方式运行应用程序。注意：应用程序应是一个有效的Wayland客户端。
`runtimeParameters`	object	该对象可以包含`runtime`特定的参数——这些参数由应用程序管理器直接传递给运行时插件。有关完整列表，请参阅运行时参数。
`supportsApplicationInterface`	bool	如果设置为`true`，则应用程序必须实现ApplicationInterface API。在这种情况下，应用程序管理器将等待应用程序连接到P2P D-Bus上的ApplicationInterface，然后将其标记为'运行'。对于支持快速启动的运行时（如`qml`运行时）这不是必须的，因为它默认为`true`。否则默认值为`false`。
`capabilities`	list<string>	应用于应用程序的、平台特定的特殊访问权限列表。稍后，中间件可以通过应用程序管理器查询这些功能并验证它们。注意：应用程序管理器本身不会对此字符串列表赋予任何含义。相反，应用程序管理器充当（数字签名的）应用程序清单和（客户特定的）中间件之间的受信人；此中间件可能需要有关其正在通信的应用程序以及应用程序管理器可以作为应用程序功能的受信任来源的更多信息。
`opengl`	object	让您可以指定所需的OpenGL版本和/或配置文件。有关更多信息，请参阅OpenGL规范。注意：如果指定的OpenGL配置与主应用程序管理器配置中的默认OpenGL配置不同，则将禁用此应用程序的快速启动机制。
`applicationProperties`	object	将用户定义的属性（键/值对）导出到应用程序和系统UI中。实际属性必须在`private`和`protected`访问控制标签下列出；其他属性将被忽略。这些属性作为ApplicationManager::application()暴露给系统UI，以及作为ApplicationInterface::applicationProperties暴露给QML应用程序应用程序可以访问私有和受保护的属性。私有密钥会覆盖相同的受保护密钥。系统UI可以访问仅受保护的属性。尽管属性被转换为QVariantMap，应用程序管理器不会以任何方式解释它们。
`logging/dlt/id`	string	如果提供了此值，则用作汽车DLT应用程序ID。 ID限制为四个字符，额外的字符将被丢弃。如果没有提供ID，则默认为"A"后面跟三位应用程序号。注意：对于QML运行时，从应用程序过程的开始到您按所述方式更改它之前，ID始终为"PCLQ"。
`logging/dlt/description`	string	如果提供，则用作汽车DLT应用程序描述，这允许使用更长的描述来扩展简短的DLT应用程序ID。如果没有明确提供，则使用默认描述。

用于《intents》列表中每个条目的字段如下

字段名称	类型	描述
`id`	string	必需。意图的ID。请确保只指定此包中的应用程序真正处理的意图ID。
`visibility`	string	在此包之外的意图可见性：可以是`private`（私有）或`public`（默认值，如果没有指定此字段）。私有意图只能由此包中的应用请求，而公共意图还可以由系统中的其他应用请求。
`handlingApplicationId`	string	如果此包包含多于一个应用程序，那么指定处理此意图的应用程序是强制性的；如果只定义了一个应用程序，则该应用程序将用作所有意图的默认处理程序。指定的应用程序ID必须属于此包。
`requiredCapabilities`	list<string>	限制能够调用此意图的客户端应用程序具有此列表中给出的至少一个能力。空列表或简单不指定此字段将导致没有能力限制。
`parameterMatch`	object	根据传入的参数筛选意图。此功能可用于使多个应用能够处理同一意图，具体取决于意图请求中的实际参数。有关此字段的详细说明，请参阅IntentObject::parameterMatch文档。
`name`	object	意图的名称。它将默认为全局部分中的`name`字段，但可以通过指定此字段为每个意图覆盖。
`icon`	string	意图的图标。它将默认为全局部分中的`icon`字段，但可以通过指定此字段为每个意图覆盖。
`description`	object	意图的描述。它将默认为全局部分中的`description`字段，但可以通过指定此字段为每个意图覆盖。
`categories`	object	此意图的类别列表。它将默认为全局部分中的`categories`字段，但可以通过指定此字段为每个意图覆盖。

runtimeParameters是针对特定运行时的，因此下面的表格中还有一个额外列，说明了哪些配置选项适用于哪个运行时

Name	Runtimes	类型	描述
`loadDummyData`	qml, qml-in-process	bool	自动加载应用程序的虚拟数据，使用与Qt的`qmlscene`和`qml`工具相同的算法。默认情况下不加载虚拟数据。
`importPaths`	qml, qml-in-process	list<string>	要添加到QML引擎导入路径的路径列表。此参数的使用相当于从命令行启动程序时设置`QML2_IMPORT_PATH`。
`resources`	qml, qml-in-process	list<string>	接收Qt资源文件（.rcc）或库的列表，将这些资源编译并注册在应用程序进程内。资源可以通过“:”或“qrc://”文件路径前缀访问。
`pluginPaths`	qml, qml-in-process	list<string>	要添加到Qt库路径的路径列表，这些路径用于查找插件。此参数的使用相当于从命令行启动程序时设置`QT_PLUGIN_PATH`。
`arguments`	native	list<string>	启动应用程序可执行文件时要使用的命令行参数列表。
`环境变量`	原生、QML	object	这是一个简单的字符串到字符串映射，描述了在创建运行时进程时应设置的环境变量。您可以设置变量为`null`来从默认环境变量中移除变量。注意：该功能仅用于开发和演示，因为它具有以下限制和副作用如果您启用安全检查运行应用程序管理器，则完全忽略这些变量。设置这些变量将禁用此应用程序的快速启动机制。
`documentUrl`	string	如果未指定文档URL启动应用程序，将使用此可选的默认文档URL（请参阅ApplicationManager::startApplication）。