辅助 · 20 / 21
Ripple st-ripple
点击波纹组件：放进任意 position: relative 的父元素，点击该区域就会从指针处扩散一圈 currentColor。它不拦截交互、不改变布局，按钮与列表项已经内嵌，一般只在自定义容器里单独使用。
基本用法：放进 relative 父元素
唯一要求是父元素 position: relative（或 absolute）。st-ripple 自身绝对定位铺满父元素、pointer-events: none，不会挡住点击；波纹色取父元素文字色 currentColor，自动与任何配色协调。
LIVE
st-ripple
已点击 {{basicClicks}} 次 · 波纹从指针位置扩散，0.35s 后消失
示例代码
<div style="position: relative; width: 230px; height: 96px;
background: var(--md-sys-color-primary);
color: var(--md-sys-color-on-primary);">
点我试试
<st-ripple></st-ripple>
</div>在自定义容器里：整行可点
列表行、设置项、卡片都可以直接放 st-ripple。父元素负责圆角与 overflow，波纹会继承 border-radius 并自动裁剪；点击坐标相对父元素计算，行内文字与图标不干扰扩散。
LIVE
自定义行
点击整行切换：{{wifiOn ? "已连接" : "未连接"}} · 波纹从点击位置扩散，父元素负责圆角与裁剪
示例代码（设置行）
<div on:click="openWifi()"
style="position: relative; display: flex; justify-content: space-between;
padding: 14px 16px; cursor: pointer;">
<span>Wi-Fi</span>
<span>已连接 ›</span>
<st-ripple></st-ripple>
</div>键盘激活：从中心扩散
键盘按 Enter / Space 产生的 click 没有坐标（detail 为 0），组件会改为从父元素中心扩散。用原生 button 或 st-button 承载焦点与键盘语义即可，st-ripple 本身不需要 tabindex。
LIVE
Enter / Space示例代码（可聚焦容器）
<button type="button" on:click="activate()"
style="position: relative; overflow: hidden;">
点我试试
<st-ripple></st-ripple>
</button>颜色与透明度
波纹没有 color 属性：颜色永远跟随父元素的 currentColor，组件里换 color 就换波纹色。透明度由皮肤 token --st-ripple-opacity 控制（默认 0.28），设为 0 就完全关闭；Apple 与 shadcn 皮肤默认关闭。
LIVE
currentColor / --st-ripple-opacity
手动区域 · opacity 0.55
颜色跟随 currentColor
Primary
Error
Success
关闭 · --st-ripple-opacity: 0
无波纹
无波纹
示例代码
<div style="position: relative; color: var(--md-sys-color-primary);
--st-ripple-opacity: 0.5;">
文字色即波纹色
<st-ripple></st-ripple>
</div>
<!-- 关闭波纹 -->
<div style="--st-ripple-opacity: 0;">...</div>嵌套组件：不会叠两层波纹
父容器与内部组件都带波纹时，事件如果源自嵌套的自定义组件（st-button、st-list-item 等），外层的 st-ripple 会自动忽略，只保留内层组件自己的波纹，避免一次点击出现多层涟漪。
LIVE
nested ripple
内部组件点击 {{innerClicks}} 次 · 外层容器 click {{outerClicks}} 次（事件照常冒泡，但外层不再生成波纹）
示例代码
<div style="position: relative;">
<st-button>内嵌按钮</st-button>
<st-ripple></st-ripple>
</div>
<!-- 点按钮：只有按钮的波纹；点空白：外层波纹 -->属性
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 无语义属性：没有 disabled / color / variant，也没有事件或公开方法。 | |||
--st-ripple-opacity | number | 0.28 | CSS 变量 / 皮肤 token；0 关闭波纹 |
插槽 / 事件 / 注意
- 无插槽、无事件；波纹纯由父元素上的指针 / 键盘事件驱动，spawn 属于内部实现、不要依赖。
- 父元素必须
position: relative（或 absolute）；组件自身absolute; inset: 0; pointer-events: none。 - 波纹色 =
currentColor；默认透明度 0.28，可用--st-ripple-opacity调整或关闭。 - 鼠标/触摸从点击坐标扩散，直径覆盖到最远角，动画 0.35s 后移除。
- 键盘 Enter / Space 触发的 click 无坐标，从父元素中心扩散。
- 事件源自嵌套自定义组件时自动忽略，避免一次点击多层涟漪。
- st-button / st-list-item / st-menu-item / st-tab-item / st-nav-item / st-split-button 已内嵌，通常不需要单独使用。