在文章页面添加「稍后再读」书签按钮，点击后文章内容自由落体掉出屏幕、侧栏列表静默刷新，同时支持在侧栏点击已收藏文章直接跳转。纯前端 localStorage 存储，无后端依赖。

IMPORTANT
Fuwari 使用 Swup 4 做页面切换，侧栏（包括「稍后再读」widget）位于 #swup-container 外部，不受 Swup DOM 替换影响。所有交互脚本必须使用 <script is:inline> 以保证在 Swup 切页后仍可执行。

一、数据结构#

使用 localStorage 存储，key 为 readLater，值为 JSON 数组，上限 20 条，最新添加的排在最前：

1
[
2
  {
3
    "slug": "post-slug",
4
    "title": "文章标题",
5
    "url": "/posts/post-slug/",
6
    "addedAt": 1716950000000
7
  }
8
]

slug：文章标识，用于去重判断
url：相对路径（/posts/xxx/），兼容 Swup 的 navigate() 方法
addedAt：Date.now() 时间戳，用于显示”5分钟前”等相对时间

二、i18n 配置#

2.1 新增枚举#

编辑 src/i18n/i18nKey.ts，在枚举末尾追加：

1
readLater = "readLater",
2
readLaterAdd = "readLaterAdd",
3
readLaterRemove = "readLaterRemove",
4
readLaterEmpty = "readLaterEmpty",

2.2 各语言翻译#

