前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载designUnit是 FAST 设计系统FAST Frame中用于计算组件高度与间距的核心尺寸设计令牌其类型为microsoft/fast-foundation提供的CSSDesignTokennumber。本文从 API 文档 的签名出发结合仓库内的 FAST Frame 设计系统文档与网站源码讲清designUnit的定位、取值方式、与其它尺寸令牌的联动关系以及如何通过 DesignToken API 读取、修改和深挖其底层机制帮助你在自己的项目中精准控制控件尺寸与密度。designUnit 是什么从 API 签名说起designUnit的 API 页面由 API Documenter 自动生成见 fast-components.designunit.md给出的签名非常简洁designUnit: import(microsoft/fast-foundation).CSSDesignTokennumber拆开看这行签名可以提炼出三层信息它来自microsoft/fast-components包页面标题即designUnit variable属于 FAST Frame 组件库对外导出的变量在 fast-components.md 的变量清单中列出。它的类型是CSSDesignTokennumber这是一个来自microsoft/fast-foundation的设计令牌实例携带的泛型参数为number意味着其值域是数值——单位尺寸本身没有像素单位数值乘以1px后才参与 CSS 计算。它对应一条 CSS 自定义属性作为 CSS 设计令牌designUnit的值会以 CSS 自定义属性--design-unit的形式发射到文档中。designUnit 在 FAST Frame 尺寸体系中的核心作用FAST Frame 设计系统文档 在 Sizing 一节中给出了designUnit的官方定义designUnitDesign Grid 的单位尺寸The unit size of the Design Grid用于计算控件的height and spacing高度与间距。也就是说FAST Frame 的全部控件尺寸并不是各自为政的硬编码像素值而是建立在一个设计网格Design Grid之上designUnit就是这个网格的基本刻度控件的高度、内边距、间距都由它的整数倍推导而来。FAST Frame 的 Sizing 令牌形成一个相互依赖的整体尺寸令牌作用与 designUnit 的关系designUnitDesign Grid 单位尺寸计算控件高度与间距的基准本身即单位baseHeightMultiplier大多数控件的基准高度乘以designUnit得出控件基础高度baseHorizontalSpacingMultiplier规划中大多数控件的内部水平内边距乘以designUnit得出水平内边距density开发中对高度/间距的整体密度调节调整上述两个 multiplier 令牌controlCornerRadius带背板的控件的圆角半径独立令牌strokeWidth/focusStrokeWidth描边宽度独立令牌关键联动关系可以概括为两条乘法公式控件基础高度 ≈ baseHeightMultiplier × designUnit 控件内部水平间距 ≈ baseHorizontalSpacingMultiplier × designUnit正因为designUnit处于乘法链的底层它天然具备一改俱改的缩放能力当你希望整站控件更紧凑或更宽松时只需调整designUnit无需逐组件改样式。仓库中的实际应用证据--design-unit 的用法仓库的网站源码直接印证了designUnit的发射形态与计算习惯。在 variables.css 中FAST 官网自己的样式将--design-unit设为4并与base-height-multiplier10、base-horizontal-spacing-multiplier3等令牌并列声明.frontpage { --base-height-multiplier: 10; --base-horizontal-spacing-multiplier: 3; --control-corner-radius: 4; --density: 0; --design-unit: 4; --direction: ltr; --disabled-opacity: 0.3; --stroke-width: 1; --focus-stroke-width: 2; ... }同一文件的后续规则展示了designUnit的标准使用姿势——通过calc()将其数值与1px相乘得到实际像素见 variables.csspadding: calc(var(--design-unit) * 1px) calc(var(--design-unit) * 4px); margin: calc(var(--design-unit) * 5px) calc(50% - 1.5px); height: calc(var(--type-ramp-plus-5-font-size) var(--design-unit) * 1px);main.css 中同样声明了--design-unit: 4并重复了上述calc()模式。这说明designUnit 的数值是无单位数字与1px相乘后才构成可用的长度这也是其类型为CSSDesignTokennumber而非字符串长度的原因。将单位尺寸声明为无单位数字而非像素字符串可以保证所有派生计算乘、加、缩放都在纯数值层面进行避免单位运算混乱。读取与修改 designUnitDesignToken API 实战designUnit是完整的CSSDesignToken实例因此 Design Tokens 文档 中定义的全部 API 都对其适用。为特定 DOM 树设置值DesignToken 的值是针对某个FASTElement或HTMLBodyElement节点设置的因此不同 DOM 子树可以拥有不同的designUnitimport { designUnit } from microsoft/fast-components; // 为整个文档设置设计单位尺寸 designUnit.setValueFor(document.body, 4); // 为某个特定组件子树设置更紧凑的单位 const app document.querySelector(my-app) as HTMLElement; designUnit.setValueFor(app, 3);读取值值沿 DOM 树向上查找返回的是该元素或最近祖先设置的值designUnit.getValueFor(document.body); // 4 designUnit.getValueFor(app); // 3设置默认值调用withDefault()后任何未显式设置值的节点树都会回退到该默认值designUnit.withDefault(4);删除值删除某个节点上的值后读取会回退到最近祖先的值designUnit.deleteValueFor(app); designUnit.getValueFor(app); // 4回退到 body 上的值在 FAST 样式表中使用designUnit可以直接作为 CSS 指令嵌入css模板字符串。运行时指令会被替换为 CSS 自定义属性并保证该属性已为元素添加详见 design-tokens.mdimport { css } from microsoft/fast-element; import { designUnit } from microsoft/fast-components; const styles css :host { padding: ${designUnit}px; height: calc(${designUnit} * 10px); } ;深入原理DesignToken 机制如何支撑 designUnitdesignUnit只是 DesignToken 体系的一个实例理解底层机制能让你安全地驾驭它。CSS 自定义属性发射与根注册DesignToken 在值被设置时通常会自动向 CSS 发射自定义属性但默认值的发射需要显式注册根节点。调用DesignToken.registerRoot()后默认值才会以自定义属性形式作用于整个文档也可以传入一个根元素将发射范围限定在该子树内。如果使用DesignSystem注册组件DesignSystem.register()会自动完成根注册并可用withDesignTokenRoot(root)指定根、传null禁用DesignToken.registerRoot(); // 默认值开始发射到整个文档 const root document.querySelector(#root)! as HTMLDivElement; DesignToken.registerRoot(root); // 限定发射范围 DesignToken.unregisterRoot(root); // 移除从源码结构看这意味着designUnit.withDefault(4)之后如果想让默认值直接体现在--design-unit上必须配合根注册否则 CSS 中拿不到该变量。派生值Derived ValuesDesignToken 的值可以是一个接收目标元素并返回匹配类型值的函数从而让designUnit依赖其它令牌动态计算designUnit.setValueFor(target, (element) { // 依据其它令牌动态推导 return baseHeightMultiplier.getValueFor(element) 10 ? 4 : 3; });任何被依赖的令牌变化都会强制派生值重新求值并同步更新已发射的 CSS 自定义属性。注意文档明确提示条件性地访问 DesignToken 或可观察属性的易变volatile值目前不被支持应在条件块之外先取完所有依赖值。订阅机制可以订阅令牌值变化既面向整棵文档树也可限定特定元素const subscriber { handleChange(record) { console.log(DesignToken ${record.token} changed for element ${record.target}); } }; designUnit.subscribe(subscriber); // 监听所有节点的变化 designUnit.subscribe(subscriber, target); // 只监听目标节点 designUnit.unsubscribe(subscriber);令牌别名可以让一个令牌引用另一个令牌实现令牌层级引用——例如将某个组件专属令牌直接指向designUnitconst controlUnit DesignToken.createnumber(control-unit); controlUnit.setValueFor(target, designUnit); controlUnit.getValueFor(target); // 与 designUnit 的当前值一致关于 CSS 覆盖的重要警示FAST Frame 文档 对自适应颜色体系给出了明确禁忌这一原则同样适用于令牌管理由 DesignToken 发射的 CSS 自定义属性应被视为不可变——如果在 CSS 中手工覆盖--design-unit令牌系统无法感知组件渲染会与令牌状态不一致。需要改变值时应始终通过DesignToken.setValueFor()API 完成。综合实战按密度调整 designUnit将上述 API 串起来即可实现一个典型的紧凑/宽松切换import { designUnit, provideFASTDesignSystem } from microsoft/fast-components; // 1. 注册组件DesignToken 根注册随之自动完成 provideFASTDesignSystem() .register(/* 你的组件注册项 */); // 2. 定义密度档位宽松 4 / 标准 4 / 紧凑 3 const densityMap { compact: 3, standard: 4, roomy: 4 }; // 3. 切换设计单位配合订阅观察变化 function setDensity(mode: keyof typeof densityMap) { designUnit.setValueFor(document.body, densityMap[mode]); } designUnit.subscribe({ handleChange(record) { console.log(designUnit changed to ${record.target}); } });由于控件高度与间距都以designUnit为基准推导一次setValueFor即可让整棵 DOM 树下的 FAST 组件整体缩放这正是设计令牌体系相对传统硬编码样式的核心优势。总结designUnit是类型为CSSDesignTokennumber的变量见 API 文档对应 CSS 自定义属性--design-unit它是 FAST Frame 设计网格的单位刻度通过baseHeightMultiplier × designUnit、baseHorizontalSpacingMultiplier × designUnit等公式推导出控件的高度与间距见 fast-frame.md数值无单位实际像素由calc(var(--design-unit) * 1px)求得仓库网站源码 variables.css 可证修改应通过setValueFor/withDefault等 DesignToken API 完成并理解根注册、派生值与订阅机制切勿在 CSS 中手工覆盖令牌发射的变量。想进一步掌握令牌体系的全貌可继续阅读 Design Tokens 文档 与 FAST Frame 设计系统文档。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐深入解析 FAST Frame 的 accentFillActive 设计令牌microsoft/fast-components 自适应色彩系统中的激活态填充色深入解析 FAST Frame 的 accentFillActive 设计令牌microsoft/fast components 自适应色彩系统中的激活态填前端UI组件LogicFlow 键盘快捷键完全指南从内置快捷键到自定义绑定与底层实现解析LogicFlow 键盘快捷键完全指南从内置快捷键到自定义绑定与底层实现解析 导读 本文是 LogicFlow 键盘快捷键Keyboard能力的实战指南前端UI组件cocoindex 实战用 Rust CLIP Qdrant 构建增量式语义图像搜索引擎cocoindex 实战用 Rust CLIP Qdrant 构建增量式语义图像搜索引擎 本文基于 cocoindex 仓库中的 Rust 示例 ex前端UI组件上一篇5分钟创建专属桌面伙伴开源桌宠DyberPet让二次元角色活起来下一篇Cloudburst Nukkit插件开发教程零基础也能学会的实战案例创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
