iter(g51): 新增 backTop 返回顶部按钮

2026-10-26 12:15:03 +08:00
parent 1eff67bccb
commit b93b6dd09b
12 changed files with 224 additions and 10 deletions
@@ -0,0 +1,46 @@
+import { h } from '@ui-arch/frame';
+import type { BackTopProps } from './types.js';
+
+/*** 返回顶部：滚动越过阈值浮现，环形进度显示已滚比例，点击平滑回顶（尊重减少动效偏好） ***/
+export function backTop(props: BackTopProps = {}): HTMLElement {
+  // —— 状态集中声明 ——
+  const threshold = props.threshold ?? 300;              // 浮现阈值
+  const scroller = props.target ?? window;               // 滚动容器
+  const el = props.target instanceof HTMLElement ? props.target : null; // 元素容器：null 表示整页
+  const ring = h('span', { class: 'ua-backtop-ring', 'aria-hidden': 'true' }); // 进度环（纯装饰）
+  const btn = h(
+    'button',
+    { type: 'button', class: 'ua-backtop', 'aria-label': '回到顶部', onClick: () => jump() },
+    ring,
+    h('span', { class: 'ua-backtop-icon', 'aria-hidden': 'true' }, '↑'),
+  ) as HTMLButtonElement;
+
+  /*** 当前滚动位置：整页用 window.scrollY，容器用 scrollTop ***/
+  const offset = (): number => (el ? el.scrollTop : window.scrollY);
+
+  /*** 可滚动总距离：不足 0 时按 0 处理，避免除零与负比例 ***/
+  const distance = (): number => (el ? el.scrollHeight - el.clientHeight : document.documentElement.scrollHeight - window.innerHeight) || 0;
+
+  /*** 同步浮现态与进度环：仅在阈值上下切换时才改类名，减少样式重算 ***/
+  const sync = (): void => {
+    const y = offset();
+    const total = distance();
+    btn.classList.toggle('is-visible', y > threshold); // 越过阈值才浮现
+    if (props.progress === false) return; // 卫语句：关掉进度环就不再算角度
+    const deg = total > 0 ? Math.min(Math.round((y / total) * 360), 360) : 0;
+    ring.style.background = `conic-gradient(var(--ua-color-accent-contrast) ${deg}deg, transparent 0)`; // 已滚比例用纯色弧
+  };
+
+  /*** 回顶：平滑滚动，用户偏好减少动效时直接跳转 ***/
+  const jump = (): void => {
+    const smooth = !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    if (el) el.scrollTo({ top: 0, behavior: smooth ? 'smooth' : 'auto' });
+    else window.scrollTo({ top: 0, behavior: smooth ? 'smooth' : 'auto' });
+    props.onClick?.();
+  };
+
+  scroller.addEventListener('scroll', sync, { passive: true }); // 被动监听：不阻塞滚动
+  window.addEventListener('resize', sync);                      // 视口变化会改可滚距离
+  sync(); // 首屏同步一次，避免刷新后停在中间位置却未浮现
+  return btn;
+}
@@ -49,3 +49,4 @@ export { cascader } from './cascader.js';
 export { splitter } from './splitter.js';
 export { autoComplete } from './autoComplete.js';
 export { datePicker } from './datePicker.js';
+export { backTop } from './backTop.js';
@@ -551,4 +551,12 @@ export interface DatePickerProps {
  onChange?: (date: string) => void;      // 选中回调（点击或 Enter）
 }

+/*** 返回顶部入参 ***/
+export interface BackTopProps {
+  target?: HTMLElement | Window; // 监听的滚动容器；缺省 window（整页）
+  threshold?: number;            // 滚动超过多少像素才浮现；缺省 300
+  progress?: boolean;            // 是否显示滚动进度环；缺省 true
+  onClick?: () => void;          // 点回顶部之后的回调（如埋点）
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方
@@ -63,7 +63,8 @@
      "cascader(props)：级联选择，多列联动面板（悬停下钻 / 点击提交），value 为路径数组信号，changeOnSelect 允许停在中间层，全键盘可操作",
      "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号",
      "autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想",
-      "datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航"
+      "datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航",
+      "backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶"
    ],
    "keyTypes": [
      "ButtonProps",
@@ -2169,6 +2170,40 @@
          "min / max 为闭区间，越界日期置灰不可点也不可键盘选中",
          "value 传信号即受控；Esc 收起（与弹窗/抽屉共用逐层关闭栈）"
        ]
+      },
+      {
+        "id": "backTop",
+        "title": "返回顶部 BackTop",
+        "demo": "sec-backtop",
+        "props": [
+          {
+            "n": "target",
+            "t": "HTMLElement | Window",
+            "d": "监听的滚动容器；缺省 window（整页）"
+          },
+          {
+            "n": "threshold",
+            "t": "number",
+            "d": "滚动超过多少像素才浮现；缺省 300"
+          },
+          {
+            "n": "progress",
+            "t": "boolean",
+            "d": "是否显示滚动进度环；缺省 true"
+          },
+          {
+            "n": "onClick",
+            "t": "() => void",
+            "d": "回顶之后的回调（适合埋点）"
+          }
+        ],
+        "example": "backTop({ threshold: 300, onClick: () => toast.info('已回到顶部') })",
+        "steps": [
+          "把返回的元素挂到页面任意位置即可，组件自身 position: fixed 定位在右下角",
+          "滚动越过 threshold 才浮现（淡入 + 上移微动画），回到阈值内自动隐藏",
+          "progress 为 true 时外环弧长等于已滚比例；内滚容器用 target 传入该元素",
+          "点击平滑回顶；系统开启「减少动效」时改为瞬间跳转"
+        ]
      }
    ]
  }
@@ -2963,3 +2963,54 @@ button.ua-step-dot:hover {
  .ua-datepicker-day,
  .ua-datepicker-nav { transition: none; }
 }
+.ua-backtop {
+  position: fixed;
+  right: 24px;
+  bottom: 24px;
+  z-index: 60;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 44px;
+  height: 44px;
+  padding: 0;
+  color: var(--ua-color-accent-contrast);
+  background: var(--ua-color-accent);
+  border: none;
+  border-radius: 50%;
+  cursor: pointer;
+  opacity: 0;
+  transform: translateY(8px) scale(0.9);
+  pointer-events: none;
+  transition: opacity 0.2s ease, transform 0.2s ease;
+  box-shadow: 0 8px 20px color-mix(in srgb, var(--ua-color-accent) 35%, transparent);
+}
+.ua-backtop.is-visible {
+  opacity: 1;
+  transform: none;
+  pointer-events: auto;
+}
+.ua-backtop.is-visible:hover {
+  transform: translateY(-2px);
+}
+.ua-backtop:focus-visible {
+  outline: 2px solid var(--ua-color-accent);
+  outline-offset: 3px;
+}
+.ua-backtop-ring {
+  position: absolute;
+  inset: -4px;
+  border-radius: 50%;
+  pointer-events: none;
+  -webkit-mask: radial-gradient(farthest-side, transparent calc(100% - 3px), var(--ua-color-text) calc(100% - 3px));
+  mask: radial-gradient(farthest-side, transparent calc(100% - 3px), var(--ua-color-text) calc(100% - 3px));
+}
+.ua-backtop-icon {
+  font-size: var(--ua-font-size-lg);
+  line-height: 1;
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-backtop {
+    transition: none;
+  }
+}