@5even7/dlc-ui 0.2.11 → 0.2.13

package/README.md

@@ -1,274 +1,277 @@
-# @5even7/dlc-ui
-
-框架无关的 **星云胶囊**、**流体进度胶囊** 与 **星云背景层（dlc-color）** 组件库：WebGL2 实时渲染，不可用时自动降级 Canvas2D。一套核心，H5 / Vue2 / Vue3 都能用。
-
-零运行时依赖；现代浏览器加载原生 ESM，旧浏览器 / Vue2 老工具链走转译后的 legacy 构建（Canvas2D 降级），互不影响。
-
-## 发版规则
-
-默认每次发布**只递增补丁号（+0.01）**，例如 `0.2.0 → 0.2.1`；除非手动明确指定新版本号，否则不升次版本。
-
-## 安装
-
-```bash
-npm install @5even7/dlc-ui
-```
-
-## 预置列表
-
-| 类型 | 预置 | 说明 |
-| --- | --- | --- |
-| capsule | `初光`（NC-01）、`沧溟`（NC-02）、`玄夜`（NC-03）、`紫霄`（NC-04）、`银汉`（NC-05）、`熔金`（NC-06） | 星云材质 |
-| progress | `星火`（NC-10）、`迁流`（NC-11）、`幻境`（NC-12） | 流体进度 |
-| progress | `汐潮`（NC-13） | 潮汐边界（潮起潮落） |
-
-`dlc-color` 复用同一套星云渲染器，只做背景层，直接使用上表 capsule 的 6 个预置。
-
-`preset` 只接受上表中的文学名称（如 `'沧溟'`），大小写不敏感、首尾空格忽略；不传时使用默认预置 `初光`（胶囊/背景层）或 `星火`（进度条）。`colors`、`seed`、`speed` 是独立属性，传了覆盖预置内置值，不传用预置默认值。
-
-## H5 使用
-
-### 现代浏览器（ESM）
-
-```js
-import { createCapsule, createProgressCapsule } from '@5even7/dlc-ui';
-import '@5even7/dlc-ui/style.css';
-
-const capsule = createCapsule(document.querySelector('#host-a'), {
-  preset: '沧溟',
-  width: '100%',
-  height: 160,
-  text: '<span class="cap-name">沧溟</span>',          // 文字区插槽内容
-  colorContent: '<span class="cap-chip">DLC</span>',   // 颜色区插槽内容
-  textRatio: 39                                        // 文字区宽度占比（%）
-});
-
-const progress = createProgressCapsule(document.querySelector('#host-b'), {
-  preset: '汐潮',
-  width: 454,
-  height: 104,
-  text: '<span class="prog-name">画境观屿</span>',
-  showValue: true
-});
-
-progress.on('change', ({ value, source }) => console.log(value, source));
-```
-
-工厂调用用 `text` / `colorContent` 选项填插槽；Vue 组件直接用默认插槽和 `#color` 插槽（见下）。
-
-### 插槽与 CSS 约定（重要）
-
-两个组件都固定有两个插槽容器：
-
-- **默认插槽（文字区）**：占左侧 `textRatio` 宽度的区域；
-- **`#color` 插槽（颜色区）**：占剩余区域（文字区右侧到右边缘）。
-
-容器**默认完全透明、无内容**：不传插槽等于没有任何文字/覆盖层。容器只负责几何定位，对插槽内容施加的样式影响**只有**：
-
-1. `box-sizing: border-box` 会作用到插槽内所有元素（组件根节点统一规则）；
-2. `pointer-events: none` 会继承（组件要把点击/拖拽留给进度条和事件系统）；需要交互时在你的内容上写 `pointer-events: auto`；
-3. 根节点 `overflow: hidden` + `border-radius` 会裁剪超出区域的内容；文字区容器自身也带 `overflow: hidden`，设置 `--hj-text-radius` 时内容按圆角裁剪；
-4. **不继承组件任何文字样式**：颜色、字体、字距、大小写、padding、背景全是页面默认——空白盒子放进去就是“干净的盒子”。
-
-层级：canvas（1）< 颜色区插槽（3）< 文字区插槽（4）< 进度数字（5，仅进度条）。
-
-进度条的 `textRatio` 建议 ≤70%：再大时右侧进度数字会压到文字区上方；需要自定义数字就 `showValue=false` 并在 `#color` 插槽里自己写。
-
-### 星云背景层（dlc-color）
-
-把星云材质铺进任意容器当背景，效果与 Capsule 完全一致：
-
-```js
-import { createColorBackground } from '@5even7/dlc-ui/color';
-import '@5even7/dlc-ui/color/style.css';
-
-const background = createColorBackground(document.querySelector('#bg-host'), {
-  preset: '沧溟',
-  quality: 'auto'
-});
-
-background.setPreset('玄夜');
-background.pause();
-```
-
-层级规则：宿主会被自动设为 `position: relative; isolation: isolate`，色层是 `position: absolute; inset: 0; z-index: -1`，画在宿主普通内容**下面**——文字、按钮、图片直接放进宿主就能显示在星云上方，一行 CSS 都不用写。色层 z-index 可用 `--dlc-color-layer-z` 调整；宿主内需要保证浮在星云上的复杂层级内容可加 `position: relative; z-index: var(--dlc-color-content-z, 1)`。
-
-透明度与兜底色：`opacity`（0~1，默认 1）让宿主自己的背景透出来；`fallbackColor` 默认用预置底色兜底，消除 WebGL 首帧编译前的空窗闪烁，传十六进制色可自定义，传 `false` 可关闭。运行中可用 `setOpacity(value)` 热更新。`mouseColor` 默认开启，颜色随鼠标像油画一样旋涡，可传 `{ mouseColor: false }` 关闭，不影响宿主上其它元素的交互。
-
-### 旧浏览器 / CDN（UMD legacy）
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/@5even7/dlc-ui/styles/theme.css" />
-<script src="https://unpkg.com/@5even7/dlc-ui/dist/index.umd.min.js"></script>
-<script>
-  const { createCapsule, createProgressCapsule } = window.CosmicCapsules;
-</script>
-```
-
-## Vue3
-
-```vue
-<script setup>
+# @5even7/dlc-ui
+
+框架无关的 **星云胶囊**、**流体进度胶囊** 与 **星云背景层（dlc-color）** 组件库：WebGL2 实时渲染，不可用时自动降级 Canvas2D。一套核心，H5 / Vue2 / Vue3 都能用。
+
+零运行时依赖；现代浏览器加载原生 ESM，旧浏览器 / Vue2 老工具链走转译后的 legacy 构建（Canvas2D 降级），互不影响。
+
+## 发版规则
+
+默认每次发布**只递增补丁号（+0.01）**，例如 `0.2.0 → 0.2.1`；除非手动明确指定新版本号，否则不升次版本。
+
+## 安装
+
+```bash
+npm install @5even7/dlc-ui
+```
+
+## 预置列表
+
+| 类型 | 预置 | 说明 |
+| --- | --- | --- |
+| capsule | `初光`（NC-01）、`沧溟`（NC-02）、`玄夜`（NC-03）、`紫霄`（NC-04）、`银汉`（NC-05）、`熔金`（NC-06） | 星云材质 |
+| progress | `星火`（NC-10）、`迁流`（NC-11）、`幻境`（NC-12） | 流体进度 |
+| progress | `汐潮`（NC-13） | 潮汐边界（潮起潮落） |
+| progress | `森息`（NC-14） | 植物实验室配色（苔藓培养 / 生长进度） |
+
+`dlc-color` 复用同一套星云渲染器，只做背景层，直接使用上表 capsule 的 6 个预置。
+
+`preset` 只接受上表中的文学名称（如 `'沧溟'`），大小写不敏感、首尾空格忽略；不传时使用默认预置 `初光`（胶囊/背景层）或 `星火`（进度条）。`colors`、`seed`、`speed` 是独立属性，传了覆盖预置内置值，不传用预置默认值。
+
+## H5 使用
+
+### 现代浏览器（ESM）
+
+```js
+import { createCapsule, createProgressCapsule } from '@5even7/dlc-ui';
+import '@5even7/dlc-ui/style.css';
+
+const capsule = createCapsule(document.querySelector('#host-a'), {
+  preset: '沧溟',
+  width: '100%',
+  height: 160,
+  text: '<span class="cap-name">沧溟</span>',          // 文字区插槽内容
+  colorContent: '<span class="cap-chip">DLC</span>',   // 颜色区插槽内容
+  textRatio: 39                                        // 文字区宽度占比（%）
+});
+
+const progress = createProgressCapsule(document.querySelector('#host-b'), {
+  preset: '汐潮',
+  width: 454,
+  height: 104,
+  text: '<span class="prog-name">画境观屿</span>',
+  showValue: true
+});
+
+progress.on('change', ({ value, source }) => console.log(value, source));
+```
+
+工厂调用用 `text` / `colorContent` 选项填插槽；Vue 组件直接用默认插槽和 `#color` 插槽（见下）。
+
+### 插槽与 CSS 约定（重要）
+
+两个组件都固定有两个插槽容器：
+
+- **默认插槽（文字区）**：占左侧 `textRatio` 宽度的区域；
+- **`#color` 插槽（颜色区）**：占剩余区域（文字区右侧到右边缘）。
+
+容器**默认完全透明、无内容**：不传插槽等于没有任何文字/覆盖层。容器只负责几何定位，对插槽内容施加的样式影响**只有**：
+
+1. `box-sizing: border-box` 会作用到插槽内所有元素（组件根节点统一规则）；
+2. `pointer-events: none` 会继承（组件要把点击/拖拽留给进度条和事件系统）；需要交互时在你的内容上写 `pointer-events: auto`；
+3. 根节点 `overflow: hidden` + `border-radius` 会裁剪超出区域的内容；文字区容器自身也带 `overflow: hidden`，设置 `--hj-text-radius` 时内容按圆角裁剪；
+4. **不继承组件任何文字样式**：颜色、字体、字距、大小写、padding、背景全是页面默认——空白盒子放进去就是“干净的盒子”。
+
+层级：canvas（1）< 颜色区插槽（3）< 文字区插槽（4）< 进度数字（5，仅进度条）。
+
+进度条的 `textRatio` 建议 ≤70%：再大时右侧进度数字会压到文字区上方；需要自定义数字就 `showValue=false` 并在 `#color` 插槽里自己写。
+
+### 星云背景层（dlc-color）
+
+把星云材质铺进任意容器当背景，效果与 Capsule 完全一致：
+
+```js
+import { createColorBackground } from '@5even7/dlc-ui/color';
+import '@5even7/dlc-ui/color/style.css';
+
+const background = createColorBackground(document.querySelector('#bg-host'), {
+  preset: '沧溟',
+  quality: 'auto'
+});
+
+background.setPreset('玄夜');
+background.pause();
+```
+
+层级规则：宿主会被自动设为 `position: relative; isolation: isolate`，色层是 `position: absolute; inset: 0; z-index: -1`，画在宿主普通内容**下面**——文字、按钮、图片直接放进宿主就能显示在星云上方，一行 CSS 都不用写。色层 z-index 可用 `--dlc-color-layer-z` 调整；宿主内需要保证浮在星云上的复杂层级内容可加 `position: relative; z-index: var(--dlc-color-content-z, 1)`。
+
+透明度与兜底色：`opacity`（0~1，默认 1）让宿主自己的背景透出来；`fallbackColor` 默认用预置底色兜底，消除 WebGL 首帧编译前的空窗闪烁，传十六进制色可自定义，传 `false` 可关闭。运行中可用 `setOpacity(value)` 热更新。`mouseColor` 默认开启，颜色随鼠标像油画一样旋涡，可传 `{ mouseColor: false }` 关闭，不影响宿主上其它元素的交互。
+
+### 旧浏览器 / CDN（UMD legacy）
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@5even7/dlc-ui/styles/theme.css" />
+<script src="https://unpkg.com/@5even7/dlc-ui/dist/index.umd.min.js"></script>
+<script>
+  const { createCapsule, createProgressCapsule } = window.CosmicCapsules;
+</script>
+```
+
+## Vue3
+
+```vue
+<script setup>
 import { DlcCapsule, DlcProgress, DlcColor } from '@5even7/dlc-ui/vue3';
