寻求用于语义化侧边注释的HTML元素及响应式实现优化方案

我之前做博客时也踩过类似的坑——既要保证语义化，又要兼容阅读器，还得保留注释和关联文本的整体性。给你分享两个靠谱的方案，完美解决你的痛点：

方案一：使用原生<details>+<summary>（首推） #

<details>和<summary>是HTML5原生的可展开/收起组件，天生就是为承载附加信息设计的，语义化拉满。而且只要给它设置行内显示，就不会破坏父级<p>的结构。关键是像Pocket这类阅读器能识别它们的语义，不会把注释内容乱插到正文里。

代码示例 #

<p>Some sentence with 
  <details class="sidenote">
    <summary class="sidenote__trigger">underlined text</summary>
    <span class="sidenote__content">Sidenote content</span>
  </details>, 
which is clickable on small viewports.</p>

CSS配置 #

通过媒体查询控制不同视口的展示逻辑：

/* 基础样式：让details变成行内元素，避免拆分p标签 */
.sidenote {
  display: inline;
  position: relative;
}

/* 大屏下（侧边固定显示注释） */
@media (min-width: 768px) {
  /* 隐藏summary默认的展开箭头 */
  .sidenote summary::-webkit-details-marker {
    display: none;
  }
  .sidenote__trigger {
    text-decoration: underline;
    cursor: default; /* 大屏不需要点击展开 */
  }
  /* 添加星号关联注释和文本 */
  .sidenote__trigger::after {
    content: "*";
    margin-left: 2px;
  }
  .sidenote__content {
    position: absolute;
    right: calc(-100% - 25px);
    width: 220px;
    display: block;
    font-size: 0.9em;
    color: #555;
  }
  /* 强制大屏下始终显示注释，忽略open状态 */
  .sidenote[open] .sidenote__content,
  .sidenote .sidenote__content {
    display: block;
  }
}

/* 小屏下（点击展开注释） */
@media (max-width: 767px) {
  .sidenote__trigger {
    text-decoration: underline;
    cursor: pointer;
    color: #2c5282; /* 用颜色提示可点击 */
  }
  .sidenote__content {
    display: none;
    margin: 8px 0 12px;
    padding: 10px;
    background-color: #f7fafc;
    border-radius: 4px;
  }
  /* 展开时显示注释 */
  .sidenote[open] .sidenote__content {
    display: block;
  }
}

这个方案的优势：

• 完全语义化，原生HTML元素自带“附加可展开信息”的含义
• 不需要自定义onclick事件，<details>原生支持展开收起
• 阅读器兼容性好，不会出现注释内容乱嵌的问题
• 注释和关联文本是一个整体，不需要额外JS匹配

方案二：<span>+ARIA属性增强语义（备选） #

如果你不想用<details>，可以保留<span>但通过ARIA属性增强语义，让阅读器能识别这是注释内容：

代码示例 #

<p>Some sentence with 
  <span class="sidenote" role="note" aria-expanded="false" aria-controls="sidenote-example">
    underlined text
    <span id="sidenote-example" class="sidenote__content">Sidenote content</span>
  </span>, 
which is clickable on small viewports.</p>

配套JS（控制展开状态） #

document.querySelectorAll('.sidenote').forEach(note => {
  note.addEventListener('click', () => {
    const isExpanded = note.getAttribute('aria-expanded') === 'true';
    note.setAttribute('aria-expanded', !isExpanded);
    note.classList.toggle('active');
  });
});

CSS可以沿用你原来的逻辑，只是通过ARIA属性告诉阅读器这是注释，相比纯<span>更友好，但语义化程度不如<details>。

内容的提问来源于stack exchange，提问作者kslstn