TinyVue 组件库实战指南：从安装到上手一篇就够了

TinyVue 组件库实战指南：从安装到上手，一篇就够了

本文适合想快速上手 OpenTiny TinyVue 组件库的开发者，涵盖安装配置、核心组件使用、国际化、主题定制等内容，配有完整示例代码。

一、TinyVue 是什么？

TinyVue 是华为云 OpenTiny 团队开源的企业级 Vue 组件库，具备以下核心特点：

• 跨框架支持：一套代码，同时支持 Vue 2 和 Vue 3（通过适配层）
• 丰富组件：130+ 高质量组件，覆盖表单、表格、导航、反馈等场景
• 企业级设计：来自华为内部沉淀，适合 ToB 中后台系统
• 主题定制：支持 CSS 变量定制和完整主题包切换
• 国际化：内置多语言支持，覆盖中英文及更多语种

npm 包名：@opentiny/vue

官网地址：opentiny.design

---

二、快速安装

1. 安装依赖

# npm
npm install @opentiny/vue @opentiny/vue-theme

# yarn
yarn add @opentiny/vue @opentiny/vue-theme

# pnpm
pnpm add @opentiny/vue @opentiny/vue-theme

2. 全量引入（适合快速上手）

在 main.js 或 main.ts 中全量注册：

import { createApp } from 'vue'
import App from './App.vue'
import TinyVue from '@opentiny/vue'
import '@opentiny/vue-theme/index.less'

const app = createApp(App)
app.use(TinyVue)
app.mount('#app')

3. 按需引入（推荐，减小打包体积）

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import '@opentiny/vue-theme/index.less'

createApp(App).mount('#app')

<!-- 在组件中按需导入 -->
<script setup>
import { TinyButton, TinyInput, TinyForm, TinyFormItem } from '@opentiny/vue'
</script>

注意 ：在模板中使用组件时，组件名前缀统一用 tiny-，例如 <tiny-button>、<tiny-input>。

---

三、基础组件示例

3.1 Button 按钮

Button 是最基础的交互组件，支持多种类型和尺寸。

<template>
  <div>
    <!-- 类型 -->
    <tiny-button>默认</tiny-button>
    <tiny-button type="primary">主要</tiny-button>
    <tiny-button type="success">成功</tiny-button>
    <tiny-button type="warning">警告</tiny-button>
    <tiny-button type="danger">危险</tiny-button>

    <!-- 尺寸 -->
    <tiny-button size="large" type="primary">大号</tiny-button>
    <tiny-button size="medium" type="primary">中号</tiny-button>
    <tiny-button size="small" type="primary">小号</tiny-button>

    <!-- 禁用状态 -->
    <tiny-button type="primary" :disabled="true">禁用</tiny-button>

    <!-- 带图标 -->
    <tiny-button type="primary" :icon="IconSearch">搜索</tiny-button>
  </div>
</template>

<script setup>
import { TinyButton } from '@opentiny/vue'
import { IconSearch } from '@opentiny/vue-icon'
</script>

小提示 ：TinyVue 的图标与业界不同，图标是函数 （如 IconSearch），需要直接将函数引用传给 :icon prop，不需要调用执行。

---

3.2 Input 输入框

<template>
  <div>
    <!-- 基础输入框 -->
    <tiny-input v-model="value" placeholder="请输入内容" />

    <!-- 带清空按钮 -->
    <tiny-input v-model="value" clearable placeholder="可清空" />

    <!-- 密码框 -->
    <tiny-input v-model="password" type="password" show-password placeholder="请输入密码" />

    <!-- 文本域 -->
    <tiny-input
      v-model="textarea"
      type="textarea"
      :rows="4"
      placeholder="请输入多行文本"
    />

    <!-- 带前缀/后缀图标 -->
    <tiny-input v-model="value" :prefix-icon="IconSearch" placeholder="搜索..." />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyInput } from '@opentiny/vue'
import { IconSearch } from '@opentiny/vue-icon'

const value = ref('')
const password = ref('')
const textarea = ref('')
</script>

---

3.3 Form 表单

Form 是企业后台中最常用的组件，支持丰富的校验规则。