-import '@5even7/dlc-ui/style.css';
-
-function onProgressChange({ value }) {
-  console.log(value);
-}
-</script>
-
-<template>
+import '@5even7/dlc-ui/style.css';
+
+function onProgressChange({ value }) {
+  console.log(value);
+}
+</script>
+
+<template>
   <dlc-capsule preset="沧溟" width="100%" height="160" :text-ratio="45" @click="...">
-    <span class="cap-code">NC-02</span>
-    <span class="cap-name">沧溟</span>
-    <template #color><span class="cap-chip">DLC</span></template>
+    <span class="cap-code">NC-02</span>
+    <span class="cap-name">沧溟</span>
+    <template #color><span class="cap-chip">DLC</span></template>
   </dlc-capsule>
-
+
   <dlc-progress preset="汐潮" :width="454" :height="104" @change="onProgressChange">
-    <span class="prog-name">画境观屿</span>
+    <span class="prog-name">画境观屿</span>
   </dlc-progress>
-
+
   <dlc-color preset="沧溟" style="height: 200px">
-    这段内容显示在星云背景上方
+    这段内容显示在星云背景上方
   </dlc-color>
-</template>
-```
-
-## Vue2
-
-```js
+</template>
+```
+
+## Vue2
+
+```js
 import { DlcCapsule, DlcProgress } from '@5even7/dlc-ui/vue2';
