组件清单

  • 10 分钟

配置组件清单是构建代码组件的关键步骤。 当您使用 pac pcf init 命令时，将使用您的一些选项对 ControlManifest.Input.xml 文件进行初始化，例如组件的名称和类型。 您还必须自定义该文件，以指定您使用的任何属性和资源，并启用您在组件中使用的任何框架功能。

组件属性

属性可定义代码组件和托管应用程序之间的契约。 它们应该从实现组件的方式中抽象出制作者，但仍可为使用该组件的制作者提供可配置的功能。 以下是您可能需要添加到组件的一些常见属性类型：

  • 允许业务数据在代码组件中传入和传出。 例如，通过将地理位置传递到组件中，组件可以显示一张地图，以突出显示特定位置。
  • 允许控制组件的功能和行为。 以我们的地图示例为例，可以添加一个属性，指示用户是否可以放大或缩小地图。
  • 允许自定义组件样式的某些方面。 例如，该组件提供制作者可以配置的属性，允许您在地图上自定义图钉颜色。

以下屏幕截图是一个清单示例，显示了为进度指示器组件定义的属性。

显示进度指示器组件中属性代码的屏幕截图。

当制作者配置代码组件时，清单中定义的属性可用于配置。 此图显示了在应用程序设计器中，制作者看到的进度指示器组件的以上清单。 它允许制作者查看可用的属性并对其进行自定义。

显示进度指示器组件属性窗格中属性的屏幕截图。

属性特性

您可以根据需要配置属性的一些特性。 以下是您应该考虑的较常见特性：

  • of-type - 此特性定义属性的数据类型。 有多种类型可供选择，例如 SingleLine.Text 与 Enum。 某些类型（例如 Enum）可提供固定列表以供选择，为制作者提供更丰富的配置体验。 有些类型会根据从托管应用传递的类型来限制数据内容。 有些更适合数据绑定，例如 Lookup.Simple。 发布组件后，请始终尽量避免更改数据类型。

  • usage - 此特性标识属性是输入、输出还是绑定。 它适用于模型驱动应用。 绑定选项期望有一个关联的表数据列来提供数据值。

  • required - 指示属性是否需要值。 当在发布组件后添加新属性时，请考虑针对使用该组件的现有应用，将该属性设为必需会产生的影响。

  • default-value - 此属性具有提供给组件的默认值。 在模型驱动应用中，仅允许对具有输入使用类型的属性使用此属性。 提供默认值有助于制作者了解应如何设置属性。 向现有组件添加新属性时，默认值通常设置为可通过该属性进行配置之前，该组件使用的值。

在评估计划添加的属性时，您需要考虑以下几点：

  • 避免组件有太多属性，让制作者不必浏览一长串选项。
  • 使用清晰的属性名称。 如果可能，请在描述中提供足够多的详细信息，让制作者能够了解属性的用途。
  • 考虑添加一些属性，以允许制作者设计组件的样式。 如果可能会在各种应用程序中使用该组件，这些属性可能很重要。
  • 发布组件后避免重命名或删除属性，因为这样会使现在正在使用的应用造成中断性变更。

组件资源

清单中的资源节点标识组件所需的资源文件。 在新组件中，最初仅包含必需的 code 元素。 您可以添加组件需要的其他资源。 最常见的是 css 和 resx。

css 元素允许您找到识别应加载的 CSS（级联样式表）文件。 如果您要加载多个文件，可以选择指定加载它们的顺序。 以下代码是加载两个 CSS 文件的示例。

<css path="css/ComponentCommon.css" order="1" />
<css path="css/ProgressIndicator.css" order="2" />

清单中的 resx 节点可标识一个文件，该文件用于管理您定义的本地化字符串。 如果您要进行本地化，将此节点添加到新组件，并在添加属性时进行更新会更方便。 清单中属性的 display-name-key 和 description-key 特性值用于查找本地化值（如果可以在加载的 resx 资源文件中找到）。

例如，请查看以下属性定义以及这些特性是如何定义的。

 <property name="PercentComplete" description-key="PercentComplete_Desc" display-name-key="PercentComplete" required="true" usage="input" of-type="Whole.None" default-value="40" />

在 resx 文件（这是一个使用 Microsoft ResX Schema 的 XML 文件）中，您将为属性键定义以下数据元素。

<data name="PercentComplete" xml:space="preserve">
        <value>Percent Complete</value>
</data>
<data name="PercentComplete_Desc" xml:space="preserve">
        <value>Percent Complete is the current value for how much has been completed.</value>
</data>

然后您要为支持的每种语言创建单独的 resx 文件。

接下来，在清单资源节点中添加以下 resx 节点，在使用组件时加载文件。

<resx path="strings/ProgressIndicator.1033.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.1035.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.3082.resx" version="1.0.0" />

使用组件功能

框架的设备、实用程序和 WebAPI 功能可供模型驱动应用中的组件使用。 要使用其中一项功能，您必须添加 uses-feature 节点，从而在清单的 feature-usage 节点中声明此功能。 以下代码是启用 WebAPI 功能的示例。

<feature-usage>
    <uses-feature name="WebAPI" required="true" />
 </feature-usage>