清单定义

注意：本页面描述了自 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: { quitTime: 100 }

  capabilities:
  - cameraAccess
  - locationAccess

intents:
- id: setFrequency
  handlingApplicationId: com.pelagicore.radio.app
  name:
    en: "Change the radio frequency"
- id: systemAboutToShutDown # broadcast from the sys-ui
  handleOnlyWhenRunning: yes

info.yaml 文件标题（第一个 YAML 文档）中的字段如下

字段名称	类型	说明
`formatVersion`	int	必需。目前始终为 `1`。
`formatType`	字符串	必需。始终为 `am-package`。

info.yaml 元数据（第二个 YAML 文档）中的字段如下

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

applications 列表中的每个条目所使用的字段如下：

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

在intents列表中的每个条目使用的字段如下

字段名称	类型	说明
`id`	字符串	必需。意图的id。请确保只指定此包中应用程序实际处理的Intent IDs。
`visibility`	字符串	此意图在此包外部的外观：可以是`private`或`public`（默认，如果未指定此字段）。私有意图只能由此包中的应用程序请求，而公共意图还可以由系统中的其他应用程序请求。
`handlingApplicationId`	字符串	如果此包包含多个应用程序，则必须指定哪个应用程序处理此意图；如果定义了一个应用程序，则此应用程序将为所有意图的默认处理程序。给出的应用程序id必须在此包内。
`handleOnlyWhenRunning`	布尔值	默认情况下，当针对应用发送请求时，应用将自动启动，但它们当前并未运行。将`handleOnlyWhenRunning`标志设置为`true`将阻止此行为，并且只有当该应用实际运行时，针对该意图的请求才会转发给其处理应用。这对于系统中与应用活动相关的通知特别有用，例如网络可用性的更改。
`requiredCapabilities`	list	限制可以调用该意图的客户端应用，使其至少包含列表中给出的能力之一。空列表或完全不指定此字段将导致无能力限制。
`parameterMatch`	对象	根据传入的参数过滤意图。这可以用于使多个应用能够处理相同的意图，具体取决于意图请求中的实际参数。请参阅IntentObject::parameterMatch文档以获取此字段的详细解释。
`name`	对象	意图的名称。它将默认为全局包部分的`name`字段，但可以通过指定此字段在每个意图中覆盖。
`icon`	字符串	意图的图标。它将默认为全局包部分的`icon`字段，但可以通过指定此字段在每个意图中覆盖。
`description`	对象	意图的描述。它将默认为全局包部分的`description`字段，但可以通过指定此字段在每个意图中覆盖。
`categories`	list	此意图的类别列表。它将默认为全局包部分的`categories`字段，但可以通过指定此字段在每个意图中覆盖。

runtimeParameters是特定于运行时的，因此下表包含一个额外列，指出配置选项应用的运行时

名称	运行时	类型	说明
`loadDummyData`	qml, qml-in-process	布尔值	已过时。使用与Qt的`qmlscene`和`qml`工具相同的算法自动加载应用程序的示例数据。默认情况下不加载示例数据。
`importPaths`	qml, qml-in-process	list	要添加到QML引擎的导入路径的路径列表。使用此参数的作用等同于在命令行启动程序时设置`QML2_IMPORT_PATH`。
`resources`	qml, qml-in-process	list	接受一个Qt资源文件 (.rcc) 或其他已编译资源的应用程序库列表，并在应用程序进程中注册它们。可以使用“:”或“qrc://”文件路径前缀访问资源。
`pluginPaths`	qml, qml-in-process	list	要添加到Qt库路径的路径列表，这些路径用于查找插件。使用此参数的作用等同于在命令行启动程序时设置`QT_PLUGIN_PATH`。
`arguments`	native	list	启动应用程序的可执行文件时应使用的命令行参数列表。
`environmentVariables`	native, qml	对象	一个简单的字符串到字符串映射，描述了启动运行时进程时应设置的環境变量。你可以通过将其设置为`null`来删除默认环境中的变量。注意：此功能仅适用于开发和演示，因为它有以下限制和副作用如果启用安全检查运行应用程序管理器，则完全忽略这些变量。设置这些变量将禁止为此应用程序使用快速启动机制。
`documentUrl`	native, qml, qml-in-process	字符串	一个可选的默认文档URL，如果未指定文档URL启动应用程序，则使用该URL（请参阅ApplicationManager::startApplication）。