# @cntransun/gbos 中文文档

规范地址：https://npmcn.com/package/%40cntransun/gbos/

版本：0\.1\.68
npm 元数据更新时间：2026-11-10T00:37:53.264Z
中文译文更新时间：2026-11-10T04:42:59.162Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cntransun/gbos
原文对照：https://npmcn.com/package/%40cntransun/gbos/?lang=original

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

- 包体积（解压后）：1.4 MB，5 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：vue ^3\.5\.0，echarts \>=5\.5\.0，maptalks ^1\.12\.0，@maptalks/gl ^0\.124\.0，@maptalks/vt ^0\.124\.0，element-plus ^2\.14\.0，maptalks\.markercluster ^0\.10\.0，@element-plus/icons-vue ^2\.3\.0
- 首次发布：2026-10-06T12:39:39.521Z
- 最新版本发布：2026-11-10T00:37:53.102Z
- 近 30 天下载量：6884（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：69（近 12 个月 69 个）

## 中文简介

G-BOS共享Vue组件

## 安装

```sh
npm install @cntransun/gbos
```

也可以使用：`pnpm add @cntransun/gbos`、`yarn add @cntransun/gbos`、`bun add @cntransun/gbos`

## README

# @cntransun/gbos

G-BOS 前端公共组件库。

## 安装

```bash
npm install @cntransun/gbos element-plus @element-plus/icons-vue
```

使用地图相关组件时，还需安装：

```bash
npm install maptalks maptalks.markercluster @maptalks/gl @maptalks/vt
```

使用图表组件时，还需安装：

```bash
npm install echarts
```

Peer 依赖：`vue ^3.5`、`element-plus ^2.14`、`@element-plus/icons-vue ^2.3`；地图相关为 `maptalks`、`maptalks.markercluster`、`@maptalks/gl`、`@maptalks/vt`；图表为 `echarts >=5.5`。

### 接入

```javascript
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import { install } from '@cntransun/gbos'
import '@cntransun/gbos/style.css'
import request from '@/utils/request'

const app = createApp(App)

app.use(ElementPlus)
app.use({ install }, {
  request, // 必填，与宿主 HTTP 封装一致
  locale: getLocale, // 可选：'zh_CN' | 'en_US'，或返回上述值的函数
})
```

| `install` 参数 | 说明 |
| --- | --- |
| `request` | 必填，请求方法 |
| `locale` | 可选，`zh_CN` / `en_US` 或 `() => locale`；未传则读 `localStorage['app-locale']` |

安装后全局注册：`VehicleTreePanel`、`VehicleTreeSelect`、`VirtualTreeSelect`、`CompanyTreePanel`、`CompanyTreeSelect`、`CustomMap`、`ResizablePanel`、`CustomDatePicker`、`CustomDatetimePicker`、`CustomVirtualTree`、`CustomEchart`、`TableColumnSetting`、`CustomDialog`。

同时挂到原型：`this.$centerAlert`（居中提示）、`this.$modal`（顶部提示和确认框）。宿主在 `install` 之前已经设置过 `$modal` 时，保留宿主的，不覆盖。

`this.$modal` 方法：`msg`、`msgSuccess`、`msgError`、`msgWarning`、`confirm`、`alert`。消息和弹框会挂到无界主应用的 `body`。也可 `import { modal } from '@cntransun/gbos'` 自行挂载。

也可按需具名导入：

```javascript
import {
  VehicleTreePanel,
  VehicleTreeSelect,
  VirtualTreeSelect,
  CompanyTreePanel,
  CompanyTreeSelect,
  CustomMap,
  ResizablePanel,
  CustomDatePicker,
  CustomDatetimePicker,
  CustomVirtualTree,
  CustomEchart,
  TableColumnSetting,
  CustomDialog,
  centerAlert,
  modal,
  showVehicleExpiredStatus,
  showVehicleScrappedStatus,
  showVersionUpdate,
} from '@cntransun/gbos'
```

* * *

## 组件

### VehicleTreePanel

车辆组织树面板（全部 / 收藏 / 分组）。

