@ones-op/bridge

我们提供了一套工具库，可以帮助你调用 ONES 系统内提供的一些工具方法

安装

在插件 /web 目录，通过以下命令安装此包：

npm
Yarn
pnpm

npm install @ones-op/bridge

yarn add @ones-op/bridge

pnpm add @ones-op/bridge

使用

import { modal } from '@ones-op/bridge'

modal.newCreateTask()

此示例适用于 ONES v6.88.0 及以上版本。更早的宿主请使用下文列出的原有新建方法。

APIs

通过 modal 暴露的方法，你可以唤起 ONES 系统内的一系列弹窗

newCreateTask

发送 NewCreateTask 事件，唤起当前的新建工作项弹窗。此方法也用于替代 createSubTask。

要求

宿主要求 ONES v6.88.0 及以上版本；使用的 @ones-op/bridge 版本及其 @ones-op/rc-peta 依赖必须已导出 modal.newCreateTask。旧宿主不支持此事件，仅升级 SDK 不会为宿主增加相应能力。

参数

参数	说明	类型	必填	默认值
modalProps	弹窗配置	`NewCreateTaskModalProps`	否	`{}`

属性	行为
`projectUUID`、`issueTypeUUID`	默认项目和工作项类型，优先于对应字段的默认值。
`projectCondition`、`issueTypeCondition`	限制项目或工作项类型的候选范围，例如使用 `uuid_in`。
`defaultValues`	字段 UUID 与值组成的数组。字段不在表单中时不会提交。
`contextValues`	字段 UUID 与值组成的数组，字段不在表单中时仍会提交。同一字段优先取 `defaultValues`，两者均优先于表单配置的默认值。
`canImportTasks`、`canCreateTheNext`	展示导入入口或继续创建下一个选项。
`disableToastWhenSuccess`	禁用创建成功提示。
`onTaskCreated`	每次创建成功后触发，参数为工作项摘要及是否继续创建的布尔值。
`onCancel`	弹窗关闭时触发，成功创建且不再继续创建时也会触发。
`onFormFinish`	接管表单校验后的流程。传入后宿主不会创建工作项，也不会调用 `onRequestCreate`，并会关闭弹窗。
`onRequestCreate`	接管创建请求。返回 `response` 时执行宿主的创建结果处理；不返回 `response` 时，由 `submitControl` 控制是否提交字段控件，然后继续创建或关闭弹窗。

类型

以下类型可从 @ones-op/bridge 导入。CreatedTask 是工作项摘要，不是完整详情。字段值格式以目标字段的配置为准。

import type { ReactNode } from 'react'

interface TaskFieldValue {
  field_uuid: string
  original_value_handling?: 'modify_original' | 'append_original'
  value?: any
  append?: any
  update?: any
  delete?: any
}

interface CreatedTask {
  uuid: string
  number: string
  issue_type_uuid: string
  issue_type_name: string
  project_uuid: string
  parent_uuid: string
  display_id: string
  summary: string
  project_identifier: string
}

interface CreateTaskParams {
  uuid: string
  project_uuid: string
  issue_type_uuid: string
  field_values: TaskFieldValue[]
  recommend_field_values?: TaskFieldValue[]
  position_mode?: 'before' | 'after'
  anchor_item_uuid?: string
  upstream_item_uuid?: string
  upstream_field_uuid?: string
}

interface CreateTasksResult {
  async_compute_token: string
  bad_tasks: any[]
  tasks: CreatedTask[]
}

interface NewCreateTaskModalProps {
  title?: string
  taskUUID?: string
  projectUUID?: string
  issueTypeUUID?: string
  projectCondition?: Record<string, any>
  issueTypeCondition?: Record<string, any>
  defaultValues?: TaskFieldValue[]
  contextValues?: TaskFieldValue[]
  canImportTasks?: boolean
  canCreateTheNext?: boolean
  disableToastWhenSuccess?: boolean
  okText?: ReactNode
  cancelText?: ReactNode
  extraHeader?: ReactNode
  onProjectUUIDChange?: (projectUUID?: string) => void
  onIssueTypeUUIDChange?: (issueTypeUUID?: string) => void
  onCancel?: () => void
  onTaskCreated?: (task: CreatedTask, createTheNext: boolean) => void
  onFormFinish?: (createTask: CreateTaskParams, formValues: Record<string, any>) => void
  onRequestCreate?: (
    tasks: CreateTaskParams[],
  ) => Promise<{ submitControl: boolean; response?: CreateTasksResult }>
}

示例

import { modal } from '@ones-op/bridge'

