Guava Docs

Appearance

开发接入常见问题 ​

刚开始用 Guava UI 写代码，一堆报错看不懂？ 这里汇总了开发接入过程中最常碰到的问题，直接找你的场景。

环境准备相关 ​

Q: 依赖装不上或者启动报错怎么办？ ​

按这个顺序执行命令：

  1. 删除 pnpm-lock.yaml 和 node_modules
  2. 重新运行 pnpm install
bash
rm -rf node_modules pnpm-lock.yaml
pnpm install

Q: Node.js / pnpm 版本不对怎么办？ ​

工具要求版本
Node.js24.18.0
pnpm11.9.0

必须严格匹配

版本不一致会导致各种奇怪的构建和运行时问题。用 nvm use 24.18.0 切换。

Q: 项目路径有什么要求？ ​

路径不能有中文或空格，否则依赖安装和构建可能失败。

  • ✅ 正确：/Users/xxx/projects/guava-ui
  • ❌ 错误：/Users/xxx/我的项目/guava-ui

控制台报错相关 ​

Q: 控制台报 Vue Router 警告："Record with path xxx is either missing a component(s) or children property"？ ​

描述

原因：路由配置里写了某个页面，但对应的组件文件还没创建。

解决：把路由指向的组件文件建好就行了。

Q: 控制台报 "Uncaught (in promise) TypeError: l.iconName.startsWith is not a function"？ ​

描述

原因：把 Element Plus 的图标组件传给了 prefix-icon / suffix-icon，但 GvInput 只接受字符串名称。

vue
<!-- ❌ 错误：传了组件 -->
<GvInput :prefix-icon="Search" />

<!-- ✅ 正确：传字符串 -->
<GvInput prefix-icon="el-icon-search" />

Q: 控制台报 "The dicType needs to be set"？ ​

原因：GvSelect 没有设置 dic-type 属性。

vue
<!-- ✅ 正确 -->
<GvSelect v-model="value" dic-type="e#1=选项一:2=选项二" />

组件使用相关 ​

Q: 用组件时遇到问题，去哪查？ ​

  1. 先看组件文档，基本覆盖了大部分使用方式
  2. 如解决不了 → 提 Issue

Q: import 组件时为什么报"引入组件时报错"？ ​

引入组件时不要加 {}，否则会报错：

ts
// ✅ 正确
import { GuavaUI } from 'guava-ui';

// ❌ 错误：不要加花括号包裹单个组件

Q: import ts 文件时报错是怎么回事？ ​

和组件不同，引入 ts 文件或多个内容时必须加 {}：

ts
// ✅ 正确：ts 文件必须带花括号
import { debounce, throttle } from '@/utils';
import { a, b } from './utils';

Q: script 标签里代码报错，语法不生效？ ​

项目所有 script 都用的 TSX 语法，不要写 lang="ts"：

vue
<!-- ✅ 正确 -->
<script lang="tsx" setup>
// TSX 语法支持
</script>

<!-- ❌ 错误 -->
<script lang="ts" setup>
// 可能报语法错误
</script>

Q: 新增文件后编辑器报类型错误？ ​

原因：Vue (Official) 插件缓存问题。

解决：重启编辑器即可。

Q：我在页面的script标签里使用了组件，为什么提示找不到名称？ ​

描述

原因：因为项目使用的是 TSX 语法，全局导入的组件只对 .vue 文件的 <template> 有效。

解决：在 script 标签里引入对应的组件：

vue
<!-- ✅ 正确 -->
<script setup lang="tsx">
import { GvDatePicker } from 'guava-ui';

const formDataList = ref([
  // ...
  {
    type: 'text',
    format: [1, 'isDate', 10],
    label: '开始日期  ',
    prop: 'startDate',
    edit: true,
    width: 'auto',
    render: (scope: Recordable<any>) => (
      <div>
        <GvDatePicker size="small" type="date" disabled={!!scope.row.id} v-model={scope.row.startDate} />
      </div>
    )
  }
  // ...
]);
</script>

Q：我的table表格右侧顶部为什么没有搜索框？ ​

如下图，为什么我的table表格右侧顶部没有红色标记2区域的搜索框？

描述

原因是少设置了参数 query。表头数据结构中设置 query: true 即可。当 query: true 时，表格顶部会显示全局搜索框。全局搜索过滤条件为设置了 query: true 的字段，未设置 query: true 的字段不参与全局搜索。上图中参与全局搜索的字段是绿色标记区域中的3个字段。

typescript
{
  label: '用户账号',
  prop: 'u@account',
  fixed: 'left',
  query: true,
  width: 'auto'
},

功能相关 ​

Q: 菜单怎么是动态生成的？想自定义菜单怎么办？ ​

菜单是根据路由配置动态生成的。要自定义菜单，改路由配置就行。

TIP

确保路由配置和实际目录结构一致，否则菜单会显示异常。

Q: 要嵌入外部系统的页面需要怎么办？ ​

在路由配置router/index.ts里添加静态路由配置，创建路由对应组件文件，在组件中引入外部页面（如 iframe）地址即可。

Q: 数据来源是多个表时，表头搜索项报错？ ​

原因：多表联查时字段没有加别名，导致 SQL 解析歧义。

解决：筛选字段用 表别名@字段名 格式：

typescript
<!-- ✅ 正确 -->
{
  type: 'text',
  format: [0, 'isAny', 30],
  label: '应收单号',
  field: 'obo@billNo'  // 表别名@字段名
},

Q: 翻页后复选框回调获取不到值？ ​

原因：DOM 更新是异步的，翻页后立即获取勾选值可能还没渲染完。

解决：加一行 await sleep(1) 等待渲染完成：

typescript
<!-- ✅ 正确 -->
await sleep(1); // 必须加，否则可能获取不到勾选的值
// 然后获取选中的值

升级维护相关 ​

Q: 升级 guava-ui 版本？ ​

常规升级：

  1. 项目根目录下控制台执行命令行
bash
pnpm guava:upgrade
  1. 查看升级内容，调整项目中受影响的代码

Q: 使用了pnpm guava:upgrade后，未生效？ ​

1.删除旧依赖和锁文件

typescript
// mac 
rm -rf node_modules pnpm-lock.yaml package-lock.json

// windows
rmdir /s /q node_modules
del /q pnpm-lock.yaml package-lock.json

2.重新安装依赖并启动项目

bash
pnpm install && pnpm dev

3.查看升级内容，调整项目中受影响的代码