# @bytenew/bn-bus-ui 中文文档

规范地址：https://npmcn.com/package/%40bytenew/bn-bus-ui/

版本：1\.1\.528
npm 元数据更新时间：2026-11-06T07:18:36.093Z
中文译文更新时间：2026-11-08T21:58:43.926Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bytenew/bn-bus-ui
原文对照：https://npmcn.com/package/%40bytenew/bn-bus-ui/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.8 MB，52 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：6 个
- 首次发布：2026-05-29T05:40:53.199Z
- 最新版本发布：2026-11-06T07:18:35.873Z
- 近 30 天下载量：3623（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：128（近 12 个月 128 个）

## 中文简介

班牛业务组件库，集合版

## 安装

```sh
npm install @bytenew/bn-bus-ui
```

也可以使用：`pnpm add @bytenew/bn-bus-ui`、`yarn add @bytenew/bn-bus-ui`、`bun add @bytenew/bn-bus-ui`

## README

# BnBusUi - 班牛业务组件库

## 项目简介

BnBusUi 是班牛（ByteNew）业务组件库，为工单智能管理平台提供统一的 Vue 3 组件封装。本组件库基于 Element Plus 和 Vue 3 开发，提供了一套完整的业务组件解决方案。

## 技术栈

### 核心框架

-   **Vue 3** (^3.0.0) - 渐进式 JavaScript 框架
-   **Element Plus** (^2.11.9) - 基于 Vue 3 的组件库

### 构建工具

-   **Vite** (^6.0.1) - 下一代前端构建工具
-   **@vitejs/plugin-vue** (^5.2.1) - Vite Vue 插件

### 主要依赖

-   **axios** (^1.7.9) - HTTP 客户端
-   **lodash** (^4.17.21) - JavaScript 实用工具库
-   **sass** (^1.83.0) - CSS 预处理器
-   **vuedraggable** (^4.1.0) - 拖拽组件
-   **vxe-table** (^4.17.38) - 高性能表格组件
-   **@logicflow/core** & **@logicflow/extension** (^1.1.20) - 流程图引擎
-   **codemirror** (^5.65.20) & **codemirror-editor-vue3** (^2.8.0) - 代码编辑器

### 编译工具

-   **@babel/core** & **@babel/preset-env** - JavaScript 编译器
-   **babel-plugin-component** - 组件按需加载插件
-   **core-js** - JavaScript polyfill 库

## 安装与使用

### 安装

```bash
npm install @bytenew/bn-bus-ui
```

### 全局引入

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import BnBusUi from '@bytenew/bn-bus-ui'
import '@bytenew/bn-bus-ui/common.scss'

const app = createApp(App)
app.use(BnBusUi)
app.mount('#app')
```

### 按需引入

```javascript
import { BnSelect, BnCondition, BnSmartForm } from '@bytenew/bn-bus-ui'

export default {
  components: {
    BnSelect,
    BnCondition,
    BnSmartForm
  }
}
```

### 全局配置

```javascript
import { setGlobalConfig } from '@bytenew/bn-bus-ui'

// 设置 API 基础 URL
setGlobalConfig({
  apiBaseUrl: 'https://your-api-domain.com'
})
```

## 组件列表

### 1\. BnAddress - 地址选择器

**功能描述**：省市区街道级联选择组件，支持异步加载地址数据。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | Array | \- | 绑定值，地址数组 |
| disabled | Boolean | false | 是否禁用 |
| valueKey | String | 'id' | 选项值的键名 |
| levelNum | Number | 4 | 地址层级数量（1-4） |
| postFunc | Function | \- | 远程请求方法 |
| postData | Object | {} | 请求参数 |
| pathUrl | String | '' | 请求地址 |
| wrapShow | Boolean | false | 是否整行展示 |

**使用示例**：

```vue
<template>
  <BnAddress 
    v-model="addressValue"
    :postFunc="httpRequest"
    pathUrl="/address/getAreaDataList"
    :levelNum="3"
  />
</template>

<script setup>
import { ref } from 'vue'
const addressValue = ref([])
</script>
```

* * *

### 2\. BnSelect - 高级选择器

**功能描述**：增强版下拉选择组件，支持远程搜索、分页加载、多选全选等功能。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | Any | \- | 绑定值 |
| options | Array | \[\] | 选项列表 |
| placeholder | String | '请选择' | 占位符 |
| optionProps | Object | {value:'id', label:'title'} | 选项结构配置 |
| multiple | Boolean | false | 是否多选 |
| collapseTags | Boolean | true | 多选时是否折叠展示 |
| labelInValue | Boolean | true | 是否返回完整对象 |
| postFunc | Function | \- | 远程请求方法 |
| pathUrl | String | '' | 请求地址 |
| isPage | Boolean | true | 是否分页 |
| checkedAll | Boolean | true | 是否显示全选 |

**使用示例**：

```vue
<template>
  <BnSelect 
    v-model="selectedValue"
    :options="optionList"
    :postFunc="httpRequest"
    pathUrl="/api/select/options"
    multiple
    checkedAll
  />
