launchpad-ux-custom-components

概述

此技能介绍基于 Constellation 设计系统的 Pega Launchpad Custom UX。内容包括：

• 何时应考虑构建自定义 Constellation 组件，而不是仅使用开箱即用的视图和模板。
• 实现自定义组件前需要准备哪些信息和设计输入。
• Custom UX 如何融入整体 Launchpad 架构和 DX 模式。

自定义组件通过添加专用可视化、交互或集成来扩展标准 Constellation UX，同时遵循 Launchpad 的设计语言和运行时模型。

生成代码前的强制对话流程

IMPORTANT：用户请求自定义组件时，Agent 必须遵循 references/conversation-flow.md 中定义的分步对话流程。

完成所有步骤并获得用户确认前，不要生成任何代码。

此流程可确保：

1. Step 1：确认开箱即用的 Constellation 组件无法满足需求
2. Step 2：查看 UX Boosters 目录：https://launchpad.io/ux-boosters
3. Step 3：收集详细需求（功能、位置、数据、交互）
4. Step 4：提出组件类型建议（Field/Widget/Template）并获得用户确认
5. Step 5：仅在此之后生成代码

完整的对话脚本和示例请参阅 references/conversation-flow.md。

---

前提条件

在为 Launchpad 构建自定义 DX 组件之前，请确保具备：

1. 开发环境

   • Node.js（LTS 版本，例如 18.x 或 20.x）
   • npm（随 Node.js 一同安装）
   • 代码编辑器（推荐使用 VS Code）

2. Launchpad Provider 访问权限

   • 对 Launchpad Provider 的管理员访问权限
   • 一个要使用该组件的应用程序

3. DXCB 的 OAuth 客户端凭据

   • 在 Launchpad Studio 中，点击 9 点菜单并转到 Administration setup
   • 添加新的 OAuth 2.0 client registration
   • 记下 clientId 和 clientSecret，用于 tasks.config.json

4. Provider 详细信息

   • 前端 URL（例如，https://your-provider.launchpad.io）
   • Isolation ID（可在 Provider 设置中找到）

何时构建自定义 UX

只要现成的 Constellation 组件和模板符合业务和 UX 要求，就应优先使用。在决定构建新的自定义组件之前，Astro 应明确提醒用户：

1. 先查看 UX Boosters 目录

   • 访问预构建 Launchpad 自定义 UX 组件的公共目录：**https://launchpad.io/ux-boosters**。
   • 确认是否已有符合需求且可一键安装到 Provider 的组件。

2. 确认 Constellation / Launchpad 是否已提供现成功能

   • 验证所需模式是否已作为标准 Constellation 视图、区域模板或字段 / 小部件配置提供。
   • 如果有现成选项，Astro 应建议使用该选项，而不是创建新的自定义组件。

只有在完成这些检查后，才考虑自定义 UX：

• 业务需要一种现成方案不支持的可视化或交互模式（例如，专用图表、地图、日程安排器或复合布局）。
• 必须在 Launchpad 体验中嵌入外部小部件或库（例如第三方地图、图表或文档查看器）。
• 需要一种适用于多种案例类型或多个门户的可复用 UX 模式，且无法使用现有 Constellation 构建模块清晰建模。
• 希望通过定制视图提升特定用户角色的工作效率或信息清晰度，实现标准表单和列表模式无法满足的需求。

决定采用自定义 UX 之前，请确认：

• 所需行为无法通过标准 Constellation 视图、区域模板和现成组件（包括可安装的 UX Boosters）建模。
• 自定义体验仍能遵循 Launchpad 的导航、无障碍和响应式规范。
• 长期维护成本（更新、安全性、库升级）在可接受范围内。

构建自定义 UX 组件前的准备工作

要成功设计并实现自定义 UX 组件，请先收集以下信息：

1. 用户和用例定义

   • 谁会使用该组件（用户画像、角色、渠道）？
   • 组件会出现在哪个门户或页面中？
   • 它应帮助用户更快或更准确地完成哪项任务或决策？

2. 数据和 API

   • 组件需要哪些Launchpad 数据（案例、数据对象、数据页）？
   • 哪些 DX API 或 Data View 端点会提供数据？
   • 组件必须向 Launchpad 传回哪些输入属性（筛选条件、选择项、操作）？

