GroupBlock 分组块

memoryName 保持唯一且稳定，不要在无关分组间复用。
始终可见的状态或表单段落设 collapsible=false，避免暗示存在隐藏内容。
只读值与轻量跳转用 TxBlockLine，自定义控件用 TxBlockSlot，标准表单行用 TxBlockInput / TxBlockSelect，布尔值与导航用 TxBlockSwitch。
行标题保持简短，长说明放进描述，不要在行内嵌套复杂布局。
组内行的直角由分组负责；不要在行上写 border-radius: 0 模仿这种外观。

API 参考

TxGroupBlock

属性

属性名	类型	默认值	说明
`name`	`string`	必填	分组标题。
`description`	`string`	`''`	标题下方的说明。
`defaultIcon`	`TxIconSource \| string`	-	折叠时的图标，也是 `activeIcon` 的回退。
`activeIcon`	`TxIconSource \| string`	-	展开时的图标；未设置时用 `defaultIcon`。
`iconSize`	`number`	`22`	头部图标尺寸（px）。
`collapsible`	`boolean`	`true`	允许点击头部展开或折叠。
`collapsed`	`boolean`	`false`	外部折叠状态，在用户切换或有持久化值之前随变化生效。
`defaultExpand`	`boolean`	-	首屏展开状态，优先于 `collapsed`；未设置时取 `!collapsed`。
`memoryName`	`string`	`''`	以 `tuff-block-storage-` 为前缀把展开状态存入 `localStorage`。

事件

事件名	参数	说明
`update:expanded`	`expanded: boolean`	用户切换展开状态后触发。
`toggle`	`expanded: boolean`	与 `update:expanded` 同时触发。

插槽

插槽名	参数	说明
`default`	-	分组内的行。
`icon`	`{ active: boolean }`	自定义头部图标。
`header-extra`	`{ active: boolean }`	头部操作区，位于折叠箭头之前。

TxBlockLine

属性

属性名	类型	默认值	说明
`title`	`string`	`''`	行标题。
`description`	`string`	`''`	非链接行的值，可被 `description` 插槽替换。
`link`	`boolean`	`false`	渲染为带链接样式的原生按钮，并派发 `click`。

事件

事件名	参数	说明
`click`	`event: MouseEvent`	仅 `link` 时触发。

插槽

插槽名	参数	说明
`description`	-	自定义值或链接内容。

TxBlockSlot

属性

属性名	类型	默认值	说明
`title`	`string`	`''`	标题；有 `label` 插槽时不渲染。
`description`	`string`	`''`	描述；有 `label` 插槽时不渲染。
`defaultIcon`	`TxIconSource \| string`	-	非激活时的图标，也是 `activeIcon` 的回退。
`activeIcon`	`TxIconSource \| string`	-	激活时的图标；未设置时用 `defaultIcon`。
`iconSize`	`number`	`20`	图标尺寸（px）。
`active`	`boolean`	`false`	切换到 `activeIcon` 并传入插槽作用域，不改变行样式。
`disabled`	`boolean`	`false`	禁用样式，阻止 `click`。

事件

事件名	参数	说明
`click`	`event: MouseEvent`	点击行时触发；绑定后行可聚焦，也响应 Enter / Space。

插槽

插槽名	参数	说明
`default`	`{ active: boolean }`	右侧控件区。
`icon`	`{ active: boolean }`	自定义图标。
`label`	-	替换标题与描述。
`tags`	-	标题旁（或自定义标签下方）的元信息。

TxBlockInput

属性

属性名	类型	默认值	说明
`modelValue`	`string \| number`	`''`	输入值，配合 `v-model`。
`title`	`string`	`''`	行标题。
`description`	`string`	`''`	行描述。
`defaultIcon`	`TxIconSource \| string`	-	未聚焦时的图标，也是 `activeIcon` 的回退。
`activeIcon`	`TxIconSource \| string`	-	聚焦时的图标。
`disabled`	`boolean`	`false`	禁用行与输入框。
`placeholder`	`string`	`''`	占位文本。
`clearable`	`boolean`	`false`	透传给 `TxInput`。
`inputType`	`'text' \| 'password' \| 'number' \| 'email'`	`'text'`	透传为 `TxInput` 的类型。

