63 lines
3.3 KiB
JSON
63 lines
3.3 KiB
JSON
{
|
||
"slug": "backtotop",
|
||
"end": "vue3",
|
||
"curated": true,
|
||
"summary": "Vue 3 返回顶部按钮，滚动越过 threshold 后显示，环形进度按整页滚动比例实时推进。",
|
||
"usage": [
|
||
"`defineProps` 只声明 threshold 与 showRing 两个 prop，组件无 `defineEmits` 也无插槽，显隐完全由内部滚动监听决定。",
|
||
"进度环是两个同心 `<circle>`，`strokeDashoffset` 由 `computed(() => circumference * (1 - progress))` 算出；showRing 为假时整段 svg 都不渲染。",
|
||
"threshold 是 `defineProps` 的 Number（默认 400），`visible` 是内部 ref：`onScroll` 里越过阈值后把根元素类 `is-visible` 置真，DOM 始终存在，显隐交给 CSS 类。",
|
||
"滚动监听在 `onMounted` 里以 `passive: true` 注册，并立即主动调用一次，避免刷新落在页面中部时状态不对。",
|
||
"点击回顶由模板 `@click=\"toTop\"` 触发 `window.scrollTo({ top: 0, behavior: 'smooth' })`，没有使用 scrollIntoView。"
|
||
],
|
||
"bestPractices": [
|
||
"根元素是 div 加 `role=\"button\"`，不是原生按钮；要真正键盘可达还需补 tabindex 与按键处理。",
|
||
"进度按 `scrollY / (scrollHeight - innerHeight)` 计算，页面高度变化时不会主动重算，只在下一次滚动事件里更新。",
|
||
"组件一旦挂载就监听 window，同页放多个实例会各注册一份监听，一页只应保留一个。",
|
||
"关掉 showRing 后只剩 `.kole-backtop-arrow` 的 ↑ 字符，尺寸与定位仍由 `.kole-backtop` 提供。"
|
||
],
|
||
"a11y": [
|
||
"根元素带 `aria-label=\"返回顶部\"` 与 `role=\"button\"`，读屏器能播报名，但缺 tabindex 所以键盘 Tab 不到。",
|
||
"进度环 svg 未做 aria 隐藏也没有 title，这组装饰性图形会进入无障碍树。",
|
||
"回顶不改变焦点，焦点仍停在原处，长页面里建议配合 skip link 或在业务侧自行移焦。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "Vue 3 端的 API 载体是 2 个 props（threshold / showRing），无 `defineEmits` 事件、无插槽，显隐与滚动进度都是内部状态。",
|
||
"table": [
|
||
{
|
||
"name": "showRing",
|
||
"type": "Boolean",
|
||
"desc": "是否显示环形进度（frameworks/BackToTop.vue3.vue:2）"
|
||
},
|
||
{
|
||
"name": "threshold",
|
||
"type": "Number",
|
||
"desc": "触发阈值（frameworks/BackToTop.vue3.vue:17）"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/BackToTop.vue3.vue",
|
||
"kind": "Vue 3",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/BackToTop.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"backtotop-ex-1"
|
||
],
|
||
"notes": [
|
||
"props 声明见 frameworks/BackToTop.vue3.vue:16-19。",
|
||
"显示阈值判定见 frameworks/BackToTop.vue3.vue:31，进度比例在第 30 行，环偏移计算在第 25 行。",
|
||
"根元素的 role 与 aria-label 见 frameworks/BackToTop.vue3.vue:2-3，该元素没有 tabindex。",
|
||
"滚动监听的注册与主动首调见 frameworks/BackToTop.vue3.vue:37-40，passive 选项在第 38 行。",
|
||
"该端无事件出口：frameworks/BackToTop.vue3.vue 全文未出现 defineEmits。"
|
||
]
|
||
}
|