102 lines
4.6 KiB
JSON
102 lines
4.6 KiB
JSON
{
|
||
"slug": "themeswitcher",
|
||
"end": "html",
|
||
"curated": true,
|
||
"summary": "原生主题切换：模式存 localStorage，品牌色写 CSS 变量，深浅靠根节点类。",
|
||
"usage": [
|
||
"三个模式选项 .kole-themesw-opt 各带 data-mode（light / dark / auto），点击写入 localStorage 的 kole-mode 后重渲染。",
|
||
"实际深浅判定在 effective()：auto 时读 matchMedia(\"(prefers-color-scheme: dark)\") 的 matches，否则直接用 mode。",
|
||
"深浅落地方式是给根节点加类：document.documentElement.classList.toggle(\"kole-dark\", actual === \"dark\")。",
|
||
"品牌色是一组动态创建的 .kole-themesw-color（带 role=\"radio\"、aria-checked、tabindex），选中时写 document.documentElement.style.setProperty(\"--kole-color-brand\", brand)。",
|
||
"读写 localStorage 都用 try / catch 包住，模式非法时回退 auto（frameworks/ThemeSwitcher.html:37）。",
|
||
"系统主题变化有监听：media 的 change 事件里只在 mode === \"auto\" 时重渲染。"
|
||
],
|
||
"bestPractices": [
|
||
"模式与品牌色是两个独立状态（mode 与 brand），品牌色没有持久化，刷新后回到默认色。",
|
||
"localStorage 的 try / catch 不要删，隐私模式下访问会抛异常导致整段脚本中断。",
|
||
"选项与色点是运行时创建的，色点的 role / aria-checked / tabindex 都在 JS 里设置，改结构时注意这些属性也要跟着改。"
|
||
],
|
||
"a11y": [
|
||
"容器声明 role=\"radiogroup\" 与 aria-label，选项声明 role=\"radio\" 且脚本维护 aria-checked，这一组语义完整。",
|
||
"色点与选项都补了 Enter / Space 键盘处理（e.key === \"Enter\" || e.key === \" \"），是本端无障碍做得最完整的一处。",
|
||
"radiogroup 内缺少方向键在选项间移动的约定行为，只能用 Tab 逐个走。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "attrs",
|
||
"note": "H5 端的状态有三处落点：模式选项的 data-mode、根节点上的 kole-dark 类、以及 --kole-color-brand 这个内联 CSS 变量；localStorage 存模式，选项与色点由脚本创建并维护 role=\"radio\" 与 aria-checked。",
|
||
"table": [
|
||
{
|
||
"name": "auto",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:19）。"
|
||
},
|
||
{
|
||
"name": "dark",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:18）。"
|
||
},
|
||
{
|
||
"name": "kole-btn",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:25）。"
|
||
},
|
||
{
|
||
"name": "kole-btn--primary",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:25）。"
|
||
},
|
||
{
|
||
"name": "kole-card",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:23）。"
|
||
},
|
||
{
|
||
"name": "kole-card__body",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:24）。"
|
||
},
|
||
{
|
||
"name": "kole-demo",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:15）。"
|
||
},
|
||
{
|
||
"name": "kole-desc",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:13）。"
|
||
},
|
||
{
|
||
"name": "kole-h2",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:12）。"
|
||
},
|
||
{
|
||
"name": "kole-page",
|
||
"type": "类名",
|
||
"desc": "H5 端结构里使用的类名（frameworks/ThemeSwitcher.html:11）。"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/ThemeSwitcher.html",
|
||
"kind": "H5 原生",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/ThemeSwitcher.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"themeswitcher-ex-1"
|
||
],
|
||
"notes": [
|
||
"选项与 data-mode 见（frameworks/ThemeSwitcher.html:17-19），容器 role=\"radiogroup\" 见（frameworks/ThemeSwitcher.html:16）。",
|
||
"色点创建与键盘处理见（frameworks/ThemeSwitcher.html:41-43），选项键盘处理见（frameworks/ThemeSwitcher.html:48）。",
|
||
"深浅判定见（frameworks/ThemeSwitcher.html:50），根类切换与品牌色变量见（frameworks/ThemeSwitcher.html:53）与（frameworks/ThemeSwitcher.html:56）。",
|
||
"系统主题监听见（frameworks/ThemeSwitcher.html:60-63）。"
|
||
]
|
||
}
|