feat: issue-2563

[ceilf6]

Summary

• add Switch round and line shape styles for web and mobile common styles
• add shape demo entries to web and mobile Switch API docs

Related Issue

• closes [Switch] 支持方形等外观设计 #2563

Checks

• pnpm exec prettier --check docs/web/api/switch.md docs/web/api/switch.en-US.md docs/mobile/api/switch.md docs/mobile/api/switch.en-US.md
• pnpm exec stylelint style/web/components/switch/_index.less style/web/components/switch/_var.less style/mobile/components/switch/_index.less style/mobile/components/switch/_var.less --allow-empty-input
• pnpm run typecheck

[ceilf6]

@ceilf6/repo-guard CR

[ceilf6]

🛡️ ceilf6/repo-guard

代码评审报告: feat: issue-2563

风险等级: 中
处理建议: 请求修改
决策摘要: 样式方案总体思路合理，但存在多处对现有 checked/disabled/loading 状态样式的覆盖风险（--shape-line / --line 用 background-color: transparent 硬性覆盖已有状态色），且这是纯样式 PR 却完全没有组件层（Vue/React/mobile 组件 props、class 绑定逻辑）改动，导致 shape 属性目前只有 CSS class 定义、没有任何地方能实际触发这些 class，{{ shape }} demo 大概率无法渲染出效果。

级联分析

• 变更符号: .@{prefix}-switch--shape-round / .@{prefix}-switch--shape-line（web），.@{prefix}-switch--round / .@{prefix}-switch--line（mobile），新增 less 变量 @switch-round-* / @switch-line-*
• 受影响流程: Switch 组件 web/mobile 的视觉渲染；API 文档 demo 渲染（{{ shape }} 依赖组件层存在 shape prop 及对应 demo 组件，而本 PR 未包含 tdesign-common 之外任何具体框架（Vue/React）的组件实现）
• 变更集外调用方: tdesign-common 本身只提供样式变量与 class 定义，真正消费方是 tdesign-vue-next / tdesign-react / tdesign-miniprogram 等下游仓库的 Switch 组件代码，它们需要新增 shape prop 并绑定对应 class，否则本 PR 的样式永远不会被应用
• 置信度: medium（diff 本身自洽，但无法验证下游组件仓库是否已同步或计划同步 shape prop；{{ shape }} demo 片段在当前仓库找不到对应 demo 源文件）

问题发现

1. [高] --shape-line / --line 用 background-color: transparent 强制覆盖已有状态样式，可能导致视觉倒退

   • 证据: web 端 &--shape-line 内对 hover、is-checked、is-loading、is-disabled 都重复写 background-color: transparent；mobile 端同理对 checked/disabled 组合选择器也是如此
   • 受影响调用方/流程: 所有已存在的 checked/disabled/loading 状态选择器（这些选择器在 _index.less 前半部分已经定义了具体的 background-color），line 形态下这些颜色变化全部转移到新增的 ::before 伪元素背景色，逻辑上可行，但意味着任何后续对基础状态背景色的样式改动都要求作者记得同步维护 ::before 分支，容易产生状态遗漏（例如本 PR 未见对 focus/active/键盘可访问性相关样式的覆盖处理）
   • 最小可行修复: 在 PR 描述或注释中明确 line 形态刻意分离背景色到 ::before，并检查是否遗漏了 focus-visible 等状态；如果代码库有类似"状态色统一变量化"约定，尽量让 ::before 直接复用同一组变量而不是硬编码 transparent

2. [高] 本仓库看不到 shape 属性/prop 的任何实际接入点，{{ shape }} demo 可能渲染失败

   • 证据: 全部改动集中在 style/* 和 docs/*/api/switch.md，没有任何框架组件源码（本仓库若为 tdesign-common，可能本身就不含组件实现，但需要确认 {{ shape }} 片段引用的 demo 文件是否已存在于其他关联 PR/仓库）
   • 受影响调用方/流程: API 文档预览、下游框架的 Switch 组件（需要新增 shape prop 才能让用户使用这套新 class）
   • 最小可行修复: 在 PR 描述中明确本仓库职责边界（仅提供样式基础设施），并链接到下游组件仓库（tdesign-vue-next/tdesign-react/tdesign-miniprogram）对应实现 PR；如果这些下游 PR 尚未存在或未合并，应在 issue/PR 中说明合并顺序依赖，避免文档 demo 先行导致断链

3. [中] mobile 端 _var.less 混用 CSS 变量 var(--td-switch-round-radius, 6px) 与硬编码 .3s ease（transition: all .3s ease），与 web 端使用 @switch-transition 变量的方式不一致

   • 证据: web 端 line 形态用 transition: @switch-transition;，mobile 端 line 形态用硬编码 transition: all .3s ease;
   • 受影响调用方/流程: 全局 transition 时间调整时，mobile line 形态不会同步生效；与代码库既有变量化约定不一致
   • 最小可行修复: 复用已有的 mobile transition 变量（如存在），或新增一个 @switch-transition 类似变量，避免硬编码魔法值

