iter(g51): 新增 backTop 返回顶部按钮
This commit is contained in:
HIsheR
+37
-2
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"$schema": "ui-arch-registry-index/0.1",
|
||||
"generatedAt": "2026-10-26T04:13:49.611Z",
|
||||
"generatedAt": "2026-10-26T04:14:40.933Z",
|
||||
"repoRoot": ".",
|
||||
"packages": [
|
||||
{
|
||||
@@ -192,7 +192,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",
|
||||
@@ -2298,6 +2299,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 传入该元素",
|
||||
"点击平滑回顶；系统开启「减少动效」时改为瞬间跳转"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -21,7 +21,7 @@
|
||||
|
||||
- `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核
|
||||
- `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架
|
||||
- `packages/skin/ui`（@ui-arch/ui）：49 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
|
||||
- `packages/skin/ui`（@ui-arch/ui）：50 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
|
||||
- `packages/design/tokens`（@ui-arch/tokens）：设计令牌
|
||||
- `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private）
|
||||
- `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html
|
||||
|
||||
+1
-1
@@ -34,7 +34,7 @@ ui-arch-mvp/
|
||||
│ │ ├── table-core/ # 表格状态内核
|
||||
│ │ └── frame/ # 信号 + hyperscript 微框架
|
||||
│ ├── skin/ # 皮肤层（DOM 组件，可发布）
|
||||
│ │ └── ui/ # 49 个组件 + ui.css
|
||||
│ │ └── ui/ # 50 个组件 + ui.css
|
||||
│ ├── design/ # 资产层（可发布）
|
||||
│ │ └── tokens/ # --ua-* 设计令牌
|
||||
│ └── tools/ # 工程层（private，不发布）
|
||||
|
||||
@@ -11,13 +11,13 @@ npm run demo # 打开演示：apps/demo/dist/demo.html
|
||||
npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全量文档 llms-full.txt
|
||||
```
|
||||
|
||||
## 组件（共 49 个）
|
||||
## 组件（共 50 个）
|
||||
|
||||
<!-- ua:components -->
|
||||
accordion · alert · autoComplete · avatar · badge · breadcrumb · button · carousel · card · cascader · checkbox · dataTable · datePicker · descriptions · divider · drawer · empty · form · image · inputNumber · list · menu · modal · notification · pagination · popover · progress · radioGroup · rate · result · segmented · select · skeleton · slider · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · transfer · tree · upload
|
||||
accordion · alert · autoComplete · avatar · backTop · badge · breadcrumb · button · carousel · card · cascader · checkbox · dataTable · datePicker · descriptions · divider · drawer · empty · form · image · inputNumber · list · menu · modal · notification · pagination · popover · progress · radioGroup · rate · result · segmented · select · skeleton · slider · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · toast · tooltip · transfer · tree · upload
|
||||
<!-- /ua:components -->
|
||||
|
||||
分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel）、其他（divider / splitter）。
|
||||
分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / autoComplete / datePicker / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree）、数据展示（dataTable / descriptions / card / list / timeline / tag / avatar / image / carousel）、其他（divider / splitter / backTop）。
|
||||
|
||||
## 可访问性约定
|
||||
|
||||
@@ -31,7 +31,7 @@ accordion · alert · autoComplete · avatar · badge · breadcrumb · button ·
|
||||
|---|---|
|
||||
| `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） |
|
||||
| `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） |
|
||||
| `packages/skin/ui` | @ui-arch/ui：49 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
|
||||
| `packages/skin/ui` | @ui-arch/ui：50 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
|
||||
| `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
|
||||
| `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
|
||||
| `apps/demo` | 交互演示（esbuild 打包成单文件） |
|
||||
|
||||
@@ -12,6 +12,7 @@ import {
|
||||
alert,
|
||||
autoComplete,
|
||||
avatar,
|
||||
backTop,
|
||||
badge,
|
||||
breadcrumb,
|
||||
button,
|
||||
@@ -685,6 +686,17 @@ const content = h(
|
||||
button({ label: '错误（可关）', variant: 'danger', onClick: () => notification({ title: '保存失败', description: '服务端返回 500，请稍后重试', variant: 'danger' }) }),
|
||||
),
|
||||
),
|
||||
section(
|
||||
'sec-backtop',
|
||||
'返回顶部',
|
||||
'backTop：滚动越过阈值浮现（右下角悬浮），外环弧长即已滚比例，点击平滑回顶并尊重减少动效偏好。',
|
||||
h(
|
||||
'div',
|
||||
{ class: 'row' },
|
||||
h('span', { class: 'desc' }, '本页已挂载一个实例：向下滚动超过 300px 后右下角出现，外环显示滚动进度。'),
|
||||
backTop({ threshold: 300, onClick: () => toast.info('已回到顶部') }),
|
||||
),
|
||||
),
|
||||
section(
|
||||
'sec-datepicker',
|
||||
'日期选择',
|
||||
|
||||
+26
-1
@@ -1,6 +1,6 @@
|
||||
# @ui-arch 组件库 Agent 文档（无图形版）
|
||||
|
||||
> 自动生成于 2026-10-26T04:13:49.611Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
|
||||
> 自动生成于 2026-10-26T04:14:40.933Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
|
||||
> 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
|
||||
|
||||
## 快速上手
|
||||
@@ -1311,6 +1311,30 @@ datePicker({ value: dateVal, min: '2026-10-20', max: '2026-10-31', onChange: (d)
|
||||
|
||||
现场演示：apps/docs/demo.html#sec-datepicker
|
||||
|
||||
### backTop — 返回顶部 BackTop
|
||||
|
||||
参数：
|
||||
|
||||
- target：HTMLElement | Window —— 监听的滚动容器；缺省 window（整页）
|
||||
- threshold：number —— 滚动超过多少像素才浮现；缺省 300
|
||||
- progress：boolean —— 是否显示滚动进度环；缺省 true
|
||||
- onClick：() => void —— 回顶之后的回调（适合埋点）
|
||||
|
||||
示例：
|
||||
|
||||
```
|
||||
backTop({ threshold: 300, onClick: () => toast.info('已回到顶部') })
|
||||
```
|
||||
|
||||
手把手：
|
||||
|
||||
1. 把返回的元素挂到页面任意位置即可，组件自身 position: fixed 定位在右下角
|
||||
2. 滚动越过 threshold 才浮现（淡入 + 上移微动画），回到阈值内自动隐藏
|
||||
3. progress 为 true 时外环弧长等于已滚比例；内滚容器用 target 传入该元素
|
||||
4. 点击平滑回顶；系统开启「减少动效」时改为瞬间跳转
|
||||
|
||||
现场演示：apps/docs/demo.html#sec-backtop
|
||||
|
||||
API 速览：
|
||||
|
||||
- button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
|
||||
@@ -1364,6 +1388,7 @@ API 速览：
|
||||
- splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号
|
||||
- autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想
|
||||
- datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航
|
||||
- backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶
|
||||
|
||||
一行用法：
|
||||
|
||||
|
||||
@@ -98,6 +98,7 @@
|
||||
- splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号
|
||||
- autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想
|
||||
- datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航
|
||||
- backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶
|
||||
- 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
|
||||
- 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
|
||||
- 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user