自定义项目组件

适用环境	SaaS
	私有部署

要求

ONES
v3.11.16+

概述

插件使用该能力可以向 ONES 的项目添加自定义组件，用户可以按照 ONES 的统一标准来使用——自定义组件在导航栏的顺序以及基础配置。

插件开发者可以自定义组件的内容

自定义组件的使用和其他的组件一致

自定义组件的特性

用户可以自定义组件的 UI 和功能；
支持用户配置组件名称、组件描述；
当承载有该能力的插件启用后，能力所定义的自定义组件会出现在每个项目的组件库，用户可以按照标品的统一标准来使用这些组件；
当承载有该能力的插件停用/卸载后，能力所定义的自定义组件以及用户使用这些组件创建的对象都会从项目删除；
允许开发者实现自定义组件的内容在不同项目间的复制功能；

自定义组件的场景

标品已有的组件无法满足的功能场景
用户自定义更加多元的项目配置需求场景

如果自定义组件需要考虑多语言的场景，请使用 插件多语言支持

警告

该能力必须和前端插槽ones:project:component:new搭配使用

用法

使用该能力需要添加后端能力插件承载project自定义组件和前端插槽ones:project:component:new，然后在代码中实现自己的自定义组件功能。

第一步：通过 OP 工具添加并使用能力

在插件根目录使用命令行输入 OP 命令添加能力（该指令需要 OP 工具版本 1.0 及以上）

npx op add ability

选中并添加project-custom-component@1.0.0, 根据提示, 填写关联插槽 ones:project:component:new 名称。

OP 工具会为插件添加如下内容

config/plugin.yaml中 abilities, modules 字段新增相关段落

service:
  app_id: ...
  name: ability-project-custom-component
  ...
  ...
modules:
  - id: ones-project-component-new-weUW
    title: customComponent1
    moduleType: ones:project:component:new
    entry: modules/ones-project-component-new-weUW/index.html
abilities:
  - id: ...
    name: project自定义组件
    version: 1.0.0
    abilityType: ProjectCustomComponent
    function:
      #插件数据复制方法名称
      copyPluginData: copyTest
    relateModule:
      #自定义组件入口
      componentModuleEnter: 'ones-project-component-new-weUW'
    config:
      - key: component_name
        label: 自定义组件名称
        value: 自定义组件
        fieldType: Input
        show: true
      - key: component_desc
        label: 自定义组件描述
        value: ''
        fieldType: TextArea
        show: true
        props:
          placeholder: 自定义组件描述，允许为空
      - key: is_support_copy
        label: 是否支持插件数据复制
        # 如果值设置为true,则需要完成copytest方法
        value: true
        fieldType: Switch
        show: false

web/src 下新增 ones-project-component-new-weUW 文件夹

backend/src目录下新增 project-custom-component.ts 文件，如果开发者想要实现自定义项目组件在多个项目间的数据复制功能，开发者可以在该文件中的copyTest方法中完成。

import { Logger } from '@ones-op/node-logger'
import type { PluginRequest, PluginResponse } from '@ones-op/node-types'

// 插件开发者如果要实现自定义组件的数据复制，需要在该方法内完成。
export const copyTest = async (request: PluginRequest): Promise<PluginResponse> => {
  Logger.info('copyTest  enter')
  const body = request?.body as any

  let srcProjectUUID = body.srcProjectUUID
  let dstProjectUUID = body.dstProjectUUID

  Logger.info(
    '[Plugin] copyTest',
    'url:',
    request.url,
    'srcProjectUUID:',
    srcProjectUUID,
    'dstProjectUUID:',
    dstProjectUUID,
  )

  return {
    body: {
      code: 200,
      body: {
        state: 0,
        message: 'success',
      },
    },
  }
}

新特性：标品数据映射

版本线	ONES
v6.1.x	v6.1.88+
v6.2.x	v6.2.22+

在copyPluginData方法入参中增加属性更完整地描述复制动作，并支持标品数据映射。修改后的request body如下：

{
  "srcProjectUUID": "源项目UUID",
  "dstProjectUUID": "目标项目UUID",
  "dstProjectOwner": "操作者用户UUID",
  "jobUUID": "复制任务UUID", // 用于获取标品数据映射文件
  "fileKeys": ["relation"] // 目前是固定值，用于获取标品数据映射文件
}

获取标品数据映射文件的方法如下：

const urlResponse = await OPFetch(
  `/team/${globalThis.onesEnv.teamUUID}/queue/${jobID}/file_download/url`,
  {
    params: {
      file_key: 'relation',
    },
  },
)
const fileResponse = await OPFetch(urlResponse.data.url, {
  responseType: 'text',
})

该文件中包含了复制项目过程中生成的全部实体UUID映射关系，文件格式为CSV，其中有两种类型的行：

类型标识：只有一列，类型标识以下的行都属于这种类型的映射关系，直到遇到下一个类型标识或文件结尾
映射关系：两列，第一列为源对象UUID，第二列为复制结果对象UUID

第二步：完成自定义组件的功能

第二步中，开发者需要根据自己的实际需求完成自己的自定义组件功能设计

组件设计

web/src/modules/ones-project-component-new-weUW/index.tsx

import React from 'react'
import ReactDOM from 'react-dom'
import { ConfigProvider } from '@ones-design/core'
import './index.css'

ReactDOM.render(
  <ConfigProvider>customComponent1</ConfigProvider>,
  document.getElementById('ones-mf-root')
)

web/src/modules/ones-project-component-new-weUW/index.css

#ones-mf-root {}

自定义组件数据复制功能

开发者需要在backend/src/project-custom-component.ts文件的copyTest方法中完成自己的插件数据复制逻辑

第三步：安装插件并使用

安装并启用插件，如果在config/plugin.yaml下的abilities.relateModule.componentModuleEnter配置没有填好则会在安装时报错

在配置中心 -> 插件管理 -> 业务插件中的插件详情页面可以配置自定义组件的名称和描述，如下图所示

在项目管理 -> 项目 -> 设置 -> 项目组件的左边栏中，自定义组件位于插件组件下，其使用方式与其他的组件相同

示例

项目内迭代工时统计

要求​

概述​

用法​

第一步：通过 OP 工具添加并使用能力​

新特性：标品数据映射​

第二步：完成自定义组件的功能​

组件设计​

自定义组件数据复制功能​

第三步：安装插件并使用​

示例​

要求

概述

用法