modal.newCreateTask({
  projectUUID: 'projectUUID',
  issueTypeUUID: 'issueTypeUUID',
  defaultValues: [{ field_uuid: 'field001', value: 'Example task' }],
  canCreateTheNext: true,
  onTaskCreated(task, createTheNext) {
    console.log(task.uuid, createTheNext)
  },
})

新建子工作项

通过 contextValues 设置新建子工作项上的上层级字段。字段 UUID 和允许创建的子工作项类型需要根据层级配置确定，不应使用父工作项上的下层级字段，也不能假定旧 parent_uuid 字段能够表示当前配置的层级。以下示例适用于值为工作项 UUID 数组的层级字段：

modal.newCreateTask({
  projectUUID: 'parentProjectUUID',
  issueTypeCondition: { uuid_in: ['childIssueTypeUUID'] },
  contextValues: [{ field_uuid: 'upstreamFieldUUID', value: ['parentTaskUUID'] }],
})

newCreateRelatedTask

发送 NewCreateRelatedTask 事件，唤起当前的新建关联工作项弹窗。与 newCreateTask 一样，需要 ONES v6.88.0 及以上版本，并使用已导出此方法的 SDK 版本。

参数

参数	说明	类型	必填	默认值
modalProps	包含源工作项的弹窗配置	`NewCreateRelatedTaskModalProps`	是

sourceTask.uuid、sourceTask.issueTypeUUID、sourceTask.projectUUID 均为必填，缺少任意一项时 SDK 会在发送事件前抛错。顶层 projectUUID 指定新工作项的默认项目，sourceTask.projectUUID 表示源工作项所属项目。

defaultRelationUUID 指定默认关联关系，disabled 禁止切换关联关系，closeable 展示可关闭源工作项关联的开关。选择关联关系时，宿主会限制可选工作项类型，并设置对应关联字段的值。

onTaskCreated 的第二个参数是当前选中的关联关系 UUID，不是 createTheNext 布尔值，也不是独立的关联成功结果。开启 closeable 时，不能仅凭该参数判断是否创建了源工作项关联。

类型

interface NewCreateRelatedTaskModalProps extends Omit<NewCreateTaskModalProps, 'onTaskCreated'> {
  disabled?: boolean
  defaultRelationUUID?: string
  sourceTask: {
    uuid: string
    issueTypeUUID: string
    projectUUID: string
  }
  closeable?: boolean
  onTaskCreated?: (task: CreatedTask, relationUUID?: string) => void
}

示例

modal.newCreateRelatedTask({
  sourceTask: {
    uuid: 'sourceTaskUUID',
    issueTypeUUID: 'sourceIssueTypeUUID',
    projectUUID: 'sourceProjectUUID',
  },
  projectUUID: 'targetProjectUUID',
  defaultRelationUUID: 'relationUUID',
  onTaskCreated(task, relationUUID) {
    console.log(task.uuid, relationUUID)
  },
})

按 ONES 版本选择新建方法

ONES 版本	适用的新建方法与事件
`v6.88.0` 之前	`createTask` / `CreateTask`、`createSubTask` / `CreateSubTask`、`createRelatedTask` / `CreateRelatedTask`
`v6.88.0` 及以上	`newCreateTask` / `NewCreateTask`、`newCreateRelatedTask` / `NewCreateRelatedTask`

原有三个事件仍适用于 v6.88.0 之前的 ONES 版本；从 v6.88.0 起废弃，宿主仅提示事件已废弃，不再打开对应弹窗。SDK 保留三个旧方法，并在废弃注释中注明版本边界。请根据目标宿主版本选择 API，SDK 不会自动识别版本或转换参数。

将集成迁移到 ONES v6.88.0 及以上版本时，需要同步调整以下参数：

旧 API 或参数	迁移方式
`createTask` / `CreateTask`	`newCreateTask` / `NewCreateTask`
`createSubTask` / `CreateSubTask`、`parentTask`	使用 `newCreateTask`，在 `contextValues` 中传入子工作项的上层级字段，并用 `issueTypeCondition` 限制允许的子工作项类型
`createRelatedTask` / `CreateRelatedTask`、`relatedTask`	`newCreateRelatedTask` / `NewCreateRelatedTask`，传入 `sourceTask: { uuid, issueTypeUUID, projectUUID }`
`defaultValue.projectUUID`、`defaultValue.issueTypeUUID`	顶层 `projectUUID`、`issueTypeUUID`
其他 `defaultValue` 字段	改为 `defaultValues` 或 `contextValues`，使用实际字段 UUID 及其支持的值格式
`defaultValue.relatedTypeValue`	确认当前关联关系 UUID 后传入 `defaultRelationUUID`
`disabledFields`	新协议没有通用的字段禁用参数；限制项目或类型候选范围时可使用 `projectCondition` / `issueTypeCondition`
`onOk(result)`	对 `newCreateTask` 使用 `onTaskCreated(task, createTheNext)`；仅关注最后一次创建时判断 `!createTheNext`。新回调不再返回 `queryToTask`
`onRelatedSuccess`	改用 `newCreateRelatedTask.onTaskCreated(task, relationUUID)`，注意新回调的参数结构
`extra`	将支持的属性直接放到新配置中