</template>
```

* * *

### 3\. BnDrop - 下拉菜单选择器

**功能描述**：自定义下拉选择组件，支持单选/多选、远程搜索、分页加载。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | Any | {} | 绑定值 |
| options | Array | \[\] | 选项列表 |
| placeholder | String | '请选择' | 占位符 |
| multiple | Boolean | false | 是否多选 |
| labelInValue | Boolean | true | 是否返回对象 |
| canUncheck | Boolean | true | 单选是否可取消 |
| width | Number | 200 | 下拉框宽度 |
| border | Boolean | false | 是否显示边框 |
| clearable | Boolean | false | 是否可清空 |

**使用示例**：

```vue
<template>
  <BnDrop 
    v-model="dropValue"
    :options="menuOptions"
    placeholder="请选择菜单"
    @change="handleChange"
  />
</template>
```

* * *

### 4\. BnCondition - 规则条件配置

**功能描述**：规则引擎条件配置组件，支持选择字段、设置计算条件、配置值类型。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | Object | \- | 绑定值 |
| columnList | Array | \[\] | 可选字段列表 |
| columnData | Object | \- | 当前字段完整数据 |
| allowSelectColumn | Boolean | false | 是否允许选择字段 |
| allowDel | Boolean | true | 是否允许删除 |
| allowValueType | Boolean | true | 是否显示值类型选择 |
| searchTypes | Object | {} | 自定义计算条件 |
| valueTypes | Object | {} | 自定义值类型 |
| optionProps | Object | 见代码 | 字段映射配置 |
| postFunc | Function | \- | 请求方法 |

**使用示例**：

```vue
<template>
  <BnCondition 
    v-model="ruleValue"
    :columnList="columns"
    allowSelectColumn
    allowDel
    @change="handleChange"
    @del="handleDelete"
  />
</template>
```

* * *

### 5\. BnAdvancedFilter - 高级筛选

**功能描述**：高级筛选条件配置组件，是 BnCondition 的简化版，用于列表筛选场景。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | Object | \- | 绑定值 |
| columnList | Array | \[\] | 可选字段列表 |
| allowSelectColumn | Boolean | false | 是否允许选择字段 |
| allowDel | Boolean | true | 是否允许删除 |
| searchTypes | Object | {} | 自定义计算条件 |
| optionProps | Object | 见代码 | 字段映射配置 |
| postFunc | Function | \- | 请求方法 |

* * *

### 6\. BnSmartForm - 智能表单

**功能描述**：动态表单渲染组件，根据字段配置自动渲染各类表单组件，支持联动、校验、数据回填等高级功能。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| id | String/Number | \- | 表单ID（编辑时使用） |
| components | Array | \- | 组件列表配置 |
| editType | String | \- | 编辑类型：新建/编辑/复制 |
| postFunc | Function | \- | 请求方法 |
| extendPost | Object | \- | 扩展参数 |
| extraInfo | Object | \- | 扩展信息 |
| dataBack | Object | \- | 数据回填规则 |

**方法**：

| 方法名 | 说明 |
| --- | --- |
| getFormContent() | 获取表单内容 |
| checkFormContent() | 校验表单 |
| getHere(item) | 滚动到指定字段 |

**使用示例**：

```vue
<template>
  <BnSmartForm 
    ref="smartForm"
    :id="formId"
    :components="componentList"
    :postFunc="httpRequest"
    :extendPost="{appId: 'xxx', tableCode: 'xxx'}"
    @change="handleChange"
  />
  <el-button @click="saveForm">保存</el-button>
</template>

<script setup>
import { ref } from 'vue'
const smartForm = ref(null)
const formId = ref('')
const componentList = ref([])

const saveForm = () => {
  const check = smartForm.value.checkFormContent()
  if (check.checked) {
    const content = smartForm.value.getFormContent()
    // 提交表单数据
  }
}
</script>
```

* * *

### 7\. BnDatePicker - 日期选择器

**功能描述**：增强版日期选择组件，支持日期范围、日期时间、自定义格式。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| type | String | 'daterange' | 选择器类型 |
| modelValue | Any | \- | 绑定值 |
| startKey | String | 'start' | 开始时间键名 |
| endKey | String | 'end' | 结束时间键名 |
| dataFormat | String | \- | 日期格式 |
| disabled | Boolean | false | 是否禁用 |
| clearable | Boolean | true | 是否可清空 |
| placeholder | String | '选择日期' | 占位符 |
| rangeSeparator | String | '-' | 范围分隔符 |

**使用示例**：

```vue
<template>
  <BnDatePicker 
    v-model="dateRange"
    type="daterange"
    dataFormat="YYYY-MM-DD"
  />
