VisuallyHidden 视觉隐藏

隐藏视觉内容，同时保留辅助技术文本或可聚焦跳转。

Beta

示例

直接操作示例，查看组件在具体任务中的状态与反馈。

交互示例 · 本地数据

VisuallyHidden 焦点示例

展示可聚焦 skip link 与图标按钮的隐藏可访问名称。

普通隐藏文本保留可访问名称；focusable 模式让真实 skip link 在获得焦点时恢复可见。
可聚焦跳转

按 Tab 可聚焦下面的隐藏跳转链接。

跳到示例结果
示例结果：焦点跳转目标
图标按钮名称
交互示例 · 本地数据

VisuallyHidden 图标名称

仅图标按钮通过隐藏文本获得稳定的可访问名称。

仅图标按钮通过隐藏文本获得稳定的可访问名称。
卡片操作

使用建议

隐藏不等于删除内容

为图标按钮补充名称或为复杂视觉提供文字时使用；纯装饰内容应通过 aria-hidden 从可访问树中移除。

focusable 只用于真实焦点入口

skip link 等可操作内容可以开启 focusable，让内部链接获得焦点时恢复可见；普通说明保持默认隐藏。

跳转目标必须可定位

skip link 的 href 需要指向稳定 ID，目标在必要时设置 tabIndex=-1，并验证焦点与滚动结果。

引入方式

从已验证的公开子路径导入组件；全局样式接入方式见安装指南。

import { BaseVisuallyHidden } from '@inf-monkeys-tech/monkeys-design/components/base';

当前限制

  • VisuallyHidden 不会判断文本是否重复、跳转目标是否存在，也不替代可访问名称和页面焦点顺序审查。
  • T17 尚缺真实 Chromium hydration、focus、axe、visual 与 packed React 18/19 证据；尤其是 focus-within 恢复可见与 skip link 焦点移动尚未完成浏览器闭环。
  • Browser focus/focus-within behavior, automated axe checks, and deterministic visual evidence are pending T17/T23.

API

查看组件源码
export interface BaseVisuallyHiddenProps
  extends Omit<
    HTMLAttributes<HTMLSpanElement>,
    'children' | 'className' | 'style'
  > {
  children?: ReactNode;
  focusable?: boolean;
  appearance?: BaseAppearance;
  className?: string;
  classNames?: BaseVisuallyHiddenClassNames;
  style?: CSSProperties;
}
属性说明类型默认值
children在 BaseVisuallyHidden 内渲染的子内容；支持渲染函数时以对应的 Props 类型为准。ReactNode—
focusable视觉隐藏内容是否仍可通过键盘获得焦点。booleanfalse
appearance覆盖组件使用的外观令牌或局部样式配置。BaseAppearance—
className追加到组件根元素的 CSS 类名。string—
classNames按组件公开的结构插槽分别追加 CSS 类名。BaseVisuallyHiddenClassNames—
style追加到组件根元素的内联样式。CSSProperties—