<template>
  <tiny-form
    ref="formRef"
    :model="formData"
    :rules="rules"
    label-width="100px"
  >
    <tiny-form-item label="用户名" prop="username">
      <tiny-input v-model="formData.username" placeholder="请输入用户名" />
    </tiny-form-item>

    <tiny-form-item label="邮箱" prop="email">
      <tiny-input v-model="formData.email" placeholder="请输入邮箱" />
    </tiny-form-item>

    <tiny-form-item label="性别" prop="gender">
      <tiny-radio-group v-model="formData.gender">
        <tiny-radio label="male">男</tiny-radio>
        <tiny-radio label="female">女</tiny-radio>
      </tiny-radio-group>
    </tiny-form-item>

    <tiny-form-item>
      <tiny-button type="primary" @click="handleSubmit">提交</tiny-button>
      <tiny-button @click="handleReset">重置</tiny-button>
    </tiny-form-item>
  </tiny-form>
</template>

<script setup>
import { ref, reactive } from 'vue'
import {
  TinyForm, TinyFormItem, TinyInput,
  TinyButton, TinyRadioGroup, TinyRadio
} from '@opentiny/vue'

const formRef = ref(null)

const formData = reactive({
  username: '',
  email: '',
  gender: ''
})

const rules = {
  username: [
    { required: true, message: '请输入用户名', trigger: 'blur' },
    { min: 3, max: 20, message: '用户名长度在 3 到 20 个字符', trigger: 'blur' }
  ],
  email: [
    { required: true, message: '请输入邮箱', trigger: 'blur' },
    { type: 'email', message: '请输入正确的邮箱格式', trigger: 'blur' }
  ],
  gender: [
    { required: true, message: '请选择性别', trigger: 'change' }
  ]
}

const handleSubmit = () => {
  formRef.value.validate((valid) => {
    if (valid) {
      console.log('表单数据：', formData)
    }
  })
}

const handleReset = () => {
  formRef.value.resetFields()
}
</script>

---

3.4 Grid 表格

Grid 是 TinyVue 的明星组件，专为大数据量场景设计，性能卓越。

<template>
  <tiny-grid :data="tableData" border>
    <tiny-grid-column type="index" width="60" title="序号" />
    <tiny-grid-column field="name" title="姓名" width="120" />
    <tiny-grid-column field="age" title="年龄" width="80" />
    <tiny-grid-column field="email" title="邮箱" min-width="200" />
    <tiny-grid-column field="status" title="状态" width="100">
      <template #default="{ row }">
        <tiny-tag :type="row.status === 'active' ? 'success' : 'danger'">
          {{ row.status === 'active' ? '正常' : '禁用' }}
        </tiny-tag>
      </template>
    </tiny-grid-column>
    <tiny-grid-column title="操作" width="160" fixed="right">
      <template #default="{ row }">
        <tiny-button type="text" @click="handleEdit(row)">编辑</tiny-button>
        <tiny-button type="text" @click="handleDelete(row)">删除</tiny-button>
      </template>
    </tiny-grid-column>
  </tiny-grid>
</template>

<script setup>
import { ref } from 'vue'
import { TinyGrid, TinyGridColumn, TinyButton, TinyTag } from '@opentiny/vue'

const tableData = ref([
  { id: 1, name: '张三', age: 28, email: 'zhangsan@example.com', status: 'active' },
  { id: 2, name: '李四', age: 32, email: 'lisi@example.com', status: 'inactive' },
  { id: 3, name: '王五', age: 25, email: 'wangwu@example.com', status: 'active' },
])

const handleEdit = (row) => {
  console.log('编辑：', row)
}
const handleDelete = (row) => {
  console.log('删除：', row)
}
</script>

---

四、布局系统

TinyVue 提供栅格布局系统，通过 TinyRow 和 TinyCol 组合实现响应式布局。

<template>
  <!-- 基础 24 列栅格 -->
  <tiny-row :gutter="16">
    <tiny-col :span="6">
      <div class="col-block">6列</div>
    </tiny-col>
    <tiny-col :span="12">
      <div class="col-block">12列</div>
    </tiny-col>
    <tiny-col :span="6">
      <div class="col-block">6列</div>
    </tiny-col>
  </tiny-row>

  <!-- 响应式断点 -->
  <tiny-row :gutter="16">
    <tiny-col :xs="24" :sm="12" :md="8" :lg="6">
      <div class="col-block">响应式列</div>
    </tiny-col>
    <tiny-col :xs="24" :sm="12" :md="8" :lg="6">
      <div class="col-block">响应式列</div>
    </tiny-col>
  </tiny-row>
