vui-uniapp

Virtual UI (VUI)

基于 uni-app 的 Vue 3 跨端组件库 —— 49 个开箱即用的组件，一套代码同时跑 iOS / Android / H5 / 微信小程序等各家小程序。

官网：https://virtualman333.github.io/vui/

在线演示：https://virtualman333.github.io/vui/demo/ —— 含「组件总览」「AI 组件演示」「开发者测试」三个页面，桌面与手机浏览器直接打开即可，无需安装。

目录

• 特性
• 环境要求
• 安装
• 快速开始
• 主题定制
• 组件总览
• TypeScript 支持
• 常见问题
• 版本与发布
• 贡献指南
• 许可证

特性

• 跨端一致：iOS / Android / H5 / 各家小程序，一套代码多端运行
• AI 场景就绪：内置对话气泡、流式打字机、推理过程面板、Markdown 渲染、模型选择等 12 个 AI 组件
• 零配置引入：基于 easycom，配好一次后无需 import，直接写标签
• 可换肤：全部颜色收敛到 SCSS 变量，改一个 $vui-primary 即可全库换色
• 类型友好：内置 TypeScript 声明，编辑器可提示 props 与事件
• 零第三方依赖：不依赖任何 UI 框架，包体干净
• 独立成包：每个组件是独立 uni_module，也可只用其中几个

环境要求

安装

方式一：npm 安装 + easycom（推荐）

npm install vui-uniapp --save
# 或
yarn add vui-uniapp
# 或
pnpm add vui-uniapp

安装后在项目的 pages.json 里加入 easycom 配置：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^vui-(.*)": "vui-uniapp/uni_modules/vui-$1/components/vui-$1/vui-$1.vue"
    }
  }
}

配置完成后 不需要 import，在任意页面直接使用：

<template>
  <view class="page">
    <vui-button type="primary" @click="onClick">点我</vui-button>
    <vui-switch v-model="checked" />
  </view>
</template>

<script>
export default {
  data() {
    return { checked: true };
  },
  methods: {
    onClick() {
      console.log('clicked');
    }
  }
};
</script>

CLI 项目补充：如果组件没有正常编译，在 vite.config.js 中把包排除出预构建：

export default defineConfig({
  plugins: [uni()],
  optimizeDeps: { exclude: ['vui-uniapp'] }
});

方式二：全量注册（Vue3 插件）

不想配 easycom，也可以在入口一次性注册全部组件。

// main.js
import { createSSRApp } from 'vue';
import App from './App.vue';
import VUI from 'vui-uniapp';

export function createApp() {
  const app = createSSRApp(App);
  app.use(VUI); // 一次性注册全部组件
  return { app };
}

注册后 PascalCase 与 kebab-case 两种写法都可用，即 <VuiButton> 和 <vui-button> 等价。

方式三：uni_modules 本地导入

不使用 npm 时，把仓库中的 uni_modules 目录整体拷贝到你的项目根目录（或从 HBuilderX 插件市场导入本库）。uni-app 会自动扫描 uni_modules 下的组件，无需任何配置，直接使用即可。

这种方式不会把包体积算进 npm 依赖，适合只想用其中几个组件的场景。

快速开始

下面是一个包含表单校验、弹窗、消息提示的完整页面示例：

