StyleButton 使用手册

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

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

组件介绍

在 SnowUI 与 Apple 两种视觉风格之间切换，适合提供界面风格选择的入口。

使用选择

用于切换支持的视觉风格；明暗模式使用 ColorSchemeButton。它不意味着可以通过一个按钮改变任意组件私有样式。

bind:mode 同步风格，defaultMode 提供初始模式。
默认把模式应用到文档；局部控制使用 applyToDocument=false，不提供 children 时使用纯图标布局。

快速开始

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

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

API

关键字	类型	默认值	描述
mode	`SnowUIStyleMode`	—	当前视觉风格，支持 bind:mode。挂载时优先于 defaultMode；点击更新该值，同步页面属性时也会跟随根节点变化。
defaultMode	`SnowUIStyleMode`	—	挂载时的非受控初值；mode 优先。均未提供时读取页面根节点；applyToDocument=false 时回退为 snowui。
applyToDocument	`boolean`	`true`	将当前状态同步到 document.documentElement：mode="ios"；SnowUI 时移除 mode。false 时不读写或观察页面属性，由调用方处理主题目标；不写入 storage。
ariaLabel	`string`	—	覆盖按钮的可访问名称；默认描述点击后切换到的状态，跟随 LocaleProvider。
snowuiLogo	`Snippet`	`—（内置图形）`	替换当前为 snowui 时显示的 SnowUI Logo。仅改变图形，不接管切换逻辑。
appleLogo	`Snippet`	`—（内置图形）`	替换当前为 apple 时显示的 Apple Logo。仅改变图形，不接管切换逻辑。
children	`Snippet`	—	显示在状态图形之后的自定义内容；未提供时宿主 Button 自动使用 iconOnly 布局。
disabled	`boolean`	`false`	禁用按钮操作；不会阻止外部绑定值或页面属性的同步。
onModeChange	`(mode: SnowUIStyleMode) => void`	—	用户点击切换后接收新值；初始化、外部赋值及页面属性观察同步不会调用此回调。
onclick	`(event: MouseEvent) => void`	—	有效点击时先调用，再执行状态切换；当前实现不会以 preventDefault() 取消后续切换。disabled 时不调用。

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

使用边界与详细说明

使用

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

StyleButton 平铺 Button 的兼容 Props，支持全部变体与尺寸。默认读取 document.documentElement：mode="ios" 为 Apple 风格，移除该属性为 SnowUI 风格。当前 SnowUI 状态使用 SnowUILogo variant="icon"，Apple 状态使用 Apple 品牌 Logo 矢量，而不是图标库中的 Apple Icon；无额外 children 时，StyleButton 主动向 Button 声明 iconOnly=true，因此 sm / md / lg 的四边 padding 分别保持 Button 原生的 4 / 8 / 12px。

点击后立即切换，不写入 storage，也不增加图标替换、风格切换动效。applyToDocument={false} 时只维护受控状态，适合由 Test、iframe 等宿主管理实际风格目标。

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

StyleButton 样式覆盖

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

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

本组件源文件没有直接消费已登记的专属 override。组合子组件的样式通过公开 parts 或显式 child 配置；不要凭名称猜测变量。

设计指南 · Token · 组合边界

StyleButton 类型与状态

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

可双向绑定：bind:mode。

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

共享 Frame API · 返回 API

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

SnowUIStyleMode

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

export type SnowUIStyleMode = "snowui" | "apple";

ButtonProps

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

type ButtonProps = ComponentProps<typeof Button>;