---
title: "FineTuneCard 属性检查器"
description: "共用一个值对象的紧凑属性检查器"
category: AiContext
status: beta
since: 0.3.9
tags: [form, inspector, panel, ai]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
六个字段走同一个 `values` 对象；与 `defaults` 不同时，头部翻到「已修改」并高亮改动的字段。
:::TuffDemoWrapper{demo="FineTuneCardFineTuneCardDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const DEFAULTS = { layout: 'row', width: 324, height: 96, radius: 28, opacity: 100, type: null }
  const values = ref({ ...DEFAULTS })

  const typeOptions = [
    { value: 'seasonal', label: '季节限定' },
    { value: 'classic', label: '经典款' },
  ]
  </script>

  <template>
    <TxFineTuneCard
      v-model:values="values"
      :defaults="DEFAULTS"
      :type-options="typeOptions"
      title="风味卡片"
    />
  </template>
---
:::

### 最佳实践

- `defaults` 传当前预设的初始值，不是常量：切换预设时一起换。
- 撤销栈用 `change`，状态用 `update:values`；两者同时发出，不要在一个处理器里做两遍。
- `ranges` 贴合真实约束（如 `radius` 不超过短边的一半），让夹取挡住非法值。
- 检查器很窄（240px），标签用缩写；`fieldLabels` 可整套替换为本地化文案。
- 非英文界面传入 `layoutLabels`：三个布局选项只有图形，读屏读到的就是这些名称。
- 每个数值框的 `aria-label` 由 `valueLabelFormatter` 从标签生成；非英文界面一并传入，否则读屏读作「<标签> value」。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `values` | `FineTuneValues` | — | 六个字段的值对象，受控。 |
| `defaults` | `Partial<FineTuneValues>` | — | 比较基准，决定头部状态与逐字段高亮。 |
| `edited` | `boolean` | — | 强制头部状态，忽略 `defaults`。 |
| `title` | `string` | `'Fine-tune'` | 卡片标题。 |
| `layoutLabel` / `typeLabel` | `string` | `'Layout'` / `'Type'` | 两个分区的标题。 |
| `layoutLabels` | `Partial<Record<FineTuneLayout, string>>` | `row layout / col layout / grid layout` | 三个布局选项的可访问名称。 |
| `typeOptions` | `FineTuneTypeOption[]` | `[]` | 类型选项 `{ value, label }`。 |
| `typePlaceholder` | `string` | `'Select type'` | 未选择时的占位文案。 |
| `adjustLabel` / `editedLabel` | `string` | `'Adjust'` / `'Edited'` | 头部两态的文案。 |
| `fieldLabels` | `Partial<Record<FineTuneField, string>>` | `W / H / Radius / Opacity` | 四个数值域的标签。 |
| `valueLabelFormatter` | `(label: string) => string` | `` (label) => `${label} value` `` | 由标签生成每个数值框的 `aria-label`。 |
| `ranges` | `Partial<Record<FineTuneField, FineTuneRange>>` | 见下 | 逐字段的取值范围。 |
| `disabled` | `boolean` | `false` | 一次性禁用全部控件。 |

默认范围：`width` 40–999、`height` 24–999、`radius` 0–64、`opacity` 0–100。

### 事件

| 事件名 | 回调参数 | 说明 |
|------|------|------|
| `update:values` | `(values: FineTuneValues)` | 任一字段改动时触发，参数为整个新对象。 |
| `change` | `(key, value)` | 与 `update:values` 同时触发，参数为改动的键与新值。 |

## 概述

- 布局分段复用 `TxFlatRadio`：是真正的 `radiogroup`，方向键切换，只占一个 Tab 停靠点。
- 四个数值域是 `TxScrubField`：标签即手柄，可拖动、键盘步进或直接键入。
- 类型选择器向上弹出，为 `combobox` + `listbox`：方向键从当前选中项开始漫游，Home / End、Enter / 空格提交，Esc 关闭并归还焦点，点击外部或焦点移出时关闭。
- 值不变时不发事件；`disabled` 传给分段、数值域与选择器。
- 减弱动效时，「可调整」的微光停止并恢复为实色文字。

## 技术实现

- 类型选择器 `TxFineTuneChipSelect` 是内部件，不导出。
- 移植自 [Beautiful UI](https://www.beautifului.dev)（© 2026 Shane Levine，MIT）。
- 源码：`packages/tuffex/packages/components/src/fine-tune-card/`。

<TuffDocSourceLink />
