企业官网建设流程全解析

• 前端
• UI组件

导读

本文围绕 FAST 组件体系（@microsoft/fast-components）中NumberFieldAppearance类型展开，讲解fast-number-field数字输入组件所支持的"filled"（填充式）与"outline"（描边式）两种视觉外观的定义、用法与底层实现。你将掌握如何在 DesignSystem 注册与 HTML 标记中切换外观、理解该类型与样式模板、组件选项之间的关联，并了解自定义组件时如何继承这一外观机制。

一、NumberFieldAppearance 类型定义

NumberFieldAppearance是 @microsoft/fast-components 包中用于描述fast-number-field组件外观的类型，定义非常简单且具约束性：它只允许两个字符串字面量取值。

export declare type NumberFieldAppearance = "filled" | "outline";

该类型声明位于 fast-components.numberfieldappearance.md，由 API Documenter 从源码自动生成，因此它精确反映了组件对外公开的类型契约。

两个取值的语义

组件文档明确说明：fast-number-field支持这两种视觉外观，且控制默认使用 outline 外观（见 fast-number-field.mdx）。

为什么要用联合类型而不是布尔值

"filled" | "outline"这种字符串字面量联合类型是 FAST 组件体系中的常见做法。相比布尔值（如filled?: boolean），它具备两个优势：

• 可扩展性：未来若新增第三种外观（如"underlined"），只需扩充联合成员，不会破坏既有取值；
• 自文档化：appearance属性直接承载可读的语义字符串，便于在模板、样式选择器与开发者工具中识别。

二、外观在实际组件中的用法

2.1 在 HTML 标记中切换外观

外观通过appearance属性作用于fast-number-field元素，结合min、max等属性即可得到一个带范围约束的填充式数字输入框：

<fast-number-field appearance="filled" min="0" max="10"></fast-number-field>

该示例来自组件的官方使用文档 fast-number-field.mdx，是验证外观切换最直接的方式。

2.2 通过 DesignSystem 注册组件

在脚本中，fastNumberField()函数返回一个组件注册，用于将fast-number-field配置进 DesignSystem：

import { provideFASTDesignSystem, fastNumberField } from "@microsoft/fast-components"; provideFASTDesignSystem() .register( fastNumberField() );

fastNumberField变量被类型化为(overrideDefinition?: OverrideFoundationElementDefinition<NumberFieldOptions>) => FoundationElementRegistry<NumberFieldOptions, ...>，它实现了numberFieldTemplate，并生成<fast-number-field>元素（见 fast-components.fastnumberfield.md）。

2.3 注册时定制步进图标

注册阶段还支持通过NumberFieldOptions覆盖步进按钮（spin button）的图标：

provideFASTDesignSystem() .register( fastNumberField({ stepDownGlyph: `...your step down glyph...`, stepUpGlyph: `...your setup up glyph...`, }) );

NumberFieldOptions的完整定义如下：

export declare type NumberFieldOptions = FoundationElementDefinition & StartEndOptions & { stepDownGlyph?: string | SyntheticViewTemplate; stepUpGlyph?: string | SyntheticViewTemplate; };

它继承了FoundationElementDefinition（组件基础定义）与StartEndOptions（start/end 插槽配置），并额外声明stepDownGlyph、stepUpGlyph两个可选属性，二者既可以是字符串（内联 SVG 等），也可以是SyntheticViewTemplate模板（见 fast-foundation.numberfieldoptions.md）。

三、外观与样式的关联：numberFieldStyles

外观之所以能产生不同的视觉效果，关键在于样式模板numberFieldStyles。它被类型化为FoundationElementTemplate<ElementStyles, NumberFieldOptions>，是fast-number-field在 @microsoft/fast-components 中的样式实现（见 fast-components.numberfieldstyles.md）。

fast-number-field的组成可以概括为：

