涟漪 Ripple

v-ripple 是库里的公共点按反馈指令：按下时从按压点扩散一圈淡淡的 currentColor，松开后淡出。 展开 450ms、淡出 150ms、不透明度 12%，颜色取自元素自身的文字颜色，所以 text-ds-on-primary、 text-ds-on-tonal 这些既有的 token 会自动决定涟漪的颜色，不需要额外配置。

库里的 Button、IconButton、Tab、NavigationItem、NavigationRailItem、NavigationDrawerItem、 Input 的尾部按钮、Option 与 Select 触发器都已经接上，直接使用即可。

用法

指令默认导出为 vRipple，在 <script setup> 里导入即可当 v-ripple 用：

<script setup lang="ts">
import { vRipple } from "@sharpdotnut/dotsharp";
</script>

<template>
  <button v-ripple class="rounded-full px-4 py-2">点我</button>
</template>

需要在全局注册（例如在应用入口）：

import { createApp } from "vue";
import { vRipple } from "@sharpdotnut/dotsharp";
import App from "./App.vue";

createApp(App).directive("ripple", vRipple).mount("#app");

选项

指令值可省略（等价于 v-ripple）或传对象；传 false 关闭：

选项	类型	默认值	说明
color	string	currentColor	扩散颜色
opacity	number	0.12	颜色不透明度
center	boolean	false	总是从元素中心扩散，忽略按压位置
unbounded	boolean	false	不裁剪到元素边界，也不改写元素的 overflow

<div v-ripple="{ opacity: 0.16 }">更明显一点的涟漪</div>
<div v-ripple="{ color: 'var(--ds-primary-strong)' }">指定颜色</div>
<div v-ripple="false">关掉涟漪</div>

行为细节

• 元素自身需要能承载绝对定位的涟漪：指令会在元素 position 为 static 时补上 relative， 在 overflow 为 visible 时补上 hidden（unbounded 时两者都跳过），并设置 isolation: isolate， 让涟漪只画在元素背景与内容之间，不会盖住文字。
• disabled 或 aria-disabled="true" 的元素不会产生涟漪，无需手动关闭。
• 键盘 Enter / Space 触发时从元素中心扩散；prefers-reduced-motion: reduce 下不播放。
• 同一元素同时只保留一个涟漪，重复按压不会叠加。