3. 交互和行为

   • 主要的用户操作有哪些（仅查看、选择、拖放、行内编辑、打开详情等）？
   • 组件应如何响应状态变化（加载、错误、空状态、成功）？
   • UX 中是否必须强制执行任何业务规则（选择数量限制、必经步骤、验证消息）？

4. 视觉和布局设计

   • 展示布局、层级和关键状态的草图或线框图。
   • 遵循 Constellation 设计令牌（颜色、字体、间距）和布局模式。
   • 响应式行为规范（桌面、平板、手机断点）。

5. 技术限制和库

   • 所需的任何外部库或 SDK（地图、图表、文档查看器）及其许可 / 安全影响。
   • 性能或安全注意事项（大型数据集、PII、外部调用）。

预先记录这些输入有助于确保自定义 UX 组件：

• 以真实用户需求为基础；
• 符合 Launchpad 和 Constellation 的设计规则；并且
• 具备可实现性和可维护性。

自定义 UX 如何融入 Launchpad 和 DX

自定义 UX 组件应与 Launchpad 的 DX 方法顺畅集成：

• 将 DX API 和 Data Views 作为主要数据访问层，而不是直接在浏览器中调用后端系统。
• 将组件视为仅包含 UI 逻辑：复杂的业务规则和决策应尽可能保留在服务器端。
• 遵循 Launchpad 的安全和访问控制模型；不要绕过身份验证或授权检查。
• 遵循 Constellation 的导航模型（例如打开案例、分配项和对话框的方式），以保持体验一致。

DXCB – 自定义 UX 组件框架

DXCB（Digital Experience Component Builder） 是用于构建兼容 Constellation 的自定义组件的框架和工具集。它提供了一种标准方式来：

• 将前端代码（通常基于 React）组织为 Constellation 扩展。
• 将组件绑定到来自 DX API 和 Data Views 的 Launchpad 数据和上下文。
• 打包并注册组件，使其作为可复用的构建模块出现在 Launchpad 门户和视图中。

使用 DXCB 可确保自定义组件：

• 遵循 Constellation 的设计系统（布局网格、字体、间距、颜色）。
• 正确集成 Launchpad 的案例上下文、路由和刷新模型。
• 更易于升级，因为它们遵循已知的扩展模式，而不是临时编写的自定义代码。

开始使用 DXCB 项目

总体而言，使用 DXCB 构建 Launchpad 自定义组件包括以下步骤：

1. 初始化 DXCB 项目
   在终端中，进入要创建 DXCB 项目的文件夹：

   npx @pega/custom-dx-components@~25.1 init
   

   重要提示：请务必查看 Pega 官方文档，确认当前推荐的版本（参见本技能末尾的Pega 官方文档部分）。

   • 根据提示输入项目名称、组织、版本和描述。
   • 组织/库名称应保持相对简短，以便为有意义的组件名称留出空间。

2. 配置 tasks.config.json
   初始化后，DXCB 会创建一个 tasks.config.json 文件。使用 Launchpad Provider 的详细信息配置 server-config 部分（参见前提条件）：

   • server – Provider 前端 URL
   • clientId 和 clientSecret – OAuth 凭据
   • isolationID – Provider 隔离 ID

   凭据属于敏感信息，请遵循组织内部的安全规范。

3. 创建组件文件夹
   在 components 目录中（例如，src/components）：

   • 为每个组件创建一个文件夹（例如，range-slider-template）。
   • 添加：
     • 一个用于定义组件类型、子类型和配置的 config.json。
     • 一个 React 实现文件（例如，index.tsx），使用 getPConnect()，并在需要时使用全局 PCore。

选择合适的组件类型

DXCB 支持三种主要的 Constellation 组件：

• 布局模板 ——视图的整体布局（DETAILS、FORM、PAGE）。
• Widget ——用于仪表板和 Utilities 的独立面板／卡片（PAGE、CASE 或 PAGE & CASE）。
• 字段组件 ——具有字段子类型（Integer、Text、Decimal 等）的单字段控件。

如果不确定，请从 Constellation UX 模式的角度考虑：

