Reach UI 中的 Disclosure 组件详解：构建可访问的内容展示控件

什么是 Disclosure 组件

Disclosure 是 Reach UI 库中提供的一个 React 可访问性组件，用于创建符合 WAI-ARIA 标准的交互式内容展示控件。它由三个核心部分组成：触发按钮（DisclosureButton）、内容面板（DisclosurePanel）以及管理状态的容器组件（Disclosure）。

核心概念与工作原理

Disclosure 组件的工作机制类似于常见的折叠面板（Collapse Panel）或手风琴（Accordion）组件，但更专注于单一内容的展开/收起功能：

1. 状态管理：Disclosure 组件内部维护着展开/收起的状态
2. 无障碍支持：自动处理 ARIA 属性和键盘交互
3. 组合模式：采用复合组件设计，提供灵活的 API

安装与基本使用

安装方法

npm install @reach/disclosure
# 或
yarn add @reach/disclosure

基础示例

import { Disclosure, DisclosureButton, DisclosurePanel } from "@reach/disclosure";

function BasicDisclosure() {
  return (
    <Disclosure>
      <DisclosureButton>显示更多内容</DisclosureButton>
      <DisclosurePanel>
        这里是隐藏的内容，点击按钮后会显示出来！
      </DisclosurePanel>
    </Disclosure>
  );
}

组件 API 深度解析

1. Disclosure 容器组件

作为整个组件的状态管理核心，Disclosure 不直接渲染 DOM 元素，而是作为上下文提供者。

主要属性

属性名	类型	必填	说明
defaultOpen	boolean	否	初始是否展开，默认为 false
id	string/num	否	用于生成子组件的 ID，未提供时会自动生成
onChange	function	否	状态变化时的回调函数
open	boolean	否	控制展开状态的属性，用于实现受控组件

使用技巧

// 受控组件示例
const [isOpen, setIsOpen] = React.useState(false);

<Disclosure open={isOpen} onChange={() => setIsOpen(!isOpen)}>
  {/* 子组件 */}
</Disclosure>

2. DisclosureButton 触发按钮

负责用户交互的按钮组件，默认渲染为 <button> 元素。

关键特性

• 自动处理键盘交互（Enter/Space 键）
• 动态更新 ARIA 属性（aria-expanded）
• 支持自定义渲染元素（通过 as 属性）

样式定制

/* 基础样式 */
[data-reach-disclosure-button] {
  /* 自定义样式 */
}

/* 展开状态 */
[data-reach-disclosure-button][data-state="open"] {
  /* 展开时样式 */
}

/* 收起状态 */
[data-reach-disclosure-button][data-state="collapsed"] {
  /* 收起时样式 */
}

3. DisclosurePanel 内容面板

包含可折叠内容的容器组件，默认渲染为 <div> 元素。

重要特性

• 自动管理显示/隐藏状态
• 与按钮建立 ARIA 关联
• 支持动画过渡效果

高级用法与最佳实践

1. 自定义渲染元素

<Disclosure>
  <DisclosureButton as="div" role="button" tabIndex={0}>
    自定义触发元素
  </DisclosureButton>
  <DisclosurePanel as="section">
    使用 section 标签作为内容容器
  </DisclosurePanel>
</Disclosure>

2. 状态共享模式

function CustomDisclosure() {
  const { open, panelId } = useDisclosureContext();
  
  return (
    <>
      <button aria-expanded={open} aria-controls={panelId}>
        {open ? "收起" : "展开"}
      </button>
      <div id={panelId} hidden={!open}>
        自定义内容
      </div>
    </>
  );
}

无障碍设计考虑

Reach UI 的 Disclosure 组件严格遵循 WAI-ARIA 1.2 规范：

1. 自动设置 aria-expanded 状态
2. 建立按钮与面板的 aria-controls 关联
3. 支持键盘导航操作
4. 确保焦点管理合理

常见问题解答

Q: 什么时候应该使用 Disclosure 而不是 Accordion？

A: 当只需要管理单个内容的展开/收起时使用 Disclosure；当需要管理一组互相关联的折叠面板时，应该使用 Accordion 组件。

Q: 如何实现动画效果？

A: 可以通过 CSS 过渡或结合动画库实现。DisclosurePanel 提供了 data-state 属性用于区分展开/收起状态。

Q: 为什么我的样式不生效？

A: 确保使用正确的数据属性选择器（如 [data-reach-disclosure-button]）而非类名选择器。

总结

Reach UI 的 Disclosure 组件为开发者提供了一个开箱即用的可访问性解决方案，简化了折叠内容交互的实现过程。通过合理的组件设计和丰富的 API，它既满足了基本需求，又提供了足够的灵活性来应对各种定制场景。