---
name: tabler-vue-usage
description: Tabler-Vue 组件库使用指南 — 在项目中如何正确使用各类组件 / Component library usage guide for AI assistants
encoding: utf-8
charset: utf-8
---

# Tabler-Vue 组件库使用技能
# Tabler-Vue Component Library Skills

本文件定义一组技能（Skills），供 AI 助手在协助用户使用 `@gulcc/tabler-vue` 组件库时调用。每个技能对应一个常见的开发场景，描述了该场景下应使用的组件、Tabler CSS 类名和代码模式。

> 本文件为宏观使用指南。每个组件的详细 API 和代码示例见 `<CurrentUrl />/skills/{组件名}/SKILL.md`。
> This file is a macro-level usage guide. For detailed API and code examples per component, see `<CurrentUrl />/skills/{ComponentName}/SKILL.md`.

---

## 🤖 AI 生成规则 / AI Generation Rules

| # | 中文 | English |
|---|------|---------|
| 1 | 必须使用 Vue 3 `<script setup lang="ts">` + Composition API，禁止 Options API | Must use Vue 3 `<script setup lang="ts">` + Composition API. Options API is prohibited. |
| 2 | 只使用本文件中明确列出的组件名，禁止伪造不存在的组件或 Props | Only use component names listed here. Do not fabricate non-existent components or props. |
| 3 | 使用响应式解构 `const { value = 0 } = defineProps<Props>()`，禁止 `withDefaults` | Use reactive destructuring. `withDefaults` is prohibited. |
| 4 | 使用 `defineModel()`，禁止手写 `emit('update:xxx')` | Use `defineModel()`. Manual `emit('update:xxx')` is prohibited. |
| 5 | 优先使用 Tabler CSS utility class，除过渡动画外不写 `<style scoped>` | Prefer Tabler CSS utilities. No `<style scoped>` except for transitions. |
| 6 | 始终给 `v-for` 绑定 `:key` | Always bind `:key` to `v-for`. |
| 7 | 不要引入第三方库，除非用户明确要求 | Do not introduce third-party libraries unless requested. |

---

## Quick Start / 项目引入

```bash
pnpm add @gulcc/tabler-vue @tabler/core @tabler/icons-vue
```

```ts
import { createApp } from 'vue'
import '@tabler/core/dist/css/tabler.min.css'
import TablerVue from '@gulcc/tabler-vue'

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

按需引入 / On-Demand Import:

```vue
<script setup lang="ts">
import { TButton, TBadge, TCard } from '@gulcc/tabler-vue'
import { IconHeart } from '@tabler/icons-vue'
</script>
```

---

## 布局容器 / Layout Container (TContainer)

`TContainer` is the page-level layout skeleton. Two modes: **pattern mode** (12 presets) and **flexible sub-component mode**.

```vue
<!-- Pattern mode / pattern 模式 -->
<TContainer pattern="classic" header-height="56px" aside-width="220px">
  <template #header>顶部导航 / Top Nav</template>
  <template #aside>侧边菜单 / Side Menu</template>
  主内容区 / Main Content
  <template #footer>底部版权 / Copyright</template>
</TContainer>

<!-- Flexible mode / 灵活子组件模式 -->
<TContainer>
  <TContainerHeader height="56px">Header</TContainerHeader>
  <TContainerAside width="220px">Sidebar</TContainerAside>
  <TContainerMain>Content</TContainerMain>
  <TContainerFooter height="60px">Footer</TContainerFooter>
