DooTask 应用工具库

这是一个为 DooTask 应用开发设计的工具库，提供了一系列实用的 API，用于与主应用进行交互。它封装了微前端通信、用户数据获取、页面交互等多种功能，让您的 DooTask 应用开发变得简单高效。

特点

• 类型支持 - 完善的 TypeScript 类型定义，提供智能提示
• 异步 API - 所有方法都返回 Promise，支持异步操作
• 强大功能 - 提供完整的用户、系统信息和交互方法

安装

npm install @dootask/tools --save

使用方法

基本使用

直接引入并使用，所有方法都是异步的：

import {
  appReady,
  isMicroApp,
  getThemeName,
  getUserInfo,
  openWindow,
  closeApp,
  UnsupportedError,
  // 更多API...
} from "@dootask/tools"

// 等待应用准备就绪
try {
  await appReady()
  console.log("应用已准备就绪")
} catch (error) {
  if (error instanceof UnsupportedError) {
    console.log("当前环境不支持微前端模式")
  }
}

// 检查是否在微前端环境中
const isMicro = await isMicroApp()
if (isMicro) {
  console.log("当前在微前端环境中运行")

  try {
    // 获取当前主题
    const theme = await getThemeName()
    console.log("当前主题：", theme)

    // 获取用户信息
    const user = await getUserInfo()
    console.log("用户信息：", user)

    // 打开新窗口（需要在 Electron 环境中）
    await openWindow({
      name: "my-window",
      url: "https://example.com",
    })

    // 关闭当前应用
    await closeApp()
  } catch (error) {
    if (error instanceof UnsupportedError) {
      console.log("当前操作在此环境下不支持")
    }
  }
}

API 文档

应用状态相关

| 函数名 | 参数 | 返回值 | 异常 | 说明 | | ------------------ | ---- | ------------------ | ------------------ | -------------------------------------- | | appReady() | - | Promise<void> | UnsupportedError | 应用准备就绪的 Promise 对象 | | isMicroApp() | - | Promise<boolean> | - | 检查当前是否在微前端环境中运行 | | isEEUIApp() | - | Promise<boolean> | - | 检查是否为 EEUI 应用（App 客户端） | | isElectron() | - | Promise<boolean> | - | 检查是否为 Electron 应用（电脑客户端） | | isMainElectron() | - | Promise<boolean> | - | 检查是否为主 Electron 窗口 | | isSubElectron() | - | Promise<boolean> | - | 检查是否为子 Electron 窗口 |

用户和系统信息

| 函数名 | 参数 | 返回值 | 异常 | 说明 | | ------------------- | ---- | ------------------------------------------- | ------------------ | -------------------------------------------- | | getThemeName() | - | Promise<string> | UnsupportedError | 获取当前主题名称 | | getUserId() | - | Promise<number> | UnsupportedError | 获取当前用户 ID，0 表示未登录 | | getUserToken() | - | Promise<string> | UnsupportedError | 获取当前用户 Token | | getUserInfo() | - | Promise<DooTaskUserInfo> | UnsupportedError | 获取当前用户信息对象 | | getBaseUrl() | - | Promise<string> | UnsupportedError | 获取基础 URL | | getSystemInfo() | - | Promise<DooTaskSystemInfo> | UnsupportedError | 获取系统信息对象 | | getWindowType() | - | Promise<string> | UnsupportedError | 获取页面类型，可能的值为 'popout' 或 'embed' | | getLanguageList() | - | Promise<{[key: DooTaskLanguage]: string}> | UnsupportedError | 获取语言列表 | | getLanguageName() | - | Promise<DooTaskLanguage> | UnsupportedError | 获取当前语言名称 | | getSafeArea() | - | Promise<DooTaskSafeArea> | UnsupportedError | 获取移动端安全距离 |

应用控制

| 函数名 | 参数 | 返回值 | 异常 | 说明 | | ----------------------------- | ------------------------- | --------------------- | ------------------ | -------------------------------------------------------------------- | | backApp() | - | Promise<void> | UnsupportedError | 返回上一页，返回到最后一个页面时会关闭应用 | | closeApp(destroy?: boolean) | destroy?: boolean | Promise<void> | UnsupportedError | 关闭当前应用，destroy 为 true 时销毁应用 | | interceptBack(callback) | callback: () => boolean | Promise<() => void> | UnsupportedError | 设置应用关闭前的回调，返回 true 可阻止关闭。返回一个可注销监听的函数 | | nextZIndex() | - | Promise<number> | - | 获取下一个可用的模态框 z-index |

