#回到底部

回到底部只在持续追加内容的滚动区域中出现，让暂时离开实时位置的用户主动回到末尾，同时保留未读更新数量。

npm install @a3s-lab/ui@0.4.0

<div class="transcript-viewport" data-scroll-owner>
  <ol aria-label="运行记录">
    <li>依赖检查已完成。</li>
    <li>正在构建文档站。</li>
  </ol>
  <button type="button" class="back-to-bottom" data-unread="3">
    <span data-back-to-bottom-label>回到最新内容</span>
    <span data-unread-count>3</span>
  </button>
</div>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

#用法

把按钮放在真正拥有滚动的区域内。默认情况下，控制器会在距离末尾超过阈值或存在未读更新时显示按钮；data-always-visible 只适合演示和调试。

<div class="transcript-viewport" data-scroll-owner>
  <ol aria-label="运行记录">
    <li>依赖检查已完成。</li>
    <li>正在构建文档站。</li>
  </ol>
  <button type="button" class="back-to-bottom" data-unread="3">
    <span data-back-to-bottom-label>回到最新内容</span>
    <span data-unread-count>3</span>
  </button>
</div>

按需加载时，先导入共享运行时，再导入控制器。

import "@a3s-lab/ui/runtime";
import "@a3s-lab/ui/back-to-bottom";

const button = document.querySelector(".back-to-bottom");

button.addEventListener("a3s:back-to-bottom-activate", () => {
  markVisibleUpdatesAsRead();
});

button.setUnread(3);

#参数

#JavaScript API

#状态与变体

hidden 表示用户仍在实时末尾且没有未读更新；visible 表示用户离开末尾；unread 表示有新内容等待阅读。新内容到达时只增加计数，不自动滚动。用户主动回到底部后，组件清除计数并遵循 prefers-reduced-motion。

这个操作只属于持续追加且有独立滚动所有者的区域，例如运行日志、对话记录或事件流。普通短列表、静态文章和页面级滚动不需要它。

#可访问性

根元素必须是具有清晰动作名称的原生按钮。未读数量需要可见，并通过按钮名称或 data-unread-count 的可访问文本说明“未读更新”含义，不能只读出一个孤立数字。新内容到达时不抢焦点、不强制滚动；如果产品另设实时播报区域，避免在按钮上重复播报同一条更新。按钮只能控制所属滚动容器，关闭或隐藏时不得留在 Tab 顺序中。宿主负责内容传输、已读回执、虚拟列表和业务计数，组件只负责滚动位置、显隐和回到底部意图。