</TContainer>
```

---

## 颜色系统 / Color System

| 类别 / Category | 示例值 / Example Values |
|---|---|
| 品牌色 / Brand | `blue`, `azure`, `indigo`, `purple`, `pink`, `red`, `orange`, `yellow`, `lime`, `green`, `teal`, `cyan` |
| 语义色 / Status | `primary`, `secondary`, `success`, `danger`, `warning`, `info` |
| 中性色 / Neutral | `dark`, `light`, `muted` |
| 浅色变体 / Light | `primary-lt`, `success-lt`, `blue-lt` 等 |

```vue
<TButton color="primary">提交 / Submit</TButton>
<TBadge color="success-lt">已完成 / Completed</TBadge>
<TAlert color="danger" title="Error / 错误">Please check / 请检查</TAlert>
```

---

## 表单与输入 / Forms & Input

| 组件 / Component | 用途 / Purpose | v-model |
|---|---|---|
| `TInput` | 文本/数字/密码 / Text, number, password | `v-model="value"` |
| `TSelect` | 下拉选择 / Select dropdown | `v-model="value"` |
| `TCheckbox` / `TCheckboxGroup` | 复选框 / Checkbox | `v-model="value"` |
| `TRadio` / `TRadioGroup` | 单选框 / Radio | `v-model="value"` |
| `TSwitch` | 开关 / Toggle switch | `v-model="value"` |
| `TSlider` | 滑块 / Range slider | `v-model="value"` |
| `TUpload` | 文件上传 / File upload | `v-model="files"` |
| `TMaskInput` | 掩码输入 / Masked input | `v-model="value"` |

```vue
<TInput v-model="name" placeholder="Enter name / 请输入姓名" />
<TSelect v-model="city" :options="cityOptions" />
<TCheckbox v-model="agreed">I agree / 同意</TCheckbox>
```

---

## 浮层与反馈 / Overlays & Feedback

| 组件 / Component | 用途 / Purpose | 触发 / Trigger |
|---|---|---|
| `TModal` | 弹窗 / Modal dialog | `v-model="visible"` |
| `TDropdown` | 下拉菜单 / Dropdown | click / hover |
| `TPopover` | 气泡卡片 / Popover | click / hover |
| `TTooltip` | 文字提示 / Tooltip | hover |
| `TOffcanvas` | 抽屉 / Offcanvas panel | `v-model="visible"` |
| `toast` | 全局通知 / Notification | `toast.success('msg')` |

### Toast 全局通知 / Global Notifications

> 需在 App.vue 放置 `<TToastContainer />` 组件 / Must place `<TToastContainer />` in App.vue

```vue
<!-- App.vue -->
<template>
  <RouterView />
  <TToastContainer placement="top-right" />
</template>

<!-- 任意组件 / Any component -->
<script setup lang="ts">
import { toast } from '@gulcc/tabler-vue'
toast.success('操作成功 / Success')
toast.error('网络错误 / Network error', { duration: 0 })
toast.warning('即将过期 / Expiring', { title: '提示 / Notice' })
</script>
```

---

## 数据展示 / Data Display

| 组件 / Component | 用途 / Purpose |
|---|---|
| `TTable` | 表格 / Table (sort/filter/pagination/expand) |
| `TTree` / `TTreeNode` | 树形控件 / Tree control |
| `TTreeMenu` | 树形导航菜单 / Tree navigation |
| `TTimeline` | 时间轴 / Timeline |
| `TTransfer` | 穿梭框 / Transfer |
| `TCarousel` | 走马灯 / Carousel |
| `TCalendar` | 日历 / Calendar |

---

## 通用原子组件 / Atomic Components

| 组件 / Component | 用途 / Purpose | 常用 Props / Common Props |
|---|---|---|
| `TButton` | 按钮 / Button | `color`, `size`, `outline`, `ghost`, `loading`, `disabled` |
| `TBadge` | 徽章 / Badge | `color` |
| `TAvatar` | 头像 / Avatar | `src`, `size`, `color`, `initials` |
| `TCard` | 卡片 / Card | `title`, `bg`, `imgSrc`, `size` |
| `TDivider` | 分割线 / Divider | — |
| `TProgress` | 进度条 / Progress | `value`, `color`, `striped` |
| `TSpinner` | 加载圈 / Spinner | `size`, `color` |
| `TPlaceholder` | 骨架屏 / Skeleton | — |
| `TEmpty` | 空状态 / Empty state | `title`, `description` |
| `TTag` | 标签 / Tag | `color` |

---

## 导航组件 / Navigation

| 组件 / Component | 用途 / Purpose |
|---|---|
| `TTabs` / `TTabPane` | 标签页 / Tabs |
| `TBreadcrumb` | 面包屑 / Breadcrumb |
| `TPagination` | 分页 / Pagination |
| `TSteps` | 步骤条 / Steps |
| `TAccordion` / `TAccordionItem` | 折叠面板 / Accordion |

---

## 配色辅助 / Color Usage Rules

| 变体 / Variant | 处理 / Handling |
|---|---|
| 实色 `bg-*` / Solid | 必须搭配 `text-*-fg`，如 `bg-red text-red-fg` |
| 浅色 `bg-*-lt` / Light | 无需 `text-*-fg`，Tabler 自动处理 / Auto-handled |

---

## 图标使用 / Icon Usage

图标来自 `@tabler/icons-vue`，作为 Vue 组件直接渲染 / Icons render as Vue components directly:

```vue
<script setup lang="ts">
import { IconHeart, IconSettings } from '@tabler/icons-vue'
</script>

<template>
  <IconHeart :size="32" color="red" />
  <TButton color="primary">
    <IconHeart class="me-1" /> Like / 喜欢
  </TButton>
