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

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`

组件 / 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

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

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.

Tabler-Vue 组件库使用技能 ​

Tabler-Vue Component Library Skills ​

🤖 AI 生成规则 / AI Generation Rules ​

Quick Start / 项目引入 ​

布局容器 / Layout Container (TContainer) ​

颜色系统 / Color System ​

表单与输入 / Forms & Input ​

浮层与反馈 / Overlays & Feedback ​

Toast 全局通知 / Global Notifications ​

数据展示 / Data Display ​

通用原子组件 / Atomic Components ​

导航组件 / Navigation ​

配色辅助 / Color Usage Rules ​

图标使用 / Icon Usage ​

表单校验 / Form Validation ​

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

TTable ​

TSelect ​

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

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