decision-model 使用文档

简介

decision-model 是一个基于 Vue 3 的决策模型（DMN）组件库，内置了基于 Axios 的请求层、主题定制、国际化、表格边框配置等开箱即用的功能。

安装

npm install decision-model
# 或
pnpm add decision-model

依赖说明

本库将以下模块列为 peerDependencies，需要你自行安装：

• vue ^3.2.0
• ant-design-vue ^4.0.0
• @ant-design/icons-vue ^6.0.0
• pinia ^2.0.0（部分组件依赖 Pinia 管理状态）

npm install vue ant-design-vue @ant-design/icons-vue pinia

快速开始

在你的应用入口（如 main.ts）中，首先调用 setupDecisionModel 进行初始化配置。

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import { setupDecisionModel } from 'decision-model'
import 'ant-design-vue/dist/reset.css'
import 'decision-model/dist/style.css'

const app = createApp(App)

setupDecisionModel({
  baseURL: 'https://api.example.com',        // 后端接口基础地址
  token: () => localStorage.getItem('token'), // 获取 token 的函数
  onAuthRefresh: async (oldToken) => {        // 当接口返回 401 时自动调用刷新 token
    const newToken = await refreshToken(oldToken)
    return newToken
  },
  onError: (err) => {                         // 全局错误处理
    console.error('Request error:', err)
  },
  themeColor: '#1776a5',                       // 主色（会覆盖 antd 主题色）
  locale: zhCN,                                 // 语言（默认中文）
  tableBordered: false,                          // 表格是否显示边框（默认 false）
  tableAdjustHeight: 280,                       // dmn模型表格自适应高度偏移量（默认 280）
})

app.mount('#app')

之后，你就可以在任意组件中使用库提供的决策表组件（如 <DecisionModel />）以及相关组合式 API。

配置项（DecisionModelOptions）

调用 setupDecisionModel 时可传入以下配置：

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | baseURL | string | 是 | 接口基础地址，所有请求将基于此 URL | | uploadUrl | string | 否 | 文件上传接口地址，默认为 ${baseURL}/basicFile/upload | | token | () => string \| null \| Promise<string \| null> | 否 | 获取 token 的函数，请求时会携带该 token（通常作为 Authorization 头） | | onAuthRefresh | (oldToken?) => Promise<string \| null> \| string \| null | 否 | 当请求返回 401 时调用，应返回新的 token 或 null | | onError | (err: unknown) => void | 否 | 全局请求错误回调 | | timeoutMs | number | 否 | 请求超时时间（毫秒） | | themeColor | string | 否 | 主题色，会同步更新 CSS 变量 --dm-primary-color | | theme / themeConfig | ThemeConfig | 否 | Ant Design Vue 主题配置，会与默认主题合并（theme优先级更高） | | locale | Locale | 否 | Ant Design Vue 语言包，默认 zhCN | | encryptStorage | boolean | 否 | （预留）是否启用本地存储加密 | | tableBordered | boolean | 否 | 表格是否显示边框，默认 false | | tableAdjustHeight | number | 否 | 表格高度自适应调整值，默认 280 |

API 参考

初始化与全局配置

setupDecisionModel(options: DecisionModelOptions): void

必须在应用启动时调用一次，完成库的初始化。会自动加载 DMN 编辑器所需的 UMD 模块和图标库。

getDecisionModelOptions(): DecisionModelOptions

获取当前全局配置对象，若未初始化则抛出错误。

getBaseUrl(): string

获取配置的 baseURL。

getUploadUrl(): string

获取上传接口地址，优先使用 uploadUrl，否则自动拼接 baseURL/basicFile/upload。

getToken(): TokenGetter | undefined

获取配置的 token 获取函数。

getTableBordered(): boolean

获取表格边框配置。

getTableAdjustHeight(): number

获取表格高度调整值。

getUiConfig()

返回一个包含 tableBordered、themeColor、theme 的对象。

主题与样式

setThemeColor(color: string): void

动态修改主题色，会更新 CSS 变量 --dm-primary-color。

getThemeColor(): string

获取当前主题色。

setDecisionModelTheme(theme: ThemeConfig): void

运行时合并并应用新的 Ant Design 主题配置。

setDecisionModelLocale(locale: Locale): void

运行时切换语言。

setTableBordered(bordered: boolean): void

运行时修改表格边框配置。

配置状态获取

useDecisionModelConfig(): Readonly<DecisionModelConfigState>

Vue 组合式 API，返回一个只读的响应式状态对象，包含：

interface DecisionModelConfigState {
  locale: Locale & Record<string, any>
  theme: ThemeConfig
  tableBordered: boolean
  tableAdjustHeight: number
  // 允许其他动态扩展
}

示例：

<script setup>
import { useDecisionModelConfig } from 'decision-model'

const config = useDecisionModelConfig()
console.log(config.theme.token.colorPrimary)
</script>

DecisionModel 组件 Props

<DecisionModel /> 组件支持以下两个 props：

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | categoryId | string | undefined | 分类 ID，用于初始化时自动选中对应树节点。若传入，组件会在挂载后查找并展开对应节点，并选中它。 | | componentSize | 'small' \| 'middle' \| 'large' | 'middle' | 设置内部 ant-design-vue 组件的尺寸。该值会透传给内部的 a-config-provider 的 component-size 属性，统一控制按钮、输入框等组件的尺寸。 |

类型定义

TokenGetter

type TokenGetter = () => string | null | Promise<string | null>

AuthRefreshFn

type AuthRefreshFn = (oldToken?: string | null) => Promise<string | null> | string | null

ErrorHook

type ErrorHook = (err: unknown) => void

DecisionModelOptions

参见上方配置项表格。

DecisionModelConfigState

interface DecisionModelConfigState {
  locale: Locale & Record<string, any>
  theme: ThemeConfig
  tableBordered: boolean
  tableAdjustHeight: number
  [key: string]: any
}

高级用法

主题定制

主题使用 Ant Design Vue 的 ThemeConfig 类型。默认主题为：

const DEFAULT_THEME = {
  token: {
    colorPrimary: '#1776a5',
    colorLink: '#1776a5',
    colorSuccess: '#55d187',
    colorWarning: '#EFBD47',
    colorError: '#ED6F6F',
  },
}

通过 theme 选项可部分覆盖：

setupDecisionModel({
  baseURL: '...',
  theme: {
    token: {
      colorPrimary: '#ff6600',
    },
  },
})

国际化

支持 Ant Design Vue 的所有语言包，通过 locale 选项设置。运行时可通过 setDecisionModelLocale 切换。

注意事项

• 必须确保 decision-model 的样式已正确引入decision-model/dist/style.css。
• 库的部分组件依赖 Pinia 管理状态，建议在你的项目中安装并注册 Pinia。
• setupDecisionModel 必须在任何决策表组件渲染之前调用。