编辑 src/i18n/languages/*.ts（共 9 个文件），在 translation 对象中追加对应的 key-value。以 zh_CN.ts 和 en.ts 为例：

1
[I18nKey.readLater]: "稍后再读",
2
[I18nKey.readLaterAdd]: "加入稍后再读",
3
[I18nKey.readLaterRemove]: "移除稍后再读",
4
[I18nKey.readLaterEmpty]: "暂无文章",
5

6
// en.ts
7
[I18nKey.readLater]: "Read Later",
8
[I18nKey.readLaterAdd]: "Add to Read Later",
9
[I18nKey.readLaterRemove]: "Remove from Read Later",
10
[I18nKey.readLaterEmpty]: "No saved articles",

2.3 类型声明#

编辑 src/global.d.ts，在 Window 接口中添加：

1
ReadLaterStore?: {
2
    getList: () => Array<{slug: string; title: string; url: string; addedAt: number}>;
3
    saveList: (list: Array<{slug: string; title: string; url: string; addedAt: number}>) => void;
4
    has: (slug: string) => boolean;
5
    add: (item: {slug: string; title: string; url: string}) => void;
6
    remove: (slug: string) => void;
7
    renderButton: () => void;
8
    renderSidebar: () => void;
9
    pulseReadLaterCard: () => void;
10
};

三、ReadLaterButton 组件#

新建 src/components/ReadLaterButton.astro，放在文章标题右侧，与 ShareButton 并列。

3.1 模板#

两个图标切换显示：未收藏时显示 bookmark-outline，已收藏时显示实心 bookmark，通过 CSS 类 .saved 控制显隐。

1
---
2
import { Icon } from "astro-icon/components";
3

4
interface Props {
5
    slug: string;
6
    title: string;
7
    url: string;
8
    class?: string;
9
}
10
const { slug, title, url } = Astro.props;
11
const className = Astro.props.class || "";
12
---
13

14
<div class:list={["readlater-container inline-flex items-center", className]}>
15
    <button
16
        id="read-later-btn"
17
        class="readlater-btn btn-plain rounded-lg h-9 w-9 flex items-center justify-center"
18
        data-slug={slug}
19
        data-title={title}
20
        data-url={url}
21
        aria-label="稍后再读"
22
    >
23
        <Icon name="material-symbols:bookmark-outline-rounded" class="readlater-icon text-[1.1rem]" />
24
        <Icon name="material-symbols:bookmark-rounded" class="readlater-active-icon text-[1.1rem]" />
25
    </button>
26
</div>

3.2 样式#

使用 <style is:inline>，因为按钮的 .saved 类由 JS 动态添加，Astro 的 scoped style 无法匹配。

1
.readlater-container { display: inline-flex; align-items: center; }
2
.readlater-btn .readlater-icon { display: inline; }
3
.readlater-btn .readlater-active-icon { display: none; }
4
.readlater-btn.saved .readlater-icon { display: none; }
5
.readlater-btn.saved .readlater-active-icon { display: inline; }
6
.readlater-btn.saved { color: var(--primary) !important; }

3.3 ReadLaterStore 全局对象#

整个功能的核心是 window.ReadLaterStore，一个挂载在 window 上的全局对象，被按钮组件和侧栏 widget 共享。使用 if (!window.ReadLaterStore) 守卫，确保无论哪个组件先加载，都只初始化一次。

1
if (!window.ReadLaterStore) {
2
    var STORE_KEY = 'readLater';
3
    var MAX_ITEMS = 20;
4

5
    window.ReadLaterStore = {
6
        getList: function() {
7
            try { return JSON.parse(localStorage.getItem(STORE_KEY)) || []; }
8
            catch(e) { return []; }
9
        },
10
        saveList: function(list) {
11
            try {
12
                if (list.length > MAX_ITEMS) list = list.slice(0, MAX_ITEMS);
13
                localStorage.setItem(STORE_KEY, JSON.stringify(list));
14
            } catch(e) {}
15
        },
16
        has: function(slug) {
17
            return this.getList().some(function(i) { return i.slug === slug; });
18
        },
19
        add: function(item) {
20
            // 先过滤掉同 slug 条目，再插入最前面，天然去重且保留最新
21
            var list = this.getList().filter(function(i) { return i.slug !== item.slug; });
22
            list.unshift({
23
                slug: item.slug, title: item.title,
24
                url: item.url, addedAt: Date.now()
25
            });
26
            this.saveList(list);
27
        },
28
        remove: function(slug) {
29
            var list = this.getList().filter(function(i) { return i.slug !== slug; });
30
            this.saveList(list);
31
        },
32
        // ... renderButton / renderSidebar / pulseReadLaterCard
33
    };
34
}

renderButton() 同步按钮的视觉状态（检查 localStorage 中是否有当前文章 slug），renderSidebar() 重绘侧栏列表 HTML，两者均在 add/remove 后立即调用。

3.4 自由落体动画#

这是实现中最复杂的部分。需求是：点击收藏后，文章内容向下掉落并消失，同时露出首页内容，整个过程没有页面刷新感。

克隆策略#

核心矛盾：如果直接隐藏原始内容（visibility: hidden），内容区会变空白，看起来像”刷新”。

解决方案：不隐藏原内容，克隆 #content-wrapper 并用 position: fixed + z-index: 60 覆盖在原内容上方。原内容始终可见，被克隆体遮住，用户无感。

1
function prepareFallClone() {
2
    var contentEl = document.getElementById('content-wrapper');
3
    if (!contentEl) return null;
4
    var rect = contentEl.getBoundingClientRect();
5

6
    var clone = contentEl.cloneNode(true);
7
    clone.removeAttribute('id');
8
    clone.style.cssText =
9
        'position:fixed;left:' + rect.left + 'px;top:' + rect.top + 'px;' +
10
        'width:' + rect.width + 'px;height:' + rect.height + 'px;' +
11
        'z-index:60;margin:0;overflow:hidden;pointer-events:none;' +
12
        'will-change:transform,opacity;transform-origin:center center;' +
13
        'opacity:1;animation:none;';  // ← 关键：覆盖 onload-animation 的 opacity:0
14
    document.body.appendChild(clone);
15
    // 不隐藏原内容 —— 克隆体遮着，无空白闪烁
16
    return { clone: clone, contentEl: contentEl };
17
}

必须设置 animation:none
#content-wrapper 带有 onload-animation 类（opacity: 0; animation: 300ms fade-in-up）。克隆体会继承这个动画并从头播放，导致克隆体初始 opacity: 0 而完全不可见。必须在 inline style 中显式设置 opacity:1;animation:none; 覆盖。

动画与 Fetch 并行#

动画和首页数据获取同时进行。两个异步任务通过 cloneDone 和 fetchDone 两个布尔标志协调，只有两者都完成时才执行 reveal() 替换内容：

1
function animateFallClone(state, callback) {
2
    var clone = state.clone;
3
    var cloneDone = false, fetchDone = false, newContentEl = null;
4

5
    function reveal() {
6
        if (!cloneDone || !fetchDone) return;  // 两者都就绪才执行
7
        if (clone.parentNode) clone.remove();
8
        if (newContentEl) {
9
            newContentEl.style.opacity = '1';   // 瞬间显示，无渐显
10
            newContentEl.style.transition = '';
11
        }
12
        window.scrollTo(0, 0);
13
        if (window.ReadLaterStore) window.ReadLaterStore.renderSidebar();
14
        callback();
15
    }
16

17
    // CSS Transition: 自由落体
18
    requestAnimationFrame(function() {
19
        requestAnimationFrame(function() {
20
            clone.style.transition = 'transform 1s cubic-bezier(0.4,0,1,1), opacity 1s ease-in';
21
            clone.style.transform = 'translateY(120vh) scale(0.3)';
22
            clone.style.opacity = '0';
23
        });
24
    });
25

26
    clone.addEventListener('transitionend', function() { cloneDone = true; reveal(); });
27
    setTimeout(function() { cloneDone = true; reveal(); }, 1500); // 安全超时
28

29
    // Fetch 首页 HTML
30
    fetch(window.location.origin + '/')
31
        .then(function(r) { return r.text(); })
32
        .then(function(html) {
33
            var doc = new DOMParser().parseFromString(html, 'text/html');
34
            var newSwup = doc.getElementById('swup-container');
35
            var swupEl = document.getElementById('swup-container');
36
            if (newSwup && swupEl) {
37
                swupEl.innerHTML = newSwup.innerHTML;  // 替换内容区
38
                newContentEl = document.getElementById('content-wrapper');
39
                if (newContentEl) {
40
                    newContentEl.style.opacity = '0';   // 先隐藏，等动画结束再显示
41
                    newContentEl.style.transition = 'none';
42
                }
43
            }
44
            fetchDone = true;
45
            reveal();
46
        })
47
        .catch(function() { window.location.href = '/'; });  // fallback
48
}

为什么用 fetch + innerHTML 而不是 swup.navigate()？
swup.navigate('/') 会触发 Swup 自己的退出动画（约 300ms），在动画期间内容区 opacity: 0，用户会看到明显的内容消失再出现。用 fetch + innerHTML 直接替换内容，配合 opacity:0 → 1 瞬间切换，完全跳过 Swup 的动画周期，实现真正的”无刷新”。

时序图#

1
点击书签
2
├─ prepareFallClone()    → 克隆体创建，覆盖在原内容上方
3
├─ localStorage.add()    → 写入数据（被克隆体遮住，用户无感）
4
├─ renderButton()        → 按钮变为已收藏状态
5
├─ renderSidebar()       → 侧栏列表更新（被克隆体遮住）
6
│
7
├─ animateFallClone()
8
│   ├─ [并行] clone: translateY(120vh) scale(0.3) opacity:0   ← 1秒
9
│   ├─ [并行] fetch('/') → 获取首页 HTML → 替换 #swup-container
10
│   │                      → newContentEl opacity:0（先隐藏）
11
│   └─ 两者都完成 → reveal()
12
│       → 移除克隆体
13
│       → newContentEl opacity:1（瞬间显示首页）
14
│       → renderSidebar()

新建 src/components/widget/ReadLater.astro，使用 Fuwari 原生的 WidgetLayout 壳子。

4.1 模板#

1
---
2
import I18nKey from "../../i18n/i18nKey";
3
import { i18n } from "../../i18n/translation";
4
import WidgetLayout from "./WidgetLayout.astro";
5

6
interface Props { class?: string; style?: string; }
7
const className = Astro.props.class;
8
const style = Astro.props.style;
9
---
10

11
<WidgetLayout name={i18n(I18nKey.readLater)} id="read-later" class={className} style={style}>
12
    <div id="read-later-content">
13
        <div id="read-later-empty" class="hidden text-sm text-black/50 dark:text-white/50 py-1">
14
            {i18n(I18nKey.readLaterEmpty)}
15
        </div>
16
        <div id="read-later-list" class="flex flex-col gap-0.5"></div>
17
    </div>
18
</WidgetLayout>

4.2 侧栏列表渲染#

侧栏组件的 <script is:inline> 中也包含一个 ReadLaterStore 定义（带 if (!window.ReadLaterStore) 守卫），以及独立的 renderReadLaterSidebar() 函数。

关键点是事件委托：列表的点击事件绑定在 #read-later-list 容器上，而不是每个 <a> 标签上。这样无论列表内容如何更新（innerHTML 重写），点击处理始终有效：

1
var __readLaterListDelegated = false;
2

3
function renderReadLaterSidebar() {
4
    var listEl = document.getElementById('read-later-list');
5
    var emptyEl = document.getElementById('read-later-empty');
6
    if (!listEl) return;
7
    var items = window.ReadLaterStore.getList();
8

9
    // 事件委托：只绑定一次
10
    if (!__readLaterListDelegated) {
11
        __readLaterListDelegated = true;
12
        listEl.addEventListener('click', function(e) {
13
            var link = e.target.closest('a[data-slug]');
14
            if (!link) return;
15
            e.preventDefault();
16
            var slug = link.dataset.slug;
17
            var url = link.getAttribute('href');
18
            // 先从列表中删除，再跳转
19
            if (window.ReadLaterStore) {
20
                window.ReadLaterStore.remove(slug);
21
                renderReadLaterSidebar();
22
            }
23
            if (url) {
24
                if (window.swup && window.swup.navigate) {
25
                    window.swup.navigate(url);  // SPA 跳转，无全量刷新
26
                } else {
27
                    window.location.href = url;
28
                }
29
            }
30
        });
31
    }
32

33
    // 渲染列表条目（带 data-slug 属性供事件委托使用）
34
    if (items.length === 0) {
35
        listEl.innerHTML = '';
36
        if (emptyEl) emptyEl.classList.remove('hidden');
37
        return;
38
    }
39
    if (emptyEl) emptyEl.classList.add('hidden');
40
    listEl.innerHTML = items.map(function(item) {
41
        return '<a href="' + item.url + '" data-slug="' + item.slug + '" ' +
42
            'class="read-later-item btn-plain rounded-lg w-full h-9 px-2 ' +
43
            'flex items-center gap-2 text-sm cursor-pointer ...">' +
44
            '<span class="flex-1 overflow-hidden whitespace-nowrap text-ellipsis">' +
45
                item.title.replace(/</g, '&lt;') + '</span>' +
46
            '<span class="text-xs text-black/30 dark:text-white/30 shrink-0">' +
47
                timeAgo(item.addedAt) + '</span>' +
48
            '</a>';
49
    }).join('');
50
}

侧栏 widget 还注册了 Swup 的 page:view 钩子，在每次切页后重新渲染列表（此时列表 DOM 已被 Swup 替换为初始空状态）：

1
window.swup.hooks.on('page:view', function() {
2
    setTimeout(function() { renderReadLaterSidebar(); }, 50);
3
});

五、接入页面#

5.1 文章页#

编辑 src/pages/posts/[...slug].astro，在 PostMetadata 旁插入 ReadLaterButton：

1
import ReadLaterButton from "../../components/ReadLaterButton.astro";
2

3
// 在 metadata 区域：
4
<div class="flex items-start gap-4 mb-5">
5
    <PostMetadata class="flex-1 min-w-0 overflow-hidden" ... />
6
    <div class="flex items-center gap-1 shrink-0">
7
        <ReadLaterButton slug={getEntrySlug(entry)} title={entry.data.title} url={Astro.url.pathname} />
8
        <ShareButton title={entry.data.title} url={postUrl} />
9
    </div>
10
</div>

url 使用 Astro.url.pathname（相对路径 /posts/xxx/）而非完整 URL，保证 Swup 的 navigate() 方法能正确匹配路由。

PostMetadata 加 overflow-hidden 确保窄屏时内部内容被裁剪而不是把按钮挤出容器。

5.2 侧栏#

编辑 src/components/widget/SideBar.astro，在 Weather 和 Tag 之间插入 ReadLater widget：

1
import ReadLater from "./ReadLater.astro";
2

3
<Weather class="onload-animation" style="animation-delay: 150ms"></Weather>
4
<ReadLater class="onload-animation" style="animation-delay: 200ms"></ReadLater>
5
<Tag class="onload-animation" style="animation-delay: 250ms"></Tag>
6
<Categories class="onload-animation" style="animation-delay: 300ms"></Categories>

侧栏位于 #swup-container 外部（Fuwari 的 grid 布局中独占一列），Swup 的 containers: ["#swup-container", "#toc"] 配置不包含侧栏，因此 Swup 切页时侧栏 DOM 不会被替换，widget 脚本无需重复执行。

六、踩坑记录#

克隆体不可见#

#content-wrapper 带有 onload-animation 类（opacity: 0; animation: 300ms fade-in-up）。cloneNode(true) 会继承这个类，克隆体追加到 <body> 后动画从头播放，初始 opacity: 0 导致克隆体完全隐形。

修复：在克隆体的 inline style 中设置 opacity:1;animation:none; 覆盖继承的动画。

侧栏跟随掉落#

最初克隆整个 #main-grid（含侧栏），导致侧栏跟着一起掉。改为只克隆 #content-wrapper（纯内容列），侧栏不在克隆范围内，始终保持不动。

内容注入闪烁#

swupEl.innerHTML = newSwup.innerHTML 替换内容后，新的 #content-wrapper 带有 onload-animation 类，从 opacity: 0 渐显到 1，造成”空白闪烁”。

修复：注入后立即设置 newContentEl.style.opacity = '0'，等动画克隆体消失后（reveal()）再瞬间设为 1，无渐显过渡。

侧栏点击全量刷新#

最初侧栏链接使用 window.location.href = url，导致整页刷新。改用 window.swup.navigate(url) 做 SPA 跳转，只替换 Swup 容器内容，侧栏和其他区域不受影响。

七、文件清单#

文件	操作	说明
`src/i18n/i18nKey.ts`	修改	新增 4 个枚举值
`src/i18n/languages/*.ts`（9个）	修改	各语言翻译
`src/global.d.ts`	修改	`ReadLaterStore` 类型声明
`src/components/ReadLaterButton.astro`	新建	书签按钮 + 自由落体动画 + `ReadLaterStore`
`src/components/widget/ReadLater.astro`	新建	侧栏 widget + 事件委托 + Swup 钩子
`src/pages/posts/[...slug].astro`	修改	插入 `ReadLaterButton`
`src/components/widget/SideBar.astro`	修改	插入 `ReadLater` widget

一、数据结构#

二、i18n 配置#

2.1 新增枚举#

2.2 各语言翻译#

2.3 类型声明#

三、ReadLaterButton 组件#

3.1 模板#

3.2 样式#

3.3 ReadLaterStore 全局对象#

3.4 自由落体动画#

克隆策略#

动画与 Fetch 并行#

时序图#

四、侧栏 Widget#

4.1 模板#

4.2 侧栏列表渲染#

五、接入页面#

5.1 文章页#

5.2 侧栏#

六、踩坑记录#

克隆体不可见#

侧栏跟随掉落#

内容注入闪烁#

侧栏点击全量刷新#

七、文件清单#