拓冰网站定制 
前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载automattic/components是 wp-calypso 项目WordPress.com 的 JavaScript 与 API 前端内置的 React 组件库而Button是该组件库中用于承载点击触发动作语义的核心控件。本文以 packages/components/src/button/README.md 为骨架结合其 TypeScript 实现、SCSS 样式、单元测试 与 Storybook 用例完整讲解该组件的全部 Props、按钮类型、图标按钮用法与设计准则并说明其已弃用deprecated状态及向wordpress/components迁移的正确姿势。组件概览触发动作的通用按钮当前已标记弃用Buttons 表达的是用户点击或轻触后将发生什么动作。它们用于触发任何类型的操作也包括导航。该组件从automattic/components包导出见 packages/components/src/index.ts并对外暴露Button组件与其ButtonProps类型。需要特别注意的是这个按钮组件已经因为过于激进且通用的 CSSaggressive and generic CSS被弃用——当它被导入时其全局性样式会破坏许多其他按钮。因此官方建议改用wordpress/components包中的Button组件。组件源码的 JSDoc 注释index.tsx也明确标注了deprecatedStorybook 目录则归类为Deprecated/Button见 index.stories.tsx。不过由于历史原因该组件在仓库中仍有大量使用点例如 client/my-sites/activity/filterbar/index.jsx 等文件仍在import { Button, Gridicon } from automattic/components理解它的用法、实现原理与弃用原因对阅读旧代码、做增量改造仍然非常必要。快速上手基本用法从automattic/components导入Button与Gridicon后者用于图标按钮即可使用import { Button, Gridicon } from automattic/components; export default function RockOnButton() { return ( Button compact primary You rock! /Button ); }上面的示例同时叠加了compact紧凑尺寸与primary主操作视觉强调两个修饰属性这也是该组件最常见的组合用法。Props 全解7 个官方 Props 与源码中的隐藏第 8 个原文档给出了完整的 Props 表格这也是使用本组件的核心参考NameTypeDefaultDescriptionplainboolfalseRenders a button with no user-agent stylescompactboolfalseDecreases the size of the buttonprimaryboolfalseProvides extra visual weight and identifies the primary action in a set of buttonsborderlessboolfalseRenders a button without bordersscaryboolfalseIndicates a dangerous or potentially negative actionbusyboolfalseIndicates activity while a background action is being performedhrefstringnullIf provided, rendersainstead ofbutton从源码的OwnProps接口index.tsx可以看到实际实现还额外支持一个transparent布尔属性README 表格未列出用于渲染背景透明、随 CSS 变量着色的描边按钮。此外组件还透传className。Props 如何映射为样式类所有布尔修饰属性最终通过clsx拼装成 CSS 类名index.tsxplain为真时输出类名button-plain不附带任何修饰类否则输出基础类button并按属性追加is-compact、is-primary、is-scary、is-busy、is-borderless、is-transparent。测试 test/index.js 专门验证了这一映射Button scary primary borderless compact /会同时带上is-compact、is-primary、is-scary、is-borderless四个类而不带任何修饰时仅保留button类。按钮类型与设计语义原文档将按钮划分为七种类型每种都有明确的设计语义Primary主按钮用于在任何体验中突出最重要的操作。注意一个区块或一屏内不要超过一个主按钮以免给用户造成压迫感。Secondary次按钮界面中使用最频繁的类型。只有当某个按钮需要更强或更弱的视觉权重时才换用其他样式。Button with icon带图标的按钮当文字不足以表达时用图标辅助传达按钮功能。Scary危险按钮用于会删除客户数据、或事后难以恢复的操作。破坏性按钮应在动作完成前先触发确认对话框。要谨慎使用这类按钮因为它们可能给用户带来压力。Borderless无边框按钮用于较不重要或较少使用的操作因为它们的视觉存在感更低。Busy忙碌按钮当按钮已被按下、且关联动作正在执行时使用。Plain纯样式按钮当需要button-as-div时使用——重置按钮的所有样式随后由使用方自行增强。例如当你需要某元素行为上像个按钮、但外观上不像按钮时这是很好的选择。源码中的样式语义佐证这些设计语义在 style.scss 中都有对应实现基础样式.button1px 实线边框、2px 圆角、padding: 8px 14px、line-height: 22px颜色通过 CSS 变量取色--color-surface、--color-neutral-70、--color-neutral-10等并针对.rtl容器切换阿拉伯语字体族见 style.scss。主按钮.button.is-primary使用--color-accent强调色作背景hover/focus 时加深为--color-accent-60style.scss。危险按钮.button.is-scary文字颜色切换为错误色--color-error与primary叠加时.button.is-primary.is-scary背景直接使用错误色style.scss。忙碌按钮.button.is-busy设置pointer-events: none禁用交互并通过button__busy-animation关键帧动画3000ms 无限线性循环、background-position从 240px 平移到 0产生流动条纹效果style.scss 与 style.scss。主按钮、危险按钮的 busy 状态分别使用各自色系的条纹渐变。无边框按钮.button.is-borderless去掉边框与背景、左右内边距归零hover/focus 仅加深文字颜色style.scss。纯样式按钮.button-plainappearance: none、透明背景、继承文本颜色与字号、无内边距style.scss。透明按钮.button.is-transparent背景透明边框与文字颜色取--transparent-button-text-color默认回退到currentcolorhover 时切换为--transparent-button-text-color-hover默认--color-accent并以 flex 居中内容style.scss。另外基础.button还内置了[disabled]/:disabled/.disabled三种禁用态样式文字变灰、光标default以及.accessible-focus容器下的焦点环样式box-shadow: 0 0 0 2px var(--color-primary-light)无障碍设计同样有所覆盖style.scss。图标按钮与 Gridicon 组合使用当文字不足以传达含义时可以在按钮内插入 Gridicon 图标。约定是图标显示在文字左侧唯一的例外是external图标放在文字右侧。文字需要包裹在span或其他元素中以便控制间距。也可以做纯图标按钮无文字但应谨慎使用因为可能降低可读性import { Button, Gridicon } from automattic/components; export default function RockOnButton() { return ( Button Gridicon icontrash / spanButton with icon/span /Button ); }样式层面对 Gridicon 做了专门对齐默认width/height: 18px、top: 4px非末位图标带margin-right: 4pxstyle.scssborderless场景下图标放大到 24pxcompact场景还会对gridicons-plus-small、gridicons-arrow-left/right等特殊图标做微调如箭头图标因 SVG 边界盒偏低需上移 1px见 style.scss 与 style.scss。组件库的文档示例 docs/example.jsx 完整展示了各类图标按钮组合普通/危险/主按钮/主危险按钮分别搭配heart、plugins、globe、pencil、camera、time、user-circle、cart等图标以及 borderless 场景下的crossRemove、trashTrash、link-breakDisconnect等典型管理操作。源码级实现剖析渲染逻辑button与a的自动切换UnforwardedButton 是核心渲染函数其关键行为如下通过isAnchor判断只要传入了href就渲染a否则渲染button。渲染button时cleanButtonProps会把type默认设为button避免表单内按钮意外触发表单提交并剥离href、target、rel等不该出现在按钮上的属性index.tsx。渲染a时cleanAnchorProps剥离type等按钮专属属性并且当设置了target如_blank时会自动将rel中已有的noopener/noreferrer去重后追加noopener noreferrer以阻止外部链接的 referrer 泄漏index.tsx 与 index.tsx。组件通过forwardRef暴露ref 同时支持HTMLButtonElement | HTMLAnchorElement。上述行为在 test/index.js 中被系统化验证href存在时渲染为链接且type属性会被忽略第 52-63 行指定target_blank时自动补全relnoopener noreferrer第 65-83 行未传href时渲染为button默认带typebutton并且不会把target/rel误加到按钮上第 86-115 行disabled属性透传按钮被禁用第 35-39 行子元素如 Gridicon正常渲染并被包含在按钮内第 41-49 行。样式系统CSS 变量驱动的主题化整个按钮样式完全基于 CSS 自定义属性--color-surface、--color-neutral-*、--color-accent、--color-error等取色因此能随主题如暗色模式自动变化这也是它当年在 Calypso 各处被广泛复用的原因。样式文件末尾还保留了已弃用的.button.is-link样式透明、无边框、color: var(--color-link)、font-size: inherit见 style.scss供旧代码平滑过渡。Storybook 用例一览index.stories.tsx 提供了 9 个可直接预览的故事Default、Compact、Busy、Scary、Borderless、Disabled、Link带href与target_blank、Plain、Transparent在黑色背景上演示--transparent-button-text-color与 hover 颜色的自定义见第 91-108 行。这些故事是快速对比各修饰属性视觉差异的最佳入口。使用规范与设计准则原文档给出的通用准则General guidelines值得原样保留并作为 UI 文案规范使用清晰、准确的标签Use clear and accurate labels。使用句子式大小写sentence-style capitalization。以强烈、简洁、可行动的动词开头Lead with strong, concise, and actionable verbs。当用户确认某个动作时使用具体标签如Save或Trash而不是OK和Cancel。对最重要的操作进行优先级排序。过多的行动号召会造成混乱让用户不确定下一步该做什么。迁移建议为什么以及如何改用 wordpress/components弃用的根本原因写在 README 第一段该按钮引入的是激进且通用aggressive and generic的 CSS一旦被导入就可能污染并破坏页面上的其他按钮例如其全局选择器会意外命中其他元素。因此在wp-calypso 后续版本中新代码不应再使用automattic/components的Button而应改用wordpress/components包中同名的Button组件其文档位于 WordPress Gutenberg 组件文档站此处不再列出外部链接。迁移时的大致思路将import { Button, Gridicon } from automattic/components中的Button替换为import { Button } from wordpress/componentsGridicon仍可保留用于图标按钮。属性映射primary→variantprimary、compact→ 视需求用isSmall/isCompact等价物scary→isDestructivebusy→isBusyborderless→varianttertiary或variantlinkhref在wordpress/components的 Button 中同样支持渲染为链接。视觉验收由于两者样式体系不同Gutenberg 组件基于自己的 design tokens迁移后需要在对应页面做一次视觉回归。关联组件原文档末尾列出了三个关联组件它们与按钮配合使用可以覆盖更复杂的交互场景当前仓库中对应的实现位于client/components下ButtonGroup按钮组需要把多个按钮分组排列时使用参考 client/components/button-group。SplitButton分裂按钮需要为按钮附加一个次级 popover 菜单时使用参考 client/components/split-button。SpinnerButton带加载指示的按钮需要在按钮上展示加载转圈时使用参考 client/components/spinner-button。综上所述automattic/components的Button虽已被官方标记弃用但它作为 wp-calypso 历史 UI 体系的一部分其 Props 语义、样式分层与实现思路button/link 双形态、CSS 变量取色、修饰类映射至今仍有学习与迁移参考价值。阅读旧代码遇到automattic/components的 Button 时可按本文的 Props 表快速理解其视觉意图并按迁移指南逐步替换为新组件。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso CardHeading 组件完全指南用法、Props 与源码实现剖析wp calypso CardHeading 组件完全指南用法、Props 与源码实现剖析 导读 CardHeading 是 wp calypsoWordP前端CMSautomattic/components v5.0.0 升级指南wp-calypso 组件库的破坏性变更、迁移映射与源码解读automattic/components v5.0.0 升级指南wp calypso 组件库的破坏性变更、迁移映射与源码解读 automattic/co前端CMSwp-calypso Spotlight 组件实战指南用法、Props 与 JITM 集成源码解析wp calypso Spotlight 组件实战指南用法、Props 与 JITM 集成源码解析 Spotlight 是 wp calypsoWordPr前端CMS上一篇3分钟让Figma说中文设计师必备的界面汉化完全指南下一篇3分钟极速上手用FigmaCN中文插件彻底告别英文界面困扰创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 wp-calypso 中 @automattic/components Button 组件：Props 用法、源码实现与弃用迁移指南
前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载automattic/components是 wp-calypso 项目WordPress.com 的 JavaScript 与 API 前端内置的 React 组件库而Button是该组件库中用于承载点击触发动作语义的核心控件。本文以 packages/components/src/button/README.md 为骨架结合其 TypeScript 实现、SCSS 样式、单元测试 与 Storybook 用例完整讲解该组件的全部 Props、按钮类型、图标按钮用法与设计准则并说明其已弃用deprecated状态及向wordpress/components迁移的正确姿势。组件概览触发动作的通用按钮当前已标记弃用Buttons 表达的是用户点击或轻触后将发生什么动作。它们用于触发任何类型的操作也包括导航。该组件从automattic/components包导出见 packages/components/src/index.ts并对外暴露Button组件与其ButtonProps类型。需要特别注意的是这个按钮组件已经因为过于激进且通用的 CSSaggressive and generic CSS被弃用——当它被导入时其全局性样式会破坏许多其他按钮。因此官方建议改用wordpress/components包中的Button组件。组件源码的 JSDoc 注释index.tsx也明确标注了deprecatedStorybook 目录则归类为Deprecated/Button见 index.stories.tsx。不过由于历史原因该组件在仓库中仍有大量使用点例如 client/my-sites/activity/filterbar/index.jsx 等文件仍在import { Button, Gridicon } from automattic/components理解它的用法、实现原理与弃用原因对阅读旧代码、做增量改造仍然非常必要。快速上手基本用法从automattic/components导入Button与Gridicon后者用于图标按钮即可使用import { Button, Gridicon } from automattic/components; export default function RockOnButton() { return ( Button compact primary You rock! /Button ); }上面的示例同时叠加了compact紧凑尺寸与primary主操作视觉强调两个修饰属性这也是该组件最常见的组合用法。Props 全解7 个官方 Props 与源码中的隐藏第 8 个原文档给出了完整的 Props 表格这也是使用本组件的核心参考NameTypeDefaultDescriptionplainboolfalseRenders a button with no user-agent stylescompactboolfalseDecreases the size of the buttonprimaryboolfalseProvides extra visual weight and identifies the primary action in a set of buttonsborderlessboolfalseRenders a button without bordersscaryboolfalseIndicates a dangerous or potentially negative actionbusyboolfalseIndicates activity while a background action is being performedhrefstringnullIf provided, rendersainstead ofbutton从源码的OwnProps接口index.tsx可以看到实际实现还额外支持一个transparent布尔属性README 表格未列出用于渲染背景透明、随 CSS 变量着色的描边按钮。此外组件还透传className。Props 如何映射为样式类所有布尔修饰属性最终通过clsx拼装成 CSS 类名index.tsxplain为真时输出类名button-plain不附带任何修饰类否则输出基础类button并按属性追加is-compact、is-primary、is-scary、is-busy、is-borderless、is-transparent。测试 test/index.js 专门验证了这一映射Button scary primary borderless compact /会同时带上is-compact、is-primary、is-scary、is-borderless四个类而不带任何修饰时仅保留button类。按钮类型与设计语义原文档将按钮划分为七种类型每种都有明确的设计语义Primary主按钮用于在任何体验中突出最重要的操作。注意一个区块或一屏内不要超过一个主按钮以免给用户造成压迫感。Secondary次按钮界面中使用最频繁的类型。只有当某个按钮需要更强或更弱的视觉权重时才换用其他样式。Button with icon带图标的按钮当文字不足以表达时用图标辅助传达按钮功能。Scary危险按钮用于会删除客户数据、或事后难以恢复的操作。破坏性按钮应在动作完成前先触发确认对话框。要谨慎使用这类按钮因为它们可能给用户带来压力。Borderless无边框按钮用于较不重要或较少使用的操作因为它们的视觉存在感更低。Busy忙碌按钮当按钮已被按下、且关联动作正在执行时使用。Plain纯样式按钮当需要button-as-div时使用——重置按钮的所有样式随后由使用方自行增强。例如当你需要某元素行为上像个按钮、但外观上不像按钮时这是很好的选择。源码中的样式语义佐证这些设计语义在 style.scss 中都有对应实现基础样式.button1px 实线边框、2px 圆角、padding: 8px 14px、line-height: 22px颜色通过 CSS 变量取色--color-surface、--color-neutral-70、--color-neutral-10等并针对.rtl容器切换阿拉伯语字体族见 style.scss。主按钮.button.is-primary使用--color-accent强调色作背景hover/focus 时加深为--color-accent-60style.scss。危险按钮.button.is-scary文字颜色切换为错误色--color-error与primary叠加时.button.is-primary.is-scary背景直接使用错误色style.scss。忙碌按钮.button.is-busy设置pointer-events: none禁用交互并通过button__busy-animation关键帧动画3000ms 无限线性循环、background-position从 240px 平移到 0产生流动条纹效果style.scss 与 style.scss。主按钮、危险按钮的 busy 状态分别使用各自色系的条纹渐变。无边框按钮.button.is-borderless去掉边框与背景、左右内边距归零hover/focus 仅加深文字颜色style.scss。纯样式按钮.button-plainappearance: none、透明背景、继承文本颜色与字号、无内边距style.scss。透明按钮.button.is-transparent背景透明边框与文字颜色取--transparent-button-text-color默认回退到currentcolorhover 时切换为--transparent-button-text-color-hover默认--color-accent并以 flex 居中内容style.scss。另外基础.button还内置了[disabled]/:disabled/.disabled三种禁用态样式文字变灰、光标default以及.accessible-focus容器下的焦点环样式box-shadow: 0 0 0 2px var(--color-primary-light)无障碍设计同样有所覆盖style.scss。图标按钮与 Gridicon 组合使用当文字不足以传达含义时可以在按钮内插入 Gridicon 图标。约定是图标显示在文字左侧唯一的例外是external图标放在文字右侧。文字需要包裹在span或其他元素中以便控制间距。也可以做纯图标按钮无文字但应谨慎使用因为可能降低可读性import { Button, Gridicon } from automattic/components; export default function RockOnButton() { return ( Button Gridicon icontrash / spanButton with icon/span /Button ); }样式层面对 Gridicon 做了专门对齐默认width/height: 18px、top: 4px非末位图标带margin-right: 4pxstyle.scssborderless场景下图标放大到 24pxcompact场景还会对gridicons-plus-small、gridicons-arrow-left/right等特殊图标做微调如箭头图标因 SVG 边界盒偏低需上移 1px见 style.scss 与 style.scss。组件库的文档示例 docs/example.jsx 完整展示了各类图标按钮组合普通/危险/主按钮/主危险按钮分别搭配heart、plugins、globe、pencil、camera、time、user-circle、cart等图标以及 borderless 场景下的crossRemove、trashTrash、link-breakDisconnect等典型管理操作。源码级实现剖析渲染逻辑button与a的自动切换UnforwardedButton 是核心渲染函数其关键行为如下通过isAnchor判断只要传入了href就渲染a否则渲染button。渲染button时cleanButtonProps会把type默认设为button避免表单内按钮意外触发表单提交并剥离href、target、rel等不该出现在按钮上的属性index.tsx。渲染a时cleanAnchorProps剥离type等按钮专属属性并且当设置了target如_blank时会自动将rel中已有的noopener/noreferrer去重后追加noopener noreferrer以阻止外部链接的 referrer 泄漏index.tsx 与 index.tsx。组件通过forwardRef暴露ref 同时支持HTMLButtonElement | HTMLAnchorElement。上述行为在 test/index.js 中被系统化验证href存在时渲染为链接且type属性会被忽略第 52-63 行指定target_blank时自动补全relnoopener noreferrer第 65-83 行未传href时渲染为button默认带typebutton并且不会把target/rel误加到按钮上第 86-115 行disabled属性透传按钮被禁用第 35-39 行子元素如 Gridicon正常渲染并被包含在按钮内第 41-49 行。样式系统CSS 变量驱动的主题化整个按钮样式完全基于 CSS 自定义属性--color-surface、--color-neutral-*、--color-accent、--color-error等取色因此能随主题如暗色模式自动变化这也是它当年在 Calypso 各处被广泛复用的原因。样式文件末尾还保留了已弃用的.button.is-link样式透明、无边框、color: var(--color-link)、font-size: inherit见 style.scss供旧代码平滑过渡。Storybook 用例一览index.stories.tsx 提供了 9 个可直接预览的故事Default、Compact、Busy、Scary、Borderless、Disabled、Link带href与target_blank、Plain、Transparent在黑色背景上演示--transparent-button-text-color与 hover 颜色的自定义见第 91-108 行。这些故事是快速对比各修饰属性视觉差异的最佳入口。使用规范与设计准则原文档给出的通用准则General guidelines值得原样保留并作为 UI 文案规范使用清晰、准确的标签Use clear and accurate labels。使用句子式大小写sentence-style capitalization。以强烈、简洁、可行动的动词开头Lead with strong, concise, and actionable verbs。当用户确认某个动作时使用具体标签如Save或Trash而不是OK和Cancel。对最重要的操作进行优先级排序。过多的行动号召会造成混乱让用户不确定下一步该做什么。迁移建议为什么以及如何改用 wordpress/components弃用的根本原因写在 README 第一段该按钮引入的是激进且通用aggressive and generic的 CSS一旦被导入就可能污染并破坏页面上的其他按钮例如其全局选择器会意外命中其他元素。因此在wp-calypso 后续版本中新代码不应再使用automattic/components的Button而应改用wordpress/components包中同名的Button组件其文档位于 WordPress Gutenberg 组件文档站此处不再列出外部链接。迁移时的大致思路将import { Button, Gridicon } from automattic/components中的Button替换为import { Button } from wordpress/componentsGridicon仍可保留用于图标按钮。属性映射primary→variantprimary、compact→ 视需求用isSmall/isCompact等价物scary→isDestructivebusy→isBusyborderless→varianttertiary或variantlinkhref在wordpress/components的 Button 中同样支持渲染为链接。视觉验收由于两者样式体系不同Gutenberg 组件基于自己的 design tokens迁移后需要在对应页面做一次视觉回归。关联组件原文档末尾列出了三个关联组件它们与按钮配合使用可以覆盖更复杂的交互场景当前仓库中对应的实现位于client/components下ButtonGroup按钮组需要把多个按钮分组排列时使用参考 client/components/button-group。SplitButton分裂按钮需要为按钮附加一个次级 popover 菜单时使用参考 client/components/split-button。SpinnerButton带加载指示的按钮需要在按钮上展示加载转圈时使用参考 client/components/spinner-button。综上所述automattic/components的Button虽已被官方标记弃用但它作为 wp-calypso 历史 UI 体系的一部分其 Props 语义、样式分层与实现思路button/link 双形态、CSS 变量取色、修饰类映射至今仍有学习与迁移参考价值。阅读旧代码遇到automattic/components的 Button 时可按本文的 Props 表快速理解其视觉意图并按迁移指南逐步替换为新组件。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso CardHeading 组件完全指南用法、Props 与源码实现剖析wp calypso CardHeading 组件完全指南用法、Props 与源码实现剖析 导读 CardHeading 是 wp calypsoWordP前端CMSautomattic/components v5.0.0 升级指南wp-calypso 组件库的破坏性变更、迁移映射与源码解读automattic/components v5.0.0 升级指南wp calypso 组件库的破坏性变更、迁移映射与源码解读 automattic/co前端CMSwp-calypso Spotlight 组件实战指南用法、Props 与 JITM 集成源码解析wp calypso Spotlight 组件实战指南用法、Props 与 JITM 集成源码解析 Spotlight 是 wp calypsoWordPr前端CMS上一篇3分钟让Figma说中文设计师必备的界面汉化完全指南下一篇3分钟极速上手用FigmaCN中文插件彻底告别英文界面困扰创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考