注意事项

本文汇总使用 Vital Design 时的常见问题与建议。

安装与构建

Sass 编译警告或报错

组件库依赖 Sass。若出现 @import 废弃警告或 API 不兼容，请将 sass 版本控制在 1.62.x ~ 1.78.x，并参考 快速开始 - Sass 配置 additionalData。

easycom 不生效

请检查：

1. pages.json 中 easycom.custom 规则是否为 "^vd-(.*)": "vital-design/components/$1/$1.vue"
2. 组件名是否以 vd- 开头，且与目录名一致（如 vd-button → button/button.vue）
3. 使用 Vite 自动引入时，Components 插件是否注册在 Uni() 之前

样式变量未定义（如 $vd-primary）

需在 vite.config.ts 中配置：

css: {
  preprocessorOptions: {
    scss: {
      additionalData: '@import "@vital-design/styles";',
    },
  },
},

函数式调用

showToast / showDialog 报错「未找到组件实例」

showToast、showDialog、showNotify、showImagePreview 等函数式 API 依赖页面中已挂载的对应组件。请在布局根节点添加：

<vd-toast name="page" />
<vd-dialog name="page" />

多页面场景可为不同实例设置不同的 name，调用时通过 name 指定目标。

多个 Toast / Dialog 实例

同一页面存在多个实例时，函数式 API 默认操作最后一个可见实例。建议全局只保留一组函数式组件，或显式传入 name 区分。

主题与样式

修改主题色后部分组件未变化

请确认：

1. 变量是否写在 vd-config-provider 的 theme-vars 中，且组件位于其子孙节点内
2. 键名是否使用横杆形式（如 primary、radius-md），不要加 --vd- 前缀
3. 部分组件有独立 CSS 变量，需查阅对应组件文档中的「样式变量」章节

深色模式部分内容未切换

theme="dark" 仅影响 Vital Design 组件内置变量。业务自定义背景色、文字色需自行适配，或配合 useDark 在业务样式中切换。

国际化

切换语言后部分文案未更新

merge 仅作用于调用时的当前语言。切换语言后若需保留自定义文案，请在 use(name, config) 时一并传入，或在切换后再次 merge。

组件文案与业务文案

内置语言包只覆盖组件内部固定文案。页面标题、菜单、接口提示等请使用 vue-i18n 等方案单独管理。

小程序相关

自定义组件样式不生效

Vital Design 组件默认开启 virtualHost 与 addGlobalClass。在自定义组件中使用时，若样式穿透异常，可检查父级是否设置了 styleIsolation，必要时使用 :deep() 或全局类名。

列表循环中的子组件

GridItem、WaterfallItem、Tab、RateItem、DropdownItem、FabItem 等在小程序循环渲染时，建议显式传入 index，避免顺序或状态错乱。详见各组件文档的 index 属性说明。

页面滚动与 Swiper / List

Swiper 内嵌可滚动区域时，注意滑动方向冲突；List 需放在可纵向滚动的 Scroller 内，或通过 scroller 属性指定滚动容器名称。

TypeScript

模板中 vd-* 组件无类型提示

在 tsconfig.json 的 compilerOptions.types 中加入 vital-design/global.d.ts，并确保 include 包含该声明文件。使用 Vite 自动引入时，同时检查 components.d.ts 是否正常生成。

组件 ref 类型

各组件导出 *Instance 类型，可与 ref 配合使用：

import type { FormInstance } from 'vital-design';

const formRef = ref<FormInstance>();

性能建议

• 大列表优先使用 lazy-render（Tabs、Collapse 等已支持）
• 弹层类组件（Popup、Dialog）可开启 lazy-render 延迟渲染内容
• 图片较多时使用 Image 组件的懒加载，或配合 Waterfall / ImageGrid

获取帮助

• 查阅 组件文档 与示例项目 example/
• 查看 更新日志 了解近期变更
• 扫码体验见 介绍