• 案件详情区域和摘要卡片

  • 模式：案件或数据视图的 Details 区域中的 KPI、摘要面板。
  • DXCB：subtype: "DETAILS" 的 模板。
  • 示例：examples/dxcb-examples/range-slider-template/ 中的 Range Slider Template，通过 getPConnect().getActionsApi().updateFieldValue(...) 将最小值／最大值写回案件字段。

• 仪表板和登录页磁贴

  • 模式：门户登录页上的磁贴和洞察面板。
  • DXCB：subtype: "PAGE" 的 Widget（如果要在 Utilities 中复用，则使用 ["PAGE", "CASE"]）。
  • 示例：examples/dxcb-examples/calendar-widget/ 中的 Calendar Widget，显示来自 Constellation 数据页的近期工作项，并使用 PCore + getPConnect() 进行导航和预览。

• 案件视图中的 Utilities 窗格辅助工具

  • 模式：案件 Utilities 窗格中的上下文面板（洞察、时间线、相关工作）。
  • DXCB：subtype: "CASE" 的 Widget。

• 自定义字段控件

  • 模式：具有专用可视化效果的单个输入控件（评分、胶囊式选择、自定义滑块）。
  • DXCB：具有相应字段子类型的 Field（例如 "Integer"、"Text"、"Decimal"）。
  • 示例：examples/dxcb-examples/star-rating-input/ 中的 Star Rating Field，可写入整数分数并遵循 Constellation 字段行为。

选择正确的类型和子类型可确保：

• Launchpad Studio 作者能在正确的上下文中找到你的组件。
• DXCB 会生成合适的起始实现。
• 组件会显示在预期位置（Widget 选择器、布局模板或字段的 Display-as 选项）。

从 DXCB 项目到 Launchpad Studio

在 DXCB 项目中实现组件后：

1. 构建组件
   从 DXCB 项目的根目录运行 DXCB 构建脚本，例如：

   npm run buildComponent
   

2. 针对目标 Provider 进行身份验证
   使用 DXCB 身份验证脚本（例如 npm run Authenticate），让 DXCB 使用 tasks.config.json 中的 server-config 值向 Launchpad Provider 发布。

3. 发布组件
   运行发布脚本（例如 npm run publish），在 Provider 中注册组件。

成功发布后，组件会在 Launchpad Studio 中显示为：

• Widget，显示在 Widget 选择器中（Portal 或 Case / Utilities，具体取决于 type 和 subtype）。
• Template，显示在视图布局选择器中（Details、Form、Page）。
• Field，显示在匹配类型字段的 Display as 选项中。

Astro 应如何收集新组件的需求

当开发者要求 Astro 构建一个新的自定义组件时，Agent 应：

1. 找出最接近的示例

   • 浏览 Launchpad 参考仓库：https://github.com/pegasystems/constellation-ui-gallery/tree/next/src/components
   • 选择 config.json 类型和子类型（Field / Widget / Template）以及整体行为最符合需求的组件。

2. 使用 config.json.properties 作为问题清单

   • 将所选示例 config.json 中的 properties 数组视为必须填写的视图元数据。
   • 针对每个相关属性，向开发者提出有针对性的问题，例如：
     • 对于 Field 组件：
       • PROPERTY 字段（例如，inputProperty、minValueProperty、maxValueProperty）：
         • “此组件应读取和更新哪个案例/数据属性？”
       • LABEL / 辅助文本字段（例如，label、helperText）：
         • “用户应在此控件上看到什么标签和辅助文本？”
       • SELECT 选项（例如，format、maxRating）：
         • “你更倾向于 [property name] 使用哪个选项？（列出 source 中的有效值。）”
     • 对于 Widget 组件：
       • 数据源字段（例如，dataPage）：
         • “此 Widget 应使用哪个数据页？”
       • 上下文/筛选字段（例如，contextProperty、setCaseID）：
         • “Widget 是否应按当前案例筛选？如果是，哪个属性承载上下文？”
       • 特定布局字段（例如，groups、groupProperty）：
         • “哪些状态或分组应显示为列？哪个属性用于分组？”
     • 对于 Template 组件：
       • 区域配置（例如，A 区域）：
         • “哪些视图或字段应放置在区域 A 中？”
       • 数值范围（例如，min、max、step）：
         • “此控件所需的数值范围和增量是多少？”

