这是一个为 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("当前操作在此环境下不支持")
}
}
}| 函数名 | 参数 | 返回值 | 异常 | 说明 |
|---|---|---|---|---|
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 上的额外方法 |
interface PopoutWindowParams {
title?: string // 窗口标题
titleFixed?: boolean // 窗口标题是否固定
width?: number // 窗口宽度
height?: number // 窗口高度
minWidth?: number // 窗口最小宽度
url?: string // 自定义访问地址,如果为空则打开当前页面
}interface OpenWindowParams {
name?: string // 窗口唯一标识
url?: string // 访问地址
force?: boolean // 是否强制创建新窗口,而不是重用已有窗口
config?: WindowConfig // 窗口配置
}interface OpenAppPageParams {
title?: string // 页面标题
titleFixed?: boolean // 窗口标题是否固定
url?: string // 访问地址
}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
}interface requestParams {
url: string // 请求地址
method?: string // 请求方式
data?: any // 请求数据
timeout?: number // 请求超时时间
header?: any // 请求头
spinner?: boolean // 是否显示加载动画
}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", // 访问地址
})
}
})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 请求等
- 应用控制 - 关闭应用、返回操作等
- 提示框 - 各种类型的提示框演示
-
环境检测与异常处理: 这个库会自动检测是否在微前端环境中运行。如果不在微前端环境中,标注了
UnsupportedError的方法将抛出UnsupportedError异常,而环境检测方法(如isMicroApp、isElectron等)会返回false。 -
异步操作: 所有方法都是异步的,返回 Promise 对象,需要使用
await或.then()来处理结果。建议使用 try-catch 语句捕获UnsupportedError异常。 -
应用初始化: 在使用任何方法之前,建议先调用
appReady()确保应用已准备就绪。 -
环境限制: 某些方法只在特定环境中有效(如
openWindow只在 Electron 环境中有效),使用前请检查运行环境。 -
扩展调用: 如果你希望调用
$A上的方法,可以使用callExtraA方法。 -
示例学习: 建议先运行示例项目了解各种功能的使用方法。
如果你在使用中发现任何问题,或者有改进建议,欢迎在 GitHub 仓库提交 Issue 或 Pull Request。
DooTask 提供多语言后端 SDK,方便在服务端调用同一套 API:
MIT