窗口操作

| 函数名 | 参数 | 返回值 | 异常 | 说明 | | ----------------------- | ----------------------------- | --------------- | ------------------ | ---------------------------------------------- | | popoutWindow(params?) | params?: PopoutWindowParams | Promise<void> | UnsupportedError | 应用窗口独立显示 | | openWindow(params) | params: OpenWindowParams | Promise<void> | UnsupportedError | 打开新窗口（只在 isElectron 环境有效） | | openTabWindow(url) | url: string | Promise<void> | UnsupportedError | 在新标签页打开 URL（只在 isElectron 环境有效） | | openAppPage(params) | params: OpenAppPageParams | Promise<void> | UnsupportedError | 打开应用页面（只在 isEEUIApp 环境有效） |

用户交互

| 函数名 | 参数 | 返回值 | 异常 | 说明 | |---------------------------|-------------------------------|-------------------------------------|----------------------------------|----------------------------------------------| | selectUsers(params) | params: SelectUsersParams | Promise<number[]> | UnsupportedError | 选择用户，可通过多种配置自定义选择器 | | requestAPI(params) | params: requestParams | Promise<ApiSuccess> | UnsupportedError | ApiError | 请求服务器 API | | fetchUserBasic(userid) | userid: number \| number[] | Promise<DooTaskUserBasicInfo[]> | UnsupportedError | ApiError | 查询用户基本信息 | | setCapsuleConfig(config)| config: CapsuleConfig | Promise<void> | UnsupportedError | 设置胶囊配置 |

提示框

| 函数名 | 参数 | 返回值 | 异常 | 说明 | | ----------------------- | -------------------------------- | ------------------ | ------------------ | -------------- | | modalSuccess(message) | message: string \| ModalParams | Promise<void> | UnsupportedError | 弹出成功提示框 | | modalError(message) | message: string \| ModalParams | Promise<void> | UnsupportedError | 弹出错误提示框 | | modalWarning(message) | message: string \| ModalParams | Promise<void> | UnsupportedError | 弹出警告提示框 | | modalInfo(message) | message: string \| ModalParams | Promise<void> | UnsupportedError | 弹出信息提示框 | | modalConfirm(message) | message: string \| ModalParams | Promise<boolean> | UnsupportedError | 弹出确认提示框 | | modalAlert(message) | message: string | Promise<void> | UnsupportedError | 弹出系统提示框 |

消息框

| 函数名 | 参数 | 返回值 | 异常 | 说明 | | ------------------------- | ----------------- | --------------- | ------------------ | ------------ | | messageSuccess(message) | message: string | Promise<void> | UnsupportedError | 弹出成功消息 | | messageError(message) | message: string | Promise<void> | UnsupportedError | 弹出错误消息 | | messageWarning(message) | message: string | Promise<void> | UnsupportedError | 弹出警告消息 | | messageInfo(message) | message: string | Promise<void> | UnsupportedError | 弹出信息消息 |

打开特定窗口

| 函数名 | 参数 | 返回值 | 异常 | 说明 | | ------------------------------- | ------------------ | -------------- | ------------------ | ------------------------------------------ | | openDialog(dialogId) | dialogId: number | Promise<any> | UnsupportedError | 打开对话框 | | openDialogNewWindow(dialogId) | dialogId: number | Promise<any> | UnsupportedError | 打开对话框（新窗口，仅支持 Electron 环境） | | openDialogUserid(userid) | userid: number | Promise<any> | UnsupportedError | 打开对话框（指定用户） | | openTask(taskId) | taskId: number | Promise<any> | UnsupportedError | 打开任务 | | downloadUrl(url) | url: string | Promise<any> | UnsupportedError | 下载文件 |

扩展功能

| 函数名 | 参数 | 返回值 | 异常 | 说明 | | ---------------------------------------- | --------------------------------------- | -------------- | ------------------ | --------------------------------- | | callExtraA(methodName, ...args) | methodName: string, ...args: any[] | Promise<any> | UnsupportedError | 调用 $A 上的额外方法 | | callExtraStore(actionName, ...payload) | actionName: string, ...payload: any[] | Promise<any> | UnsupportedError | 调用 $store.dispatch 上的额外方法 | | callExtraEmitter(eventName, ...args) | eventName: string, ...args: any[] | Promise<any> | UnsupportedError | 调用 emitter.emit 上的额外方法 |