3. 在生成代码前确认并总结

   • 将收集到的答案总结为配置快照（将使用哪些属性、数据源、标签、范围等）。
   • 仅在此之后生成：
     • 使用这些值配置的 config.json，以及
     • 一个 index.tsx 实现，该实现：
       • 使用 getPConnect().getRawMetadata().config 读取这些值，并且
       • 遵循 references/PCore-PConnect-APIs.md 中的 PConnect / PCore 模式。

实现参考 – PConnect 和 PCore

构建 DXCB 组件时，如需更深入的代码级指导，请使用此技能文件夹中的整合参考：

• references/PCore-PConnect-APIs.md – 介绍如何在 Launchpad 自定义组件中使用每个组件的 PConnect API（getPConnect()）和全局 PCore API（数据页、事件、发布/订阅、语义 URL）。

此 SKILL.md 专注于自定义组件的设计时机和方式，以及 DXCB 如何融入 Launchpad。references/ 文档则介绍详细的实现模式。

Launchpad 组件参考仓库

重要：对于 Launchpad，请使用 Constellation UI Gallery 仓库的 next 分支作为组件模式和示例的参考：

https://github.com/pegasystems/constellation-ui-gallery/tree/next/src/components

请勿使用 master 分支或特定于 Infinity 的仓库，因为其中可能包含不适用于 Launchpad 的模式。

生成新的自定义组件时，Agent 应：

• 首先浏览 https://github.com/pegasystems/constellation-ui-gallery/tree/next/src/components 中的组件，寻找类似模式。
• 克隆并改造符合所需模式（模板、小部件或字段）的现有组件，而不是从头开始。
• 遵循该仓库中的文件夹结构、命名约定和实现模式。

该仓库中提供的组件模式示例：

• Pega_Extensions_BarCode – 条形码显示／输入组件。
• Pega_Extensions_Calendar – 日历／日程安排小部件。
• Pega_Extensions_IframeWrapper – 用于在 iframe 中嵌入外部内容的包装器。
• Pega_Extensions_KanbanBoard – 用于工作项的看板式面板。
• Pega_Extensions_Meter – 仪表／量表可视化组件。
• Pega_Extensions_QRCode – 二维码显示／输入组件。
• Pega_Extensions_RangeSlider – 用于数值范围的范围滑块模板。
• Pega_Extensions_RatingLayout – 用于案例摘要的评分布局模板。
• Pega_Extensions_SignatureCapture – 签名采集字段组件。
• Pega_Extensions_StarRatingInput – 星级评分输入字段。
• Pega_Extensions_UtilityList – 用于案例／门户上下文的实用列表小部件。

Field 组件的编码模式（例如，密码输入框）

生成新的 Field 组件（例如密码输入框、文本输入框或类似的单值控件）时，Astro 应当：

• 克隆参考仓库中现有 Field 组件的模式（例如 Pega_Extensions_StarRatingInput），而不是自行设计新结构。
  • 定义一个命名组件，例如 PegaExtensionsPasswordInput。
  • 使用来自 @pega/cosmos-react-core 的 withConfiguration，通过 export default withConfiguration(PegaExtensionsPasswordInput); 将其导出为默认导出。
• 使用 Cosmos Field 组件，而不是原始 HTML 输入元素：
  • 对于可编辑的文本/密码类输入，应渲染来自 @pega/cosmos-react-core 的 Input 组件，而不是 <input>/<label> HTML 元素。
  • 对于仅显示模式，应使用带掩码值的 Text 组件（例如，密码显示为 '***********'），而不是可编辑字段。
• 使 props 与 Constellation 运行时和 config.json 保持一致：
  • 接受如下 props：getPConnect、label、value、helperText、validatemessage、hideLabel、displayMode、hasSuggestions、fieldMetadata、additionalProps、testId、disabled、readOnly、required。
  • 规范化可能以字符串形式传入的布尔 props（例如，将 true 和 'true' 都视为 true）。
  • 使用 fieldMetadata（例如 fieldMetadata.maxLength）为 Input 设置 maxLength 等限制。