以下 API 适用于 ONES v6.88.0 之前的版本。

createTask

警告

适用于 ONES v6.88.0 之前的版本。从 v6.88.0 起废弃，该版本及之后请使用 newCreateTask 并调整参数。

唤起新建工作项的弹窗

要求

ONES	@ones-op/bridge
`>= v3.13.14, < v6.88.0`	`v0.2.0`

参数

参数	说明	类型	必填	默认值
modalProps	弹窗的配置	`CreateTaskModalProps`	否	`{}`

类型

interface TaskCreatedResult {
  /** 创建的工作项的ID */
  taskUUID: string
  /** 跳转到工作项详情的方法 */
  queryToTask: () => void
  /** 创建的工作项的详情 */
  task: Record<string, any>
}

interface CreateTaskModalProps {
  /** 弹窗标题，如果为空，则根据选择的工作项类型自动设置 */
  title?: string
  /** 表单默认值 */
  defaultValue?: {
    /** 工作项标题 */
    summary?: string
    /** 所属项目 */
    projectUUID?: string
    /** 工作项类型 */
    issueTypeUUID?: string
    /** 负责人 */
    assign?: string
    /** 任务描述 */
    descRich?: string
    /** 所属迭代 */
    sprintUUID?: string
  }
  /** 禁止更改的表单项 */
  disabledFields?: {
    /** 工作项标题 */
    summary?: boolean
    /** 所属项目 */
    projectUUID?: boolean
    /** 工作项类型 */
    issueTypeUUID?: boolean
    /** 负责人 */
    assign?: boolean
    /** 任务描述 */
    descRich?: boolean
    /** 所属迭代 */
    sprintUUID?: boolean
  }
  /** 用户点击确认，且不再继续创建下一个时的回调 */
  onOk?: (result: TaskCreatedResult) => void
  /** 点击取消按钮时的回调 */
  onCancel?: () => void
  /** 工作项被创建之后的回调 */
  onTaskCreated?: (task: TaskCreatedResult['task']) => void
  /** 其他属性 */
  extra?: Record<string, any>
}

createSubTask

警告

适用于 ONES v6.88.0 之前的版本。从 v6.88.0 起废弃，该版本及之后请使用 newCreateTask 并调整参数。

唤起新建子工作项的弹窗

要求

ONES	@ones-op/bridge
`>= v3.13.14, < v6.88.0`	`v0.2.0`

参数

参数	说明	类型	必填	默认值
modalProps	弹窗的配置	`CreateSubTaskModalProps`	是

类型

interface CreateSubTaskModalProps extends CreateTaskModalProps {
  /** 父工作项详情 */
  parentTask: {
    /** 父工作项的ID */
    uuid: string
    /** 父工作项所属的项目ID */
    project_uuid: string
    [key: string]: any
  }
}

警告

parentTask中必须包含uuid和project_uuid，否则可能导致子工作项创建不成功。你可以直接传入工作项详情接口返回的数据

createRelatedTask

警告

适用于 ONES v6.88.0 之前的版本。从 v6.88.0 起废弃，该版本及之后请使用 newCreateRelatedTask 并调整参数。

唤起新建关联工作项的弹窗

要求

ONES	@ones-op/bridge
`>= v3.13.14, < v6.88.0`	`v0.2.0`

参数

参数	说明	类型	必填	默认值
modalProps	弹窗的配置	`CreateRelatedTaskModalProps`	是

类型

interface CreateRelatedTaskModalProps extends Omit<CreateTaskModalProps, 'defaultValue'> {
  /** 表单默认值 */
  defaultValue?: CreateTaskModalProps['defaultValue'] & {
    /** 关联关系 */
    relatedTypeValue?: string
  }
  /** 要关联的工作项 */
  relatedTask: {
    /** 关联工作项的ID */
    uuid: string
    /** 关联工作项的类型 */
    issue_type_uuid: string
    [key: string]: any
  }
  /** 工作项被关联之后的回调 */
  onRelatedSuccess?: (data: Record<string, any>) => void
}

警告

