85 lines
3.6 KiB
JSON
85 lines
3.6 KiB
JSON
{
|
||
"slug": "backtotop",
|
||
"end": "html",
|
||
"curated": true,
|
||
"summary": "原生 BackToTop：滚动过阈值加 is-visible 显示，圆环进度用 strokeDashoffset 表示。",
|
||
"usage": [
|
||
"显示开关是 state 类：滚动超过 THRESHOLD（400）时 el.classList.toggle(\"is-visible\", st > THRESHOLD)。",
|
||
"圆环进度是 SVG 描边偏移：C = 2 * Math.PI * R 作 stroke-dasharray，progress 换算成 strokeDashoffset 写回。",
|
||
"阈值与半径是全页常量（THRESHOLD = 400、R = 20），改行为直接改这两个数字。",
|
||
"滚动监听带 { passive: true }，点击回到顶部走 window.scrollTo({ top: 0, behavior: \"smooth\" })。",
|
||
"圆环可用 kole-no-ring 类关掉，示例用它演示不带进度的形态。"
|
||
],
|
||
"bestPractices": [
|
||
"进度计算要先处理 max <= 0 的情况（脚本用 `max > 0 ? st / max : 0`），短页面里除以 0 会得到 NaN 写进样式。",
|
||
"onScroll 在注册后立即调了一次，首屏就有正确显隐，自己改写时别把这行初始化漏掉。",
|
||
"passive 监听不要去掉，滚动里做同步布局读取会明显掉帧。"
|
||
],
|
||
"a11y": [
|
||
"组件根是 role=\"button\" 且带 aria-label，键盘可聚焦，但脚本没绑 keydown，回车不会触发回顶。",
|
||
"圆环 SVG 带 aria-hidden，装饰图形不进读屏，这个处理是对的。",
|
||
"显示阈值是纯视觉判断，读屏用户不会知道按钮何时出现，长页面上建议在页脚另留一个回到顶部链接。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "attrs",
|
||
"note": "H5 端用类名与内联样式表达状态：显示与否是 .kole-backtop 上的 is-visible、圆环进度是 SVG 的 stroke-dashoffset 内联值，kole-no-ring 关掉圆环，行为由页内 onScroll 脚本驱动。",
|
||
"table": [
|
||
{
|
||
"name": "kole-backtop",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/BackToTop.html:24）。"
|
||
},
|
||
{
|
||
"name": "kole-backtop-arrow",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/BackToTop.html:25）。"
|
||
},
|
||
{
|
||
"name": "kole-backtop-ring-bg",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/BackToTop.html:30）。"
|
||
},
|
||
{
|
||
"name": "kole-backtop-ring-fg",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/BackToTop.html:31）。"
|
||
},
|
||
{
|
||
"name": "kole-demo-banner",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/BackToTop.html:11）。"
|
||
},
|
||
{
|
||
"name": "kole-demo-spacer",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/BackToTop.html:14）。"
|
||
},
|
||
{
|
||
"name": "kole-no-ring",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/BackToTop.html:24）。"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/BackToTop.html",
|
||
"kind": "H5 原生",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/BackToTop.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"backtotop-ex-1"
|
||
],
|
||
"notes": [
|
||
"常量与圆环初始化见（frameworks/BackToTop.html:37-41）。",
|
||
"显隐与进度写入见（frameworks/BackToTop.html:47-48），滚动监听带 passive 见（frameworks/BackToTop.html:50）。",
|
||
"点击回顶见（frameworks/BackToTop.html:51-53），kole-no-ring 类见（frameworks/BackToTop.html:24）。"
|
||
]
|
||
}
|