63 lines
3.4 KiB
JSON
63 lines
3.4 KiB
JSON
{
|
||
"slug": "backtotop",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "返回顶部：滚动超过 threshold 后自动显示，环形进度按页面滚动比例绘制，点击平滑回顶。",
|
||
"usage": [
|
||
"React 端无事件类 props：显示与否由内部滚动监听决定，threshold 是显示阈值（默认 400px）（BackToTop.jsx:4,16）。",
|
||
"环形进度靠 SVG 描边偏移实现：用 2πr 算周长，再按 scrollTop / 可滚动高度 计算 strokeDashoffset（BackToTop.jsx:8-9,38-45）。",
|
||
"滚动监听注册为 passive 并立即调用一次，避免初始已在页面中部时不显示（BackToTop.jsx:18-19）。",
|
||
"监听依赖 threshold，阈值变化会重新绑定（BackToTop.jsx:21）。",
|
||
"showRing 为假时整个 svg 不渲染，同时根节点加 kole-no-ring 类（BackToTop.jsx:29,35）。",
|
||
"回顶调用 window.scrollTo 并把 top 设为 0、behavior 设为 smooth（BackToTop.jsx:24）。"
|
||
],
|
||
"bestPractices": [
|
||
"阈值不宜过小（低于一屏的滚动量），否则页面打开即出现按钮，视觉上像悬浮杂质。",
|
||
"页面可滚动高度为 0 时进度按 0 处理，不会出现除零（BackToTop.jsx:15）。",
|
||
"按钮在页面内是固定定位元素，业务侧不要把它放进有 transform 的容器，否则 fixed 会退化成相对该容器。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端的 API 载体是 props 与回调：属性驱动外观（type/size/disabled 等布尔与枚举），交互经 onXxx 回传（如 onChange/onClick/onSelectionChange）；没有 v-model，受控组件固定写成 value + onChange，非受控则用 defaultValue。",
|
||
"table": [
|
||
{
|
||
"name": "threshold",
|
||
"type": "number",
|
||
"desc": "滚动多少像素后显示按钮，默认 400"
|
||
},
|
||
{
|
||
"name": "showRing",
|
||
"type": "boolean",
|
||
"desc": "是否渲染环形进度 svg"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"根节点带 role=\"button\" 与 aria-label=\"返回顶部\"（BackToTop.jsx:30-31），可被读屏识别为具名按钮。",
|
||
"但它是 div 而非 button，也没有 tabIndex，键盘无法聚焦与触发——语义标了、可达性没做到。",
|
||
"滚动变化高亮/显隐没有 aria-live 播报，这对装饰性按钮是合适的（避免干扰）。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/BackToTop.jsx",
|
||
"kind": "React（React）",
|
||
"desc": "React 端组件实现源码，props 与回调的唯一定义处"
|
||
},
|
||
{
|
||
"file": "frameworks/BackToTop.css",
|
||
"kind": "样式",
|
||
"desc": "该 React 实现依赖的样式文件"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"backtotop-ex-1"
|
||
],
|
||
"notes": [
|
||
"frameworks/BackToTop.jsx:4 中可指到 threshold（number）——滚动多少像素后显示按钮，默认 400",
|
||
"frameworks/BackToTop.jsx:4 中可指到 showRing（boolean）——是否渲染环形进度 svg",
|
||
"props 解构清单见 frameworks/BackToTop.jsx:4-4；本文件 table 只列该端真正消费的属性与回调。",
|
||
"过滤口径：事实包 consumedApi 里还包含绑在组件内部节点上的同名处理器（如 onClick/onChange 绑在内部 button、input、checkbox 上，见 frameworks/BackToTop.jsx 全文），它们不是对外 props，因此未进 table。",
|
||
"table 构成核验：2 行中 2 行是 frameworks/BackToTop.jsx 解构出的顶层 props（解构块 frameworks/BackToTop.jsx:4-4）；本组件 table 全部为顶层 props。"
|
||
]
|
||
}
|