@w-run/wdesign-ui 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (214) hide show
  1. package/README.md +255 -2
  2. package/dist/index.d.ts +1013 -0
  3. package/dist/parts/WdAffix.js +159 -0
  4. package/dist/parts/WdAiMessage.js +277 -0
  5. package/dist/parts/WdAlert.js +92 -0
  6. package/dist/parts/WdAnchor.js +159 -0
  7. package/dist/parts/WdAudioPlayer.js +1024 -0
  8. package/dist/parts/WdAvatar.js +6 -0
  9. package/dist/parts/WdAvatarGroup.js +46 -0
  10. package/dist/parts/WdBacktop.js +120 -0
  11. package/dist/parts/WdBadge.js +61 -0
  12. package/dist/parts/WdBento.js +40 -0
  13. package/dist/parts/WdBentoItem.js +43 -0
  14. package/dist/parts/WdBottomSheet.js +263 -0
  15. package/dist/parts/WdBreadcrumb.js +64 -0
  16. package/dist/parts/WdButton.js +94 -0
  17. package/dist/parts/WdCalendar.js +11 -0
  18. package/dist/parts/WdCard.js +113 -0
  19. package/dist/parts/WdCarousel.js +365 -0
  20. package/dist/parts/WdCascader.js +386 -0
  21. package/dist/parts/WdCheckbox.js +81 -0
  22. package/dist/parts/WdCollapse.js +135 -0
  23. package/dist/parts/WdColorPicker.js +592 -0
  24. package/dist/parts/WdCommand.js +357 -0
  25. package/dist/parts/WdContainer.js +37 -0
  26. package/dist/parts/WdCountdown.js +163 -0
  27. package/dist/parts/WdDanmaku.js +6 -0
  28. package/dist/parts/WdDatePicker.js +169 -0
  29. package/dist/parts/WdDateTimePicker.js +162 -0
  30. package/dist/parts/WdDescriptions.js +146 -0
  31. package/dist/parts/WdDivider.js +64 -0
  32. package/dist/parts/WdDrawer.js +176 -0
  33. package/dist/parts/WdDropdown.js +140 -0
  34. package/dist/parts/WdEmpty.js +79 -0
  35. package/dist/parts/WdExplorer.js +336 -0
  36. package/dist/parts/WdFileList.js +177 -0
  37. package/dist/parts/WdForm.js +111 -0
  38. package/dist/parts/WdFormItem.js +156 -0
  39. package/dist/parts/WdGrid.js +40 -0
  40. package/dist/parts/WdGroup.js +68 -0
  41. package/dist/parts/WdImagePreview.js +274 -0
  42. package/dist/parts/WdInput.js +10 -0
  43. package/dist/parts/WdInputNumber.js +253 -0
  44. package/dist/parts/WdListItem.js +60 -0
  45. package/dist/parts/WdLoading.js +128 -0
  46. package/dist/parts/WdMarkdown.js +172 -0
  47. package/dist/parts/WdMarquee.js +80 -0
  48. package/dist/parts/WdMasonry.js +40 -0
  49. package/dist/parts/WdMediaCard.js +302 -0
  50. package/dist/parts/WdMentions.js +277 -0
  51. package/dist/parts/WdModal.js +149 -0
  52. package/dist/parts/WdNav.js +311 -0
  53. package/dist/parts/WdNotification.js +112 -0
  54. package/dist/parts/WdOtp.js +107 -0
  55. package/dist/parts/WdPagination.js +252 -0
  56. package/dist/parts/WdPopconfirm.js +214 -0
  57. package/dist/parts/WdPopover.js +203 -0
  58. package/dist/parts/WdPostItem.js +84 -0
  59. package/dist/parts/WdProgress.js +48 -0
  60. package/dist/parts/WdProgressRing.js +101 -0
  61. package/dist/parts/WdPullRefresh.js +167 -0
  62. package/dist/parts/WdQRCode.js +1909 -0
  63. package/dist/parts/WdRadioGroup.js +95 -0
  64. package/dist/parts/WdRate.js +128 -0
  65. package/dist/parts/WdResult.js +86 -0
  66. package/dist/parts/WdScrollbar.js +186 -0
  67. package/dist/parts/WdSegmented.js +11 -0
  68. package/dist/parts/WdSelect.js +465 -0
  69. package/dist/parts/WdSkeleton.js +69 -0
  70. package/dist/parts/WdSlider.js +100 -0
  71. package/dist/parts/WdSortableList.js +291 -0
  72. package/dist/parts/WdSpace.js +46 -0
  73. package/dist/parts/WdSparkline.js +148 -0
  74. package/dist/parts/WdSpinner.js +6 -0
  75. package/dist/parts/WdSplitter.js +183 -0
  76. package/dist/parts/WdStatBar.js +202 -0
  77. package/dist/parts/WdStatistic.js +131 -0
  78. package/dist/parts/WdSteps.js +110 -0
  79. package/dist/parts/WdSwitch.js +63 -0
  80. package/dist/parts/WdTabBar.js +84 -0
  81. package/dist/parts/WdTable.js +589 -0
  82. package/dist/parts/WdTabs.js +219 -0
  83. package/dist/parts/WdTag.js +6 -0
  84. package/dist/parts/WdTagInput.js +181 -0
  85. package/dist/parts/WdTimePicker.js +12 -0
  86. package/dist/parts/WdTimeline.js +145 -0
  87. package/dist/parts/WdTooltip.js +108 -0
  88. package/dist/parts/WdTour.js +264 -0
  89. package/dist/parts/WdTransfer.js +446 -0
  90. package/dist/parts/WdTree.js +322 -0
  91. package/dist/parts/WdUpload.js +309 -0
  92. package/dist/parts/WdVideoPlayer.js +1006 -0
  93. package/dist/parts/WdVirtualList.js +169 -0
  94. package/dist/parts/WdWatermark.js +150 -0
  95. package/dist/parts/chunk-3LVE72ZK.js +361 -0
  96. package/dist/parts/chunk-5HYOQ52I.js +101 -0
  97. package/dist/parts/chunk-7M3MUL3B.js +275 -0
  98. package/dist/parts/chunk-AOTJ63HN.js +15 -0
  99. package/dist/parts/chunk-AXEF2U2A.js +41 -0
  100. package/dist/parts/chunk-CY3QOSFP.js +645 -0
  101. package/dist/parts/chunk-G7NN4A6J.js +40 -0
  102. package/dist/parts/chunk-HAKYCUAR.js +9 -0
  103. package/dist/parts/chunk-JDE4AHBR.js +160 -0
  104. package/dist/parts/chunk-LT3NTWIT.js +117 -0
  105. package/dist/parts/chunk-OGHYFT7B.js +387 -0
  106. package/dist/parts/chunk-Q34U2HES.js +261 -0
  107. package/dist/parts/chunk-RLSVPJHM.js +10 -0
  108. package/dist/parts/chunk-U2CDKD2T.js +30 -0
  109. package/dist/parts/chunk-UYUNYHZD.js +40 -0
  110. package/dist/parts/chunk-VUJL2HGD.js +23 -0
  111. package/dist/parts/chunk-WCFG5KNT.js +51 -0
  112. package/dist/parts/chunk-WDDAALPI.js +42 -0
  113. package/dist/parts/chunk-WFXLDBP2.js +149 -0
  114. package/dist/style/affix.css +566 -0
  115. package/dist/style/ai-msg.css +746 -0
  116. package/dist/style/alert.css +636 -0
  117. package/dist/style/anchor.css +630 -0
  118. package/dist/style/audio.css +1954 -0
  119. package/dist/style/avatar.css +651 -0
  120. package/dist/style/backtop.css +625 -0
  121. package/dist/style/badge.css +632 -0
  122. package/dist/style/bento.css +763 -0
  123. package/dist/style/bottom-sheet.css +776 -0
  124. package/dist/style/breadcrumb.css +629 -0
  125. package/dist/style/button.css +829 -0
  126. package/dist/style/calendar.css +1512 -0
  127. package/dist/style/card.css +748 -0
  128. package/dist/style/carousel.css +670 -0
  129. package/dist/style/cascader.css +862 -0
  130. package/dist/style/checkbox.css +706 -0
  131. package/dist/style/chevron.css +575 -0
  132. package/dist/style/collapse.css +648 -0
  133. package/dist/style/colorpicker.css +876 -0
  134. package/dist/style/command.css +760 -0
  135. package/dist/style/container.css +550 -0
  136. package/dist/style/countdown.css +722 -0
  137. package/dist/style/danmaku.css +644 -0
  138. package/dist/style/datepicker.css +683 -0
  139. package/dist/style/datetime-picker.css +714 -0
  140. package/dist/style/descriptions.css +712 -0
  141. package/dist/style/divider.css +604 -0
  142. package/dist/style/dot.css +585 -0
  143. package/dist/style/drawer.css +743 -0
  144. package/dist/style/dropdown.css +645 -0
  145. package/dist/style/empty.css +657 -0
  146. package/dist/style/explorer.css +944 -0
  147. package/dist/style/file-list.css +664 -0
  148. package/dist/style/flip.css +600 -0
  149. package/dist/style/form.css +638 -0
  150. package/dist/style/grid.css +618 -0
  151. package/dist/style/group.css +1022 -0
  152. package/dist/style/icon-btn.css +641 -0
  153. package/dist/style/image-preview.css +725 -0
  154. package/dist/style/input-number.css +680 -0
  155. package/dist/style/input.css +682 -0
  156. package/dist/style/list.css +630 -0
  157. package/dist/style/loading.css +667 -0
  158. package/dist/style/markdown.css +884 -0
  159. package/dist/style/marquee.css +678 -0
  160. package/dist/style/masonry.css +614 -0
  161. package/dist/style/media-card.css +1229 -0
  162. package/dist/style/mentions.css +690 -0
  163. package/dist/style/modal.css +775 -0
  164. package/dist/style/nav.css +1046 -0
  165. package/dist/style/notification.css +601 -0
  166. package/dist/style/otp.css +699 -0
  167. package/dist/style/pagination.css +680 -0
  168. package/dist/style/popconfirm.css +645 -0
  169. package/dist/style/popover.css +740 -0
  170. package/dist/style/post-item.css +676 -0
  171. package/dist/style/progress-ring.css +640 -0
  172. package/dist/style/progress.css +576 -0
  173. package/dist/style/pull-refresh.css +637 -0
  174. package/dist/style/qrcode.css +613 -0
  175. package/dist/style/radio.css +705 -0
  176. package/dist/style/rate.css +637 -0
  177. package/dist/style/result.css +597 -0
  178. package/dist/style/scroll-reveal.css +613 -0
  179. package/dist/style/scrollbar.css +644 -0
  180. package/dist/style/segmented-picker.css +679 -0
  181. package/dist/style/segmented.css +894 -0
  182. package/dist/style/select.css +937 -0
  183. package/dist/style/skeleton.css +590 -0
  184. package/dist/style/slider.css +642 -0
  185. package/dist/style/sortable.css +714 -0
  186. package/dist/style/space.css +568 -0
  187. package/dist/style/sparkline.css +606 -0
  188. package/dist/style/spinner.css +586 -0
  189. package/dist/style/splitter.css +711 -0
  190. package/dist/style/stat-bar.css +767 -0
  191. package/dist/style/statistic.css +589 -0
  192. package/dist/style/steps.css +724 -0
  193. package/dist/style/switch.css +676 -0
  194. package/dist/style/tab-bar.css +647 -0
  195. package/dist/style/table.css +1229 -0
  196. package/dist/style/tabs.css +756 -0
  197. package/dist/style/tag-input.css +710 -0
  198. package/dist/style/tag.css +682 -0
  199. package/dist/style/time-picker.css +749 -0
  200. package/dist/style/timeline.css +1082 -0
  201. package/dist/style/toast.css +598 -0
  202. package/dist/style/tooltip.css +604 -0
  203. package/dist/style/tour.css +683 -0
  204. package/dist/style/transfer.css +858 -0
  205. package/dist/style/tree.css +786 -0
  206. package/dist/style/typography.css +947 -0
  207. package/dist/style/upload.css +758 -0
  208. package/dist/style/vlist.css +591 -0
  209. package/dist/style/vplayer.css +1588 -0
  210. package/dist/style/watermark.css +570 -0
  211. package/dist/wdesign-ui.css +21093 -0
  212. package/dist/wdesign-ui.esm.js +20265 -0
  213. package/package.json +134 -4
  214. package/tokens.json +385 -0
