Kibana EUI 无障碍实践EuiCallOut 的 announceOnMount 与条件渲染公告机制【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana在 Kibana 前端代码中表单校验、异步请求结果、提交后反馈等场景下会条件性地渲染提示组件callout。这类突然出现的提示对屏幕阅读器用户默认是不可见的——除非显式启用 Elastic UIelastic/eui提供的 live-region 行为。本文基于 Kibana 仓库内置的无障碍技能文档 callouts.md系统讲解EuiCallOut的announceOnMount属性什么时候必须加、什么时候不应该加、属性经 spread 传递时如何补齐以及仓库中 Discover、Dashboard 等插件的真实落地写法。背景为什么条件渲染的 callout 需要主动播报无障碍技能总入口 SKILL.md 开宗明义无障碍是写组件的一部分而不是 lint 报错后补的工序。所有组件指南都是 shared_principles.md 的扩展该文档要求满足 WCAG 2.2 AA、遵循 W3C ARIA APG 模式并优先使用 EUI 组件而非原生 HTMLEUI 已经处理好了 aria 属性、焦点与键盘交互。在此标准下callout 指南给出的核心判断只有一条一个条件性出现的 callout校验失败、异步结果、开关切换、提交后反馈如果不选择 EUI 的live-region行为辅助技术屏幕阅读器根本听不到它。这就是announceOnMount存在的意义当组件挂载进 DOM 时把其内容作为一个 live region 公告announcement广播出去屏幕阅读器随即读出。规范用法Canonical usage原文档给出了三条决策规则覆盖全部三种情形条件渲染 → 必须设置announceOnMount。典型形态包括condition …、三元表达式、分支渲染、early return。只要 callout 的出现在运行时才决定就要在挂载时公告。始终挂载的静态 callout → 省略announceOnMount。静态提示没有突然出现的问题不需要 live region反而加了是多余行为。条件渲染但明确不需要公告少见→ 写announceOnMount{false}显式拒绝。且当理由不明显时要求在调用点callsite用注释说明为什么。此外还有一条 i18n 约束新出现的用户可见字符串title、正文必须走i18n.translate。这一点与 shared principles 的本地化要求一致——可见与辅助技术字符串aria-label、title、错误消息、正文一律不得写裸字面量若文件内已有共享的文案对象如i18nTexts.modalTitle应沿用该局部模式而不是新加内联调用。最后一条针对属性透传场景如果EuiCallOut使用了{...calloutProps}展开而announceOnMount没有出现在开标签上必须在调用点或 spread 的来源处把它合并进去——不能依赖spread 里大概有。代码示例条件 callout正例错误态出现时挂载并公告标题走 i18n{hasError ( EuiCallOut announceOnMount title{i18n.translate(form.errorTitle, { defaultMessage: Error })} colordanger {errorMessage} /EuiCallOut )}显式拒绝公告正例少见场景{decorativeCondition ( EuiCallOut announceOnMount{false} title… … /EuiCallOut )}注意这里是announceOnMount{false}而非省略——显式写法向后来审查者包括 lint 规则与 AI Agent表明我知道该不该公告这是刻意的决定。常见错误对照原文档原样给出// WRONG — 条件 callout 缺少 announceOnMount {hasError EuiCallOut titleError colordanger /} // RIGHT {hasError EuiCallOut announceOnMount titleError colordanger /} // WRONG — 静态 callout 上多余地加了 announceOnMount EuiCallOut announceOnMount titleNote colorprimary /三个反例分别对应条件渲染漏加功能缺陷屏幕阅读器听不到错误、静态渲染多加无意义的 live-region 噪声。仓库源码中的真实落地Kibana 各插件里可以找到大量遵循该规范的调用。以 Discover 的文档上下文工具栏为例action_bar_warning.tsx 中当文档类型为PREDECESSORS时 early return 一个条件性KbnInfoCalloutKbnInfoCallout announceOnMount >KbnDangerCallout announceOnMount{false} title{relationshipCalloutText} / … KbnWarningCallout announceOnMount{false} title{spacesWarningText} /这些 callout 出现在一个本就有焦点与标题的 modal 弹层内部其内容随用户操作稳定呈现被开发者显式判定为不需要 live-region 公告属于指南第 3 条规则的落地rare场景。ESLint 强制elastic/eui/callout-announce-on-mount规范不只靠自觉。Kibana 的 EUI 无障碍 lint 规则映射表 eslint.md 中登记了专管本主题的规则Rule id对应组件指南需要人工复核的形态elastic/eui/callout-announce-on-mountcomponents/callouts.mdEuiCallOut上存在{...props}且没有显式announceOnMount始终挂载的 callout规则本不应触发这条规则与 shared principles 中的升级机制escalation呼应当{...props}展开使 lint 无法追踪announceOnMount以及其他 aria 属性是否已被提供时不要盲目修改应停下来交人工确认——spread 隐藏了属性接线是文档明确列出的需要人判断的情形之一。要点小结判断标准只有一个callout 是否条件渲染。是 → 加announceOnMount否 → 省略条件但刻意不公告 →announceOnMount{false}并视情况注释理由。文案必须本地化跟随文件内已有的 i18n 模式i18n.translate或共享文案对象。属性经 spread 透传时必须确认announceOnMount在开标签上显式存在或在 spread 来源处补齐无法追踪时交人工复核。仓库内有大量可复制范例条件公告见 action_bar_warning.tsx 与 dashboard_no_match.tsx显式拒绝公告见 delete_data_view_flyout_content.tsx。更完整的组件级无障碍指南表单、弹层、表格、tooltip 等可从 组件指南索引 按组件名逐篇查阅。【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Kibana EUI 无障碍实践：EuiCallOut 的 announceOnMount 与条件渲染公告机制
Kibana EUI 无障碍实践EuiCallOut 的 announceOnMount 与条件渲染公告机制【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana在 Kibana 前端代码中表单校验、异步请求结果、提交后反馈等场景下会条件性地渲染提示组件callout。这类突然出现的提示对屏幕阅读器用户默认是不可见的——除非显式启用 Elastic UIelastic/eui提供的 live-region 行为。本文基于 Kibana 仓库内置的无障碍技能文档 callouts.md系统讲解EuiCallOut的announceOnMount属性什么时候必须加、什么时候不应该加、属性经 spread 传递时如何补齐以及仓库中 Discover、Dashboard 等插件的真实落地写法。背景为什么条件渲染的 callout 需要主动播报无障碍技能总入口 SKILL.md 开宗明义无障碍是写组件的一部分而不是 lint 报错后补的工序。所有组件指南都是 shared_principles.md 的扩展该文档要求满足 WCAG 2.2 AA、遵循 W3C ARIA APG 模式并优先使用 EUI 组件而非原生 HTMLEUI 已经处理好了 aria 属性、焦点与键盘交互。在此标准下callout 指南给出的核心判断只有一条一个条件性出现的 callout校验失败、异步结果、开关切换、提交后反馈如果不选择 EUI 的live-region行为辅助技术屏幕阅读器根本听不到它。这就是announceOnMount存在的意义当组件挂载进 DOM 时把其内容作为一个 live region 公告announcement广播出去屏幕阅读器随即读出。规范用法Canonical usage原文档给出了三条决策规则覆盖全部三种情形条件渲染 → 必须设置announceOnMount。典型形态包括condition …、三元表达式、分支渲染、early return。只要 callout 的出现在运行时才决定就要在挂载时公告。始终挂载的静态 callout → 省略announceOnMount。静态提示没有突然出现的问题不需要 live region反而加了是多余行为。条件渲染但明确不需要公告少见→ 写announceOnMount{false}显式拒绝。且当理由不明显时要求在调用点callsite用注释说明为什么。此外还有一条 i18n 约束新出现的用户可见字符串title、正文必须走i18n.translate。这一点与 shared principles 的本地化要求一致——可见与辅助技术字符串aria-label、title、错误消息、正文一律不得写裸字面量若文件内已有共享的文案对象如i18nTexts.modalTitle应沿用该局部模式而不是新加内联调用。最后一条针对属性透传场景如果EuiCallOut使用了{...calloutProps}展开而announceOnMount没有出现在开标签上必须在调用点或 spread 的来源处把它合并进去——不能依赖spread 里大概有。代码示例条件 callout正例错误态出现时挂载并公告标题走 i18n{hasError ( EuiCallOut announceOnMount title{i18n.translate(form.errorTitle, { defaultMessage: Error })} colordanger {errorMessage} /EuiCallOut )}显式拒绝公告正例少见场景{decorativeCondition ( EuiCallOut announceOnMount{false} title… … /EuiCallOut )}注意这里是announceOnMount{false}而非省略——显式写法向后来审查者包括 lint 规则与 AI Agent表明我知道该不该公告这是刻意的决定。常见错误对照原文档原样给出// WRONG — 条件 callout 缺少 announceOnMount {hasError EuiCallOut titleError colordanger /} // RIGHT {hasError EuiCallOut announceOnMount titleError colordanger /} // WRONG — 静态 callout 上多余地加了 announceOnMount EuiCallOut announceOnMount titleNote colorprimary /三个反例分别对应条件渲染漏加功能缺陷屏幕阅读器听不到错误、静态渲染多加无意义的 live-region 噪声。仓库源码中的真实落地Kibana 各插件里可以找到大量遵循该规范的调用。以 Discover 的文档上下文工具栏为例action_bar_warning.tsx 中当文档类型为PREDECESSORS时 early return 一个条件性KbnInfoCalloutKbnInfoCallout announceOnMount >KbnDangerCallout announceOnMount{false} title{relationshipCalloutText} / … KbnWarningCallout announceOnMount{false} title{spacesWarningText} /这些 callout 出现在一个本就有焦点与标题的 modal 弹层内部其内容随用户操作稳定呈现被开发者显式判定为不需要 live-region 公告属于指南第 3 条规则的落地rare场景。ESLint 强制elastic/eui/callout-announce-on-mount规范不只靠自觉。Kibana 的 EUI 无障碍 lint 规则映射表 eslint.md 中登记了专管本主题的规则Rule id对应组件指南需要人工复核的形态elastic/eui/callout-announce-on-mountcomponents/callouts.mdEuiCallOut上存在{...props}且没有显式announceOnMount始终挂载的 callout规则本不应触发这条规则与 shared principles 中的升级机制escalation呼应当{...props}展开使 lint 无法追踪announceOnMount以及其他 aria 属性是否已被提供时不要盲目修改应停下来交人工确认——spread 隐藏了属性接线是文档明确列出的需要人判断的情形之一。要点小结判断标准只有一个callout 是否条件渲染。是 → 加announceOnMount否 → 省略条件但刻意不公告 →announceOnMount{false}并视情况注释理由。文案必须本地化跟随文件内已有的 i18n 模式i18n.translate或共享文案对象。属性经 spread 透传时必须确认announceOnMount在开标签上显式存在或在 spread 来源处补齐无法追踪时交人工复核。仓库内有大量可复制范例条件公告见 action_bar_warning.tsx 与 dashboard_no_match.tsx显式拒绝公告见 delete_data_view_flyout_content.tsx。更完整的组件级无障碍指南表单、弹层、表格、tooltip 等可从 组件指南索引 按组件名逐篇查阅。【免费下载链接】kibanaYour window into all of your data项目地址: https://gitcode.com/GitHub_Trending/ki/kibana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考