carbon/motion 的 Sass 使用指南在 Carbon Design System 中接入动效曲线与时长令牌【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文面向使用 SassDart Sass 模块系统消费 IBM Carbon Design System 动效能力的开发者围绕carbon/motion包的 Sass 入口展开从安装引入、motion()函数 / Mixin、时长变量与$easings映射的完整 API到令牌的生成链路、底层 easing 数值与 surfaces 高级能力。读完你可以在自己的组件样式中直接用use carbon/motion拿到标准、进入、退出三类缓动曲线与六档时长并理解这些值的真实来源与验证方式。一、包定位与安装carbon/motion是 Carbon Design System 的动效令牌包当前仓库版本 11.52.0见 packages/motion/package.json为数字与软件产品提供基于 IBM Design Language 的动效曲线easing curve与时长duration。它在包内同时暴露 Sass 与 JavaScript 两套接口本文聚焦 Sass 侧。安装npm 或 Yarnnpm install -S carbon/motion # 或 yarn add carbon/motion安装后包内会提供index.scss包的sass字段指向它即 Sass 默认入口。需要注意令牌数值是在构建期从src/dtcg/motion.json生成的克隆仓库后需先运行一次yarn build或npm run build使js/generated/与scss/generated/目录生成完毕Sass 入口才能正常加载见 packages/motion/README.md。二、引入方式使用现代 Sass 模块系统当前版本推荐使用 Dart Sass 的use规则引入而不是旧的importuse carbon/motion;use会在命名空间默认为motion下挂载该模块的所有公开成员之后统一通过motion.前缀访问避免全局命名污染。兼容性说明早期版本V10 时代暴露的是carbon--motion函数与 Mixin引入路径为import carbon/motion/scss/motion.scss。这套旧 API 以$fast-01、$moderate-01等 V10 令牌的形式保留在 packages/motion/index.scss 中并在源码中标注了deprecated新项目请使用use与motion.命名空间风格。三、核心用法三种消费令牌的方式官方文档给出的典型用法packages/motion/docs/sass.md演示了三种消费方式use carbon/motion; .selector { // 1. 直接用 Mixin 写入 transition-timing-function include motion.motion(standard, productive); // 2. 用函数取 easing 曲线作为 transition 的组成部分 transition: opacity motion.motion(standard, productive); // 3. 直接引用时长变量 transition: opacity motion.$duration-fast-01; }三者的定位分别对应写法类型产出典型场景include motion.motion(name, mode)Mixin声明transition-timing-function: cubic-bezier(...)只想快速给选择器套上缓动曲线motion.motion(name, mode)函数返回 CSScubic-bezier()字符串内联进transition简写属性motion.$duration-*变量返回时长字符串如70ms指定过渡时长例如一个可折叠区域的标准动效可写成use carbon/motion; .collapsible { transition: opacity motion.$duration-fast-02 motion.motion(standard, productive), transform motion.$duration-fast-02 motion.motion(standard, productive); }Mixin 与函数签名packages/motion/index.scss 中的定义function motion($name, $mode: productive, $easings: $easings)$name取standard/entrance/exit之一$mode默认productive可传expressive返回对应的cubic-bezier()字符串。mixin motion($name, $mode)内部即transition-timing-function: motion($name, $mode);等价于把函数结果写到transition-timing-function属性上。函数与 Mixin 都带有健壮性校验$name或$mode不在支持集合内时会用error直接中断编译并给出可读提示例如Unable to find a mode for the easing ... called: ...见 packages/motion/index.scss。四、完整 API 一览以下是 Sass 侧公开 API 的完整清单继承并扩展自官方文档的 API 表格名称类型说明$duration-fast-01Duration70ms微交互按钮、开关对用户操作的即时反馈$duration-fast-02Duration110ms微交互淡入小型 UI 元素的细微进出场$duration-moderate-01Duration150ms微交互、小幅展开、短距离位移默认过渡速度$duration-moderate-02Duration240ms展开、系统提示toast视觉分量更重的交互$duration-slow-01Duration400ms大幅展开、重要系统通知$duration-slow-02Duration700ms背景变暗、大型 hero 过渡沉浸式强调$easingsMap嵌套映射(standard/entrance/exit) → (productive/expressive) → cubic-bezier 字符串mixin motionMixin把指定 easing 写入transition-timing-functionfunction motionFunction返回指定 easing 的cubic-bezier()字符串官方文档表格此处误标为 Mixin源码中实为函数见 packages/motion/index.scss另外index.scss还公开了进阶能力名称类型说明$surfacesMap命名动效表面surface定义与 JavaScript 侧同源function surface($name, $property: null)Function读取某个动效表面的定义或单项属性mixin surface($name)Mixin为 reveal 类表面生成完整的进入/退出过渡样式含starting-style与减少动效守卫以及已标记deprecated的 V10 兼容变量$fast-01、$fast-02、$moderate-01、$moderate-02、$slow-01、$slow-02。五、令牌数值从哪来DTCG 源定义与构建链路Sass 入口里所有变量的具体数值并非手写在.scss中而是由构建工具链生成。令牌的唯一事实来源是 packages/motion/src/dtcg/motion.json它采用 DTCGDesign Tokens Community Group格式声明duration分组定义了六档时长$value: { value: 70, unit: ms }等并附有每档的使用场景描述easing分组定义了三类曲线 × 两种模式的cubicBezier数值。构建命令为yarn build:tokensnode tasks/build.js经 packages/motion/style-dictionary 下的 transformscubic-bezier.js、duration.js与 formatsscss-tokens.js处理后输出到scss/generated/_tokens.scssindex.scss再通过use ./scss/generated/tokens将其重新导出为公开变量见 packages/motion/index.scss。这正是“TypeScript 与 Sass 同源、永不脱节”的设计src/tokens.ts里 TypeScript 侧的easingCurves数值与 Sass 侧生成值一一对应。对应到 TypeScript 侧的等价查询packages/motion/src/tokens.tsmotion(standard, productive); // → cubic-bezier(0.2, 0, 0.38, 0.9)六条缓动曲线的真实数值综合 packages/motion/src/dtcg/motion.json 与 packages/motion/src/tokens.ts 的easingCurvesCarbon 动效体系共 6 条曲线曲线productiveexpressivestandardcubic-bezier(0.2, 0, 0.38, 0.9)cubic-bezier(0.4, 0.14, 0.3, 1)entrancecubic-bezier(0, 0, 0.38, 0.9)cubic-bezier(0, 0, 0.3, 1)exitcubic-bezier(0.2, 0, 1, 0.9)cubic-bezier(0.4, 0.14, 1, 1)使用建议依据 DTCG 描述视口内移动的 UI 元素用standard元素进入屏幕用entrance元素离开屏幕用exit。productive适用于数据密集、追求效率的工作型界面expressive适用于更强调流动性、更醒目的品牌化动效。六、进阶Sass 侧的命名动效表面Surfaces除了曲线与时长index.scss还从src/surfaces.ts的 TypeScript 定义生成并导出$surfaces映射生成文件为scss/generated/_surfaces.scss用于表达“意图级”动效例如disclosure手风琴 / 表格行展开——原地 revealcontextual图标 → 气泡提示 / popover——透明度与缩放 revealstretch剪裁路径驱动的 revealclipPath插值expand卡片 / 瓦片 → 侧栏 / tearsheet——共享元素形变shared-elementinvoke按钮 → 弹窗 / 菜单——从触发元素开始形变。其中disclosure、contextual、stretch属于reveal类单元素在进入/退出样式间过渡纯 CSS 即可实现expand、invoke属于shared-element类一个元素形变为另一个元素需要 JavaScript 引擎配合纯 CSS 没有等价形态。surface() 函数use carbon/motion; $kind: motion.surface(disclosure, kind); // → reveal $dur: motion.surface(disclosure, duration); // → moderate-01 $enter-opacity: map-get(motion.surface(disclosure, enter), opacity); // → 1surface() Mixin纯 CSS 版 reveal对 reveal 类表面可以直接用 Mixin 让一个元素具备完整的进入/退出过渡[data-carbon-surfacecontextual] { include motion.surface(contextual); }该 Mixin 的实现细节见 packages/motion/index.scss值得关注静息态与[data-carbon-surface-stateenter]应用进入样式[data-carbon-surface-stateexit]应用退出样式全部过渡被包裹在media (prefers-reduced-motion: no-preference)中——偏好减少动效的用户只会得到静息样式完全不播放动画首次挂载的进入动画通过starting-style实现并声明interpolate-size: allow-keywords使block-size: auto之类的尺寸插值在支持的浏览器中生效对expand/invoke这类shared-element表面Mixin 会直接error拒绝编译提示应改用 JavaScript 引擎Motion React 等。上述行为均有测试覆盖motion.surface(contextual)的产物断言了[data-carbon-surface-stateenter]、[data-carbon-surface-stateexit]、prefers-reduced-motion媒体查询、starting-style及具体transition-duration: 110ms等输出对expand应用 Mixin 则断言其抛出shared-element morph with no CSS-only form错误见 packages/motion/tests/motion-test.js。七、Sass 与 TypeScript 的一致性保障carbon/motion对“同一份动效定义、多端消费”有明确的工程化保障单一事实来源src/dtcg/motion.json及src/dtcg/surfaces.json是令牌的唯一源头构建期双端生成yarn build:tokens同时产出js/generated/tokens.js供src/tokens.ts引用与scss/generated/_tokens.scss、_surfaces.scss供index.scss引用Sass/TS 一致性测试packages/motion/tests/motion-test.js 通过carbon/test-utils/scss的SassRenderer在 Node 环境实际渲染 Sass再把结果与 TypeScript 侧getMotionSurface(expand)/getMotionSurface(disclosure)的返回值逐项比对kind、duration、enter/exit 属性、enter-easing 等从测试层面保证两端不会漂移。也就是说你在 Sass 里读到的$duration-*、$easings以及surface()返回的数值与 React / 原生 JS 消费到的完全一致——这为“样式层写 CSS、交互层写 JS”的动效协作提供了可靠前提。八、实践要点小结引入统一使用use carbon/motion通过motion.命名空间访问克隆仓库后先yarn build生成令牌文件。曲线motion.motion(standard, productive)返回可直接写进transition的cubic-bezier()字符串Mixin 版本则直接设置transition-timing-function。时长六档变量$duration-fast-01~$duration-slow-02对应 70ms / 110ms / 150ms / 240ms / 400ms / 700ms按交互轻重选择。意图级动效surface()函数 / Mixin 用于命名表面reveal 类可直接纯 CSS 实现shared-element 类必须搭配 JavaScript 引擎两者均内置prefers-reduced-motion无障碍守卫。一致性令牌数值全部由 DTCG 源定义构建生成Sass 与 TypeScript 由测试保证同步可在样式中放心复用而无需手工维护两套数字。延伸阅读本文档原始出处packages/motion/docs/sass.mdSass 入口实现packages/motion/index.scssTypeScript 令牌实现packages/motion/src/tokens.ts动效表面架构说明packages/motion/docs/surfaces.md令牌源定义DTCG 格式packages/motion/src/dtcg/motion.json一致性测试packages/motion/tests/motion-test.js【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
