ExpandButton 使用手册

v1.0.2 · @snowui-design-system/components

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

在展开与收起之间切换，用一致的按钮反馈表达状态，适合折叠内容和详情入口。

使用选择

用于展开或还原内容。宿主 CodeBlock 等已内置同类操作时优先配置宿主，避免两套展开状态。

通过 bind:expanded 或 onExpandedChange 接收状态；defaultExpanded 提供初始值。
组件只提供展开操作，不创建或控制内容面板；由页面把状态连接到实际内容。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { ExpandButton } from '@snowui-design-system/components';</script> <ExpandButton />

API

关键字	类型	默认值	描述
expanded	`boolean`	—	当前展开状态，支持 bind:expanded；未定义时使用 defaultExpanded。点击后写入新布尔值；内容区域由调用方显示或隐藏。
defaultExpanded	`boolean`	`false`	expanded 未定义时的回退状态；首次点击后使用组件写入的 expanded，不再由此值驱动。
ariaLabel	`string`	`LocaleProvider`	未展开时按钮的可访问名称，应描述将要执行的展开动作；默认随 LocaleProvider 使用中文“展开”或英文“Expand”。
collapseAriaLabel	`string`	`LocaleProvider`	已展开时按钮的可访问名称，应描述将要执行的收起动作；默认随 LocaleProvider 使用中文“收起”或英文“Collapse”。
icon	`Snippet`	`—（arrows-out-simple）`	未展开时的自定义图标；只替换图形，展开状态与 aria-expanded 仍由组件管理。
collapseIcon	`Snippet`	`—（arrows-in-simple）`	已展开时的自定义图标；使用组件现有内容替换动效。
children	`Snippet`	—	图标后的自定义内容；不提供时启用 Button.iconOnly。组件不自动创建或控制展开面板。
onExpandedChange	`(expanded: boolean) => void`	—	点击切换后接收新状态，先于 onclick 调用；外部赋值不会触发。
onclick	`(event: MouseEvent) => void`	—	状态写入及 onExpandedChange 之后调用，不能取消已经完成的切换；禁用时不调用。

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

使用

<script lang="ts">  import { ExpandButton } from "@snowui-design-system/components";  let expanded = $state(false);</script> <ExpandButton bind:expanded bare />

expanded / defaultExpanded：受控值与默认值。
onExpandedChange：值切换回调。
icon / collapseIcon：替换默认的放大、收起图标。
ariaLabel / collapseAriaLabel：两种状态的辅助文本。
默认图标为 arrows-out-simple / arrows-in-simple，内容替换使用轻量状态按钮的 150ms replacement appear 动效。

API

其他兼容视觉、链接与事件入口参见 Button。ExpandButton 接管 children、onclick 和 aria-expanded；继承 disabled 阻止用户切换。

此区域的内容受保护。AI 在修改此区域前必须请求用户审查。

ExpandButton 样式覆盖

先阅读完整 LICENSE；同任务、同版本、同范围去重。

优先用组件公开 Props 匹配合适样式，尽可能保留原有视觉。确需改写时按样式选择与改写顺序使用自己的 class（含项目已有 Tailwind）或实例 style。以下名称来自源码实际消费的公开 override；先核对目标作用域，不修改私有 DOM。采用 SnowUI Token 时选择正确类别，外部应用不被要求安装一方 utilities。

变量	用途与默认参考
`--snowui-expand-button-motion-duration-override`	default: 150ms; Button hover / click

设计指南 · Token · 组合边界

ExpandButton 类型与状态

必填属性：无具名必填属性。

可双向绑定：bind:expanded。

继承声明：Omit<ButtonProps, "children" | "onclick" | "aria-expanded">。继承能力以基类公开文档为准；Omit 中的字段已排除，不能按基类原样使用。

共享 Frame API · 返回 API

以下为公开属性实际引用的类型声明，来自源码；Svelte Snippet 表示内容片段，ComponentProps 表示对应组件的 Props。

ButtonProps

来源：components/src/components/ExpandButton.svelte

type ButtonProps = ComponentProps<typeof Button>;