-import '@5even7/dlc-ui/style.css';
-
-export default {
+import '@5even7/dlc-ui/style.css';
+
+export default {
   components: { DlcCapsule, DlcProgress },
-  template: `
+  template: `
     <dlc-progress preset="汐潮" :width="454" :height="104" @change="onChange">
-      <span class="prog-name">画境观屿</span>
-      <template v-slot:color><span>自定义颜色区内容</span></template>
+      <span class="prog-name">画境观屿</span>
+      <template v-slot:color><span>自定义颜色区内容</span></template>
     </dlc-progress>
-  `
-};
-```
-
-## 属性（props）
-
-两个组件共有：`preset`、`width`、`height`（数字=px，或 `px/%/vw/vh/vmin/vmax/em/rem` 字符串）、`colors`（4 个颜色，支持 `#rgb` / `#rrggbb` / CSS 命名色 / `rgb()` / `rgba()`，统一归一化为小写 6 位十六进制；`rgba()` 的 alpha 会被忽略，透明请用组件级 `opacity`）、`textRatio`（文字区宽度占比 0~100，默认胶囊 39 / 进度条 54）、`label`（覆盖默认 aria-label，胶囊另带 `role="img"`）、`quality`（`auto/low/medium/high`）、`renderer`（`auto/webgl2/canvas2d`）、`respectReducedMotion`、`cssVars`。
-
+  `
+};
+```
+
+## 属性（props）
+
+两个组件共有：`preset`、`width`、`height`（数字=px，或 `px/%/vw/vh/vmin/vmax/em/rem` 字符串）、`colors`（4 个颜色，支持 `#rgb` / `#rrggbb` / CSS 命名色 / `rgb()` / `rgba()`，统一归一化为小写 6 位十六进制；`rgba()` 的 alpha 会被忽略，透明请用组件级 `opacity`）、`textRatio`（文字区宽度占比 0~100，默认胶囊 39 / 进度条 54）、`label`（覆盖默认 aria-label，胶囊另带 `role="img"`）、`quality`（`auto/low/medium/high`）、`renderer`（`auto/webgl2/canvas2d`）、`respectReducedMotion`、`cssVars`。
+
 胶囊专属：`seed`、`speed`、`mouseColor`（颜色随鼠标旋涡，默认 `true`，关闭不影响 click/悬浮/长按等事件；Canvas2D 降级路径下 `mouseColor` 不生效）。
-
+
 进度条专属：`value`、`min`、`max`（value 的合法区间，默认 0~100；**水线归一化到 [min, max]**，右侧数字仍显示原始 value）、`draggable`、`disabled`（禁用交互并置灰）、`readonly`（禁用交互但不置灰）、`edgeStyle`（`flow/tide`）、`valueSuffix`（右侧数字后缀，默认 `%`）、`showValue`（是否显示右侧百分比数字，默认 `true`，`false` 只隐藏数字、不影响无障碍信息）。
-
-插槽内容属性（H5/工厂）：`text`、`colorContent`，支持 HTML 字符串或 DOM 节点（数组）；Vue 组件请用默认插槽 / `#color` 插槽。**注意：字符串走 innerHTML，不要传入不可信/用户直接输入的内容（XSS 风险）。**
-
+
+插槽内容属性（H5/工厂）：`text`、`colorContent`，支持 HTML 字符串或 DOM 节点（数组）；Vue 组件请用默认插槽 / `#color` 插槽。**注意：字符串走 innerHTML，不要传入不可信/用户直接输入的内容（XSS 风险）。**
+
 dlc-color 背景层（`createColorBackground(host, options)`）：`preset`、`colors`、`seed`、`speed`、`quality`、`renderer`、`mouseColor`、`respectReducedMotion`、`opacity`（0~1）、`fallbackColor`（预置底色 / 十六进制色 / false）。控制器支持 `setPreset / setColors / setSeed / setSpeed / setQuality / setOpacity / setFallbackColor / setMouseColor / randomize / pause / resume / dispose` 和 `ready / presetchange / error` 事件。Vue 里可用官方组件 `dlc-color`（从 `@5even7/dlc-ui/vue2` 或 `/vue3` 导入），它的默认插槽内容会显示在背景层上方。
-
+
 胶囊控制器额外支持 `setSeed(seed)` / `setSpeed(speed)` / `setMouseColor(value)` / `setText(content)` / `setColorContent(content)` / `setTextRatio(ratio)` / `setCssVars(vars)` / `setLabel(label)` 热更新；进度控制器额外支持 `setEdgeStyle('flow' | 'tide')` / `setValueSuffix(suffix)` / `setShowValue(show)` 和同样的插槽热更新方法。`setPreset` 只接受文学名称字符串（如 `'汐潮'`）。Vue 组件实例也暴露 `setText` / `setColorContent` / `setTextRatio` / `setCssVars` / `setLabel`（胶囊另有 `setMouseColor`，进度另有 `setValueSuffix` / `setShowValue`），与 H5 控制器对称。
-
-> 进度条是完全受控组件：组件自身不再自动增长，`value` 由使用方驱动。要自动步进，自己写定时器加值即可：
->
-> ```js
-> let value = 0;
-> const timer = setInterval(() => {
->   value = Math.min(100, value + 1);
->   progress.setValue(value); // 或 Vue 里改绑定的 value
-> }, 100);
-> // 组件销毁时记得 clearInterval(timer)
-> ```
-
-> API 是可扩展的：核心返回的控制器 `on(event, fn)` 接受任意事件名；Vue wrapper 会转发 `$emit`。`ready` / `error` 在创建后异步触发，所以先创建、后监听也能收到。attrs 落点：`id` / `data-*` / `title` 等普通属性会同步到组件内部根节点；`class` / `style` 落在外层宿主 `.hj-vue-host` 上（CSS 变量可继承到内部，类选择器请写成 `.my-class .hj-capsule-root`）。
-
-## 属性 vs cssVars 边界
-
-- **内容（文字/图片/按钮）**：只归插槽管，组件不施加任何样式；
+
+> 进度条是完全受控组件：组件自身不再自动增长，`value` 由使用方驱动。要自动步进，自己写定时器加值即可：
+>
+> ```js
+> let value = 0;
+> const timer = setInterval(() => {
+>   value = Math.min(100, value + 1);
+>   progress.setValue(value); // 或 Vue 里改绑定的 value
+> }, 100);
+> // 组件销毁时记得 clearInterval(timer)
+> ```
+
+> API 是可扩展的：核心返回的控制器 `on(event, fn)` 接受任意事件名；Vue wrapper 会转发 `$emit`。`ready` / `error` 在创建后异步触发，所以先创建、后监听也能收到。attrs 落点：`id` / `data-*` / `title` 等普通属性会同步到组件内部根节点；`class` / `style` 落在外层宿主 `.hj-vue-host` 上（CSS 变量可继承到内部，类选择器请写成 `.my-class .hj-capsule-root`）。
+
+## 属性 vs cssVars 边界
+
+- **内容（文字/图片/按钮）**：只归插槽管，组件不施加任何样式；
 - **文字区宽度**：只归 `textRatio` 属性管（唯一入口，写入 `--hj-text-width`；`0` 即隐藏文字区）；
-- **区域外观（背景/内边距/圆角/左侧距）**：只归 cssVars 管；
-- **星云颜料**：只归 `colors` 属性管（与 `#color` 插槽无关，前者改画布颜料，后者放你的覆盖内容）；
-- 旧的 `--hj-copy-*`、`--hj-progress-copy-*` 变量保留为**兼容别名**，只兜底不优先。
-
-优先级统一为：**`textRatio` > cssVars（新变量） > 旧别名 > 样式表默认**。
-
-## cssVars 完整变量表
-
-所有可调值都是 CSS 变量，直接覆盖即可：
-
-```css
-.hj-progress-root {
-  --hj-radius: 24px;
-  --hj-value-right: 16px;
-}
-```
-
-也可以在创建时传 `cssVars`：
-
-```js
-createProgressCapsule(el, {
-  preset: '汐潮',
-  cssVars: { '--hj-radius': '12px', '--hj-text-bg': 'rgba(0,0,0,0.4)' }
-});
-```
-
-| 变量 | 作用 | 默认 |
-| --- | --- | --- |
-| `--hj-text-width` | 文字区宽度（`textRatio` 写这里） | 胶囊 39% / 进度条 54% |
+- **区域外观（背景/内边距/圆角/左侧距）**：只归 cssVars 管；
+- **星云颜料**：只归 `colors` 属性管（与 `#color` 插槽无关，前者改画布颜料，后者放你的覆盖内容）；
+- 旧的 `--hj-copy-*`、`--hj-progress-copy-*` 变量保留为**兼容别名**，只兜底不优先。
+
+优先级统一为：**`textRatio` > cssVars（新变量） > 旧别名 > 样式表默认**。
+
+## cssVars 完整变量表
+
+所有可调值都是 CSS 变量，直接覆盖即可：
+
+```css
+.hj-progress-root {
+  --hj-radius: 24px;
+  --hj-value-right: 16px;
+}
+```
+
+也可以在创建时传 `cssVars`：
+
+```js
+createProgressCapsule(el, {
+  preset: '汐潮',
+  cssVars: { '--hj-radius': '12px', '--hj-text-bg': 'rgba(0,0,0,0.4)' }
+});
+```
+
+| 变量 | 作用 | 默认 |
+| --- | --- | --- |
+| `--hj-text-width` | 文字区宽度（`textRatio` 写这里） | 胶囊 39% / 进度条 54% |
 | `--hj-text-min-width` | 文字区最小宽度（仅胶囊；`textRatio` 生效时组件强制归零，样式表兜底值才是 `164px`） | `0` |
-| `--hj-text-left` | 文字区左侧距离（仅进度条） | `30px` |
-| `--hj-text-bg` | 文字区背景 | 透明 |
-| `--hj-text-pad` | 文字区内边距 | `0` |
-| `--hj-text-radius` | 文字区圆角（由容器应用，内容会被裁剪到圆角内） | `0` |
-| `--hj-radius` | 根节点圆角 | `999px` |
-| `--hj-bg` / `--hj-ink` / `--hj-muted` | 全局令牌（可被插槽内容引用） | 浅色主题值 |
-| `--hj-font` / `--hj-mono` | 字体令牌（可被插槽内容引用） | Inter / 等宽栈 |
-| `--hj-shadow` | 根节点阴影 | 柔和阴影 |
-| `--hj-value-right` | 进度数字右侧距离（仅进度条） | `30px` |
+| `--hj-text-left` | 文字区左侧距离（仅进度条） | `30px` |
+| `--hj-text-bg` | 文字区背景 | 透明 |
+| `--hj-text-pad` | 文字区内边距 | `0` |
+| `--hj-text-radius` | 文字区圆角（由容器应用，内容会被裁剪到圆角内） | `0` |
+| `--hj-radius` | 根节点圆角 | `999px` |
+| `--hj-bg` / `--hj-ink` / `--hj-muted` | 全局令牌（可被插槽内容引用） | 浅色主题值 |
+| `--hj-font` / `--hj-mono` | 字体令牌（可被插槽内容引用） | Inter / 等宽栈 |
+| `--hj-shadow` | 根节点阴影 | 柔和阴影 |
+| `--hj-value-right` | 进度数字右侧距离（仅进度条） | `30px` |
 | `--dlc-color-layer-z` | 色层 z-index（dlc-color，宿主 CSS 可覆盖） | `-1` |
-
-兼容别名（deprecated，只兜底）：`--hj-copy-width`、`--hj-copy-min-width`、`--hj-copy-pad-x`、`--hj-copy-left`、`--hj-copy-max-width`、`--hj-progress-copy-pad`、`--hj-progress-copy-bg`。
-
-## 事件
-
-| 组件 | 事件 | 载荷 |
-| --- | --- | --- |
-| capsule | `ready` / `presetchange` | `{ preset }` |
-| capsule | `click` / `pointerdown` / `pointerup` / `dblclick` | `{ event, preset }` |
-| capsule | `pointerenter` / `pointerleave` | `{ event, preset }` |
-| capsule | `error` | `{ message }`（WebGL2 不可用降级时触发） |
-| progress | `ready` / `presetchange` | `{ preset }` |
+
+兼容别名（deprecated，只兜底）：`--hj-copy-width`、`--hj-copy-min-width`、`--hj-copy-pad-x`、`--hj-copy-left`、`--hj-copy-max-width`、`--hj-progress-copy-pad`、`--hj-progress-copy-bg`。
+
+## 事件
+
+| 组件 | 事件 | 载荷 |
+| --- | --- | --- |
+| capsule | `ready` / `presetchange` | `{ preset }` |
+| capsule | `click` / `pointerdown` / `pointerup` / `dblclick` | `{ event, preset }` |
+| capsule | `pointerenter` / `pointerleave` | `{ event, preset }` |
+| capsule | `error` | `{ message }`（WebGL2 不可用降级时触发） |
+| progress | `ready` / `presetchange` | `{ preset }` |
 | progress | `change` | `{ value, source }`，source ∈ `drag/prop` |
-| progress | `dragstart` / `dragend` | `{ value }` |
-| progress | `error` | `{ message }` |
-
-## 兼容性
-
-| 目标 | 构建 | 渲染 |
-| --- | --- | --- |
-| Chrome 56+ / Edge 79+ / Firefox 51+ / Safari 15+ / iOS 15+ / 新版 Android WebView | `dist/*.mjs`（原生 ESM） | WebGL2 完整效果 |
-| IE11 / 旧 WebView / Vue2 老工具链（webpack4） | `dist/*.cjs` / `dist/index.umd.min.js`（ES5 + 内置 polyfill） | Canvas2D 降级动画 |
-
-现代浏览器永远加载不到 legacy 代码，所以老设备兼容不影响新浏览器的效果、性能与观感。
-
-## 开发
-
-```bash
-npm install
-npm run build   # 产出 dist（ESM + CJS + UMD）
-npm test        # node --test tests/
-```
-
-源码入口：`src/dlc-capsule/`（星云胶囊）、`src/dlc-progress/`（进度胶囊）、`src/dlc-color/`（星云背景层）、`src/config/`（预置/默认值/文案）、`src/core/`（调度/尺寸/质量/可见性等公共核心）。
-
-## 示例怎么看
-
-三个示例页都会展示全部 6 组星云胶囊与 4 组流体进度（含潮汐 TIDE），并为两类组件各提供一个控制台（可切换“全部/单个”目标、实时调节属性），属性表详细说明每个属性/方法/事件的用途。示例代码在 `examples/` 下。
-
-```bash
-npm run demo:h5      # http://127.0.0.1:4173/examples/h5/
-cd examples/vue3 && npm install && npm run dev   # http://127.0.0.1:5173/
-cd examples/vue2 && npm install && npm run dev   # http://127.0.0.1:5174/
-```
-
-> 首次运行前请先执行 `npm run build`（示例引用的是打包产物 `dist/`），三个示例的依赖各自独立安装。
-
-## License
-
-MIT
+| progress | `dragstart` / `dragend` | `{ value }` |
+| progress | `error` | `{ message }` |
+
+`click` 与 `dblclick` 保持原生 H5 的独立事件语义：一次双击会先产生两次 `click`，随后产生一次 `dblclick`。组件不会延迟或吞掉 `click`；若业务需要单击与双击互斥，应由业务层根据自己的等待时长与交互后果处理。
+
+## 兼容性
+
+| 目标 | 构建 | 渲染 |
+| --- | --- | --- |
+| Chrome 56+ / Edge 79+ / Firefox 51+ / Safari 15+ / iOS 15+ / 新版 Android WebView | `dist/*.mjs`（原生 ESM） | WebGL2 完整效果 |
+| IE11 / 旧 WebView / Vue2 老工具链（webpack4） | `dist/*.cjs` / `dist/index.umd.min.js`（ES5 + 内置 polyfill） | Canvas2D 降级动画 |
+
+现代浏览器永远加载不到 legacy 代码，所以老设备兼容不影响新浏览器的效果、性能与观感。
+
+## 开发
+
+```bash
+npm install
+npm run build   # 产出 dist（ESM + CJS + UMD）
+npm test        # node --test tests/
+```
+
+源码入口：`src/dlc-capsule/`（星云胶囊）、`src/dlc-progress/`（进度胶囊）、`src/dlc-color/`（星云背景层）、`src/config/`（预置/默认值/文案）、`src/core/`（调度/尺寸/质量/可见性等公共核心）。
+
+## 示例怎么看
+
+三个示例页都会展示全部 6 组星云胶囊与 5 组流体进度（含潮汐 TIDE 与森息），并为两类组件各提供一个控制台（可切换“全部/单个”目标、实时调节属性），属性表详细说明每个属性/方法/事件的用途。示例代码在 `examples/` 下。
+
+```bash
+npm run demo:h5      # http://127.0.0.1:4173/examples/h5/
+cd examples/vue3 && npm install && npm run dev   # http://127.0.0.1:5173/
+cd examples/vue2 && npm install && npm run dev   # http://127.0.0.1:5174/
+```
+
+> 首次运行前请先执行 `npm run build`（示例引用的是打包产物 `dist/`），三个示例的依赖各自独立安装。
+
+## License
+
+MIT