**标签：** `<vehicle-tree-panel>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `multiple` | `Boolean` | `true` | 是否多选；`false` 时不显示复选框，点击车辆即选中 |
| `border` | `Boolean` | `true` | 是否显示 tabs 外边框 |
| `onlyAll` | `Boolean` | `false` | 仅显示「全部」树，不展示收藏/分组 Tab |
| `showCheckLinkSwitch` | `Boolean` | `false` | 「全部」树是否显示父子联动开关 |
| `showSummary` | `Boolean` | `true` | 「全部」树是否显示车辆汇总（顶栏快捷筛选 + 筛选面板内汇总） |
| `showChannel` | `Boolean` | `true` | 是否显示视频通道 |

| 事件 | 说明 |
| --- | --- |
| `check` | `{ vehicles, channels, raw, tab }` |
| `nodeClick` | `{ vehicles, channels, tab }` |
| `nodeDblClick` | `{ vehicles, channels, tab }` |
| `ready` | 「全部」树数据和虚拟树 DOM 挂载完成。组织列表为空时不触发；数据刷新后会再次触发。适合在回调里调用 `setCurrentHighlightVehicle` |

| 方法（ref） | 说明 |
| --- | --- |
| `setCheckVehicles(vehicleIds)` | 在「全部」Tab 追加勾选车辆 |
| `clearCheckVehicles()` | 清除「全部」Tab 勾选 |
| `getCheckedVehicles()` | 返回「全部」Tab 当前选中的车辆数组。多选含半选（只勾了部分通道）；单选为当前高亮车辆。不在「全部」Tab 时返回 `[]` |
| `filterByVehicleIds(vehicleIds)` | 「全部」Tab 只显示传入的车辆 id。传 `null` 取消这层过滤。关键字、汇总筛选仍然同时生效 |
| `setCurrentHighlightVehicle(vehicleId)` | 仅单选、且当前为「全部」Tab。展开父组织、滚动到该行，并在树顶显示可关闭的「当前车辆」条 |
| `setTabActive(tab)` | 设置 Tab：`all` / `favorite` / `group` |

```vue
<vehicle-tree-panel
  :show-check-link-switch="true"
  :show-summary="true"
  @check="onCheck"
/>
```

* * *

### VehicleTreeSelect

车辆树下拉选择（Popover + 树）。

**标签：** `<vehicle-tree-select>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` / `v-model` | `String | Array` | `''` | 单选：`vehicleId`；多选：`vehicleId[]` |
| `placeholder` | `String` | `''` | 空则使用包内「请选择车辆」文案 |
| `clearable` | `Boolean` | `true` | 是否可清空 |
| `disabled` | `Boolean` | `false` | 是否禁用 |
| `multiple` | `Boolean` | `true` | 是否多选 |
| `showCheckLinkSwitch` | `Boolean` | `false` | 「全部」树是否显示父子联动开关 |
| `width` | `String | Number` | `200` | 输入框宽度 |
| `popoverWidth` | `Number` | `320` | 下拉面板宽度（px） |
| `popoverHeight` | `Number` | `420` | 下拉面板高度（px） |
| `appendTo` | `String | Object` | `undefined` | 下拉挂载节点 |

| 事件 | 说明 |
| --- | --- |
| `update:modelValue` | 选中值变化 |
| `change` | `{ value, vehicles, tab? }` |

外部修改 `v-model` 时，只同步**当前 Tab**（全部 / 收藏 / 分组）的勾选，其它 Tab 保持原样。

```vue
<vehicle-tree-select v-model="vehicleIds" multiple />
```

* * *

### VirtualTreeSelect

通用虚拟化树形下拉（单选 / 多选）。

**标签：** `<virtual-tree-select>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` / `v-model` | `String | Number | Array` | `undefined` | 选中值；多选为数组 |
| `data` | `Array` | `[]` | 树数据 |
| `props` | `Object` | `{}` | 字段映射：`{ value, label, children, disabled }` |
| `placeholder` | `String` | `'请选择'` | 占位文案 |
| `clearable` | `Boolean` | `true` | 是否可清空 |
| `filterable` | `Boolean` | `true` | 是否可搜索 |
| `disabled` | `Boolean` | `false` | 是否禁用 |
| `multiple` | `Boolean` | `false` | 是否多选 |
| `showCheckLinkSwitch` | `Boolean` | `true` | 多选时是否显示底部「父子联动」开关 |
| `checkStrictly` | `Boolean` | `false` | 父子是否不关联（`true` 各自独立） |
| `collapseTags` | `Boolean` | `false` | 多选是否折叠 tag |
| `collapseTagsTooltip` | `Boolean` | `false` | 折叠 tag 是否显示 tooltip |
| `height` | `Number` | `undefined` | 固定高度；传入后不自适应 |
| `maxHeight` | `Number` | `260` | 自适应时最大高度 |
| `itemSize` | `Number` | `26` | 节点行高 |
| `onlyLeaf` | `Boolean` | `false` | 是否只能选叶子 |
| `defaultExpandedKeys` | `Array` | `undefined` | 默认展开 key；不传则展开第一项 |
| `popperClass` | `String` | `'virtual-tree-select-popper'` | 下拉 popper class |
| `teleported` | `Boolean` | `true` | 是否 teleport 到 `appendTo` |
| `appendTo` | `String | Object` | `undefined` | 下拉挂载节点 |
| `fallbackLabel` | `String` | `''` | 单选时 id 不在树中的回显文案 |
| `nodeIcon` | `String` | `undefined` | 节点图标 name；未传不显示 |

| 事件 | 说明 |
| --- | --- |
| `update:modelValue` | 选中值变化 |
| `change` | 单选：`(value, node)`；多选：`(keys, nodes)` |
| `clear` | 清空 |
| `visible-change` | 下拉显隐 |
| `remove-tag` | 多选移除 tag |

| 插槽 | 说明 |
| --- | --- |
| `default` | `{ node, data }` 自定义树节点 |
| `fallback-option` | id 不在树中时的隐藏 option，用于回显 |

```vue
<virtual-tree-select
  v-model="deptIds"
  multiple
  :data="treeData"
  :props="{ value: 'id', label: 'label', children: 'children' }"