行级发现

• [style/web/components/switch/_index.less:277] 新增 .@{prefix}-switch--shape-round 只覆盖了 track 和 handle 的 border-radius，未确认是否需要同步调整 __content 内文字/图标的 padding，是否与圆角形态下的视觉观感一致，建议对照设计稿核实
• [style/web/components/switch/_index.less:341] &.@{prefix}-is-checked .@{prefix}-switch__handle { left: 100%; } 直接硬编码 left: 100%，未使用 transform 或已有 handle 定位变量，可能与非 line 形态下 handle 位移逻辑（若使用 transform）不一致，导致两种形态动画曲线不同，建议核实是否有视觉跳变
• [style/mobile/components/switch/_index.less:60] transition: all .3s ease; 硬编码时间与缓动函数，未复用现有 mobile 过渡变量，建议对齐 web 端 @switch-transition 做法
• [style/mobile/components/switch/_index.less:41] --round class 仅覆盖 track 与 dot 的 border-radius，未见与 --small 尺寸的组合覆盖测试证据（例如 --round + --small 是否需要不同 dot-radius），建议确认是否需要级联规则或补充说明该组合已被验证兼容
• [style/web/components/switch/_var.less:78] @switch-line-track-height: 6px; 为硬编码像素值，未使用 var(--td-switch-*) CSS 变量包裹（对比 mobile 端 _var.less:50 使用了 var(--td-switch-line-track-height, 6px)），web/mobile 两端变量定义方式不一致，建议核实 web 端是否也应支持 CSS 变量覆盖以保持设计 token 体系一致

Karpathy 评审

• 假设: PR 假设下游框架组件会自行新增 shape prop 并绑定这些 class 名，但本仓库没有任何地方声明这个契约（prop 名、可选值 circle | round | line、默认值），存在隐性接口假设未落地为文档或类型约束
• 简洁性: 样式实现本身思路清晰（round 用 border-radius 变体，line 用伪元素模拟细线轨道），复杂度可控，未见过度抽象
• 结构质量: web 端新增规则块位置放在文件末尾、独立于原有状态样式定义处，导致同一状态（如 disabled）的背景色逻辑分散在两处（前面的基础规则 + 后面的 shape-line 覆盖），后续维护者修改 disabled 颜色时容易漏掉 line 形态分支，建议评估是否可以让 line 形态复用同一组状态变量而非重复罗列
• 变更范围: 变更集中、无关重构极少，符合最小改动原则
• 验证: PR 描述只给出 prettier/stylelint/typecheck 检查，未见任何视觉回归截图或 demo 实际运行结果；由于新增 class 需要外部触发才能生效，仅靠 lint 无法验证实际渲染效果是否符合 issue 中的设计稿

缺失覆盖

• 需要补充：shape 属性在至少一个具体框架（web/mobile 任一）组件源码中的实际接入示例或链接到对应实现 PR，用以验证 {{ shape }} demo 能正常渲染
• 需要补充：round/line 形态下 focus-visible、keyboard navigation、loading 动画在视觉上的验证截图或对照设计稿的核对说明
• 需要补充：web 端与 mobile 端变量定义方式（是否使用 CSS 变量包裹）不一致的说明或统一

[Copilot]

Pull request overview

This PR adds “round” and “line” shape styling for the Switch component in both web and mobile common styles, and updates the Switch API docs to include the corresponding shape demo sections (issue #2563).

Changes:

• Add new Switch shape-related LESS variables for web and mobile.
• Implement round/line shape modifier styles for Switch in web and mobile stylesheets.
• Add “shape” demo entries/sections to web and mobile Switch API docs (CN/EN).

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
style/web/components/switch/_var.less	Adds web LESS tokens for round/line shape styling.
style/web/components/switch/_index.less	Adds web shape-round and shape-line modifier styles for Switch.
style/mobile/components/switch/_var.less	Adds mobile CSS var-backed tokens for round/line shape styling.
style/mobile/components/switch/_index.less	Adds mobile --round and --line modifier styles for Switch.
docs/web/api/switch.md	Adds a “shape” demo section to the CN web Switch API doc.
docs/web/api/switch.en-US.md	Adds a “shape” demo section to the EN web Switch API doc.
docs/mobile/api/switch.md	Adds a “shape” demo section to the CN mobile Switch API doc.
docs/mobile/api/switch.en-US.md	Adds a “shape” demo section to the EN mobile Switch API doc.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[uyarn]

谢谢参与犀牛鸟活动，讨论后这个issue 决定采纳 #2604 继续推进