</template>
```

* * *

### 8\. BnRelation - 级联选择器

**功能描述**：基于 Element Plus Cascader 封装的级联选择组件。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | Array | \- | 绑定值 |
| options | Array | \[\] | 选项数据 |
| multiple | Boolean | false | 是否多选 |
| checkStrictly | Boolean | false | 是否可选择任意层级 |
| collapseTags | Boolean | true | 是否折叠展示 |
| showAllLevels | Boolean | true | 是否显示完整路径 |
| separator | String | '-' | 分隔符 |
| placeholder | String | '请选择' | 占位符 |

* * *

### 9\. BnCheck - 复选框

**功能描述**：自定义复选框组件，支持单选/多选模式、自定义选中值。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | Any | \- | 绑定值 |
| trueData | Any | \- | 选中时的值 |
| falseData | Any | \- | 未选中时的值 |
| label | String | \- | 显示文本 |
| disabled | Boolean | false | 是否禁用 |
| isChecked | Function | \- | 自定义选中判断函数 |

**使用示例**：

```vue
<template>
  <BnCheck 
    v-model="checkValue"
    :trueData="'1'"
    :falseData="'0'"
    label="启用"
  />
</template>
```

* * *

### 10\. BnMenus - 菜单导航

**功能描述**：侧边栏菜单组件，支持多级菜单。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| title | String | \- | Logo区域标题 |
| menuList | Array | \[\] | 菜单列表 |
| activeNav | Object | \- | 当前选中菜单 |
| activeKey | String | 'name' | 菜单标识键名 |
| defaultOpens | Array | \- | 默认展开的菜单 |

**使用示例**：

```vue
<template>
  <BnMenus 
    title="工单系统"
    :menuList="menus"
    v-model:activeNav="currentMenu"
  />
</template>
```

* * *

### 11\. BnColumnConfig - 字段配置

**功能描述**：表单字段配置组件，用于配置字段的基本信息、默认值、权限等。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | Object | \- | 字段配置对象 |
| row | Number | 1 | 布局列数 |
| hideFiled | Array | \[\] | 需要隐藏的配置项 |
| columnList | Array | \[\] | 字段列表 |
| disabled | Boolean | false | 是否禁用 |
| postFunc | Function | \- | 请求方法 |
| extendPost | Object | \- | 扩展参数 |

* * *

### 12\. BnFunExpr - 函数表达式编辑器

**功能描述**：函数表达式编辑组件，支持选择函数、字段，编写计算公式。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| columnList | Array | \[\] | 字段列表 |
| postFunc | Function | \- | 请求方法 |
| id | String/Number | \- | 函数规则ID |
| setToColumn | Object | \- | 目标字段 |

**方法**：

| 方法名 | 说明 |
| --- | --- |
| saveRule() | 保存规则，返回配置对象 |

* * *

### 13\. BnOrderCard - 订单卡片

**功能描述**：工单详情页订单信息展示组件，展示订单基本信息、商品列表、备注等。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| postFunc | Function | \- | 请求方法 |
| extendPost | Object | {} | 扩展参数 |

* * *

### 14\. BnFileView - 文件预览

**功能描述**：附件预览组件，支持图片、视频、Office文档等多种文件类型的预览。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| fileList | Array | \[\] | 文件列表 |
| isMini | Boolean | false | 是否最小化展示 |
| isDel | Boolean | false | 是否允许删除 |
| showSize | Boolean | false | 是否显示文件大小 |
| width | Number/String | 22 | 图片宽度 |
| row | Number | 1 | 展示列数 |
| noWarp | Boolean | false | 是否强制不换行 |

**使用示例**：

```vue
<template>
  <BnFileView 
    :fileList="attachments"
    :isDel="true"
    :width="60"
    @delFile="handleDelete"
  />