PopoutWindowParams

interface PopoutWindowParams {
  title?: string // 窗口标题
  titleFixed?: boolean // 窗口标题是否固定
  width?: number // 窗口宽度
  height?: number // 窗口高度
  minWidth?: number // 窗口最小宽度
  url?: string // 自定义访问地址，如果为空则打开当前页面
}

OpenWindowParams

interface OpenWindowParams {
  name?: string // 窗口唯一标识
  url?: string // 访问地址
  force?: boolean // 是否强制创建新窗口，而不是重用已有窗口
  config?: WindowConfig // 窗口配置
}

OpenAppPageParams

interface OpenAppPageParams {
  title?: string // 页面标题
  titleFixed?: boolean // 窗口标题是否固定
  url?: string // 访问地址
}

SelectUsersParams

interface SelectUsersParams {
  value?: string | number | Array<any> // 已选择的值，默认值: []
  uncancelable?: Array<any> // 不允许取消的列表，默认值: []
  disabledChoice?: Array<any> // 禁止选择的列表，默认值: []
  projectId?: number // 指定项目ID，默认值: 0
  noProjectId?: number // 指定非项目ID，默认值: 0
  dialogId?: number // 指定会话ID，默认值: 0
  showBot?: boolean // 是否显示机器人，默认值: false
  showDisable?: boolean // 是否显示禁用的，默认值: false
  multipleMax?: number // 最大选择数量
  title?: string // 弹窗标题
  placeholder?: string // 搜索提示
  showSelectAll?: boolean // 显示全选项，默认值: true
  showDialog?: boolean // 是否显示会话，默认值: false
  onlyGroup?: boolean // 仅显示群组，默认值: false
}

requestParams

interface requestParams {
  url: string // 请求地址
  method?: string // 请求方式
  data?: any // 请求数据
  timeout?: number // 请求超时时间
  header?: any // 请求头
  spinner?: boolean // 是否显示加载动画
}

ModalParams

interface ModalParams {
  title: string // 标题
  content?: string // 内容
  width?: number // 宽度
  okText?: string // 确定按钮文本
  cancelText?: string // 取消按钮文本
  scrollable?: boolean // 是否可滚动
  closable?: boolean // 是否可关闭
}

使用示例

检测运行环境

import { appReady, isMicroApp, isElectron, isEEUIApp, UnsupportedError } from "@dootask/tools"

// 使用 try-catch 处理异常
try {
  await appReady()
  console.log("应用已准备就绪")
} catch (error) {
  if (error instanceof UnsupportedError) {
    console.log("当前环境不支持微前端模式")
  }
}

// 环境检测方法不会抛出异常，而是返回 boolean
const isMicro = await isMicroApp()
if (isMicro) {
  console.log("在微前端环境中运行")

  // 检测是否为Electron应用
  const isElectronEnv = await isElectron()
  if (isElectronEnv) {
    console.log("在Electron环境中运行")
  }

  // 检测是否为EEUI应用
  const isEEUI = await isEEUIApp()
  if (isEEUI) {
    console.log("在EEUI应用环境中运行")
  }
} else {
  console.log("不在微前端环境中运行")
}

应用关闭拦截

import { interceptBack, modalConfirm } from "@dootask/tools"

let hasUnsavedChanges = true

// 设置应用关闭前的回调
const unsubscribe = interceptBack(async data => {
  if (hasUnsavedChanges) {
    // 如果有未保存的数据，则阻止关闭
    if (await modalConfirm("有未保存的数据，确定要关闭吗？")) {
      // 用户确认关闭，可以执行保存操作
      saveData()
      return false // 允许关闭
    } else {
      return true // 阻止关闭
    }
  }
  return false // 没有未保存的数据，允许关闭
})

// 取消监听
// unsubscribe();

选择用户

import { selectUsers } from "@dootask/tools"

// 选择用户
selectUsers({
  value: [], // 已选择的值
  projectId: 123, // 指定项目ID
  title: "选择成员", // 弹窗标题
  showSelectAll: true, // 显示全选项
}).then(result => {
  console.log("选择的用户：", result)
})

// 选择群组
selectUsers({
  value: [],
  onlyGroup: true, // 仅显示群组
  showBot: false, // 不显示机器人
}).then(result => {
  console.log("选择的群组：", result)
})