</template>
```

> 图标放在文字左侧加 `me-1`，右侧加 `ms-1` / Use `me-1` when icon is left of text, `ms-1` when right.

---

## 表单校验 / Form Validation

本库**没有** `TForm` / `TFormItem` 包裹组件 / This library does **NOT** have `TForm` wrapper:

```vue
<TInput
  v-model="email"
  label="Email / 邮箱"
  :error="!isValid"
  error-message="Invalid / 格式不正确"
  wrapper-class="mb-3"
/>
```

---

## 复杂组件数据接口 / Data Interfaces

### TTable

```ts
interface TableColumn {
  key: string
  title: string
  width?: string | number
  align?: 'left' | 'center' | 'right'
  sortable?: boolean
  filters?: { text: string; value: any }[]
  render?: (text: any, record: T, index: number) => any
  fixed?: 'left' | 'right'
}
```

### TSelect

```ts
interface SelectOption {
  label: string
  value: any
  disabled?: boolean
}
```

---

## 高频组件事件与插槽 / Events & Slots

| 组件 / Component | 事件 / Events | 插槽 / Slots |
|---|---|---|
| `TModal` | `@update:modelValue`, `@close`, `@open` | `default`, `header`, `title`, `footer` |
| `TDropdown` | `@select` | `default`, `item` |
| `TTable` | `@page-change`, `@sort-change`, `@filter-change` | `#cell(key)` 自定义列渲染 |
| `TPagination` | `@update:page`, `@update:page-size` | — |
| `TAccordion` | `@change` | `#title`, `#icon`, `default` |
| `TUpload` | `@update:modelValue`, `@change` | — |

表格自定义列插槽示例 / Custom Table Column Slot:

```vue
<TTable :columns="columns" :data="tableData">
  <template #cell(name)="{ row }">
    <strong>{{ row.name }}</strong>
  </template>
  <template #cell(action)="{ row }">
    <TButton size="sm" color="danger" @click="handleDelete(row)">删除 / Delete</TButton>
  </template>
</TTable>
```

---

## 各组件详细 SKILL 文件 / Per-Component SKILL Files

> 本文件提供整体概览。每个组件的详细 Props、Events、Slots、基础用法和进阶场景，可在独立的组件 SKILL 文件中查阅，AI 助手会在需要时自动引用。

每个组件的 SKILL 文件位于：`{当前URL}/skills/{组件名}/SKILL.md`

| 分类 | 组件 SKILL |
|---|---|
| **基础** | `TButton` · `TBadge` · `TSpinner` · `TTag` · `TTagList` · `TAvatar` · `TAvatarList` |
| **布局** | `TCard` · `TDivider` · `TRibbon` · `TContainer` · `TPlaceholder` · `TButtonGroup` · `TButtonList` · `TButtonActions` |
| **导航** | `TTabs` · `TTabPane` · `TBreadcrumb` · `TPagination` · `TSteps` · `TAccordion` · `TNavbar` · `TNavbarBrand` · `TNavMenu` · `TTreeMenu` · `TTreeMenuItem` |
| **数据展示** | `TTable` · `TTree` · `TTreeNode` · `TTimeline` · `TTimelineItem` · `TTransfer` · `TCarousel` · `TCalendar` · `TTracking` · `TScrollSpy` |
| **反馈** | `TAlert` · `TModal` · `TDropdown` · `TPopover` · `TTooltip` · `TOffcanvas` · `TSlidedown` · `TDelete` |
| **表单** | `TInput` · `TSelect` · `TCheckbox` · `TRadio` · `TSwitch` · `TSlider` · `TUpload` · `TMaskInput` · `TAutosize` · `TInputOtp` · `TSwitchIcon` |
| **选择** | `TCombobox` · `TTreeSelect` · `TTreeSelectNode` · `TColorCheck` · `TColorPicker` · `TColorPickerPanel` · `TImageCheck` · `TImageCheckItem` · `TSelectboxes` · `TSelectboxItem` · `TSegmentedControl` · `TTimeZone` |
| **状态** | `TStatus` · `TStatusDot` · `TStatusIndicator` · `TProgress` · `TProgressBar` · `TEmpty` · `TCountup` · `TStarRating` |
| **其他** | `TSignaturePad` · `TBytes` · `TCronPicker` · `TOtpCountdown` · `TPrivacyMask` |

> 文件中涉及的组件 Props、Events、Slots 均基于组件源码生成，AI 引用时可确保类型正确。
> All component APIs in these files are generated from the actual source code, ensuring type accuracy.