• 使用 PConnect Actions API 和状态映射进行数据绑定：
  • 从 getPConnect() 获取 PConnect 实例，并由此得出：
    • const actions = pConn.getActionsApi();
    • const propName = pConn.getStateProps().value;（作为该字段数据来源的 case 字段名）。
  • 值发生变化时，仅在值确实改变的情况下，使用 actions.updateFieldValue(propName, newValue) 更新 case 字段。
  • 失去焦点时，使用 actions.triggerFieldChange(propName, newValue) 触发验证并处理建议；在适用情况下，还要调用 pConn.ignoreSuggestion()。
• 遵循 Constellation 的显示模式和状态：
  • 如果 displayMode === 'DISPLAY_ONLY'，则不要渲染可编辑输入框；应返回不可编辑的表示形式（对于密码，使用带掩码的 Text 值）。
  • 使用 validatemessage、hasSuggestions 等 props 设置 Cosmos Input 的 status（'error'、'pending' 等），并遵循现有 Pega_Extensions_* Field 组件的模式。

首选前端包

为 Launchpad Custom UX 生成或调整 React 组件时，Agent 应遵循以下优先级顺序：

1. 首先，检查 @pega/cosmos-react-core（https://www.npmjs.com/package/@pega/cosmos-react-core）中是否有符合要求的现有组件。常见组件包括：`Input`、`Button`、`Text`、`Flex`、`Grid`、`Card`、`Badge`、`Icon`、`FormField`、`Select`、`Checkbox`、`DatePicker`、`Modal`、`Table`、`Tabs` 等。应直接使用这些组件，而不是自行实现。

2. 其次，如果没有单个组件符合要求，则组合使用多个 Cosmos 组件。从 @pega/cosmos-react-core 组合布局、表单和显示组件。

3. 最后，只有在没有现成 Cosmos 组件或组合能够满足要求时，才创建自定义组件。

• 检查参考仓库中现有组件的 import 语句，并在新代码中复用这些包和组件。
• 确保将任何导入的包添加到目标项目的 package.json 依赖项中。

有关首选包的详细列表和完整优先级指南，请参阅 references/frontend-packages.md。

仓库约定和文件结构

创建 DXCB 组件时，请遵循以下命名和结构约定，以确保一致性并便于发现：

文件夹和文件命名

• 组件文件夹：使用 Pega_Extensions_<Name> 格式（例如，Pega_Extensions_StarRatingInput、Pega_Extensions_Calendar）。
• 文件夹名称必须与 config.json 中的 name 和 componentKey 值一致。
• 每个组件的标准文件：

文件	用途	必需
index.tsx	React 主组件实现	✅ 是
config.json	DX 组件元数据（类型、子类型、属性）	✅ 是
Docs.mdx	Storybook/组件库文档	✅ 是
demo.stories.tsx	用于预览组件的 Storybook 故事	✅ 是
demo.test.tsx	Jest 单元测试	✅ 是
styles.ts	Styled-components / CSS-in-JS	可选
localizations.json	i18n 字符串	可选

组件实现约定

• React 导入：始终在文件顶部包含 React 默认导入。这可确保 JSX 在 DXCB TypeScript 配置下正常工作：

  import React, { useState, useEffect, useCallback } from 'react';
  

  重要：不要在没有 React 默认导入的情况下使用 import { useState } from 'react'。DXCB 项目的 tsconfig 使用 "jsx": "react"，这要求 JSX 转换时 React 处于作用域内。

• 使用 withConfiguration 导出：始终使用 @pega/cosmos-react-core 中的 withConfiguration 包装组件：

  import React from 'react';
  import { withConfiguration } from '@pega/cosmos-react-core';
  
  const PegaExtensionsMyComponent = (props) => { /* ... */ };
  
  export default withConfiguration(PegaExtensionsMyComponent);
  

• TypeScript React 模式：使用 TypeScript 函数组件。

• getPConnect 类型：除非仓库中已有更强的共享类型，否则组件属性使用 getPConnect?: any。避免创建重复的一次性 PegaConnect、PegaActionsApi 或 PegaStateProps 接口。

• 字段样式组件：

  • 将 hideLabel 保留为公开属性名。
  • 仅在内部传递 labelHidden={hideLabel} 给 Cosmos 控件。
  • 将 disabled、readOnly 和 required 声明为布尔类型，但使用共享模式将运行时字符串 'true' 强制转换为布尔值：

    const [readOnlyBool, requiredBool, disabledBool] = [readOnly, required, disabled].map(
      (v) => v === true || v === 'true'
    );
    