• 模板：来自 fast-foundation 的numberFieldTemplate（类型为FoundationElementTemplate<ViewTemplate<NumberField>, NumberFieldOptions>，见 fast-foundation.numberfieldtemplate.md）；
• 类：NumberField，继承自FormAssociatedNumberField，基于<input type="number">语义实现（见 fast-foundation.numberfield.md）；
• 样式：@microsoft/fast-components 提供的numberFieldStyles。

这种"fast-foundation 提供类与模板、fast-components 提供样式与注册"的分层结构，正是外观可切换的架构基础：appearance属性在模板中驱动 CSS 类名，numberFieldStyles中通过属性选择器（如:host([appearance="filled"])之类的机制）应用不同的填充或描边样式。

四、数字输入框的完整属性面

要理解两种外观的实际表现，还需要了解组件承载的属性全集。下表来自fast-number-field组件文档（fast-number-field.mdx）中公开的字段清单，其中appearance即由NumberFieldAppearance类型约束：

与之对应的公开方法包括stepUp()（按 step 增加值）、stepDown()（按 step 减少值）与select()（全选文本）；事件方面会派发自定义的input与change事件（见 fast-foundation.numberfield.md）。

值得注意的是，hideStep与appearance相互独立：即使外观为"filled"，也仍然可以通过hide-step属性隐藏步进按钮（参考 fast-foundation.numberfield.hidestep.md），两种配置互不干扰。

五、自定义组件时如何保留外观能力

若要在自己的设计系统中创建数字输入组件，可以基于 fast-foundation 的NumberField类、NumberFieldOptions与numberFieldTemplate组合自定义外观：

import { NumberField, NumberFieldOptions, numberFieldTemplate as template, } from "@microsoft/fast-foundation"; import { numberFieldStyles as styles } from "./my-number-field.styles"; export const myNumberField = NumberField.compose<NumberFieldOptions>({ baseName: "number-field", styles, template, shadowOptions: { delegatesFocus: true, }, stepDownGlyph: `...default step down glyph...`, stepUpGlyph: `...default setup up glyph...`, });

这段代码来自官方组件文档（fast-number-field.mdx）。要点如下：

• NumberField.compose<NumberFieldOptions>接收NumberFieldOptions作为选项类型，因此stepDownGlyph、stepUpGlyph均可作为自定义默认图标传入；
• shadowOptions.delegatesFocus: true表明组件期望把焦点委托给渲染进 shadow DOM 的 input 元素；
• 若想让自己的my-number-field支持 filled/outline 外观，需要在自定义样式模板中根据appearance属性分别定义填充式与描边式样式，沿用NumberFieldAppearance的两个取值语义。

六、相关文件索引

围绕NumberFieldAppearance的完整资料链如下，便于进一步研读：

• 类型定义：sites/website/src/docs/1.x/api/fast-components.numberfieldappearance.md
• 组件使用指南：sites/website/src/docs/1.x/components/fast-number-field.mdx
• 组件类与 API：sites/website/src/docs/1.x/api/fast-foundation.numberfield.md
• 选项类型：sites/website/src/docs/1.x/api/fast-foundation.numberfieldoptions.md
• 模板定义：sites/website/src/docs/1.x/api/fast-foundation.numberfieldtemplate.md
• 注册函数：sites/website/src/docs/1.x/api/fast-components.fastnumberfield.md
• 样式实现：sites/website/src/docs/1.x/api/fast-components.numberfieldstyles.md
• 完整组件导出清单：sites/website/src/docs/1.x/api/fast-components.md

七、小结

NumberFieldAppearance以"filled" | "outline"两个字符串字面量，为fast-number-field提供了清晰、可扩展的外观契约：组件默认使用 outline，开发者可在标记中通过appearance属性一键切换，也可在自定义组件时沿用同一语义。结合 fast-foundation 的类与模板、fast-components 的样式与注册函数，这一小型类型构成了数字输入组件视觉定制与设计系统集成的关键一环。

• 前端
• UI组件