如何实现可接收多任意值的TailwindCSS圆形clip-path工具类？

问题背景 #

我需要编写一个可接收多个任意值的TailwindCSS @utility，用于为图片添加圆形clip-path。最初尝试的代码无法生效：

<script src="https://unpkg.com/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@utility clipcirc-* {
  clip-path: circle(--value([percentage]) at --value([percentage]) --value([percentage]));
}
</style>

<img class="clipcirc-[40%_50%_50%]" src="https://picsum.photos/200/200">

目前已通过拆分为三个独立工具类实现功能，但希望使用单工具类的实现方式：

<script src="https://unpkg.com/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@utility clipcirc-radius-* {
  --clip-circ-radius: --value([percentage]);
  clip-path: circle(var(--clip-circ-radius) at var(--clip-circ-x) var(--clip-circ-y));
}
@utility clipcirc-x-* {
  --clip-circ-x: --value([percentage]);
}
@utility clipcirc-y-* {
  --clip-circ-y: --value([percentage]);
}
</style>

<img class="clipcirc-radius-[40%] clipcirc-x-[50%] clipcirc-y-[50%]" src="https://picsum.photos/200/200">

解决方案 #

可以通过TailwindCSS的--value-list语法实现单工具类接收多参数，具体代码如下：

<script src="https://unpkg.com/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@utility clipcirc-* {
  /* 定义包含三个百分比参数的列表，下划线为参数分隔符 */
  --clip-circ-values: --value-list([percentage], [percentage], [percentage]);
  /* 使用CSS的nth()函数分别提取半径、X坐标、Y坐标 */
  clip-path: circle(nth(var(--clip-circ-values), 1) at nth(var(--clip-circ-values), 2) nth(var(--clip-circ-values), 3));
}
</style>

<!-- 调用时传入三个用下划线分隔的百分比值 -->
<img class="clipcirc-[40%_50%_50%]" src="https://picsum.photos/200/200">

原理说明 #

• --value-list([percentage], [percentage], [percentage])会将传入的下划线分隔值解析为一个CSS列表变量
• nth(var(--clip-circ-values), N)用于从列表中提取第N个参数，分别对应圆形的半径、中心X坐标、中心Y坐标
• 最终生成的CSS会正确解析为clip-path: circle(40% at 50% 50%)，实现预期的圆形裁剪效果

简化写法（可选） #

如果你希望更简洁的实现，也可以直接将完整的radius at x y字符串作为参数传入：

<script src="https://unpkg.com/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
@utility clipcirc-* {
  clip-path: circle(--value);
}
</style>

<!-- 调用时需要包含"at"关键字，用下划线分隔 -->
<img class="clipcirc-[40%_at_50%_50%]" src="https://picsum.photos/200/200">

这种方式更简洁，但需要严格遵循radius at x y的语法格式。

内容的提问来源于stack exchange，提问作者David Deprost