弹出窗口和页面

import { popoutWindow, openWindow, openTabWindow, openAppPage, isElectron, isEEUIApp } from "@dootask/tools"

// 将当前页面作为独立窗口显示
popoutWindow()

// 将当前页面作为独立窗口显示（自定义窗口信息）
popoutWindow({
  title: "独立窗口", // 窗口标题
  width: 1000, // 窗口宽度
  height: 700, // 窗口高度
  minWidth: 800, // 窗口最小宽度
})

// 在Electron环境中打开新窗口
isElectron().then(isElectron => {
  if (isElectron) {
    openWindow({
      name: "my-window-id", // 窗口唯一标识
      url: "https://example.com", // 访问地址
      force: false, // 是否强制创建新窗口，而不是重用已有窗口
      config: {
        title: "标题", // 窗口标题
        titleFixed: true, // 窗口标题是否固定
        width: Math.min(window.screen.availWidth, 1200), // 窗口宽度
        height: Math.min(window.screen.availHeight, 800), // 窗口高度
      },
    })

    // 在新标签页打开URL
    openTabWindow("https://example.com")
  }
})

// 在EEUI环境中打开应用页面
isEEUIApp().then(isEEUI => {
  if (isEEUI) {
    openAppPage({
      title: "标题", // 页面标题
      titleFixed: true, // 窗口标题是否固定
      url: "https://example.com", // 访问地址
    })
  }
})

请求服务器 API

import { requestAPI } from "@dootask/tools"

// 请求服务器API
requestAPI({
  url: "users/info", // 访问接口路径，接口文档请查看 https://你的域名/docs/index.html
}).then(res => {
  console.log(res)
})

显示提示框

import { modalSuccess, modalError, modalWarning, modalInfo, modalAlert } from "@dootask/tools"

// 显示成功提示
modalSuccess("操作成功！")

// 显示错误提示
modalError("操作失败！")

// 显示警告提示
modalWarning("请注意！")

// 显示信息提示
modalInfo("提示信息")

// 显示系统提示框
modalAlert("系统消息")

// 使用复杂参数
modalSuccess({
  title: "成功",
  content: "操作已完成",
  width: 400,
})

弹出消息框

import { messageSuccess, messageError, messageWarning, messageInfo } from "@dootask/tools"

// 弹出成功消息
messageSuccess("操作成功！")

// 弹出错误消息
messageError("操作失败！")

// 弹出警告消息
messageWarning("请注意！")

// 弹出信息消息
messageInfo("提示信息")

示例项目

我们提供了一个完整的示例项目，展示如何在 Vue 3 + Vite 项目中使用 @dootask/tools：

查看示例

# 进入示例目录
cd example

# 安装依赖
npm install

# 启动开发服务器
npm run dev

示例项目包含以下功能演示：

• 应用状态检测 - 检测微前端环境、获取用户信息、主题、语言等
• 窗口管理 - 打开独立窗口、新窗口等操作
• 用户交互 - 用户选择器、API 请求等
• 应用控制 - 关闭应用、返回操作等
• 提示框 - 各种类型的提示框演示

注意事项

1. 环境检测与异常处理: 这个库会自动检测是否在微前端环境中运行。如果不在微前端环境中，标注了 UnsupportedError 的方法将抛出 UnsupportedError 异常，而环境检测方法（如 isMicroApp、isElectron 等）会返回 false。

2. 异步操作: 所有方法都是异步的，返回 Promise 对象，需要使用 await 或 .then() 来处理结果。建议使用 try-catch 语句捕获 UnsupportedError 异常。

3. 应用初始化: 在使用任何方法之前，建议先调用 appReady() 确保应用已准备就绪。

4. 环境限制: 某些方法只在特定环境中有效（如 openWindow 只在 Electron 环境中有效），使用前请检查运行环境。

5. 扩展调用: 如果你希望调用 $A 上的方法，可以使用 callExtraA 方法。

6. 示例学习: 建议先运行示例项目了解各种功能的使用方法。

贡献和反馈

如果你在使用中发现任何问题，或者有改进建议，欢迎在 GitHub 仓库提交 Issue 或 Pull Request。

后端服务

DooTask 提供多语言后端 SDK，方便在服务端调用同一套 API：

• Go
• Python
• Node

许可证

MIT