<template>
  <view class="page">
    <vui-card title="用户信息" shadow>
      <vui-form ref="formRef" :model="form" :rules="rules">
        <vui-form-item label="用户名" prop="username" required>
          <vui-input v-model="form.username" placeholder="请输入用户名" />
        </vui-form-item>
        <vui-form-item label="手机号" prop="mobile" required>
          <vui-input v-model="form.mobile" placeholder="请输入手机号" />
        </vui-form-item>
        <vui-form-item label="性别">
          <vui-radio-group>
            <vui-radio v-model="form.gender" label="男" :value="1" />
            <vui-radio v-model="form.gender" label="女" :value="2" />
          </vui-radio-group>
        </vui-form-item>
      </vui-form>

      <vui-button type="primary" @click="submit">提交</vui-button>
    </vui-card>

    <vui-message ref="message" />
    <vui-modal v-model="visible" title="提示" content="提交成功" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      visible: false,
      form: { username: '', mobile: '', gender: 1 },
      rules: {
        username: [{ required: true, message: '请输入用户名' }],
        mobile: [
          { required: true, message: '请输入手机号' },
          { pattern: /^1\d{10}$/, message: '手机号格式不正确' }
        ]
      }
    };
  },
  methods: {
    async submit() {
      const ok = await this.$refs.formRef.validate();
      if (!ok) return;
      this.visible = true;
      this.$refs.message.show('提交成功', 'success');
    }
  }
};
</script>

主题定制

VUI 的所有颜色都收敛为 SCSS 变量，并且在每个组件内部都有 !default 兜底。 你只需要在项目的 uni.scss 里重新赋值，即可全库生效，不需要改任何组件文件。

uni-app 会把 uni.scss 自动注入到所有组件的样式编译上下文，因此无需 @import。

/* uni.scss —— 把这部分加到你的项目里，按需修改 */

/* 功能色（品牌主色建议改 $vui-primary） */
$vui-primary: #2979ff;
$vui-success: #18bc37;
$vui-warning: #f3a73f;
$vui-error: #e43d33;
$vui-info: #8f939c;
$vui-region-active-color: #f07b00;

/* 文字色 */
$vui-text-color: #333;
$vui-text-color-regular: #606266;
$vui-text-color-secondary: #909399;
$vui-text-color-placeholder: #c0c4cc;
$vui-text-color-disabled: #e4e7ed; // 禁用态文字（比 placeholder 更淡）
$vui-text-color-inverse: #fff;

/* 边框色 */
$vui-border-color: #dcdfe6;
$vui-border-color-light: #ebeef5;
$vui-border-color-lighter: #e5e6eb;

/* 填充与背景色 */
$vui-bg-color: #fff;
$vui-bg-color-hover: #f2f3f5;
$vui-fill-color: #f1f1f1;
$vui-fill-color-light: #f5f7fa;
$vui-fill-color-lighter: #fafafa;
$vui-track-color: #ebedf0;
$vui-active-bg-color: #f5f9ff;
$vui-gray-color: #ccc;
$vui-white: #fff;

/* 代码块（深色底 + 配套前景），vui-code 与 vui-markdown 共用同一对变量 */
$vui-code-bg: #282c34;
$vui-code-color: #abb2bf;

例如只想换品牌主色：

/* uni.scss */
$vui-primary: #7166f0;

保存后重新编译，所有组件的主色（按钮、单选、复选、加载、进度条、步骤条等）会统一变成你设置的颜色。

说明：遮罩层与阴影使用的半透明黑 rgba(0,0,0,.x) 属于视觉层次而非主题色，因此保持中性、不随主题色变化。

组件总览

共 49 个组件、308 个属性、78 个事件。 完整 API（属性 / 事件 / 插槽）见 docs/API.md。

基础组件

表单组件

数据展示

反馈组件

媒体组件

AI 组件

TypeScript 支持

包内已包含类型声明（types/index.d.ts），无需额外安装 @types。

import { VuiButton, VuiTable } from 'vui-uniapp';
import type { VuiTableProps } from 'vui-uniapp';

同时注册了全局组件类型，在 <template> 中使用 <vui-button> 时也能获得属性提示。

常见问题

Q：组件不渲染 / 提示"未知组件"？

1. 确认 pages.json 的 easycom.custom 路径写对了（注意结尾的 .vue）；
2. 修改 pages.json 后需要重启编译器才生效；
3. CLI 项目请参考上面「方式一」的补充配置。

Q：想只用其中几个组件，怎么减小体积？