/>
```

* * *

### CompanyTreePanel

组织树侧栏面板。

**标签：** `<company-tree-panel>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `multiple` | `Boolean` | `false` | 是否多选（勾选框） |
| `checkStrictly` | `Boolean` | `false` | 多选时父子是否不联动（未展示底部开关时生效） |
| `showCheckLinkSwitch` | `Boolean` | `true` | 多选时是否显示底部「父子联动」开关 |
| `showFleet` | `Boolean` | `true` | 是否显示车队；`true` 调 `getOrgTree`，`false` 调 `getOperableOrgTree` |
| `visible` / `v-model:visible` | `Boolean` | `true` | 面板显隐 |

| 事件 | 说明 |
| --- | --- |
| `node-click` | 单选节点数据；再次点击当前节点为 `null` |
| `check` | `(nodeData, info)` |
| `check-change` | `(checkedNodes, checkedKeys, info)` |

```vue
<company-tree-panel v-model:visible="show" @node-click="onNode" />
```

* * *

### CompanyTreeSelect

公司树下拉（内部请求公司列表并封装 VirtualTreeSelect）。

**标签：** `<company-tree-select>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` / `v-model` | `String | Number | Array` | `undefined` | 单选：公司 id；多选：id 数组 |
| `queryType` | `Number` | `1` | 接口 `queryType` |
| `queryParams` | `Object` | `{}` | 额外查询参数 |
| `placeholder` | `String` | `''` | 空则使用「请选择公司」 |
| `clearable` | `Boolean` | `true` | 是否可清空 |
| `filterable` | `Boolean` | `true` | 是否可搜索 |
| `disabled` | `Boolean` | `false` | 是否禁用 |
| `multiple` | `Boolean` | `false` | 是否多选 |
| `showCheckLinkSwitch` | `Boolean` | `true` | 多选是否显示父子联动开关 |
| `checkStrictly` | `Boolean` | `false` | 父子是否不关联 |
| `collapseTags` | `Boolean` | `false` | 多选折叠 tag |
| `collapseTagsTooltip` | `Boolean` | `false` | 折叠 tag tooltip |
| `onlyLeaf` | `Boolean` | `false` | 是否只能选叶子 |
| `width` | `String | Number` | `220` | 宽度 |
| `appendTo` | `String | Object` | `undefined` | 下拉挂载节点 |
| `teleported` | `Boolean` | `true` | 是否 teleport |
| `fallbackLabel` | `String` | `''` | id 不在树中的回显文案 |

| 事件 | 说明 |
| --- | --- |
| `update:modelValue` | 选中值变化 |
| `change` | `(value, nodeOrNodes)` |
| `clear` | 清空 |
| `visible-change` | 下拉显隐 |
| `remove-tag` | 多选移除 tag |
| `loaded` | `(treeData)` 树加载完成 |

| 方法（ref） | 说明 |
| --- | --- |
| `reload()` | 重新请求公司树 |

