---
title: 理念总览
description: Tuffex 是什么、背后的三块理念版图，以及完整组件索引
category: Foundations
status: beta
since: 0.3.9
tags: [concepts, overview, foundations, utils]
syncStatus: reviewed
verified: true
---

## 安装

三种引入形态——按组件、按套件入口、或根入口——以及各自需要的样式文件。从《[安装与引入](./installation.zh.mdc)》开始。

## Tuffex Components 组件库

Tuffex（`@talex-touch/tuffex`）是服务 Talex Touch 生态的 Vue 3 组件库：同一套组件覆盖桌面端 CoreBox、插件 Surface 与本文档站。组件按套件划分——**基础**承载日常界面主体、**进阶**承载高级交互与视觉表达、**AI** 承载 AI 原生界面、**数据**承载可视化与图表家族、**流程**承载画布上的流程编排——侧边栏顶部的套件切换器在这五个组件套件之外，另列「理念」作为第六个纯文档套件；选中哪个套件就直接进入它的总览页。

- 交互标本：每个套件页开头都有一块组件预览——《[基础套件](./base-suite.zh.mdc)》《[进阶套件](./pro-suite.zh.mdc)》《[AI 套件](./ai-suite.zh.mdc)》《[数据套件](./data-suite.zh.mdc)》《[流程套件](./flow-suite.zh.mdc)》——每个格子都是可交互的真实组件，点名称直达文档。
- 分套件引入：`@talex-touch/tuffex/base`、`/pro`、`/ai` 三个分类入口按需加载；图表族在同包的 `@talex-touch/tuffex/charts` 子路径下。
- 版本演进与变更日志：详见《[组件变更历程](./changelog.zh.mdc)》，记录每个组件的引入版本（Since xx）、每次发版更新的组件清单与版本门禁。

## Design Foundations 设计基础

组件视觉的最底层是一组 `--tx-*` design token：字体栈与字号字重体系、明暗双主题下的颜色语义（主色、成功/警告/危险、文本与填充分层）。组件不各自定义视觉，而是统一消费这层变量——改主题就是改 token，业务侧自定义也应落在同一层。完整清单见《[Design Foundations 设计基础](./foundations.zh.mdc)》。

## 主题定制

设计基础列出的是 token 清单，《[主题定制](./theming.zh.mdc)》讲的是怎么覆盖它们：全局 token、深色与高对比度选择器、AI 套件自带的 `--tx-bui-*` 层，以及约三百个可以只改一个组件或一棵子树的组件变量。

## 图标体系

`TxIcon` 自己判断一个图标字符串**是什么**，而不需要调用方声明——Iconify class、七个内置字形之一、emoji，或显式的 URL / 文件来源。《[图标体系](./icons.zh.mdc)》讲清这套解析顺序，以及应用如何教组件从自己的存储里加载图标。

## Utils 工具函数

与组件配套的公开工具函数，从根入口与 `./utils` 子路径导出：`nextZIndex` 统一浮层层级、`toast` 轻提示、对话框编排、环境守卫（`hasWindow` 等）、触感反馈与动画辅助。组件内部走的也是这一层，业务侧复用同一入口即可保证行为一致。完整 API 见《[Utils 工具函数](./utils.zh.mdc)》。

## 组合工作台 Demo

这一组 Demo 用真实后台片段校验组件组合：搜索输入、开关、按钮、状态徽标、进度条与可选择表格会在同一个响应式面板里协同工作。