package/README.md CHANGED
@@ -1,3 +1,256 @@
1
- # Temporary Holding Version
1
+ # @w-run/wdesign-ui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Vue3 + SCSS 组件库。**92 个组件**、194 个设计令牌、全量样式与按需样式入口,
4
+ 配套图标库 [`@w-run/wdesign-icons`](../icons)。
5
+
6
+ > 代码约定与写法硬规则见 [CONVENTIONS.md](./CONVENTIONS.md);
7
+ > 令牌清单见 [TOKENS.md](./TOKENS.md);
8
+ > 只发 ESM,`dist/` 由 `tools/build-lib.mjs` 生成。
9
+
10
+ ## 设计四原则(硬规则)
11
+
12
+ 1. **主题色 `#D62839`** —— 红只做点缀,界面红色面积 ≤ 10%
13
+ 2. **不用硬边框 / 分割线** —— 区域只用色块分层 + 留白区分
14
+ 3. **圆润优先** —— 大圆角、胶囊、软几何
15
+ 4. **留白、极简** —— 少色、少元素、一屏一个焦点
16
+
17
+ ### 区域分层
18
+
19
+ | 层 | 色值 | 用途 |
20
+ |---|---|---|
21
+ | L0 页面底 | `#F7F8FA` | 画布 |
22
+ | L1 卡片 | `#FFFFFF` + 单层阴影 | 内容容器 |
23
+ | L2 浅色块 | `#FBEAEB`(更浅 `#FDF2F3`) | 高亮 / 选中 / 次级按钮 |
24
+ | L3 主题红 | `#D62839` | 主按钮 / 关键数据 / 进度 |
25
+ | L4 深色锚点 | `#1C1C1C` / `#2F2F2F` | 深色卡 · 两级(锚点 / 浮层) |
26
+
27
+ 浅色与深色主题的**主题色都是 `#D62839`**,只换底与文字,不换红。
28
+
29
+ ## 安装与使用
30
+
31
+ ```bash
32
+ npm i @w-run/wdesign-ui @w-run/wdesign-icons
33
+ npm i -D sass # 只有要用源码 scss 时才需要
34
+ ```
35
+
36
+ ```ts
37
+ import { createApp } from 'vue'
38
+ import { WdButton, WdIcon } from '@w-run/wdesign-ui'
39
+ import '@w-run/wdesign-ui/style' // 全量样式(推荐)
40
+ import '@w-run/wdesign-icons/style.css'
41
+
42
+ const app = createApp(App)
43
+ app.component('WdButton', WdButton)
44
+ app.component('WdIcon', WdIcon)
45
+ app.mount('#app')
46
+ ```
47
+
48
+ ```vue
49
+ <WdButton variant="primary" size="lg">主按钮</WdButton>
50
+ <WdIcon name="heart" :size="28" />
51
+ ```
52
+
53
+ ### JS 按需引入
54
+
55
+ 整包是 778 KB(未压缩)。只想要一两个组件时,走 `parts/` 入口:
56
+
57
+ ```ts
58
+ // 只引一个按钮 —— 打包器只会带进它真正依赖的代码
59
+ import WdButton from '@w-run/wdesign-ui/parts/WdButton'
60
+ import '@w-run/wdesign-ui/style/tokens'
61
+ import '@w-run/wdesign-ui/style/base'
62
+ import '@w-run/wdesign-ui/style/button'
63
+ ```
64
+
65
+ 实测(esbuild,仅引 `WdButton`):
66
+
67
+ | 方式 | 产物大小 |
68
+ |---|---|
69
+ | `import { WdButton } from '@w-run/wdesign-ui'` | 778 KB |
70
+ | `import WdButton from '@w-run/wdesign-ui/parts/WdButton'` | **10 KB** |
71
+
72
+ > 差约 78 倍。91 个组件每个都有对应的 `parts/<Name>.js`,
73
+ > 公共部分由打包器自动抽成共享 chunk,不会重复下载。
74
+
75
+ > 整包入口照常可用 —— `parts/` 是多一条路,不是替换。
76
+ > 组件多到几十个时,整包反而更划算(共享 chunk 会被摊薄)。
77
+
78
+ ### 样式入口
79
+
80
+ | 入口 | 内容 |
81
+ |---|---|
82
+ | `@w-run/wdesign-ui/style` | 全量(令牌 + 字体 + base + 全部组件 + 深色) |
83
+ | `@w-run/wdesign-ui/style/button` | 单个组件原子件(需自己先引令牌) |
84
+
85
+ 自己拼装时按这个顺序:
86
+
87
+ ```scss
88
+ @use '@w-run/wdesign-ui/style/tokens'; // :root { --wd-* },全站只发射一次
89
+ @use '@w-run/wdesign-ui/style/fonts'; // @font-face
90
+ @use '@w-run/wdesign-ui/style/base'; // reset + 滚动条 + reduced-motion
91
+ @use '@w-run/wdesign-ui/style/button'; // 你真正用到的组件
92
+ ```
93
+
94
+ > ⚠️ 原子件只引用 `var(--wd-*)`,自己**不发射**变量。跳过 `tokens` 会得到一份
95
+ > 「颜色全部失效但样式表照样加载」的产物 —— 不报错、不告警,最难查的一类问题。
96
+
97
+ ## 组件一览
98
+
99
+ ### 基础
100
+
101
+ | 组件 | 说明 |
102
+ |---|---|
103
+ | `WdButton` | 按钮:`variant` primary/tint/dark/ghost;`size` lg/md/sm;`iconOnly`、`block`、`loading` |
104
+ | `WdTag` | 标签:`variant` tint/gray/dark;`dot` |
105
+ | `WdBadge` | 徽标:`value`、`dot`、`max`、`tone` |
106
+ | `WdAvatar` / `WdAvatarGroup` | 头像 / 头像堆叠:`tone` 0–3 明度档(0 = 按名字自动)、`max` |
107
+ | `WdDivider` | 分隔:水平/垂直、带文字对齐、虚线 |
108
+ | `WdSpace` | 间距容器:`size`、`direction`、`between`、`grow` |
109
+ | `WdGrid` | 网格:`columns`(数字或 `auto`)、`gap` |
110
+ | `WdBento` | **拼贴栅格**:格子可跨列跨行,大小错落但边缘严格对齐。`columns` 基准列数、`rowHeight` 行高基准、`gap` 三档。和 `WdGrid`(等宽列)分场景:列表用 Grid,首屏 / 作品集 / 仪表盘用 Bento。⚠️ 与 `WdMasonry` 的区别:瀑布流按内容高度排(边缘不齐),拼贴按固定行高跨行(边缘对齐)。 |
111
+ | `WdBentoItem` | Bento 的子项:`colSpan` / `rowSpan` 跨列跨行、`tone` flat\|tint\|ink、`radius` 四档、`interactive` 可点击(hover 抬升 + 焦点环,渲染为 `<button>`)。 |
112
+ | `WdContainer` | 版心:`maxWidth`、`pad` |
113
+ | `WdCard` | 卡片:`variant` default/tint/dark、`padding`、`hoverable`;**结构化头部** `title`/`meta`/`cover` + `#extra` 右侧动作、`#footer` 页脚 |
114
+ | `WdGroup` | 控件组:capsule/joined/inset,自动压掉子项外框 |
115
+
116
+ ### 表单
117
+
118
+ | 组件 | 说明 |
119
+ |---|---|
120
+ | `WdInput` | 输入框:`shape` pill/rounded、`clearable`、`showCount`;`#icon` / `#suffix` |
121
+ | `WdSelect` | 选择:单选/多选、`filterable`、`maxTagCount` |
122
+ | `WdCascader` | 级联:`options` 树、`changeOnSelect` |
123
+ | `WdCheckbox` / `WdSwitch` / `WdRadioGroup` | 勾选 / 开关 / 单选组,均支持受控与非受控 |
124
+ | `WdSegmented` | 分段控制:`tone` light/dark、`overflow` wrap/scroll/auto |
125
+ | `WdSlider` | 滑杆:`min`/`max`/`step`、`showValue` |
126
+ | `WdRate` | 评分:`count`、`clearable`、自定义 `icon` |
127
+ | `WdColorPicker` | 取色:`presets`、`editable` |
128
+ | `WdOtp` | 验证码:separate/pill/underline,自动前进/回退/粘贴 |
129
+ | `WdMentions` | @ 提及:`users`、`trigger` |
130
+ | `WdUpload` | 上传:拖拽 + 进度、`maxCount`/`maxSize` |
131
+ | `WdTransfer` | 穿梭框:`data`、`filterable` |
132
+ | `WdForm` / `WdFormItem` | 表单:`rules` 校验、`labelPosition`、`scrollToError` |
133
+ | `WdDatePicker` / `WdTimePicker` / `WdDateTimePicker` / `WdCalendar` | 日期、时间、日期时间、日历(区间 + 标记 + 底部文字) |
134
+ | `WdSortableList` | 拖动排序(HTML5 拖拽) |
135
+ | `WdInputNumber` | 数字输入:`min`/`max`/`step`/`precision`、长按连续增减、`shape` pill、`hideStep` |
136
+ | `WdTagInput` | 标签输入:回车/逗号成标签、**退格删末尾(仅输入框为空时)**、**输入法组合期间的 Enter 不上屏**、`max`/`maxlength`/`allowDuplicate`/`separators` |
137
+
138
+ ### 数据展示
139
+
140
+ | 组件 | 说明 |
141
+ |---|---|
142
+ | `WdTable` | 表格:排序、勾选、展开行、树形、`maxHeight` 吸顶;`#cell-<key>` 插槽 |
143
+ | `WdTree` | 树:`checkable`、`cascade`、自定义 `#label`/`#icon`/`#extra` |
144
+ | `WdVirtualList` | 虚拟列表:只渲染可视区,万级数据不卡 |
145
+ | `WdPagination` | 分页:`simple`、`showSizeChanger` |
146
+ | `WdDescriptions` | 描述列表:`columns`、`vertical`、`striped` |
147
+ | `WdStatistic` | 数值:`precision`、`separator`、进场滚动 |
148
+ | `WdSparkline` | **迷你趋势线**:把一串数字画成形,只做「趋势」这一件事。`data` 数据点、`height` 高度、`area` 面积填充、`dot` 末点标记、`smooth` 平滑度(0 折线 / 1 平滑)、`color` 线条色、`label` 无障碍描述(必填)。纯 SVG 手画、零依赖,不引图表库 —— 代价是不做坐标轴 / tooltip / 多系列,那些该交给真正的图表库。⚠️ 数据点少于 5 个时建议用折线(`smooth=0`),平滑会把峰值削平。 |
149
+ | `WdStatBar` | 指标条组:`items`、`countUp` 数字滚动、`surface` 底/无底 |
150
+ | `WdCountdown` | 倒计时:`target`、`format`、`labels`、`hideZeroDays`、`colon` 冒号分隔 |
151
+ | `WdTabBar` | 移动端底部标签栏:`items`、`floating` 悬浮胶囊、`fab` 中央凸起按钮 |
152
+ | `WdTimeline` | 时间线:vertical/alternate/horizontal、`collapsible` |
153
+ | `WdCollapse` | 折叠:`accordion`、`#item-<i>` 插槽 |
154
+ | `WdTabs` | 页签:`closable`、`addable`、`scrollable` |
155
+ | `WdSteps` | 步骤条:`current` |
156
+ | `WdProgress` | 进度:`thin`、`onDark`、自定义色 |
157
+ | `WdProgressRing` | **环形进度**:独立指标的环形表达,中心可放数字/图标/文案。`value` 0–100、`size` 直径、`thickness` 环宽、`color` 进度色、`intent`(normal/inverse,inverse 时默认走中性色——别把「80% 错误率」画成喜庆红)、`onDark` 深色底、`label` 无障碍(必填)。默认插槽替换中心内容。用 stroke-dasharray 画,不是 conic-gradient(后者接缝有硬边、做不了圆头端帽)。⚠️ 与 `WdProgress` 不是替代关系:条形用于行内/表格,环形用于独立指标。 |
158
+ | `WdPullRefresh` | **下拉刷新**:移动端「下拉看有没有新内容」。`threshold` 触发距离(默认 64)、`damping` 阻尼系数(默认 0.5,手指拖 100px 内容走 50px)、`max` 最大位移、`refreshing` 受控刷新态、`pullText`/`releaseText`/`loadingText` 三态文案。受控用 `:refreshing` 自己收尾;非受控用 ref 调 `done()`。⚠️ 只在**滚动容器到顶时**才接管手势,否则往下滑列表会误触;`touch-action: pan-x` 保留横向手势。 |
159
+ | `WdSkeleton` | 骨架:text/rect/circle、`count` |
160
+ | `WdEmpty` / `WdResult` | 空状态 / 结果页。空状态支持 `size` sm/md/lg(嵌入卡片 vs 整页)与 `variant` empty/search/error(**只有 error 用红**,`role=alert`) |
161
+ | `WdExplorer` | 资源管理器:详情 / 图标双视图 |
162
+ | `WdFileList` | 文件树列表 |
163
+ | `WdScrollbar` | 自定义滚动条:`always`、`native` 兜底 |
164
+ | `WdSplitter` | 分栏:横向/纵向拖拽,`resize` / `resizeEnd` |
165
+
166
+ ### 反馈
167
+
168
+ | 组件 | 说明 |
169
+ |---|---|
170
+ | `WdAlert` | 提示条:info/success/warning/danger、`closable` |
171
+ | `WdModal` / `WdDrawer` | 模态框 / 抽屉:Teleport + 焦点陷阱 + 层栈 |
172
+ | `WdBottomSheet` | 移动端底部面板:全宽升起、抓手条**可下拉关闭**(超过 1/4 高度或甩得够快)、内容区独立滚动、自动留底部安全区。`swipeable=false` 关掉下拉防误触,`bodyFlush` 贴边内容,`footer` 放主操作 |
173
+ | `WdMarquee` | 无限滚动带:内容复制一份、整体位移 -50%,**接缝处看不出跳回**。`direction` 反向滚、`speed` 是走完一轮的秒数、`gap` 控制项间距。`pauseOnHover` 只在真有指针的设备生效(触摸屏 hover 会粘住,所以不绑)。系统开启「减少动态效果」时不再滚动,改成可横向拖动的静态条 —— 内容不会因此被藏起来。两端渐隐用 mask 实现,`fade=false` 可关。 |
174
+ | `WdMasonry` | 瀑布流布局:**不等高内容按列堆叠**,自动加列、窄屏降列。`columns` 传数字或 `auto`(按 `minColumn` 最小列宽自己决定列数),`gap` 三档。纯 CSS multi-column 实现,不靠 JS 量高度 —— 图片没加载完时 JS 量出来是 0,得监听每张 load,之后窗口一变又要重排。每个子项都做了 `break-inside: avoid`,避免卡片被从中间劈开。⚠️ 它按列填充,视觉顺序是「一列一列」而非「一行一行」;**顺序重要时请用 WdGrid**。 |
175
+ | `WdNotification` | 通知横幅 |
176
+ | `toast()` | 命令式轻提示:`toast.success / warning / danger`,最多堆 4 条 |
177
+ | `WdPopconfirm` / `WdPopover` / `WdTooltip` / `WdDropdown` | 气泡类,走 `anchor` 定位 + 外部点击 |
178
+ | `WdSpinner` | 加载圈:`size` sm/md/lg 或像素值 |
179
+ | `WdLoading` | 区域加载遮罩:`loading`、`delay` 防闪烁、`fullscreen`、`opacity` |
180
+ | `WdTour` | 新手引导:`steps` 指向元素、遮罩挖洞、上一步/下一步/跳过、`maskOpacity` |
181
+
182
+ ### 导航
183
+
184
+ | 组件 | 说明 |
185
+ |---|---|
186
+ | `WdNav` | 导航:横栏/竖栏、`collapsed`、`iconOnly`、`sticky`、**分组可折叠**(`collapsibleGroups` + `defaultCollapsedGroups`,active 落到收起分组会自动展开并滚入视野) |
187
+ | `WdBreadcrumb` | 面包屑:`items`、`separator` |
188
+ | `WdCommand` | 命令面板(⌘K):分组、快捷键、远程 `search` |
189
+ | `WdAffix` / `WdBacktop` | 吸附 / 回到顶部 |
190
+ | `WdAnchor` | 目录/锚点导航:滚动高亮(**容器滚动与窗口滚动都支持**)、点击平滑滚动、`items`/`target`/`offset`/`stickyTop`、可受控 |
191
+
192
+ ### 媒体
193
+
194
+ | 组件 | 说明 |
195
+ |---|---|
196
+ | `WdCarousel` | 轮播:自动播放、圆点、箭头、无缝循环 |
197
+ | `WdImagePreview` | 灯箱:缩放、旋转、上一张/下一张 |
198
+ | `WdAudioPlayer` | 音频:card/bar/mini 三形态、波形、反色卡 |
199
+ | `WdVideoPlayer` | 视频:点播/直播、选集、倍速、画中画、弹幕 |
200
+ | `WdDanmaku` | 弹幕层:`items` / `src`(B 站 XML)/ `raw` |
201
+ | `WdMediaCard` | 媒体卡:`layout`(overlay/stacked)× `mediaMode`(cover/inset)两个正交维度 |
202
+
203
+ ### 内容与其他
204
+
205
+ | 组件 | 说明 |
206
+ |---|---|
207
+ | `WdMarkdown` | Markdown 渲染:内置解析器 + hljs 深色代码配色 |
208
+ | `WdAiMessage` | AI 消息:正文与思考链分离、流式输出、`actions` |
209
+ | `WdPostItem` / `WdListItem` | 文章条目 / 列表行 |
210
+ | `WdQRCode` | 二维码:dot/liquid 模块样式、中心挖空放 logo |
211
+ | `WdWatermark` | 水印:文字/图片、旋转、间距 |
212
+
213
+ ## 令牌与主题
214
+
215
+ ```css
216
+ :root {
217
+ --wd-red: #E5484D; /* 换主题色 */
218
+ --wd-tint-2: #FDECEC; /* 浅色块 */
219
+ --wd-radius-lg: 20px; /* 收紧圆角 */
220
+ }
221
+ ```
222
+
223
+ - 组件样式**只引用 `var(--wd-*)`**,且**不写 fallback** —— 令牌名写错时要立刻失效,
224
+ 而不是被兜底值掩盖(理由见 CONVENTIONS)。
225
+ - 深色:`<html data-theme="dark">` 整套翻转,**主题红不变**。
226
+
227
+ ## 字体
228
+
229
+ - 拉丁 **Mona Sans**、中文 **思源黑体 / Source Han Sans SC**,均为 VF 可变字体(wght 200–900),
230
+ 默认从 `https://box.w-run.net/npm/fonts` 加载。
231
+ - 离线 / 内网:自己写 `@font-face` 并把 `$wd-vf-fonts-enabled` 置 `false`(必须在 import 之前),
232
+ 避免多请求一次 CDN。VF 文件就在本包 `fonts/` 下。
233
+ - **WDesignSans**(自托管分段字体)仍是 WIP,默认关闭(`$wd-wdsans-enabled`):
234
+ 文件不在本仓库,宿主托管好再打开。
235
+
236
+ ## 检查器
237
+
238
+ ```sh
239
+ npm run verify # check:tokens + check:icons + typecheck + smoke-test
240
+ ```
241
+
242
+ 冒烟测试(484 项)覆盖的结构性断言:组件可编译 / `defineOptions.name` / 事件名 kebab-case /
243
+ 无手写 `<svg>` / 浮层 Teleport / `transition` 有 `:duration` 兜底 / 令牌与图标名存在 /
244
+ 模板用到的 BEM 类名有定义 / **组件内部引用别的组件必须自己 import** /
245
+ **全量样式入口收全每个原子件** / `box-sizing` 声明唯一。
246
+
247
+ > 修完检查器**必须注入一个已知错误验证它仍然会失败**,否则等于把刹车拆了。
248
+
249
+ ## 演示
250
+
251
+ 演示站是独立包 [`../wdesign-demo`](../wdesign-demo):`pnpm dev` 起在 `:5273`,
252
+ 92 个组件一页一个,通过 alias 直连本包源码,改组件即时生效。
253
+
254
+ ## License
255
+
256
+ MIT