```vue
<company-tree-select v-model="deptId" @change="onCompanyChange" />
```

* * *

### CustomMap

地图组件（maptalks）。

**标签：** `<custom-map>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `supportedMapTypes` | `Array` | `undefined` | 可选底图：`baidu` / `gaode` / `google`；有非空数组则用 prop，否则读用户习惯 |

| 事件 | 说明 |
| --- | --- |
| `ready` | `(map, maptalks, mapType, ClusterLayer)` |
| `mapTypeChange` | 当前底图类型 |

| 插槽 | 说明 |
| --- | --- |
| 默认 | `{ map }` 自定义浮层 |

```vue
<custom-map @ready="onMapReady" />
```

* * *

### ResizablePanel

可拖拽调宽面板。

**标签：** `<resizable-panel>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `width` / `v-model:width` | `Number` | `280` | 面板宽度（px） |
| `min` | `Number` | `200` | 最小宽度 |
| `max` | `Number` | `600` | 最大宽度 |
| `edge` | `String` | `'right'` | 拖拽边：`left` / `right` |

| 事件 | 说明 |
| --- | --- |
| `update:width` | 拖拽后的新宽度 |

```vue
<resizable-panel v-model:width="panelWidth" :min="280" :max="480">
  <!-- 内容 -->
</resizable-panel>
```

* * *

### CustomDatePicker

基于 `el-date-picker` 的日期选择器；除自身 props 外透传 Element Plus DatePicker 属性。

**标签：** `<custom-date-picker>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` / `v-model` | `String | Number | Date | Array` | — | 选中值 |
| `allowToday` | `Boolean` | `false` | 是否允许选当天；`false` 时最大可选到昨天 |
| `appendTo` | `String | Object` | `undefined` | 弹层挂载节点；默认无界下挂主应用 body |
| `showThisWeek` | `Boolean` | `true` | 是否显示「本周」 |
| `showThisMonth` | `Boolean` | `true` | 是否显示「本月」 |
| `showPrevMonth` | `Boolean` | `false` | 是否显示「上月」（上一个自然月月初到月末，不受 `allowToday` 影响） |
| `showLastWeek` | `Boolean` | `true` | 是否显示「近一周」 |
| `showLastMonth` | `Boolean` | `true` | 是否显示「近一个月」 |
| `showLastYear` | `Boolean` | `true` | 是否显示「近一年」 |

`type="daterange"` 且未传 `shortcuts` 时，按上表开关生成默认快捷项；传入 `shortcuts` 时以外面的为准。范围跨度最大 365 天。

```vue
<custom-date-picker
  v-model="dateRange"
  type="daterange"
  value-format="YYYY-MM-DD"
  :allow-today="false"
  :show-last-year="false"
/>
```

* * *

### CustomDatetimePicker

基于 `el-date-picker` 的日期时间范围选择器。默认 `datetimerange`，值格式 `YYYY-MM-DD HH:mm:ss`。快捷项为「今日」「昨日」，选中后是当天 `00:00:00` 到 `23:59:59`。

**标签：** `<custom-datetime-picker>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` / `v-model` | `String | Number | Date | Array` | — | 选中值 |
| `allowToday` | `Boolean` | `true` | 是否显示「今日」快捷项 |
| `allowYesterday` | `Boolean` | `true` | 是否显示「昨日」快捷项 |
| `clearable` | `Boolean` | `false` | 是否可清空 |
| `width` | `String | Number` | `360` | 选择器宽度 |
| `startPlaceholder` | `String` | `''` | 开始占位；空则用「开始日期」 |
| `endPlaceholder` | `String` | `''` | 结束占位；空则用「结束日期」 |
| `appendTo` | `String | Object` | `undefined` | 弹层挂载节点；默认无界下挂主应用 body |

今天之后的日期不可选。传入 `shortcuts` 时以外面的为准，其余 Element Plus DatePicker 属性照常透传。

```vue
<custom-datetime-picker
  v-model="queryParams.dateRange"
  :allow-today="true"
  :allow-yesterday="true"
  @change="onDateChange"
/>
```

* * *

### CustomEchart

基于 ECharts 的图表。修改 `options` 会整表替换配置。容器尺寸变化时自动 `resize`。