用「方式一 easycom」或「方式三 uni_modules」：easycom 是按需引入的，只有页面里真正用到的组件才会被打包。

Q：小程序端样式不对？

小程序对 CSS 选择器支持有限。请确认没有在页面级样式里用后代选择器强行覆盖组件内部结构， 推荐通过 props 或主题变量来定制。另外 vui-scrollbar 这类依赖滚动事件的组件在小程序端表现与 H5 略有差异。

Q：支持 Vue 2 吗？

不支持。本项目按 Vue 3 编写（modelValue / update:modelValue 语义），请使用 uni-app 的 Vue 3 项目。

Q：如何调换某个组件的颜色而不影响其他组件？

给该实例传 color / activeColor 之类的 props（具体见 docs/API.md）， 或在页面里用更高优先级的作用域样式覆盖。

版本与发布

本仓库的硬性规则：任何一次面向用户的更新，都必须同步提升版本号并发布到 npm。 不允许出现「代码已改、版本没动」或「版本已升、包没发」的状态。

完整规则见 AGENTS.md（供 AI 协作助手遵循）与 CONTRIBUTING.md（供人阅读）。

一键发布

npm run release            # 修 bug / 样式 / 文档（patch）
npm run release -- minor   # 新增组件、新增 props/事件/插槽
npm run release -- major   # 删除或重命名 props、改变默认行为

npm run release 会依次完成：

第 0 步必须在最前面：第 3~7 步里 bump / commit / tag / push 都不可回退，tag 一推版本号就被占住了。所以「发布一定会失败」的原因要在任何写入之前查完，否则会留下 AGENTS.md 第一节明令禁止的「版本已升、tag 已推、包没发」。判据与自检分别见 scripts/release-preflight.js 与 scripts/check-release.js（check:all 会跑）。

加 --dry-run 可只跑校验与产物生成、不写入任何内容：

npm run release -- minor --dry-run

版本号规则

发布凭证

npm publish 需要带 Bypass 2FA 的 npm token（普通 token 会报 EOTP）。 把 token 写入项目级 .npmrc：

//registry.npmjs.org/:_authToken=<你的 token>

.npmrc 已在 .gitignore 中，不会被提交。token 格式必须以 npm_ 开头。

也可以用机器级的凭证（npm login 写入的 ~/.npmrc）。发布前 npm run release 会先实探一次 凭证是否真的可用（npm whoami），不只看 .npmrc 文件在不在 —— 一个只写了 registry 换源配置、没有 token 的 ~/.npmrc 会让「文件存在」的判断通过，然后一路走完 bump → commit → tag → push，最后才倒在 npm publish，把仓库留在半发布状态。 凭证不可用时，脚本会在任何写入之前中止，并给出唯一要做的那个动作。

贡献指南

我们欢迎任何贡献！完整流程见 CONTRIBUTING.md，摘要如下：

1. Fork 本仓库；
2. 创建分支（git checkout -b feature-name）；
3. 修改代码。若新增组件，请保持 uni_modules/vui-xxx/components/vui-xxx/vui-xxx.vue 的目录结构；
4. 新增组件后跑一次 python scripts/inject-theme.py 注入主题变量兜底块， 并在 scripts/gen-docs.py 的 CATEGORY 中登记该组件；
5. 运行 npm run check:all 确认无误（校验链的唯一来源，见 AGENTS.md 第八节）；
6. 按版本与发布提升版本号并发布（npm run release）；
7. 推送并创建 Pull Request。

请勿手工编辑自动生成的产物：index.js、types/index.d.ts、docs/API.md、README.md 均由脚本生成，改组件后跑 npm run gen 重新生成即可。

许可证

Virtual UI (VUI) 遵循 MIT 开源许可证。

联系

• GitHub Issues：https://github.com/virtualman333/vui/issues
• Email：virtualman@yeah.net
• WeChat：virtualman2001

贡献者

感谢以下贡献者对本项目做出贡献：

• Virtualman
• Alexander