::TuffDemoWrapper{demo="ComponentsWorkflowPanelDemo" code-lang="vue" title="发布工作台" description="适合作为 Dashboard / Admin 页面组合组件的基础形态。"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const query = ref('')
  const selectedKeys = ref([1])
  const automationEnabled = ref(true)

  const columns = [
    { key: 'task', title: '任务' },
    { key: 'owner', title: '负责人' },
    { key: 'status', title: '状态' },
  ]
  const rows = [
    { id: 1, task: '发布说明', owner: 'Ivy', status: '审阅中' },
    { id: 2, task: '灰度放量', owner: 'Long', status: '进行中' },
  ]
  </script>

  <template>
    <section class="workflow-panel">
      <header>
        <h3>发布工作台</h3>
        <TxButton variant="primary" size="sm" icon="i-carbon-rocket">发布</TxButton>
      </header>
      <TuffInput v-model="query" placeholder="搜索任务" prefix-icon="i-carbon-search" clearable />
      <TuffSwitch v-model="automationEnabled" />
      <TxProgressBar :percentage="84" status="success" show-text />
      <TxStatusBadge text="审阅中" status="warning" />
      <TxDataTable v-model:selected-keys="selectedKeys" :columns="columns" :data="rows" row-key="id" selectable />
    </section>
  </template>
---
::

## 教程路径

- 新手先读《[Tuffex 组合界面教程](../getting-started/tuffex-composition.zh.mdc)》，掌握“操作区 → 状态区 → 数据区”的页面切法。
- 后台首屏建议从“运营状态面板”模式开始，再按需向下展开表格、趋势图、导航配置和详情抽屉。
- 列表页优先把关键词、范围筛选和无结果恢复设计成同一条路径，复用 `TxSearchInput`、`TxSearchSelect`、`TxSearchEmpty`。
- 数据列表建议使用 `TxDataTable` 承担主体、`TxPagination` 承担页码、`TxSkeleton` / `TxLayoutSkeleton` 承担等待态。
- 设置页与后台壳层建议使用 `TxTabs` 固定分区，`TxDropdownMenu` / `TxPopover` 放轻操作与短说明，`TxDrawer` 承载高密度配置。
- 数据区必须同时设计加载、空态和错误恢复路径，优先复用 `TxLoadingState`、`TxEmptyState`、`TxErrorState`。
- 任务反馈路径建议使用 `TxToastHost` 挂载通知、`TxTooltip` 解释动作、`TxLoadingOverlay` 阻断局部刷新、`TxSpinner` 表达行内等待。
- 权限编排路径建议用 `TxTree` 选择权限域、`TxTreeSelect` 选择归属团队、`TxTransfer` 分配资源、`TxTimeline` 展示审计进度。
- 发布配置路径建议用 `TxCascader` 选择发布范围、`TxFlatSelect` 选择包格式与发布模式、`TxSegmentedSlider` 表达风险档位、`TxSlider` 调整灰度比例、`TxTagInput` 记录短标签。
- 组件细节按下方分组查阅；侧边栏仅突出仍需关注的迁移状态，已审阅页面只在状态看板中显示 `已确认`。
- 后台页优先使用 `TxDataTable`、`TxStatusBadge`、`TxProgressBar` 与图表组件组合，避免手写一次性 SVG 或重复状态 UI。

## 迁移状态看板

- `开发中`：文档仍在完善，示例/API 可能继续调整。
- `AI 迁移`：已完成迁移，但仍建议结合源码核对。
- `已审阅`：人工审阅完成。

::DocsComponentSyncTable
::

## 套件总览

每个套件都有一个总览页，承载自己那一部分的实时预览和组件清单——也就是在切换器里选中该套件后，侧边栏的第一个条目。

| 套件 | 分组 | 组件数 | 引入入口 |
|------|------|--------|----------|
| [基础套件](./base-suite.zh.mdc) | 通用 / 表单 / 布局 / 导航 / 数据展示 / 反馈 / 状态占位 | 94 | `@talex-touch/tuffex/base` |
| [进阶套件](./pro-suite.zh.mdc) | 高级交互 / 视觉效果 / 底层原语 | 27 | `@talex-touch/tuffex/pro` |
| [AI 套件](./ai-suite.zh.mdc) | 对话 / 智能体 / 推理与生成 / 上下文与洞察 | 34 | `@talex-touch/tuffex/ai` |
| [数据套件](./data-suite.zh.mdc) | 图表 / 可视化 | 10 | `@talex-touch/tuffex/pro`（可视化 + 图表）+ `@talex-touch/tuffex/charts`（图表族入口） |
| [流程套件](./flow-suite.zh.mdc) | 流程编排 | 1 | `@talex-touch/tuffex/ai` |

理念是第六个套件——纯文档性质、不对应组件入口。本页就是它的总览：上半是组件库定位、设计基础与工具函数，下半是完整组件索引。

## 基础组件

日常界面的主体组件，通过 `@talex-touch/tuffex/base` 分类入口引入。套件页见《[基础套件](./base-suite.zh.mdc)》，设计基础见《[Foundations 设计基础](./foundations.zh.mdc)》，工具函数见《[Utils 工具函数](./utils.zh.mdc)》。

### 通用

- [Button 按钮](./button.zh.mdc)
- [Icon 图标](./icon.zh.mdc)
- [Avatar 头像](./avatar.zh.mdc)
- [Avatar Variants 头像变体](./avatar-variants.zh.mdc)
- [Tag 标签](./tag.zh.mdc)
- [Badge 徽标](./badge.zh.mdc)
- [StatusBadge 状态徽标](./status-badge.zh.mdc)
- [IconChip 图标角标](./icon-chip.zh.mdc)
- [Kbd 快捷键](./kbd.zh.mdc)
- [Divider 分割线](./divider.zh.mdc)

### 表单

- [Form 表单](./form.zh.mdc)
- [Input 输入](./input.zh.mdc)
- [SensitiveInput 敏感输入框](./sensitive-input.zh.mdc)
- [Textarea 多行输入](./textarea.zh.mdc)
- [NumberInput 数字输入](./number-input.zh.mdc)
- [SearchInput 搜索输入框](./search-input.zh.mdc)
- [TagInput 标签输入](./tag-input.zh.mdc)
- [ScrubField 拖拽数值域](./scrub-field.zh.mdc)
- [Select 选择器](./select.zh.mdc)
- [FlatSelect 扁平选择](./flat-select.zh.mdc)
- [SearchSelect 搜索选择器](./search-select.zh.mdc)
- [TreeSelect 树选择器](./tree-select.zh.mdc)
- [Cascader 级联选择](./cascader.zh.mdc)
- [Picker 滚轮选择](./picker.zh.mdc)
- [DatePicker 日期选择](./date-picker.zh.mdc)
- [IconPicker 图标选择器](./icon-picker.zh.mdc)
- [Radio 单选框](./radio.zh.mdc)
- [FlatRadio 平铺单选](./flat-radio.zh.mdc)
- [Checkbox 复选框](./checkbox.zh.mdc)
- [Switch 开关](./switch.zh.mdc)
- [Slider 滑块](./slider.zh.mdc)
- [SegmentedSlider 分段滑块](./segmented-slider.zh.mdc)
- [Rating 评分](./rating.zh.mdc)
- [FileUploader 文件上传](./file-uploader.zh.mdc)
- [ImageUploader 图片上传](./image-uploader.zh.mdc)

### 布局

- [Container 容器](./container.zh.mdc)
- [Flex 弹性布局](./flex.zh.mdc)
- [Grid 栅格](./grid.zh.mdc)
- [GridLayout 网格布局](./grid-layout.zh.mdc)
- [Stack 堆叠](./stack.zh.mdc)
- [Splitter 分割面板](./splitter.zh.mdc)
- [Scroll 滚动](./scroll.zh.mdc)
- [Collapse 折叠](./collapse.zh.mdc)
- [Card 卡片](./card.zh.mdc)
- [CardItem 卡片项](./card-item.zh.mdc)
- [GroupBlock 分组块](./group-block.zh.mdc)

### 导航

- [Tabs 标签页](./tabs.zh.mdc)
- [TabBar 底部导航](./tab-bar.zh.mdc)
- [NavBar 导航栏](./nav-bar.zh.mdc)
- [SidebarNav 侧边导航](./sidebar-nav.zh.mdc)
- [Breadcrumb 面包屑](./breadcrumb.zh.mdc)
- [Steps 步骤条](./steps.zh.mdc)
- [Pagination 分页](./pagination.zh.mdc)
- [DropdownMenu 下拉菜单](./dropdown-menu.zh.mdc)
- [FlatDropdown 扁平下拉](./flat-dropdown.zh.mdc)
- [ContextMenu 右键菜单](./context-menu.zh.mdc)

### 数据展示

- [DataTable 数据表格](./data-table.zh.mdc)
- [Descriptions 描述列表](./descriptions.zh.mdc)
- [Tree 树形](./tree.zh.mdc)
- [SortableList 拖拽排序](./sortable-list.zh.mdc)
- [Timeline 时间线](./timeline.zh.mdc)
- [Transfer 穿梭框](./transfer.zh.mdc)
- [StatCard 指标卡片](./stat-card.zh.mdc)
- [CellLink 单元格链接](./cell-link.zh.mdc)
- [DotIndicator 圆点指示器](./dot-indicator.zh.mdc)
- [FilterChips 筛选胶囊](./filter-chips.zh.mdc)
- [MarkdownView Markdown 渲染](./markdown-view.zh.mdc)
- [ImageGallery 图片预览](./image-gallery.zh.mdc)

### 反馈

- [Dialog 弹窗](./dialog.zh.mdc)
- [Modal 模态框](./modal.zh.mdc)
- [Drawer 抽屉](./drawer.zh.mdc)
- [Popover 弹出层](./popover.zh.mdc)
- [Tooltip 提示](./tooltip.zh.mdc)
- [Toast 提示](./toast.zh.mdc)
- [ToastPanel 浮出面板](./toast-panel.zh.mdc)
- [Alert 提示条](./alert.zh.mdc)
- [StatusHint 状态提示](./status-hint.zh.mdc)
- [Progress 进度](./progress.zh.mdc)
- [ProgressBar 进度条](./progress-bar.zh.mdc)
- [Spinner 加载](./spinner.zh.mdc)
- [LoadingOverlay 加载遮罩](./loading-overlay.zh.mdc)
- [SelectionActions 划词工具条](./selection-actions.zh.mdc)

### 状态占位

- [Empty 空状态](./empty.zh.mdc)
- [EmptyState 空态引导](./empty-state.zh.mdc)
- [NoData 无数据](./no-data.zh.mdc)
- [NoSelection 未选择](./no-selection.zh.mdc)
- [SearchEmpty 搜索空态](./search-empty.zh.mdc)
- [ErrorState 错误状态](./error-state.zh.mdc)
- [OfflineState 离线](./offline-state.zh.mdc)
- [PermissionState 权限不足](./permission-state.zh.mdc)
- [GuideState 引导状态](./guide-state.zh.mdc)
- [BlankSlate 空白页](./blank-slate.zh.mdc)
- [LoadingState 加载态](./loading-state.zh.mdc)
- [Skeleton 骨架屏](./skeleton.zh.mdc)
- [LayoutSkeleton 布局骨架](./layout-skeleton.zh.mdc)

## 进阶套件

高级交互、视觉效果与底层原语，通过 `@talex-touch/tuffex/pro` 分类入口引入。套件页见《[进阶套件](./pro-suite.zh.mdc)》。

### 高级交互

- [CommandPalette 命令面板](./command-palette.zh.mdc)
- [SearchPanel 内联搜索面板](./search-panel.zh.mdc)
- [MarkdownEditor Markdown 编辑器](./markdown-editor.zh.mdc)
- [CodeEditor 代码编辑器](./code-editor.zh.mdc)
- [VirtualList 虚拟列表](./virtual-list.zh.mdc)
- [VersionCapsule 版本胶囊](./version-capsule.zh.mdc)

### 视觉效果

- [GlassSurface 玻璃拟态](./glass-surface.zh.mdc)
- [GradientBorder 渐变边框](./gradient-border.zh.mdc)
- [OutlineBorder 描边容器](./outline-border.zh.mdc)
- [BorderBeam 流光边框](./border-beam.zh.mdc)
- [PrismGlow 棱镜光](./prism-glow.zh.mdc)
- [CornerOverlay 角标容器](./corner-overlay.zh.mdc)
- [GradualBlur 渐变模糊](./gradual-blur.zh.mdc)
- [EdgeFadeMask 边缘渐隐遮罩](./edge-fade-mask.zh.mdc)
- [GlowText 扫光](./glow-text.zh.mdc)
- [KeyframeStrokeText 关键帧描边](./keyframe-stroke-text.zh.mdc)
- [TuffLogoStroke Logo 描边](./tuff-logo-stroke.zh.mdc)
- [TextMorph 文本形变](./text-morph.zh.mdc)
- [IconMorph 图标形变](./icon-morph.zh.mdc)
- [TextTransformer 文本变换](./text-transformer.zh.mdc)
- [Transition 动效](./transition.zh.mdc)
- [Stagger 依次进入](./stagger.zh.mdc)
- [Fusion 交融](./fusion.zh.mdc)
- [FusionSurface 融合表面](./fusion-surface.zh.mdc)
- [Liquid 液态流体](./liquid.zh.mdc)
- [FlipOverlay 翻转遮罩](./flip-overlay.zh.mdc)
- [ImageGeneration 生图占位](./image-generation.zh.mdc)
- [MetalFx 液态金属](./metal-fx.zh.mdc)
- [VoiceBeam 语音光束](./voice-beam.zh.mdc)

### 底层原语

- [BaseSurface 基础表面](./base-surface.zh.mdc)
- [BaseAnchor 锚点定位](./base-anchor.zh.mdc)
- [Floating 浮动层](./floating.zh.mdc)
- [AutoSizer 自适应尺寸](./auto-sizer.zh.mdc)
- [ResizeBox 显式尺寸动画](./resize-box.zh.mdc)

## AI 套件

AI 原生界面组件族，部分移植自 [Beautiful UI](https://www.beautifului.dev)（MIT），完整案例见《[AI 套件](./ai-suite.zh.mdc)》，通过 `@talex-touch/tuffex/ai` 分类入口引入。

### 对话

- [Chat 消息列表](./chat.zh.mdc)
- [ChatComposer 消息输入](./chat-composer.zh.mdc)
- [PromptBar 提示条](./prompt-bar.zh.mdc)
- [AttachmentTray 附件区](./attachment-tray.zh.mdc)
- [ModeChip 模式芯片](./mode-chip.zh.mdc)
- [MessageActions 消息操作条](./message-actions.zh.mdc)
- [SuggestionChips 建议胶囊](./suggestion-chips.zh.mdc)
- [ChoiceCard 选项卡片](./choice-card.zh.mdc)
- [TypingIndicator 打字中](./typing-indicator.zh.mdc)
- [ConversationStream 会话流](./conversation-stream.zh.mdc)

### 智能体

- [Agents 智能体列表](./agents.zh.mdc)
- [AgentScreen 智能体屏幕](./agent-screen.zh.mdc)
- [AgentTrace 智能体轨迹](./agent-trace.zh.mdc)
- [TaskRows 任务行](./task-rows.zh.mdc)
- [ToolCallCard 工具调用卡片](./tool-call-card.zh.mdc)
- [ToolChips 工具调用流](./tool-chips.zh.mdc)
- [ToolConfirmation 工具授权](./tool-confirmation.zh.mdc)
- [ApprovalCard 澄清问卷卡](./approval-card.zh.mdc)
- [WorkingIndicator 工作指示器](./working-indicator.zh.mdc)
- [BotAvatar 机器人头像](./bot-avatar.zh.mdc)

### 推理与生成

- [AI Elements AI 对话元素](./ai-elements.zh.mdc)
- [ChainOfThought 推理时间线](./chain-of-thought.zh.mdc)
- [ReasoningDisclosure 推理过程](./reasoning-disclosure.zh.mdc)
- [ThinkingOrb 思考指示球](./thinking-orb.zh.mdc)
- [StreamElement 流式回答](./stream-element.zh.mdc)
- [StreamText 流式文字](./stream-text.zh.mdc)
- [StreamMarkdown 流式 Markdown](./stream-markdown.zh.mdc)
- [CodeStream 流式代码块](./code-stream.zh.mdc)
- [InlineCitation 行内引用](./inline-citation.zh.mdc)
- [Sources 引用来源](./sources.zh.mdc)

### 上下文与洞察

- [ContextCards 检索片段卡](./context-cards.zh.mdc)
- [ContextIndicator 上下文用量](./context-indicator.zh.mdc)
- [InsightCards 洞察卡](./insight-cards.zh.mdc)
- [RecommendationCard 建议卡](./recommendation-card.zh.mdc)
- [FineTuneCard 属性检查器](./fine-tune-card.zh.mdc)

## 数据

数据可视化与图表：tuffex 主包的可视化组件（经 `@talex-touch/tuffex/pro` 引入）+ 同包 `@talex-touch/tuffex/charts` 子路径下的图表家族（kumo 同构、无 echarts）。套件页见《[数据套件](./data-suite.zh.mdc)》。

### 图表

同包 `@talex-touch/tuffex/charts` 子路径下图表家族（kumo）的文档，随 tuffex 主包一起发布。

- [Charts 图表](./charts.zh.mdc)
- [Chart Colors 图表色板](./chart-colors.zh.mdc)
- [TimeseriesChart 时序图](./timeseries-chart.zh.mdc)
- [Maps 地图](./maps.zh.mdc)
- [SankeyChart 桑基图](./sankey-chart.zh.mdc)
- [Custom Chart 自定义图表](./custom-chart.zh.mdc)

### 可视化

- [SparkChart 迷你折线图](./spark-chart.zh.mdc)
- [AllocationBar 占比条](./allocation-bar.zh.mdc)
- [DiffTable 变更表格](./diff-table.zh.mdc)
- [SignalMeter 信号量表](./signal-meter.zh.mdc)

## 流程

流程编排：点阵画布上的节点、分支与连线。经 `@talex-touch/tuffex/ai` 入口引入——和数据套件一样，这是文档层面的划分。套件页见《[流程套件](./flow-suite.zh.mdc)》。

### 流程编排

- [Flowchart 流程画布](./flowchart.zh.mdc)

## 技术实现

- 中心页范围：本页既是理念套件总览，也是组件文档索引；单组件 API、Props、最佳实践细节由各组件详情页承载。
- 源码注册表：`packages/tuffex/packages/components/src/components.ts` 定义文档覆盖测试使用的导出组件 slug 集合。
- Demo 注册表：`apps/nexus/app/components/content/demo-registry.ts` 把本页每个 `TuffDemoWrapper` demo 映射到独立 Vue demo 文件。
- 预览网格：`apps/nexus/app/components/docs/DocsComponentsGallery.vue` 渲染各套件页的「组件预览」网格；`suite` 为必填 prop，一次只渲染该套件那一段。
- **实测覆盖:** Coverage: `apps/nexus/test/docs/tuffex-component-docs-coverage.test.ts` 校验导出组件具备中英文文档、本地化中心页链接已文档化组件、所有 demo 引用都能解析到已注册 Vue 文件。

## 无障碍

`:focus-visible` 上的焦点环、`prefers-reduced-motion` 处理、高对比度调色板，以及组件共用的 ARIA 约定——同时坦白说明覆盖到哪里为止。见《[无障碍](./accessibility.zh.mdc)》。