Power Apps Component Fremework

简介

Microsoft Power Apps Component Framework 使您能够创建可重复使用的代码组件，在 Power Apps 应用程序和 Power Pages 网站中使用。 当现成组件无法满足应用制作者的需求时，Component Framework 使开发人员能够构建代码组件。 代码组件是视觉对象控件，可帮助您创建自定义用户体验。 这些组件还可以包括商业逻辑作为可视化的补充，以强制实施方案特有的规则。

优点

Power Apps 组件基于支持现代 Web 实践的强大框架构建而成。 因此，它具有许多优点，例如：

• 对丰富的框架 API 的访问权限，从而可公开各种功能，例如组件生命周期管理、上下文数据和元数据等。

• 支持客户端框架，例如 React 和 AngularJS。

• 通过 Web API、实用程序和数据格式化方法以及设备功能（例如，相机、位置和麦克风等）无缝访问服务器。

• 性能优化。

• 可重用性。

• 使用响应式 Web 设计原则，以针对任何屏幕大小、设备或方向提供最佳查看和交互体验。

• 能够将所有文件与其他应用资源捆绑到单个解决方案文件中。

可创建的组件类型

• 字段 - 窗体上字段的自定义控件。 例如，您可以使用自定义代码组件呈现滑块，而不是通过简单的文本框输入数字。 滑块可以具有自定义业务逻辑，以根据其他绑定到组件的可用数据限制滑块上的停止点。

• 数据集 - 用于显示数据行的自定义控件。 例如，您可以构建每日计划程序代码组件，而不使用包含行和列的通用网格显示今日预约。 该代码组件可以包括拖放等功能以重新安排预约。

创建者工具包组件

Power Platform 创建者工具包是几个常用 Power Apps Component Framework 控件的集合。 此外，该工具包还包括一组模板和其他实用程序，有助于提高开发人员的工作效率。 包含的所有组件均使用 Fluent UI 框架，具有一致性。 这些组件可以随时使用，也可为您要构建的代码组件提供灵感。 您可以在 GitHub 上找到这些组件的所有源代码。

结构

您可以使用 HTML、CSS 和 TypeScript 实现代码组件。 虽然不要求使用任何特定的 UI 框架，但 React 和 Fluent UI 是常用的选择。

组件构成

• 清单文件
• 组件实现
• 资源文件

要创建组件，代码需要实现一个接口，以使托管应用按照一致的方式与您的组件交互。 本任务由实现 StandardControl 接口的代码组件类完成。

export class FirstControl implements ComponentFramework.StandardControl<IInputs, IOutputs> {}

Power Apps 组件生命周期

开发组件时，要实现下表中的全部或部分 StandardControl 接口方法，具体取决于组件要求。 这些方法允许托管运行时管理代码组件的生命周期。

方法	描述
init	必需。 本方法用于初始化组件实例。 组件可以通过本方法启动远程服务器调用和其他初始化操作。 使用本方法无法初始化数据集值；必须使用 updateView 方法。
updateView	必需。 当组件属性包中的任何值发生变化时，将会调用本方法。 如果在 init 方法中启动了任何可能未完成的加载数据请求，则代码必须处理此状态并提供可视加载指示器。
getOutputs	可选。 在接收新数据之前由框架调用。 动态管理控件中的绑定属性时使用本方法。
destroy	必需。 当从 DOM 树中删除组件时调用。 destroy 方法用于进行清理以及释放组件所使用的任何内存。 例如，如果正在使用 React，请在 destroy 方法中使用 ReactDOM.unmountComponentAtNode。 这可以防止因在指定浏览器会话中加载和卸载代码组件而导致的任何性能问题。

生成 Power Apps 代码组件时，您可使用各种工具组合来精简整个流程的所需步骤。

步骤	描述	工具
创建	使用模板创建和初始化组件项目。	Power Platform 命令行接口 (CLI)
实施	描述和实现组件行为和样式。	您选择的代码编辑器或集成开发环境 (IDE)
生成	验证和转译 TypeScript 代码，自定义组件清单。	Power Platform CLI 或 Visual Studio Code
调试	验证组件行为并排除故障，而无需将其部署到 Dataverse 环境。	Power Platform CLI
打包	创建 Dataverse 解决方案文件，并将组件打包为该解决方案的一部分。	Power Platform CLI 和 Visual Studio msbuild

当您开始生成代码组件时，可使用 CLI 以通过模板来构建初始文件。 以下命令是使用字段模板初始化组件的示例：

pac pcf init --namespace Contoso --name Slider --template field

安装 CLI 的先决条件之一是安装节点包管理器 (npm)，它用于管理依赖项和生成您的代码组件。 当您使用 init 命令时，它会创建一个 package.json 文件，该文件配置了代码组件的依赖项以及将在组件开发期间使用的一些命令（例如 build）。 在初始化组件后，您运行的第一个 npm 命令是 install。 此命令将下载支持 Power Apps Component Framework 所需的所有库。

npm install

在开发代码组件时，您可以使用以下生成命令检查是否存在任何代码问题：

npm run build

此命令可验证您的清单，运行 TypeScript 转译器，并告知您任何问题。

测试工具也可用，因此您可以在本地测试代码组件，而无需将其部署到环境。 您可以通过使用以下启动命令，使用代码组件启动测试工具：

npm start

您还可以使用 npm start watch 命令启用观看模式。 如果您在观看模式下对代码进行更改，测试工具将自动发现这些更改，而无需重启。

要加快代码组件的测试速度，CLI 可以对开发环境进行身份验证，并推送代码组件，以在真实应用中进行测试。 以下命令将生成最新版本的代码组件并将其推送到当前配置的 Dataverse 开发环境。

pac pcf push --publisher-prefix dev

当您在将 Power Apps 解决方案部署到 Dataverse 环境的过程中打包组件时，将使用 msbuild 命令。 例如，以下命令将初始化组件的新解决方案，并创建 msbuild 项目文件，以管理在生成期间创建输出解决方案文件。

pac solution init --publisher-name Contoso --publisher-prefix contoso ‑‑outputDirectory vssolution

要在解决方案中打包代码组件，您必须添加对组件的引用。 这将确保在运行生成时，您的组件将包含在生成的输出解决方案中。 以下命令将添加该引用：

pac solution add-reference --path \<path to your Power Apps component framework project\>

您可使用 msbuild 命令生成解决方案文件，并配置解决方案引用。 以下命令首次运行生成：

msbuild /t:build /restore

组件清单

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

组件属性

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

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

<property name="sampleProperty" display-name-key="Property_Display_Key" description-key="Property_Desc_Key" of-type="SingleLine.Text" usage="bound" required="true" />
    <property name="test1" display-name-key="Property_Display_Key" description-key="Property_Desc_Key" of-type="SingleLine.Text" usage="bound" required="true" />
    <property name="test2" display-name-key="Property_Display_Key" description-key="Property_Desc_Key" of-type="SingleLine.Text" usage="bound" required="true" />

属性特性

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

• 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" />

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

<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>