企业官网建设流程全解析

• 前端
• UI组件

DisclosureAppearance 是 FAST 组件库（@microsoft/fast-components）中为fast-disclosure折叠面板组件定义的对外观类型别名，它通过字面量联合类型将组件的视觉样式收敛为"accent"与"lightweight"两种可枚举取值。本文以 fast-components.disclosureappearance.md 为骨架，结合仓库中的组件文档、Foundation 层源码 API 说明与设计系统文档，系统讲解该类型在 FAST 自适应界面系统中的定位、两种取值的设计语义、在 JSX/模板与自定义设计中的落地方式，以及背后的 accessibility（无障碍）与设计令牌联动机制。

类型定义：字面量联合类型

该文档给出了完整的类型签名：

export declare type DisclosureAppearance = "accent" | "lightweight";

这是 TypeScript 中的字符串字面量联合类型（string literal union type）：

• 类型名：DisclosureAppearance，由@microsoft/fast-components包对外导出；
• 合法取值仅有两个："accent"（强调/主色外观）与"lightweight"（轻量/链接式外观）；
• 由于是字面量类型而非普通string，任何传入组件实例的其他字符串（如"outline"、"filled"、空字符串）都会在编译期直接报错，从而在类型层面就锁死了组件外观的合法性。

在 fast-components.md 的 "Type Aliases" 汇总表中，DisclosureAppearance与AnchorAppearance、ButtonAppearance、TextFieldAppearance等并列，同属 FAST 对外暴露的组件外观类型族。值得注意的是，AnchorAppearance的文档描述同样是 "Types of anchor appearance"，这说明 disclosure 在视觉语义上被设计为"锚点/链接式"的交互控件——它的触发器在默认外观下看起来更像超链接而非实体按钮。

与 fast-disclosure 组件的关系

DisclosureAppearance是fast-disclosure组件的appearance属性（attribute）的类型来源。在 fast-disclosure 组件文档 中，官方示例直接使用了"lightweight"取值：

<fast-disclosure appearance="lightweight"> <strong slot="title">Read about FAST</strong> <div> FAST is a collection of technologies built on Web Components and modern Web Standards, designed to help you efficiently tackle some of the most common challenges in website and application design and development. </div> </fast-disclosure>

组件本身是原生details/summary控件的 Web Component 实现：title槽位承载可点击的摘要（summary）内容，默认槽位承载被折叠的附加内容。关于组件的完整注册与 API，可参见 fastDisclosure 注册函数 与 Disclosure 基础类。

两种外观的设计语义

在 FAST 的设计令牌（design tokens）体系下，"accent"会联动强调色令牌；"lightweight"则更多依赖前景文本色。二者共同覆盖了"强提示"与"弱提示"两种视觉层级，这也是 FAST "自适应界面系统"设计哲学的典型体现。

如何在模板与自定义组件中使用

1. 使用 FAST Design System 注册组件（最简单路径）

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

注册后即可在 HTML/模板中通过appearance属性切换两种外观：

<!-- 强调色外观 --> <fast-disclosure appearance="accent"> <span slot="title">展开详情</span> <p>这里是折叠的附加内容。</p> </fast-disclosure> <!-- 轻量链接式外观 --> <fast-disclosure appearance="lightweight"> <span slot="title"></span> <p>这里是折叠的附加内容。</p> </fast-disclosure>

2. 在 JSX / 模板引擎中传值

由于appearance最终是组件的公开属性，在支持 TSX 或模板绑定的场景下可以显式赋值以享受类型提示：

// 在编译期即可获得类型校验 <fast-disclosure appearance="lightweight"> <strong slot="title">Read about FAST</strong> <div>Content here.</div> </fast-disclosure>

当appearance属性未显式指定时，组件使用样式表内部的默认外观分支（详见下文源码分析），一般表现为不强调、贴近默认文本的外观。

3. 基于 FAST Foundation 打造自有 disclosure 组件

