Glass Text Web Component (毛玻璃文字组件)

一个轻量、无依赖的 Web Component，用于在图片上创建毛玻璃文字效果。所有属性均使用 kebab-case（例如 image-src、font-size），可通过 npm 安装或直接引入源码使用。

在线演示：blur-text.seeridia.top

🚀 如何使用

方式一：通过 npm 安装

npm install frosted-glass-text

在项目中引入即可（该模块会自动注册 <glass-text>）：

<script type="module">
  import 'frosted-glass-text';

  // 也可以使用默认导出：
  // import GlassText from 'frosted-glass-text';
</script>

方式二：直接引入文件

1. 在你的项目中引入 glass-text.js 文件。

   <script type="module" src="path/to/glass-text.js"></script>

2. 在你的HTML中使用 <glass-text> 标签，并提供图片源。

   <glass-text image-src="path/to/your-image.jpeg">
     你的文字
   </glass-text>
   
   <glass-text
     image-src="path/to/another-image.png"
     blur="8"
     brightness="1.2"
     font-size="80px"
     font-family="'微软雅黑', sans-serif"
   >
     更多文字
   </glass-text>

🛠️ API / 属性

通过设置 HTML 属性来控制组件的各种参数，非法值会被忽略并在控制台给出提示。

| 属性 | 描述 | 默认值 | | --------------- | ----------------------------------------------------------------------------- | -------------- | | image-src | (必需) 背景图片的 URL。 | '' | | blur | 毛玻璃模糊半径（数值，单位 px）。 | 10 | | brightness | 毛玻璃亮度（数值 ≥ 0，1 为原始亮度）。 | 0.8 | | object-fit | 图片填充模式（如 cover / contain / fill 等）。 | cover | | aspect-ratio | 固定容器宽高比，例如 16/9、1。设置后不再根据图片自动撑开。 | 自动探测 | | text-x | 文字 X 轴位置，支持 % 或长度单位。 | 50% | | text-y | 文字 Y 轴位置，支持 % 或长度单位。 | 50% | | font-size | 文字大小，需要包含长度单位。 | 100px | | font-weight | 文字字重（400、bold 等）。非法值会回退到默认值。 | 700 | | font-family | 文字字体。 | sans-serif |

🎨 样式与 CSS 变量

除了常规 CSS（宽度、阴影、圆角等），组件还暴露了两个 CSS 变量用于控制默认效果：

• --glass-blur：兜底模糊值。
• --glass-brightness：兜底亮度值。

当图片加载失败时，组件会自动加上 data-image-error="true" 并显示 <slot> 内的回退内容。

glass-text {
  width: min(90vw, 800px);
  border-radius: 12px;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.5);
  margin: 20px auto;
  --glass-blur: 12px;
}

glass-text[data-image-error="true"] {
  background: repeating-linear-gradient(45deg, #333, #333 10px, #111 10px, #111 20px);
  color: #fff;
}

如需完全控制宽高比，可以使用 CSS 原生的 aspect-ratio，或设置 aspect-ratio 属性。

🔁 事件

• image-load：图片加载成功时触发，event.detail 包含 src 与 aspectRatio。
• image-error：图片加载失败时触发，event.detail 只包含失败的 src。

const glassText = document.querySelector('glass-text');

glassText?.addEventListener('image-error', (event) => {
  console.warn('图片加载失败', event.detail.src);
});

🧑‍💻 TypeScript

库内置 glass-text.d.ts 类型定义，安装后可直接获得补全与事件类型：

import 'frosted-glass-text';

const el = document.querySelector('glass-text');
el?.addEventListener('image-load', (event) => {
  const ratio = event.detail.aspectRatio;
});