</template>

<script setup>
import { TinyRow, TinyCol } from '@opentiny/vue'
</script>

<style scoped>
.col-block {
  background: #e8f4fd;
  border: 1px solid #409eff;
  text-align: center;
  padding: 12px 0;
  border-radius: 4px;
}
</style>

---

五、国际化配置

TinyVue 内置完整的国际化方案，切换语言非常便捷。

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import TinyVue from '@opentiny/vue'
import zhCN from '@opentiny/vue-locale/lib/zh-CN'
import enUS from '@opentiny/vue-locale/lib/en-US'
import '@opentiny/vue-theme/index.less'

const app = createApp(App)

// 配置中文（默认）
app.use(TinyVue, {
  locale: zhCN
})

app.mount('#app')

动态切换语言：

<template>
  <tiny-config-provider :locale="currentLocale">
    <div>
      <tiny-button @click="toggleLang">切换语言</tiny-button>
      <tiny-date-picker v-model="date" />
    </div>
  </tiny-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { TinyConfigProvider, TinyButton, TinyDatePicker } from '@opentiny/vue'
import zhCN from '@opentiny/vue-locale/lib/zh-CN'
import enUS from '@opentiny/vue-locale/lib/en-US'

const date = ref('')
const isZh = ref(true)
const currentLocale = ref(zhCN)

const toggleLang = () => {
  isZh.value = !isZh.value
  currentLocale.value = isZh.value ? zhCN : enUS
}
</script>

---

六、主题定制

方式一：CSS 变量覆盖（轻量级）

/* 在全局 CSS 中覆盖主色调 */
:root {
  --ti-base-color: #722ed1;       /* 主品牌色 */
  --ti-color-primary: #722ed1;
  --ti-color-primary-hover: #9254de;
  --ti-border-radius-base: 6px;   /* 圆角 */
}

方式二：使用主题包

# 安装主题工具
npm install @opentiny/vue-theme-tool -D

// vite.config.js
import { defineConfig } from 'vite'
import { themePreprocessorPlugin } from '@opentiny/vue-theme-tool'

export default defineConfig({
  plugins: [
    themePreprocessorPlugin({
      // 自定义主题变量
    })
  ]
})

---

七、常见问题 & 最佳实践

Q1：组件样式没有生效？

确保在入口文件中引入了样式：

import '@opentiny/vue-theme/index.less'

如果使用 Vite，确保 vite.config.js 中配置了 less 预处理器支持。

Q2：图标怎么使用？

TinyVue 图标是函数，不是字符串或组件，需要特别注意：

<script setup>
import { IconEdit, IconDelete } from '@opentiny/vue-icon'

// 正确：将函数传给 :icon prop
// 错误：不能写 :icon="IconEdit()" 或 :icon="'icon-edit'"
</script>

<template>
  <tiny-button :icon="IconEdit">编辑</tiny-button>
</template>

Q3：表格数据量很大时如何优化性能？

使用 TinyGrid 的虚拟滚动功能：

<tiny-grid
  :data="largeData"
  :scroll-y="{ enabled: true, gt: 100 }"
  height="500px"
>
  <!-- 列定义 -->
</tiny-grid>

Q4：如何在 TypeScript 项目中使用？

TinyVue 提供完整的类型声明，直接导入即可，无需额外配置：

import type { TinyFormInstance } from '@opentiny/vue'

const formRef = ref<TinyFormInstance | null>(null)

---

八、小结

TinyVue 是一款成熟的企业级组件库，其跨 Vue 2/3 的能力和华为内部场景打磨让它在 ToB 项目中表现出色。核心要点总结：

知识点	要点
安装	@opentiny/vue + @opentiny/vue-theme
模板写法	前缀用 tiny-，如 <tiny-button>
图标使用	函数引用，直接传给 :icon prop
布局	优先 TinyRow + TinyCol 栅格布局
表格	TinyGrid 适合大数据量，支持虚拟滚动
国际化	@opentiny/vue-locale 配合 TinyConfigProvider
主题	CSS 变量覆盖或使用主题包工具

希望这篇指南能帮助你快速上手 TinyVue！如果觉得有帮助，欢迎点个赞 👍

---

相关链接

• GitHub：github.com/opentiny/ti...
• 官网文档：opentiny.design/tiny-vue
• NPM：www.npmjs.com/package/@op...