如果不想直接使用@microsoft/fast-components的成品，可以基于@microsoft/fast-foundation的Disclosure基类自行组合设计系统外观：

import { Disclosure, disclosureTemplate as template, } from "@microsoft/fast-foundation"; import { disclosureStyles as styles } from "./my-disclosure.styles"; export const myDisclosure = Disclosure.compose({ baseName: "disclosure", template, styles, });

此时appearance的语义由你自己的样式表决定——DisclosureAppearance类型的"accent" | "lightweight"联合约束了合法的取值域，样式表（styles）则负责把这两个取值映射为真实的视觉呈现。Fast 组件的样式模板定义可参考 disclosureStyles。

源码级实现：appearance 如何影响渲染

从 Disclosure 基础类 的 API 可以推断其内部实现脉络：

• 状态属性expanded: boolean：决定是否展示额外内容，对应 HTML 中 summary 的aria-expanded语义；
• 标题属性title: string：作为触发器的可见标题（与slot="title"内容协同）；
• show()/hide()/toggle()：公开方法，展开、收起、切换折叠状态；
• 受保护的setup()：在组件挂载时注册事件监听并设定默认折叠模式；
• 受保护的onToggle()：在每次切换时更新 ARIA 属性并派发toggle事件。

appearance属性本身并不参与折叠逻辑，它是样式层的开关：FAST 的组件样式模板中通过类似:host([appearance="accent"])这样的属性选择器对两种取值分别施加设计令牌。这一点在 high-contrast.md 的设计系统文档中体现得尤为明显——其高对比度样式专门为appearance="accent"分支补充了:hover、:active、:focus及disabled等状态下的强调色控制规则，说明"accent"分支具备完整的交互状态设计，而"lightweight"分支则共享默认的轻量文本外观。

从类型设计角度，DisclosureAppearance与 AnchorAppearance（同样为"accent" | "lightweight"语义族）保持一致，进一步印证了 disclosure 触发器"锚点化"的视觉定位：两种取值都不包含"outline"、"filled"等实体按钮形态，设计意图是把折叠触发器控制在"强调链接"与"普通链接"两档之间。

无障碍与交互细节（accessibility 联动）

FAST 的 Disclosure 组件基于 W3C ARIA 实践指南（APG）中的 disclosure 模式实现，其无障碍行为由 Foundation 层保证：

• 触发切换时onToggle()同步更新aria-expanded属性，让屏幕阅读器获知折叠面板的当前展开/收起状态；
• 每次切换派发toggle事件，便于外部监听展开/收起行为做统计或联动；
• 组件支持start、end两个辅助槽位（位于摘要内容前后），可在不影响语义的前提下补充图标等装饰内容。

appearance的两种取值不会改变上述无障碍契约，只会改变视觉层级——在需要强调的场景选"accent"，在需要弱化、融入正文的场景选"lightweight"，二者在键盘操作、ARIA 属性与事件派发上保持一致。

快速验证清单

1. 类型层面：appearance只接受"accent" | "lightweight"，其余字符串在 TS 编译期报错；
2. 注册层面：使用provideFASTDesignSystem().register(fastDisclosure())注册组件（见 fastDisclosure）；
3. 模板层面：在<fast-disclosure appearance="...">上直接声明外观，title槽位放触发器，默认槽位放折叠内容；
4. 样式层面：若自行基于Disclosure.compose()定制，请确保样式表对两种外观取值分别提供视觉映射，可参考 disclosureStyles 与设计系统的外观分支写法（high-contrast.md）；
5. 行为层面：验证展开/收起时aria-expanded正确翻转、toggle事件按预期触发（对应 Disclosure 基类 的show()/hide()/toggle()契约）。

参考文档索引

• DisclosureAppearance 类型定义
• fast-disclosure 组件指南
• fastDisclosure 注册函数
• disclosureStyles 样式模板
• Disclosure 基础类 API
• fast-components 类型别名汇总

• 前端
• UI组件