基础组件与工具

本篇汇总 @vben/components 中的小型基础组件（basic / icon / avatar / transition）与支撑模块（hooks / store / api / utils / adapter）。

1. Basic 基础组件

@vben/components/basic，已做全局安装（withInstall），模板中直接使用：

组件	用途	关键 props
`BasicTitle`	区块标题（可带左侧色块、底部线、帮助提示）	`helpMessage`、`helpPosition`、`span`（左侧色块）、`normal`（不加粗）、`line` / `dashed`（底部线）
`BasicHelp`	文字旁的问号帮助图标（悬浮提示）	`text`（提示内容）、`placement`、`maxWidth`
`BasicArrow`	展开/收起箭头（带旋转动画）	`expand`、`up`、`down`、`inset`

<BasicTitle help-message="此处配置角色的数据权限范围">数据权限</BasicTitle>

2. Icon 图标

@vben/components/icon。对 @vben/icons 的增强：除 iconify 图标外，icon 以 http 开头时渲染为 <img>（用于后端下发的自定义图标 URL）。

Prop	类型	默认值	说明
`icon`	`string`	`''`	iconify 名称（如 `ant-design:home-outlined`）或图片 URL
`size`	`string \| number`	`'16px'`	尺寸

3. MdpAvatar 头像

@vben/components/avatar。增强版头像，src 支持传 Promise<string>（先异步取图片地址再渲染），适合「文件服务签名 URL」这类需要异步换地址的场景。

Prop	说明
`src`	图片地址或返回地址的 Promise
`size`	尺寸（px）

4. Transition 动画组件

@vben/components/transition，一组预置过渡动画，直接用组件包裹内容即可：

<CollapseTransition>
  <div v-show="expanded">折叠内容</div>
</CollapseTransition>

组件	效果
`CollapseTransition`	高度折叠展开（手风琴常用）
`FadeTransition`	淡入淡出
`ScaleTransition` / `ScaleRotateTransition`	缩放 / 缩放旋转
`SlideXTransition` / `SlideYTransition`（及 `Reverse` 变体）	滑动
`ScrollXTransition` / `ScrollYTransition`（及 `Reverse` 变体）	滚动
`ExpandTransition` / `ExpandXTransition`	展开（JS 动画）

5. useMessage 消息提示

@vben/components/hooks 导出，对 antdv message / Modal / notification 的统一封装（自动居中、内置图标、国际化按钮文案）：

import { useMessage } from '@vben/components/hooks';

const {
  createMessage,        // antdv message 本体
  notification,         // 右上角通知（已配置 placement/duration）
  createConfirm,        // 确认框
  createSuccessModal,   // 成功弹窗
  createErrorModal,     // 错误弹窗
  createInfoModal,      // 信息弹窗
  createWarningModal,   // 警告弹窗
} = useMessage();

createMessage.success('保存成功');
createConfirm({
  iconType: 'warning',
  title: '确认删除？',
  content: '删除后不可恢复',
  onOk: handleRemove,
});

6. Store：字典与 Schema

@vben/components/store 导出两个 Pinia store。

useDictStore 字典 store

全局字典缓存（工厂基于 @vben/stores 的 createDictStore，数据源为后端字典接口），ApiDict 组件底层就是它：

import { useDictStore } from '@vben/components/store';

const dictStore = useDictStore();

dictStore.getDictItemList('common.state');           // 原始字典项列表
dictStore.getDictItemOptionList('common.state');     // Select 可直接用的 options
dictStore.getDictItemOptionList('common.state', locale, true); // 国际化 + 忽略禁用
dictStore.getDictItem('common.state', 'ENABLED');    // 单个字典项
dictStore.isLoaded('common.state');                  // 是否已加载

options 的 value 会按字典项的 dataType 自动转型（整型/布尔/字符串），label 支持按 i18nJson 国际化。

useSchemaStore 动态表单 schema

把后端「字段元数据」（字段名、组件、必填、占位、栅格跨度等）转换为 useVbenForm 可用的 schema 并缓存，配合代码生成器使用——后端下发表结构元数据，前端零编码渲染出表单与详情。

7. Api 模块

@vben/components/api，组件包内部使用的公共接口（也可在业务代码中复用）：

导出	说明
`uploadApi` / `uploadFile`	普通文件上传（FileUpload 默认接口）
`findUrlByIds` / `findUrlByObject`	按文件 ID / 业务对象查询文件 URL（回显用）
`findDictItemByUniqKey`	批量拉取字典项（字典 store 的数据源）
`initPartUpload` / `uploadPart` / `getUploadProgress` / `completePartUpload` / `abortPartUpload`	分片上传协议接口，见分片上传
`SysFileVo` / `SysDictItemVo`	文件、字典项类型定义

8. Utils 与 Adapter

@vben/components/utils：

导出	说明
`get`	按 `a.b.c` 路径取对象值
`toPascalCase` / `getFileNameWithoutExtension`	组件名转换（component-map 自动注册用）
`useBreakpoint`	响应式断点监听
`render.tsx` / `domUtils.ts` / `event/`	渲染与 DOM 工具

@vben/components/adapter：form 与 vxe-table 的组件适配层（useVbenForm、useVbenVxeGrid、单元格渲染器、启动初始化），是组件包中使用最广的模块，单独成章——见表单与表格适配层。

@vben/components/styles：动态表单的公共样式（common-form.scss / common-detail.scss），在动态表单页面入口引入：

import '@vben/components/styles';