事件

事件名	参数	说明
`update:modelValue`	`value: string \| number`	输入值变化时触发。
`input`	`value: string \| number`	透传 `TxInput` 的 `input`。
`focus`	`event: FocusEvent`	输入框聚焦时触发。
`blur`	`event: FocusEvent`	输入框失焦时触发。

插槽

插槽名	参数	说明
`control`	`{ value: string \| number, focused: boolean }`	替换默认的 `TxInput`。
`tags`	-	标题旁的元信息。

TxBlockSelect

属性

属性名	类型	默认值	说明
`modelValue`	`string \| number`	`''`	选中值，配合 `v-model`。
`title`	`string`	`''`	行标题。
`description`	`string`	`''`	行描述。
`defaultIcon`	`TxIconSource \| string`	-	未选值时的图标，也是 `activeIcon` 的回退。
`activeIcon`	`TxIconSource \| string`	-	已选值时的图标。
`disabled`	`boolean`	`false`	禁用行与选择器。
`placeholder`	`string`	`''`	占位文本。

事件

事件名	参数	说明
`update:modelValue`	`value: string \| number`	选中值变化时触发。
`change`	`value: string \| number`	与 `update:modelValue` 同时触发。

插槽

插槽名	参数	说明
`default`	-	`TxSelect` 的选项，如 `TuffSelectItem`。
`tags`	-	标题旁的元信息。

TxBlockSwitch

属性

属性名	类型	默认值	说明
`modelValue`	`boolean`	必填	开关值，配合 `v-model`。
`title`	`string`	必填	行标题。
`description`	`string`	必填	行描述。
`defaultIcon`	`TxIconSource \| string`	-	关闭时的图标，也是 `activeIcon` 的回退。
`activeIcon`	`TxIconSource \| string`	-	开启时的图标；未设置时用 `defaultIcon`。
`disabled`	`boolean`	`false`	禁用行与开关。
`guidance`	`boolean`	`false`	以箭头替代开关，作为导航行。
`loading`	`boolean`	`false`	透传给内部开关：滑块转为旋转环，行叠加 shimmer 并暂停交互。

事件

事件名	参数	说明
`update:modelValue`	`value: boolean`	开关值变化时触发。
`change`	`value: boolean`	用户切换后透传开关的 `change`。
`click`	`event: MouseEvent`	仅 `guidance` 模式触发。

插槽

插槽名	参数	说明
`tags`	-	标题旁的元信息。

概述

首屏展开状态依次取持久化值、defaultExpand、!collapsed；用户切换后，props 变化不再覆盖当前状态。
分组内容始终挂载，折叠只改变高度、透明度与 display。
分组重置组内每行的 --fake-radius 与外边距，圆角只出现在分组卡片上；单独使用的行保留 12px 圆角。
TxBlockLine 默认是非交互的 div，link 时才是 <button type="button">。
TxBlockSlot 的控件区不收缩；TxBlockInput 例外，输入框可收缩到 120px，为标题让出空间。
TxBlockSwitch 的忙碌提示只在内部开关上（is-loading + aria-busy），行只叠加 shimmer；guidance 模式不改写 modelValue。

技术实现

展开与折叠由 GSAP 过渡高度和透明度，结束后释放为 auto 或 display: none。
源码：packages/tuffex/packages/components/src/group-block/。

查看源码

packages/tuffex/packages/components/src/group-block/index.ts

自定义

主题变量	用途
`--tx-border-color-lighter`	分组边框与头部分隔线。
`--tx-fill-color-dark` / `--tx-fill-color` / `--tx-fill-color-light`	头部、行与悬停表面。
`--tx-text-color-primary` / `--tx-text-color-secondary`	标题、标签、描述、引导箭头与加载环。
`--tx-color-primary` / `--tx-color-primary-dark-2`	链接行的文字色与悬停色。
`--tx-color-white`	加载 shimmer 的高光。