relatedTask中必须包含uuid和issue_type_uuid，否则可能导致工作项关联不成功。你可以直接传入工作项详情接口返回的数据

refreshList

通过调用refreshList方法，你可以手动触发标品中列表的刷新

要求

ONES	@ones-op/bridge
`v3.13.24+`	`v0.3.0+`

参数

参数	说明	类型	必填	默认值
listName	列表的名字	`ListName`	是

类型

type ListName =
  | 'memberList'
  | 'codeRepositoryList'
  | 'planTestcaseList'
  | 'testPlanList'
  | 'requirementTraceabilityList'

memberList

可用：v0.3.0+
ONES 要求：v3.11.15+

触发成员列表刷新（支持标品中所有成员列表）。

codeRepositoryList

可用：v0.3.0+
ONES 要求：v3.13.9+

代码仓管理列表页刷新

planTestcaseList

可用：v0.3.0+
ONES 要求：v3.13.24+

测试管理 / 测试计划 / 用例列表刷新

testPlanList

可用: v0.3.1+
ONES 要求: v3.13.35+

测试管理 / 测试计划 / 测试计划列表刷新

requirementTraceabilityList

可用：v0.3.0+
ONES 要求：v3.13.24+

测试管理 / 测试计划 / 需求跟踪列表刷新

invokeProgressManager

通过调用invokeProgressManager方法，可以激活全局进度管理器。

要求

ONES	@ones-op/bridge
`v3.13.24+`	`v0.3.0+`

lifecycle

通过调用 lifecycle 实例的方法，插件可以操作自身的部分生命周期。

要求

@ones-op/bridge
`v0.9.0+`

destroy

插件可以通过调用 lifecycle.destroy 方法，来销毁自身。

警告

这通常在手动激活的插件模块中使用，如果你使用的插槽并无特别说明，一般情况下不需要调用该方法。

ONES 要求：v3.11.40+

onDestroy

在销毁插件之前被调用。

要求

ONES	@ones-op/bridge
`v3.13.58+`	`v0.6.1+`

参数

参数	说明	类型	必填	默认值
callback	当前回调会在销毁插件之前被调用。	`CallbackFn`	是

类型

function onDestroy(callback: () => void): void

dashboardCard

通过 dashboardCard 模块提供的 hook，你可以完成仪表盘卡片的相关功能

警告

该模块仅在仪表盘卡片的插件模块中可用

要求

ONES	@ones-op/bridge
`v3.13.50+`	`v0.6.0+`

useOnSubmitConfig

在卡片配置弹窗中（scene 为 setting）调用 useOnSubmitConfig 方法，可以在用户点击保存配置时，触发你传入的回调。

参数

参数	说明	类型	必填	默认值
callback	用户点击弹窗上的保存按钮时的回调	`CallbackFn`	是

类型

type CallbackFn = <T = any>(submit: (config: T) => void) => void | Promise<void>

function useOnSubmitConfig<T>(callback: CallbackFn<T>): void

useCustomMenus

在卡片渲染区域中（scene 为 render）调用 useCustomMenus 方法，可以给卡片挂载自定义菜单

参数

参数	说明	类型	必填	默认值
customMenus	自定义菜单	`CustomMenuItem[]`	是

类型

type CustomMenuItem = {
  key: string; // 菜单的唯一标识
  label: string; // 菜单标题
  onClick: () => void ｜ Promise<void>; // 点击菜单的回调
};

function useCustomMenus(customMenus: CustomMenuItem[]): void;

OPProvider

当插件调用函数 lifecycle.destroy 时，OPProvider 将卸载其子组件。当插件在 YAML 中配置了属性 enableDelayDestroy 并设置为 true 来延迟销毁组件时，这个 provider 会将自己的子组件卸载。

要求

ONES	@ones-op/bridge
`v3.13.58+`	`v0.6.1+`

安装​

使用​

APIs​

modal​

newCreateTask​

要求​

参数​

类型​

示例​

新建子工作项​

newCreateRelatedTask​

参数​

类型​

示例​

按 ONES 版本选择新建方法​

createTask​

要求​

参数​

类型​

createSubTask​

要求​

参数​

类型​

createRelatedTask​

要求​

参数​

类型​

refreshList​

要求​

参数​

类型​

memberList​

codeRepositoryList​

planTestcaseList​

testPlanList​

requirementTraceabilityList​

invokeProgressManager​

要求​

lifecycle​

要求​

destroy​

onDestroy​

要求​

参数​

类型​

dashboardCard​

要求​

useOnSubmitConfig​

参数​

类型​

useCustomMenus​

参数​

类型​

OPProvider​

要求​

安装

使用