**标签：** `<custom-echart>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `options` | `Object` | `{}` | ECharts 配置，传入后 `setOption(options, true)` |
| `width` | `String` | `'100%'` | 宽度 |
| `height` | `String` | `'300px'` | 高度 |
| `className` | `String` | `'chart'` | 容器 class |

```vue
<custom-echart :options="chartOptions" height="360px" />
```

* * *

### TableColumnSetting

表格列显隐设置。直接改传入列对象的 `visible`。`persist` 为 `true` 时写入 `localStorage`，key 为「当前应用 + `cacheKey`」。无界下应用名取 `window.__WUJIE.id`（如 `base-module`），否则取地址第一段。基础应用缓存前缀仍是 `base-module-table-cols:`。

**标签：** `<table-column-setting>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` / `v-model` | `Array` | `[]` | 列配置：`{ prop, label, visible, disabled? }` |
| `width` | `Number | String` | `220` | 弹出层宽度 |
| `persist` | `Boolean` | `false` | 是否把显隐记到 `localStorage` |
| `cacheKey` | `String` | `''` | 缓存 key，`persist` 为 `true` 时建议必传 |

`disabled` 为 `true` 的列不参与全选。重置恢复为页面初次传入的显隐，并清掉这份缓存。

```vue
<table-column-setting v-model="columns" persist cache-key="user-list" />
```

* * *

### CustomDialog

封装 `el-dialog`，透传属性和插槽。默认挂到当前窗口的 `body`，传入 `appendTo` 可改挂载节点。

**标签：** `<custom-dialog>`

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` / `v-model` | `Boolean` | `false` | 是否显示 |
| `appendTo` | `String | Object` | 当前窗口 `body` | 弹窗挂载节点 |

其余属性和插槽与 `el-dialog` 相同。

```vue
<custom-dialog v-model="visible" title="标题" width="480px">
  内容
</custom-dialog>
```

* * *

## 方法

### `$centerAlert`

居中提示，无确认按钮。安装后使用 `this.$centerAlert`，也可 `import { centerAlert } from '@cntransun/gbos'`。

| 方法 | 说明 |
| --- | --- |
| `success(title, message?, options?)` | 成功 |
| `error(title, message?, options?)` | 失败 |
| `warning(title, message?, options?)` | 警告 |
| `info(title, message?, options?)` | 信息 |
| `loading(title?, message?)` | 加载中，不可点遮罩或按 Esc 关闭；返回关闭函数 |

短文案时弹窗较窄，文字变长会加宽，超过上限后在框内换行。`options` 会覆盖 `ElMessageBox.alert` 的默认配置。

```javascript
this.$centerAlert.success('操作成功', '数据已保存')

const close = this.$centerAlert.loading('处理中...', '请稍候')
close()
```

### `showVersionUpdate()`

版本更新提示，使用 `ElMessageBox.alert`，无确认按钮。图标在左、文案在右。图案暂时写死，倒计时固定 6 秒。倒计时结束执行 `window.top.location.reload()`。点关闭、遮罩或 Esc 只关掉提示，不刷新。返回关闭函数。

安装后也可使用 `this.$showVersionUpdate`。

```javascript
import { showVersionUpdate } from '@cntransun/gbos'

const close = showVersionUpdate()
close()
```

### `showVehicleExpiredStatus()`

车辆服务已到期提示。无确认按钮，点遮罩、关闭按钮或 Esc 关闭。包内车辆树在选中到期车辆时会自行调用；宿主也可单独引入。

```javascript
import { showVehicleExpiredStatus } from '@cntransun/gbos'

showVehicleExpiredStatus()
```

### `showVehicleScrappedStatus()`

车辆已停用/报废提示。交互与到期提示相同。包内组件不会调用，由宿主按需引入。

```javascript
import { showVehicleScrappedStatus } from '@cntransun/gbos'

showVehicleScrappedStatus()
```

## 常见问题

### @cntransun/gbos 是什么？

G-BOS共享Vue组件

### 如何安装 @cntransun/gbos？

在项目目录运行 npm install @cntransun/gbos，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.5\.0）、echarts（\>=5\.5\.0）、maptalks（^1\.12\.0）、@maptalks/gl（^0\.124\.0）、@maptalks/vt（^0\.124\.0）、element-plus（^2\.14\.0）、maptalks\.markercluster（^0\.10\.0）、@element-plus/icons-vue（^2\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cntransun/gbos 支持 TypeScript 吗？

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

### @cntransun/gbos 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cntransun/gbos 可以商用吗？

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

### @cntransun/gbos 的下载量有多少？

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

### @cntransun/gbos 还在维护吗？

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