76 lines
4.1 KiB
JSON
76 lines
4.1 KiB
JSON
{
|
||
"slug": "backtotop",
|
||
"end": "css",
|
||
"curated": true,
|
||
"summary": "CSS 端的 backtotop：.kole-backtop 是 44px 圆形回顶按钮，is-visible 控制淡入与可点。",
|
||
"usage": [
|
||
"按钮本体 .kole-backtop 默认可点被关掉：.is-visible 才把 opacity 置 1、transform 归零并恢复 pointer-events:auto（frameworks/BackToTop.css:11）。",
|
||
"进度环拆成两条：外圈 .kole-backtop-ring-bg 走描边色 --kole-color-border，进度圈 .kole-backtop-ring-fg 走品牌色并只过渡 stroke-dashoffset（frameworks/BackToTop.css:14-15）。",
|
||
"内联 svg 已旋转 -90deg 并占满 44px，配合 stroke-dashoffset 从顶部开始画（frameworks/BackToTop.css:13）。",
|
||
"不想要进度环时给根元素加 .kole-no-ring，它会隐藏 .kole-backtop-ring-bg（frameworks/BackToTop.css:18）。",
|
||
"箭头用 .kole-backtop-arrow，品牌色 18px，z-index:1 压在 svg 之上（frameworks/BackToTop.css:16）。",
|
||
"hover 只改背景为 --kole-color-brand-bg，不改尺寸（frameworks/BackToTop.css:12）。"
|
||
],
|
||
"bestPractices": [
|
||
"显示隐藏必须由使用方切类：样式层只写了 .is-visible 的终态，滚动阈值与节流逻辑不在本文件里（frameworks/BackToTop.css:11）。",
|
||
"进度值靠 svg 描边的 stroke-dashoffset 表达，代码侧要写 .kole-backtop-ring-fg 的 dasharray/dashoffset；过渡时长固定 .1s linear（frameworks/BackToTop.css:15）。",
|
||
"隐藏态依赖 opacity 与 pointer-events 而非 display:none，元素始终占位并参与渲染；若要彻底移除请自行控制 DOM（frameworks/BackToTop.css:11）。"
|
||
],
|
||
"a11y": [
|
||
"示例把按钮标成 role 加 aria-label 且给内部 svg 加 aria-hidden（site/examples/backtotop.json），样式层不提供这些属性（frameworks/BackToTop.css:3）。",
|
||
"进度环是纯装饰（stroked svg），语义信息应放在按钮的可访问名称上而非环本身（frameworks/BackToTop.css:14-15）。",
|
||
"禁用 no-ring 后按钮只剩箭头，请确认对比度仍达标，不要只靠 --kole-color-brand 的细线（frameworks/BackToTop.css:18）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "classes",
|
||
"note": "CSS 端无 props：载体是 .kole-backtop（根/按钮）、.kole-backtop-ring-bg 与 .kole-backtop-ring-fg（进度环双圈）、.kole-backtop-arrow（箭头），变体 .kole-no-ring，状态 .is-visible。",
|
||
"table": [
|
||
{
|
||
"name": "kole-backtop",
|
||
"type": "类名",
|
||
"desc": "在 frameworks/BackToTop.css 中定义的类；按类名组合表达该组件的外观与状态。"
|
||
},
|
||
{
|
||
"name": "is-visible",
|
||
"type": "类名",
|
||
"desc": "在 frameworks/BackToTop.css 中定义的类；按类名组合表达该组件的外观与状态。"
|
||
},
|
||
{
|
||
"name": "kole-backtop-ring-bg",
|
||
"type": "类名",
|
||
"desc": "在 frameworks/BackToTop.css 中定义的类；按类名组合表达该组件的外观与状态。"
|
||
},
|
||
{
|
||
"name": "kole-backtop-ring-fg",
|
||
"type": "类名",
|
||
"desc": "在 frameworks/BackToTop.css 中定义的类；按类名组合表达该组件的外观与状态。"
|
||
},
|
||
{
|
||
"name": "kole-backtop-arrow",
|
||
"type": "类名",
|
||
"desc": "在 frameworks/BackToTop.css 中定义的类；按类名组合表达该组件的外观与状态。"
|
||
},
|
||
{
|
||
"name": "kole-no-ring",
|
||
"type": "类名",
|
||
"desc": "在 frameworks/BackToTop.css 中定义的类；按类名组合表达该组件的外观与状态。"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/BackToTop.css",
|
||
"kind": "CSS",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"backtotop-ex-1"
|
||
],
|
||
"notes": [
|
||
"显示终态见 frameworks/BackToTop.css:11，进度环见 frameworks/BackToTop.css:13-15，无环变体见 frameworks/BackToTop.css:18。",
|
||
"滚动阈值（示例为 400）由脚本决定，样式文件里没有该数值，不要写进类名约定。",
|
||
"该文件名 BackToTop.css 与根类 kole-backtop 一致，但组件 slug 为 backtotop，引用时注意大小写。"
|
||
]
|
||
}
|