</template>
```

* * *

### 15\. BnImportOrder - 批量导入

**功能描述**：工单批量导入组件，支持 Excel 文件上传导入。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| postFunc | Function | \- | 请求方法 |
| postData | Object | {} | 请求参数，需包含 tableCode、appId、tableId；appId/tableId 用于查询导入模板下拉 |
| pathUrl | String | '/biztable/io/import' | 导入接口地址 |

**方法**：

| 方法名 | 说明 |
| --- | --- |
| open() | 打开导入弹框，并获取版本限制和导入模板列表 |

* * *

### 16\. BnExportOrder - 数据导出

**功能描述**：工单数据导出组件，支持选择导出字段、验证码校验。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| postFunc | Function | \- | 请求方法 |
| cacheKey | String | \- | 缓存键值 |
| postData | Object | {} | 请求参数 |
| searchCondition | Object | {} | 筛选条件 |
| watchComponents | Array | \[\] | 可导出的字段列表 |

**方法**：

| 方法名 | 说明 |
| --- | --- |
| open(data) | 打开导出弹框 |

* * *

### 17\. BnOrderShare - 工单分享

**功能描述**：工单分享链接生成组件，支持生成网页端/移动端分享链接，以及手淘、抖音、京东等平台的长/短链接。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| tableId | String/Number | \- | 工单表 ID |
| appId | String/Number | \- | 应用 ID |
| tableCode | String | \- | 工单表 Code |
| companyId | String/Number | \- | 公司 ID |
| postFunc | Function | \- | 通用请求方法，用于获取分享配置及平台链接 |

**方法**：

| 方法名 | 参数 | 说明 |
| --- | --- | --- |
| open(taskId?) | taskId：工单ID（可选，传入则为编辑分享模式） | 打开分享弹框 |

**使用示例**：

```vue
<template>
  <BnOrderShare
    ref="orderShare"
    :table-id="tableInfo.tableId"
    :app-id="tableInfo.appId"
    :table-code="tableInfo.tableCode"
    :post-func="post"
  />
  <el-button @click="openShare">分享</el-button>
</template>

<script setup>
import { ref } from 'vue'
const orderShare = ref(null)
const openShare = () => {
  orderShare.value.open()         // 创建分享
  // orderShare.value.open(taskId) // 编辑分享
}
</script>
```

### 18\. BnVirtPopover - 虚拟滚动 Popover

**功能描述**：基于虚拟滚动的大数据量 Popover 组件。

**Props 参数**：

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| width | Number/String | 220 | 弹窗宽度 |

* * *

### 19\. BnInpNum - 数字输入框

**功能描述**：数字输入组件。

* * *

### 20\. BnRadio - 单选框

**功能描述**：单选框组件。

* * *

### 21\. BnWebLog - 接口日志

**功能描述**：接口请求日志记录与展示组件。

* * *

## 工具函数

组件库提供了以下工具函数：

```javascript
import { 
  idsToTexts,           // ID数组转文本
  insertText,           // 向输入框插入文本
  tidyRuleComponents,   // 整理规则组件列表
  searchValueToJson,    // 筛选值转JSON
  getSearchComponents,  // 获取筛选组件列表
  getWatchComponents,   // 获取查看组件列表
  tidyComponents,       // 整理组件列表
  tidyShowSubDataFile,  // 整理子表单附件数据
  tidyJumpSearchData,   // 整理跳转筛选数据
  recordApiLog          // 记录API日志
} from '@bytenew/bn-bus-ui'
```

## 开发说明

### 本地开发

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建
npm run build

# 预览构建结果
npm run serve
```

### 项目结构

```
BnBusUi/
├── packages/           # 组件源码
│   ├── BnAddress/     # 地址选择器
│   ├── BnSelect/      # 高级选择器
│   ├── BnCondition/   # 规则条件
│   ├── BnSmartForm/   # 智能表单
│   └── ...
├── examples/          # 示例代码
├── install.js         # 组件库入口
├── vite.config.js     # Vite 配置
└── package.json       # 包配置
```

## 浏览器兼容性

-   Chrome >= 80
-   Firefox >= 75
-   Safari >= 13
-   Edge >= 80

## 版本信息

-   当前版本：1.1.331
-   作者：辛巴
-   许可证：ISC

## 注意事项

1.  本组件库基于 Vue 3 开发，不兼容 Vue 2
2.  使用组件前请确保已引入 Element Plus
3.  部分组件需要传入 `postFunc` 方法用于数据请求
4.  组件库使用 Sass 预处理器，需要配置相应的构建工具支持

## 常见问题

### @bytenew/bn-bus-ui 是什么？

班牛业务组件库，集合版

### 如何安装 @bytenew/bn-bus-ui？

在项目目录运行 npm install @bytenew/bn-bus-ui，或使用 pnpm add / yarn add / bun add。

### @bytenew/bn-bus-ui 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bytenew\_\_bn-bus-ui 是否存在。

### @bytenew/bn-bus-ui 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bytenew/bn-bus-ui 可以商用吗？

@bytenew/bn-bus-ui 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bytenew/bn-bus-ui 的下载量有多少？

根据 npm 官方下载统计，@bytenew/bn-bus-ui 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,623 次，日均约 121 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bytenew/bn-bus-ui 还在维护吗？

最新版本 1\.1\.528 发布于 2026/11/06（2 天前）；至今共发布 128 个版本，其中过去 12 个月发布了 128 个；首次发布于 2026/05/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。