项列表
定义和用法
“项列表”组件是一个小组件，用于将数据集中的项列表显示为单级列表或结构树。最终用户可通过“项列表”小组件对整个列表或特定列表项执行操作。当数据以单级列表显示时，最终用户还可通过项列表搜索、排序和筛选列表。
 |
在 Windchill Navigate 9.3 及更早版本中，“项列表”组件为内置混搭。现在，“项列表”可用作小组件，而“项列表”混搭已被弃用。建议使用“项列表”小组件，而不使用已弃用的混搭。
|
下面的两个示例图示为“项列表”组件：
可通过以下方式配置“项列表”组件：
• 启用或禁用搜索和筛选 (仅限单级列表)
• 设置初始筛选和排序选项 (仅限单级列表)
• 设置网格中的最大行数
• 定义是否可以从此列表中选择项，如果可从此列表中选择项，那么是否可以选择一个或多个项
• 设置初始展开层级 (仅限结构树)
• 选取是否显示“导出”操作并允许用户选择导出的文件格式
• 选取是导出所有数据，还是仅导出与筛选条件匹配的数据
• 配置嵌入式操作栏中提供的操作
用户可以使用筛选框或搜索框来筛选或搜索项列表。但是，如果配置中未启用筛选框和搜索框，筛选和搜索功能将不可用。可以单击列标题，按此列对列表进行排序。要反转排序顺序，请再次单击列标题。
“项列表”组件包含嵌入式“操作栏”组件。通过配置操作栏，可以启用其他功能，例如对一个或多个列表项执行操作。有关详情，请参阅操作栏 (测试版)。默认情况下，项列表包含“导出”操作，可以将项列表导出为 CSV 文件。
项列表还包括“恢复默认值”按钮。“恢复默认值”按钮恢复筛选、搜索和网格级别操作的默认设置，包括排序、交换以及显示/隐藏列。
单级列表与结构树
如前所述，项列表支持单级列表和结构树。项列表在用户界面中显示为单级列表还是结构树，具体取决于 GetItems 服务的输入的格式设置。有关详情，请参阅下面的 GetItems 服务。
如果项列表为结构树，不支持搜索、排序和筛选，即使使用以下配置特性对其进行配置也是如此。
如果项列表为单级列表，默认展开层级不适用。
绑定特性
输入 | ||||
|---|---|---|---|---|
特性名称 | 说明 | 特性类型 | ||
input | 用于标识要从后端系统中获取的数据。 需要输入时，请将 waitForInput 配置特性设置为 true。 JSON 示例： { "version":"1.0.0", "data":[ { "adapter":{ "instanceName":"windchill", "thingName":"PTC.WCAdapter" }, "itemListsData":[ { "items":[ { "id":{ "value":"OR:wt.workflow.work.WorkItem:1432583" } } ], "objectType":"PTC.Workflow.WorkItem" } ] } ] } | CCO 格式的 JSON | ||
selectedItems | 用于标识和选择网格项及其属性作为输入。可以将其他组件的 output 绑定特性绑定到此特性。 JSON 示例： { "data":[ { "itemListsData":[ { "items":[ { "workItem":{ "value":"OR:wt.workflow.work.WorkItem:143921" } }, { "workItem":{ "value":"OR:wt.workflow.work.WorkItem:143928" } } ], "objectType":"PTC.Workflow.WorkItem" } ], "adapter":{ "instanceName":"windchill", "thingName":"PTC.WCAdapter" } } ], "version":"1.0.0", "statusMessage":"OK", "status":"200" }
| CCO 格式的 JSON | ||
tailoringName | 用于唯一标识“项列表”组件的实例。此值在内部使用，可供查找此特定实例的定制信息。 只有在自定义任务存在专用的定制页面时，才使用此绑定特性。 | |||
输出 | ||||
|---|---|---|---|---|
特性名称 | 说明 | 特性类型 | ||
totalItemsNumber | 与搜索和筛选条件匹配的列表项数。
| 整数 | ||
selectedItems | 用于标识选定的网格项及其属性。此特性可绑定到其他组件的 input 绑定特性。 JSON 示例： { "data":[ { "itemListsData":[ { "items":[ { "workItem":{ "value":"OR:wt.workflow.work.WorkItem:143921" } }, { "workItem":{ "value":"OR:wt.workflow.work.WorkItem:143928" } } ], "objectType":"PTC.Workflow.WorkItem" } ], "adapter":{ "instanceName":"windchill", "thingName":"PTC.WCAdapter" } } ], "version":"1.0.0", "statusMessage":"OK", "status":"200" } | CCO 格式的 JSON | ||
配置特性
以下表格和图像显示用于配置此组件的 JSON 字段。
有关详情，请参阅组件配置结构。
有关子特性的详情，请参阅子特性和容器键。
特性名称 | 说明 | 特性类型 | 默认值 | 必需或可选 | |||
|---|---|---|---|---|---|---|---|
actionBarConfiguration | 嵌入式操作栏的配置。有关详情，请参阅操作栏 (测试版)。 | 不适用 | 可选 | ||||
attributes | 要显示的属性。这些属性在网格中显示为列标题。 有关在属性列中包括操作的信息，请参阅此表格下方的注解。
| 不适用 | 必需 | ||||
defaultWidth | 可用于设置属性列的默认宽度。 选项：Auto、Custom • Auto：当 defaultWidth 为空或设置为 Auto 时，列的宽度相等。 示例： "defaultWidth": { "selectedKey": "Auto" } • Custom：当 defaultWidth 设置为 Custom 时，列具有基于定义值的自定义宽度。 示例： "defaultWidth": { "selectedKey": "Custom", "additionalData": { "width": { "value": "600" } } } | 不适用 | 可选 | ||||
fieldTitleOverride | 字段标签，该字段用于改写列标题值。 • 如果 fieldTitleOverride 为空，列标题值是从元数据中提取的属性的显示名称 (标签)。 • 如果 fieldTitleOverride 以及元数据中的显示名称均为空，列标题值为空。 | 不适用 | 可选 | ||||
hidden | 不适用 | 可选 | |||||
defaultExpansionLevel | 定义结构树的初始展开层级。接受数字 1-9 以及 -1 作为输入。当特性设置为 -1 时，结构树最初会完全展开，并显示所有层级。
| 3 | 可选 | ||||
defaultSelectedFilterValue | 初始选定值或作为筛选依据的值。如果此特性的值为空，没有默认筛选。 此特性为 filterFields 的子特性，只有在配置中包含 filterFields 时，此特性才相关。其容器键为 itemListFilterFieldDefinition。
| 不适用 | 可选 | ||||
defaultSortDirection | 默认排序的方向。选项：asc (表示升序) 和 dsc (表示降序)。如果此特性的值为空，排序方向为升序。 此特性为 defaultSortField 的子特性，只有在配置中包含 defaultSortField 时，此特性才相关。其容器键为 itemListDefaultSortFieldDefinition。
| asc | 可选 | ||||
defaultSortField | 要按其进行排序的初始列。如果此特性的值为空，项列表按第一列进行排序。
| 不适用 | 可选 | ||||
enableSearch | 是否显示搜索字段。选项：true 和 false。
| true | 可选 | ||||
exportUnFilteredData | 将项列表数据导出到文件时，是包含所有数据，还是仅包含筛选的数据。选项：true 和 false。 如果此特性设置为 true，导出的文件会包含所有数据 (无论筛选与否)。 如果此特性设置为 false，导出的文件中仅包含筛选的数据。 由于 maxNumberOfRowsInGrid 特性限制而在项列表网格中不可见的数据仍包括在导出的文件中。 此特性为 showExportAction 的子特性，只有在配置中包含 showExportAction 时，此特性才相关。其容器键为 itemListExportDefinition。 | false | 可选 | ||||
exportTypes | 可用的导出类型。选项：exportToCsv 和 exportToExcel。可以包括其中一个或两个选项。 如果包括 exportToCsv，“导出”按钮以标准格式将数据导出为 CSV 文件。 如果包括 exportToExcel，“导出”按钮将针对 Excel 格式化的数据导出为 CSV 文件。 如果仅包括一个选项，“导出”按钮会自动以选定格式 (标准 CSV 或 Excel 格式的 CSV) 导出数据。如果同时包括这两个选项，“导出”按钮将显示为菜单按钮，允许用户选择所需的导出格式。 此特性为 showExportAction 的子特性，只有在配置中包含 showExportAction 时，此特性才相关。其容器键为 itemListExportDefinition。 | exportToCsv, exportToExcel | 可选 | ||||
filterFields | 后端系统中用于筛选数据的字段的 ID。如果此特性的值为空，没有可用于筛选数据的选项。
| 不适用 | 可选 | ||||
filterLabelOverride | 筛选器标签，该筛选器用于改写从 GetItems 服务返回的显示值。 此特性为 filterFields 的子特性，只有在配置中包含 filterFields 时，此特性才相关。其容器键为 itemListFilterFieldDefinition。 | 不适用 | 可选 | ||||
implementationConfigurations | 应用程序构建器的入口点，用于传递其实现过程中所需的其他值，以便进一步自定义此组件。 | 不适用 | 可选 | ||||
label | 项列表的标题。 | [[PTC.ItemList]] | 可选 | ||||
maxNumberOfRowsInGrid | 要在网格区域中显示的最大行数。建议输入一个小于 10000 的值。
| 500 | 可选 | ||||
searchHintText | 在搜索框中显示的提示文本。 此特性为 enableSearch 的子特性，只有在 enableSearch 设置为 true 时，此特性才相关。其容器键为 itemListSearchDefinition。 | Find Item | 可选 | ||||
selectionType | 用于控制：一次可在网格中选择的项数。选项： • none - 不能选择网格项 • single - 一次只能选择一个网格项 • multi - 一次可以选择一个或多个网格项 | multi | 可选 | ||||
showExportAction | 启用或禁用导出操作。选项：true 和 false。 | true | 可选 | ||||
showImplementationActions | 指定要包括在嵌入式操作栏中的其他操作，例如“设计文件”、“绘图”和“附件”预定义配置中的“全部下载”按钮。 | 不适用 | 可选 | ||||
waitForInput | 在触发对填充网格的项的检索之前，是否在运行时等待值传递到项列表的输入混搭参数。选项：true 和 false。 | false | 可选 | ||||
| | 如果包含的属性具有 HTML 值，且这些值在属性列中显示菜单按钮，该操作必须处在 PTCNav 键下方。示例： { "label":"", "icon":"", "PTCNav":{ "Action":{ "type":"openUrl", "data":{ "url":"http://www.linkTofile.pdf" } } } } |
示例配置
自定义服务
除了配置外，每个组件还支持通过扩展其业务逻辑来自定义组件。每个组件的业务逻辑在事物模板中都包含可改写的服务，您可以对这些服务进行扩展和改写。下表对此组件的可改写服务进行了详细说明。
有关各个服务的返回值和参数的示例，请参阅自定义服务的输入/输出示例。
| | 将 CCO 格式的 JSON 对象从业务逻辑实现组件返回到“项列表”组件时，仅包含单一对象类型的属性。当前，项列表不支持包括不同对象类型的属性。 |
名称 | 说明 |
|---|---|
ComputeMessages | 计算要显示在用户界面中项列表网格上方的所需消息。该属性会接收当前消息 JSON 和建议的消息 JSON，并返回通知消息 JSON，其中包含要在项列表中显示的消息。 参数： currentMessages (必需) - JSON 对象，其中包含显示在用户界面中的当前通知消息。 suggestedMessages (必需) - JSON 对象，其中包含一系列建议的消息。推荐使用建议的消息。 input (可选) - CCO 格式的 JSON，其中包含位于结构根节点处的项的输入 ID。 configuration (可选) - 包含配置的 JSON。 scope (可选) - 用于指示 getItemsResponse 中数据范围的 JSON。JSON 对象中包含的 scope 键可接受值 root 和 child。适用于层次结构数据。示例： { "scope": "root" } 返回：JSON 对象，其中包含要显示在项列表网格中的消息。示例： "INFO":{ { "messages":[ "[[PTC.Nav.ItemList.HiddenItemsBecauseAccessRightMessage]]" ] } } |
DefHookGetImplementationActionsList | 返回 GetImplementationSettings 服务中的 implementationActions 键下方列出的操作。 参数：无 返回：JSON:Array |
DefHookImplementationAttributesDefinition | 返回选定属性的实现特定定义。 参数：无 返回：JSON:Array |
DefHookImplementationConfigurationDefinitionGroup | 返回实现特定定义，其中包含实现的自定义配置。 参数：无 返回：JSON:Array |
DefHookMaxRowsProperties | 返回要在网格区域中显示的最大行数的特性。 参数：无 返回：JSON |
GetChildren | 接收项并返回 CCO 格式的 JSON，其中包含该项的子项，即层次数据结构中比该项低一级的所有项。返回的 JSON 将以单级列表形式而非层次结构数据形式包含子项。 只要用户展开未加载子项的项列表中的项，即会调用此服务。 此服务的默认实现假定已针对项到输入数据的转换实现 MapItemToInputObject 服务 (如果需要)。 参数： input (可选) - CCO 格式的 JSON，其中包含位于结构根节点处的项的输入 ID。 configuration (必需) - 包含配置的 JSON。 item (必需) - JSON，其中包含要返回子项的父项。 返回：CCO 格式的 JSON |
GetConfigurations | 返回组件实现的可用配置。 参数：无 返回：JSON |
GetImplementationLabel | 返回此组件的本地化名称，或返回可用于获取此本地化名称的标记。此本地化名称显示在 Mashup Builder 用户界面中。 参数：无 返回：字符串 |
GetImplementationSettings | 返回实现的设置数据。实现可通过改写此服务来提供其自己的设置。有关详情，请参阅有关项列表的 GetImplementationSettings 服务的其他信息 主题。 此服务支持包含以下键：itemIdentifierKeys、itemExpansionKeys、hasChildrenKeys、overrideItemsDataForExport 和 implementationActions。 参数：无 返回：JSON 对象 |
GetItems | 返回后端系统中的项列表。 要创建项列表的自定义实现，请改写此服务以检索自定义数据。 参数： input (可选) - CCO 格式的 JSON，其中包含要从后端系统获取的数据的输入 ID，以及后端系统的适配器信息。 使用此参数时，请确保将 waitForInput 配置特性设置为 true。 configuration (可选) - 包含配置的 JSON。 返回：CCO 格式的 JSON |
GetItemsByExpansionPath | 返回的层次结构 CCO 中包含路径上从根节点到所请求项的所有项，包括所有请求属性 itemIdentifierKeys 和 itemExpansionKeys，如 GetImplementationSettings 服务中所定义。层次结构 CCO 包括路径上的所有同级。 当 selectedItems 绑定特性接收到用来指定未加载项的输入时，将调用该服务。 参数： input (可选) - CCO 格式的 JSON，其中包含位于结构根节点处的项的输入 ID。 configuration (必需) - 包含配置的 JSON。 itemExpansionValues (必需) - JSON 数组，其中包含请求展开的项的 itemExpansionKeys。数组值根据树中的路径进行排序，从根项开始。 返回：CCO 格式的 JSON |
GetItemsForExport | 处理 CCO 格式的配置 JSON 和输入 JSON，并返回 CCO 格式的 JSON，其中包含导出所需的所有项。默认情况下，此服务会返回一个空 CCO，但实现可以通过改写此服务来返回要导出的项。在这种情况下，要导出的数据即此服务返回的项。 当 selectedItems 绑定特性接收到用来指定未加载项的输入时，将使用此服务的结果。 参数： input (可选) - CCO 格式的 JSON，其中包含要从后端系统获取的数据的输入 ID。 configuration (可选) - 包含配置的 JSON。 返回：CCO 格式的 JSON |
GetStructureSkeleton | 返回 CCO 格式的层次结构的所有层级，其中结构中的每个项均包含 itemIdentifierKeys 和 itemExpansionKeys，如 GetImplementationSettings 服务中所定义。 参数： input (可选) - CCO 格式的 JSON，其中包含位于结构根节点处的项的输入 ID。 configuration (可选) - 包含配置的 JSON。 返回：CCO 格式的 JSON |
InitializeFilters | 返回配置中每个筛选器字段的筛选器类型定义。 参数： input (可选) - CCO 格式的 JSON，其中包含要从后端系统获取的数据的输入 ID，以及后端系统的适配器信息。 configuration (可选) - 包含配置的 JSON。 返回：CCO 格式的 JSON |
MapItemToInputObject | 将项映射到输入，随后此输入可供 GetItems 服务使用。 默认实现将返回没有任何更改的项。如需进行任何更改，例如，更改项的对象类型，请改写此服务。此服务仅用于 GetChildren 服务的默认实现。 参数： input (可选) - CCO 格式的 JSON，其中包含位于结构根节点处的项的输入 ID。 item (必需) - JSON，其中包含要映射到输入的项。 |
PrepareDataForExport | 以信息表形式接收数据，并为导出做准备。默认实现将按原样返回数据，但实现也可以改写此服务，以便根据需要修改数据。 参数： configuration (必需) - 包含配置的 JSON。 dataInfoTable (必需) - 包含要导出的数据的信息表。 data (可选) - CCO 格式的 JSON 对象，其中包含要导出的数据。 gridQuery (可选) - 表示 QUERY 类型数据的 JSON 对象，其中包含项列表网格中的查询筛选器。 searchTerm (可选) - 用于在网格的每一行中进行搜索的字符串。 filterOptions (可选) - 包含筛选所依据的选项的信息表。 返回：信息表 |
实施定义