config.json 结构

确保 config.json 遵循以下结构：

{
  "name": "Pega_Extensions_MyComponent",
  "componentKey": "Pega_Extensions_MyComponent",
  "label": "My Custom Component",
  "description": "A custom component for...",
  "type": "Field",
  "subtype": "Text",
  "properties": [
    {
      "name": "label",
      "label": "Label",
      "format": "TEXT"
    },
    {
      "name": "value",
      "label": "Value",
      "format": "PROPERTY"
    }
  ]
}

Storybook 约定

创建组件的 demo.stories.tsx 时：

• 对于取值受限的属性，使用 select 控件，而不是自由文本输入。
• 为 testId、hideLabel、disabled、readOnly、required 等常用属性设置合理的默认值。
• 如有需要，在 Docs.mdx 中记录其他故事。
• 仅在故事正常渲染所需的范围内模拟 PConnect/PCore。

验证与测试

在确认组件完成之前，请执行以下验证步骤以确保质量：

代码检查

运行代码检查工具，以发现代码风格问题和潜在错误：

npm run lint

自动修复问题：

npm run fix

构建验证

发布前，请验证组件能否正确构建：

npm run buildComponent

组件交付检查清单

在完成组件实现前，请使用此检查清单：

• 文件夹名称遵循 Pega_Extensions_<Name> 约定
• config.json 中的 name 和 componentKey 与文件夹名称一致
• index.tsx 导出经过类型定义且由 withConfiguration 包装的组件
• 字段样式组件将 hideLabel（而非 labelHidden）用作公开属性
• 布尔属性（disabled、readOnly、required）能够处理字符串 'true' 值
• getPConnect 遵循仓库约定（getPConnect?: any）
• 已根据仓库示例或官方文档验证 PConnect/PCore 的用法
• Docs.mdx 说明了组件，且与实际属性一致
• demo.stories.tsx 使用恰当的模拟数据进行渲染
• Storybook 控件对受限属性使用 select
• 已在 Docs.mdx 的 ## Examples 下记录其他故事
• demo.test.tsx 覆盖关键渲染、行为和边缘情况
• 仅在确有必要时才创建 styles.ts 和 localizations.json
• 如果组件必须显示在图库中，则已更新相关的源注册文件
• npm run lint 通过（或明确报告问题）
• 相关测试已通过 npm run test
• 已明确记录任何跳过的验证步骤

防护准则

构建自定义组件时，请遵循以下规则，避免常见问题：

• 不要臆造 DX 组件元数据。 参照仓库现有组件的结构和命名模式。
• 除非明确要求，否则不要手动编辑生成的包或发布产物。
• 如果仓库已有合适的选项，不要为了方便而添加包依赖。 请先检查现有的 package.json。
• 不要让组件处于未完成状态。 如果请求意味着要交付可用组件，请完成实现并提供所有必需文件。
• 不要绕过 Constellation 模式。 使用 Cosmos 组件而非原始 HTML；遵循主题、无障碍和响应式行为要求。
• 不要跳过验证。 始终运行 npm run lint 和相关测试，或明确说明跳过验证的原因。

Pega 官方文档

如需获取最新指南，请参阅以下 Pega 官方资源：

主题	文档链接
使用 DX 组件扩展 Launchpad	https://docs.pega.com/bundle/launchpad/page/platform/launchpad/extend-applications-constellation-dx-components.html
在 Launchpad 中使用 DX 组件	https://docs.pega.com/bundle/launchpad/page/platform/launchpad/working-constellation-dx-component-launchpad.html
初始化 DXCB 项目	https://docs.pega.com/bundle/constellation-dx-components/page/constellation-dx-components/custom-components/initialize-project.html
Constellation DX 组件概述	https://docs.pega.com/bundle/constellation-dx-components/page/constellation-dx-components/custom-components/custom-components.html
Launchpad 与 Infinity 的差异	https://docs.pega.com/bundle/launchpad/page/platform/launchpad/differences-constellation-dx-components-launchpad-infinity.html