@cntransun/gbos

G-BOS 前端公共组件库。

安装

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

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

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

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

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。

接入

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' 自行挂载。

也可按需具名导入：

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 |

<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 保持原样。

<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，用于回显 |

<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) |

<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() | 重新请求公司树 |

<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 } 自定义浮层 |

<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 | 拖拽后的新宽度 |

<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 天。

<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 属性照常透传。

<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 |

<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 的列不参与全选。重置恢复为页面初次传入的显隐，并清掉这份缓存。

<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 相同。

<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 的默认配置。

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

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

showVersionUpdate()

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

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

import { showVersionUpdate } from '@cntransun/gbos'

const close = showVersionUpdate()
close()

showVehicleExpiredStatus()

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

import { showVehicleExpiredStatus } from '@cntransun/gbos'

showVehicleExpiredStatus()

showVehicleScrappedStatus()

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

import { showVehicleScrappedStatus } from '@cntransun/gbos'

showVehicleScrappedStatus()