Logseq 项目中的屏幕阅读器对大纲结构解析问题分析

问题背景

Logseq 作为一款基于大纲结构的笔记工具，其核心功能依赖于对层级化内容的可视化展示。然而，当前版本存在一个影响视障用户使用体验的关键问题：屏幕阅读器无法正确识别和解析大纲的层级结构。

技术现状分析

在现有实现中，Logseq 通过视觉样式（如缩进）来展示块与子块之间的层级关系。但这种实现方式仅停留在视觉层面，没有为辅助技术提供足够的语义信息。具体表现为：

1. 屏幕阅读器（如 NVDA）会线性读取所有块内容，无法感知块之间的嵌套关系
2. 缺乏适当的 ARIA 属性或语义化 HTML 标记来传达结构信息
3. 导航时无法区分不同层级的块，导致视障用户难以理解内容组织方式

技术解决方案探讨

方案一：语义化 HTML 结构

最理想的解决方案是采用标准的 HTML 列表结构：

<ul>
  <li>一级块
    <ul>
      <li>二级块</li>
    </ul>
  </li>
</ul>

这种方式的优势包括：

• 原生支持屏幕阅读器的层级导航
• 符合 W3C 无障碍标准
• 无需额外维护 ARIA 属性
• 大多数现代屏幕阅读器对此有良好支持

方案二：ARIA 属性补充

如果直接修改 HTML 结构会影响现有样式或功能，可以考虑使用 ARIA 属性：

<div role="list">
  <div role="listitem">一级块
    <div role="list">
      <div role="listitem">二级块</div>
    </div>
  </div>
</div>

这种方案的优势是：

• 可以保持现有 DOM 结构不变
• 能够渐进式地改进无障碍特性
• 对现有 CSS 和 JavaScript 的影响较小

实现建议

基于技术评估，建议优先采用语义化 HTML 方案，因为：

1. 这是最符合标准的前端实践
2. 长期维护成本更低
3. 不仅解决屏幕阅读器问题，还能提升整体代码质量
4. 现代 CSS 完全可以配合语义化 HTML 实现相同的视觉效果

如果确实需要保留现有 DOM 结构，则应完整实现 ARIA 方案，包括：

• 正确的 role 属性
• aria-level 属性标明层级
• aria-posinset 和 aria-setsize 属性提供位置信息

兼容性考量

在实现过程中需要注意：

1. 不同屏幕阅读器对 ARIA 的支持程度
2. 键盘导航的完整实现
3. 与现有功能的交互一致性
4. 性能影响，特别是在大型文档中

总结

Logseq 作为一款知识管理工具，其无障碍功能的完善不仅关乎用户体验，也体现了开发团队对包容性设计的重视。通过采用标准化的前端实践，可以同时提升产品的可访问性和代码质量，为所有用户提供更好的使用体验。