diff --git a/README.en.md b/README.en.md
index fec5973..fa7d42b 100644
--- a/README.en.md
+++ b/README.en.md
@@ -37,6 +37,8 @@ Uploads become WebP images with a maximum long edge of 1920 pixels, without enla
Items are sorted by latest update by default.
+The background moves subtly as you scroll, and item cards slide into view on their first entrance. The first screen appears immediately. Both effects respect the system's reduced-motion preference.
+
The first visit downloads the interface. If a module fails to load after login, the page reloads once to fetch the current application; if it fails again, use Reload to try again.
Click the app name at the top-left to unlock the private area. Locking or refreshing hides it again.
diff --git a/README.md b/README.md
index 8be2d00..6595fcd 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,8 @@ docker compose up -d
物品默认按最近更新排列。
+滚动时背景轻微视差移动,物品卡片首次滚入视野时滑入显示。首屏内容直接显示,系统开启“减少动态效果”时关闭这两种动效。
+
首次打开会下载界面程序。若文件加载失败,登录后会自动重新加载最新页面一次;仍失败可点击“重新加载”重试。
点击左上角“物品管理”输入隐私区密码;解锁后可设置隐私物品、分类和位置;物品的隐私开关位于“标签”右侧。锁定或刷新后重新隐藏。
diff --git a/desktop/package.json b/desktop/package.json
index f7246cb..c3df079 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -1,6 +1,6 @@
{
"name": "@itemmanager/desktop",
- "version": "26.7.1",
+ "version": "26.8.0",
"private": true,
"description": "物品管理桌面客户端",
"author": "MCJ",
diff --git a/package.json b/package.json
index 98c3a6f..14fcb0f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "itemmanager-workspace",
- "version": "26.7.1",
+ "version": "26.8.0",
"private": true,
"license": "MIT",
"packageManager": "pnpm@11.7.0",
diff --git a/web/package.json b/web/package.json
index 28c984e..fa933a8 100644
--- a/web/package.json
+++ b/web/package.json
@@ -1,6 +1,6 @@
{
"name": "@itemmanager/web",
- "version": "26.7.1",
+ "version": "26.8.0",
"private": true,
"license": "MIT",
"packageManager": "pnpm@11.7.0",
diff --git a/web/src/renderer/features/items/ItemGalleryGrid.jsx b/web/src/renderer/features/items/ItemGalleryGrid.jsx
index 1a4ba0b..cdd5c8b 100644
--- a/web/src/renderer/features/items/ItemGalleryGrid.jsx
+++ b/web/src/renderer/features/items/ItemGalleryGrid.jsx
@@ -1,6 +1,14 @@
+import { useEffect, useRef } from 'react';
+
import ItemGalleryCard from './ItemGalleryCard';
+import { observeScrollReveal } from './scroll-reveal';
+import './scroll-reveal.css';
export default function ItemGalleryGrid({ items, bulkMode = false, bulkSelectedIds = new Set(), onSelect }) {
+ const gridRef = useRef(null);
+ const seenRef = useRef(new WeakSet());
+ useEffect(() => observeScrollReveal(gridRef.current, seenRef.current), [items]);
+
if (!items.length) {
return (
@@ -11,7 +19,7 @@ export default function ItemGalleryGrid({ items, bulkMode = false, bulkSelectedI
}
return (
-
+
{items.map((item) => (
element.classList.remove('scroll-reveal-enter'));
+ }
+
+ function configure() {
+ observer?.disconnect();
+ observer = null;
+ clearMotion();
+ if (preference?.matches || typeof IntersectionObserver !== 'function') return;
+ const waiting = new WeakSet();
+ try {
+ const next = new IntersectionObserver(entries => {
+ if (!active || observer !== next || preference?.matches) return;
+ for (const { target, isIntersecting } of entries) {
+ if (!container.contains(target) || seen.has(target)) continue;
+ if (!isIntersecting) {
+ waiting.add(target);
+ continue;
+ }
+ seen.add(target);
+ next.unobserve(target);
+ // The initial visible cards never wait for an animation.
+ if (waiting.has(target)) target.classList.add('scroll-reveal-enter');
+ }
+ }, { threshold: 0.05 });
+ observer = next;
+ container.querySelectorAll('.item-gallery-card').forEach(element => {
+ if (!seen.has(element)) next.observe(element);
+ });
+ } catch {
+ observer?.disconnect();
+ observer = null;
+ }
+ }
+
+ function finish(event) {
+ if (event.target.matches?.('.item-gallery-card')) event.target.classList.remove('scroll-reveal-enter');
+ }
+
+ configure();
+ if (preference?.addEventListener) preference.addEventListener('change', configure);
+ else preference?.addListener?.(configure);
+ container.addEventListener('animationend', finish);
+ container.addEventListener('animationcancel', finish);
+ container.addEventListener('focusin', finish);
+
+ return () => {
+ active = false;
+ observer?.disconnect();
+ if (preference?.removeEventListener) preference.removeEventListener('change', configure);
+ else preference?.removeListener?.(configure);
+ container.removeEventListener('animationend', finish);
+ container.removeEventListener('animationcancel', finish);
+ container.removeEventListener('focusin', finish);
+ clearMotion();
+ };
+}
diff --git a/web/src/renderer/features/layout/AppShell.jsx b/web/src/renderer/features/layout/AppShell.jsx
index 7d5be6a..5c74404 100644
--- a/web/src/renderer/features/layout/AppShell.jsx
+++ b/web/src/renderer/features/layout/AppShell.jsx
@@ -2,6 +2,7 @@ import CatalogWorkspace from '../catalog/CatalogWorkspace';
import ItemsGalleryPage from '../items/ItemsGalleryPage';
import TagManager from '../tags/TagManager';
import Toolbar from './Toolbar';
+import PageBackground from './PageBackground';
const CATALOG_CONTEXT_TITLES = {
category: '分类管理',
@@ -55,6 +56,7 @@ export default function AppShell({
return (
+
{
+ const layer = layerRef.current;
+ const shell = layer?.parentElement;
+ if (!shell || typeof window.requestAnimationFrame !== 'function') return;
+
+ const preference = window.matchMedia?.('(prefers-reduced-motion: reduce)');
+ let stopped = false;
+ let frame = null;
+ let pendingSource = null;
+
+ function documentSource() {
+ return document.scrollingElement || document.documentElement;
+ }
+
+ function defaultSource() {
+ const page = documentSource();
+ if (page.scrollHeight > page.clientHeight) return page;
+ return [...shell.querySelectorAll(SCROLL_SURFACES)].find(surface => surface.scrollHeight > surface.clientHeight) || page;
+ }
+
+ function draw() {
+ frame = null;
+ if (stopped || preference?.matches) return;
+ const source = pendingSource?.isConnected ? pendingSource : defaultSource();
+ pendingSource = null;
+ const range = Math.max(0, source.scrollHeight - source.clientHeight);
+ const progress = range ? Math.min(1, Math.max(0, source.scrollTop / range)) : 0;
+ layer.style.setProperty('--page-parallax-y', `${Math.round(-56 * progress * 100) / 100}px`);
+ }
+
+ function schedule(source) {
+ if (stopped || preference?.matches) return;
+ pendingSource = source;
+ if (frame === null) frame = window.requestAnimationFrame(draw);
+ }
+
+ function onScroll(event) {
+ const target = event.target;
+ if (target === document || target === window) {
+ schedule(documentSource());
+ } else if (target instanceof Element && shell.contains(target) && target.matches(SCROLL_SURFACES)
+ && !target.closest('[role="dialog"], .dialog-backdrop') && target.scrollHeight > target.clientHeight) {
+ schedule(target);
+ }
+ }
+
+ function cancelPending() {
+ if (frame !== null) window.cancelAnimationFrame?.(frame);
+ frame = null;
+ pendingSource = null;
+ }
+
+ function onPreferenceChange() {
+ cancelPending();
+ if (preference?.matches) layer.style.setProperty('--page-parallax-y', '0px');
+ else schedule(defaultSource());
+ }
+
+ function onResize() {
+ schedule(defaultSource());
+ }
+
+ window.addEventListener('scroll', onScroll, { capture: true, passive: true });
+ window.addEventListener('resize', onResize, { passive: true });
+ if (preference?.addEventListener) preference.addEventListener('change', onPreferenceChange);
+ else preference?.addListener?.(onPreferenceChange);
+ onPreferenceChange();
+
+ return () => {
+ stopped = true;
+ cancelPending();
+ window.removeEventListener('scroll', onScroll, true);
+ window.removeEventListener('resize', onResize);
+ if (preference?.removeEventListener) preference.removeEventListener('change', onPreferenceChange);
+ else preference?.removeListener?.(onPreferenceChange);
+ };
+ }, []);
+
+ return ;
+}
diff --git a/web/src/renderer/features/layout/page-motion.css b/web/src/renderer/features/layout/page-motion.css
new file mode 100644
index 0000000..8a9090c
--- /dev/null
+++ b/web/src/renderer/features/layout/page-motion.css
@@ -0,0 +1,25 @@
+.page-background {
+ position: fixed;
+ z-index: -1;
+ inset: -64px;
+ pointer-events: none;
+ background:
+ radial-gradient(ellipse at 8% 18%, rgb(15 118 110 / 11%), transparent 52%),
+ radial-gradient(ellipse at 88% 62%, rgb(47 111 159 / 10%), transparent 54%),
+ radial-gradient(ellipse at 42% 100%, rgb(217 119 6 / 4%), transparent 42%);
+ transform: translate3d(0, var(--page-parallax-y, 0px), 0);
+ will-change: transform;
+}
+
+@media (max-width: 1024px), (pointer: coarse) {
+ .page-background {
+ transform: translate3d(0, calc(var(--page-parallax-y, 0px) * 0.45), 0);
+ }
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .page-background {
+ transform: none;
+ will-change: auto;
+ }
+}
diff --git a/web/tests/renderer/page-background.test.jsx b/web/tests/renderer/page-background.test.jsx
new file mode 100644
index 0000000..449660d
--- /dev/null
+++ b/web/tests/renderer/page-background.test.jsx
@@ -0,0 +1,124 @@
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import PageBackground from '../../src/renderer/features/layout/PageBackground';
+
+let frames, nextFrame, preference, requestFrame;
+
+function dimensions(element, top, height = 1200, viewport = 400) {
+ Object.defineProperties(element, {
+ scrollTop: { configurable: true, value: top },
+ scrollHeight: { configurable: true, value: height },
+ clientHeight: { configurable: true, value: viewport }
+ });
+}
+
+function flushFrame() {
+ const pending = [...frames.values()];
+ frames.clear();
+ pending.forEach(callback => callback(0));
+}
+
+function fixture() {
+ const view = render();
+ return { ...view, layer: view.container.querySelector('.page-background'), grid: view.getByTestId('gallery') };
+}
+
+beforeEach(() => {
+ frames = new Map(); nextFrame = 0;
+ requestFrame = vi.fn(callback => { frames.set(++nextFrame, callback); return nextFrame; });
+ vi.stubGlobal('requestAnimationFrame', requestFrame);
+ vi.stubGlobal('cancelAnimationFrame', vi.fn(id => frames.delete(id)));
+ preference = Object.assign(new EventTarget(), { matches: false, media: '(prefers-reduced-motion: reduce)' });
+ vi.stubGlobal('matchMedia', vi.fn(() => preference));
+ dimensions(document.documentElement, 0, 400, 400);
+});
+
+afterEach(() => { cleanup(); vi.unstubAllGlobals(); });
+
+describe('decorative page parallax', () => {
+ it('is inaccessible decoration and coalesces desktop nested scrolling into one bounded update', () => {
+ const { layer, grid } = fixture();
+ expect(layer).toHaveAttribute('aria-hidden', 'true');
+ flushFrame(); requestFrame.mockClear();
+ dimensions(grid, 200);
+ fireEvent.scroll(grid);
+ dimensions(grid, 600);
+ fireEvent.scroll(grid);
+ expect(requestFrame).toHaveBeenCalledTimes(1);
+ flushFrame();
+ expect(layer.style.getPropertyValue('--page-parallax-y')).toBe('-42px');
+ dimensions(grid, 1200);
+ fireEvent.scroll(grid); flushFrame();
+ expect(layer.style.getPropertyValue('--page-parallax-y')).toBe('-56px');
+ expect(grid).not.toHaveAttribute('style');
+ });
+
+ it('uses document scrolling on mobile without intercepting input', () => {
+ const { layer } = fixture(); flushFrame();
+ dimensions(document.documentElement, 400);
+ const event = new Event('scroll', { cancelable: true });
+ document.dispatchEvent(event); flushFrame();
+ expect(layer.style.getPropertyValue('--page-parallax-y')).toBe('-28px');
+ expect(event.defaultPrevented).toBe(false);
+ });
+
+ it('ignores horizontal-only surfaces, editor dialogs, and other app roots', () => {
+ const { layer, grid, getByTestId } = fixture(); flushFrame();
+ dimensions(grid, 0, 400, 400);
+ fireEvent.scroll(grid);
+ const dialog = getByTestId('dialog-scroll'); dimensions(dialog, 500);
+ fireEvent.scroll(dialog);
+ const outside = document.createElement('div'); outside.className = 'item-gallery-grid';
+ document.body.append(outside); dimensions(outside, 500); fireEvent.scroll(outside); outside.remove();
+ expect(frames.size).toBe(0);
+ expect(layer.style.getPropertyValue('--page-parallax-y')).toBe('0px');
+ });
+
+ it('stops and resets when reduced motion is enabled, then resumes if disabled', () => {
+ const { layer, grid } = fixture(); flushFrame();
+ dimensions(grid, 400); fireEvent.scroll(grid); flushFrame();
+ expect(layer.style.getPropertyValue('--page-parallax-y')).toBe('-28px');
+ preference.matches = true; preference.dispatchEvent(new Event('change'));
+ expect(layer.style.getPropertyValue('--page-parallax-y')).toBe('0px');
+ fireEvent.scroll(grid);
+ expect(frames.size).toBe(0);
+ preference.matches = false; preference.dispatchEvent(new Event('change')); flushFrame();
+ expect(layer.style.getPropertyValue('--page-parallax-y')).toBe('-28px');
+ });
+
+ it('cancels pending work on unmount and ignores a callback already dispatched by the browser', () => {
+ const { layer, grid, unmount } = fixture(); flushFrame();
+ dimensions(grid, 400); fireEvent.scroll(grid);
+ const lateCallback = [...frames.values()][0];
+ unmount();
+ expect(frames.size).toBe(0);
+ lateCallback(0);
+ expect(layer.style.getPropertyValue('--page-parallax-y')).toBe('0px');
+ });
+
+ it('keeps a static background when animation frames are unavailable', () => {
+ vi.stubGlobal('requestAnimationFrame', undefined);
+ const { layer, grid } = fixture();
+ dimensions(grid, 400); fireEvent.scroll(grid);
+ expect(layer).toBeInTheDocument();
+ expect(frames.size).toBe(0);
+ expect(layer.style.getPropertyValue('--page-parallax-y')).toBe('');
+ });
+
+ it('starts static for reduced motion and tolerates browsers without matchMedia', () => {
+ preference.matches = true;
+ const first = fixture();
+ dimensions(first.grid, 400); fireEvent.scroll(first.grid);
+ expect(frames.size).toBe(0);
+ expect(first.layer.style.getPropertyValue('--page-parallax-y')).toBe('0px');
+ first.unmount();
+ vi.stubGlobal('matchMedia', undefined);
+ const second = fixture(); flushFrame();
+ dimensions(second.grid, 400); fireEvent.scroll(second.grid); flushFrame();
+ expect(second.layer.style.getPropertyValue('--page-parallax-y')).toBe('-28px');
+ });
+});
diff --git a/web/tests/renderer/scroll-reveal.test.jsx b/web/tests/renderer/scroll-reveal.test.jsx
new file mode 100644
index 0000000..b5930e9
--- /dev/null
+++ b/web/tests/renderer/scroll-reveal.test.jsx
@@ -0,0 +1,95 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import ItemGalleryGrid from '../../src/renderer/features/items/ItemGalleryGrid';
+
+const items = [{ id: 'one', title: '首屏物品' }, { id: 'two', title: '下方物品' }];
+let observers;
+let preference;
+let preferenceListeners;
+
+beforeEach(() => {
+ observers = [];
+ preferenceListeners = new Set();
+ preference = {
+ matches: false,
+ addEventListener: vi.fn((_, listener) => preferenceListeners.add(listener)),
+ removeEventListener: vi.fn((_, listener) => preferenceListeners.delete(listener))
+ };
+ vi.stubGlobal('matchMedia', vi.fn(() => preference));
+ vi.stubGlobal('IntersectionObserver', class {
+ constructor(callback) {
+ this.notify = entries => act(() => callback(entries));
+ this.observe = vi.fn();
+ this.unobserve = vi.fn();
+ this.disconnect = vi.fn();
+ observers.push(this);
+ }
+ });
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('gallery scroll reveal', () => {
+ it('shows the first screen immediately and reveals later cards only once without blocking clicks', () => {
+ const onSelect = vi.fn();
+ render();
+ expect(observers).toHaveLength(1);
+ const first = screen.getByRole('button', { name: '首屏物品' });
+ const later = screen.getByRole('button', { name: '下方物品' });
+ observers[0].notify([{ target: first, isIntersecting: true }, { target: later, isIntersecting: false }]);
+ expect(first).not.toHaveClass('scroll-reveal-enter');
+ expect(later).toBeVisible();
+ observers[0].notify([{ target: later, isIntersecting: true }]);
+ expect(later).toHaveClass('scroll-reveal-enter');
+ fireEvent.click(later);
+ expect(onSelect).toHaveBeenCalledWith('two');
+ fireEvent.animationEnd(later);
+ expect(later).not.toHaveClass('scroll-reveal-enter');
+ observers[0].notify([{ target: later, isIntersecting: false }, { target: later, isIntersecting: true }]);
+ expect(later).not.toHaveClass('scroll-reveal-enter');
+ });
+
+ it('keeps cards readable when reduced motion is requested or observation is unavailable', () => {
+ preference.matches = true;
+ const view = render();
+ expect(observers).toHaveLength(0);
+ expect(screen.getByRole('button', { name: '下方物品' })).toBeVisible();
+ view.unmount();
+ preference.matches = false;
+ vi.stubGlobal('IntersectionObserver', undefined);
+ render();
+ expect(screen.getByRole('button', { name: '下方物品' })).toBeVisible();
+ });
+
+ it('stops current motion on preference changes and ignores callbacks after unmount', () => {
+ const view = render();
+ expect(observers).toHaveLength(1);
+ const later = screen.getByRole('button', { name: '下方物品' });
+ observers[0].notify([{ target: later, isIntersecting: false }, { target: later, isIntersecting: true }]);
+ expect(later).toHaveClass('scroll-reveal-enter');
+ act(() => {
+ preference.matches = true;
+ preferenceListeners.forEach(listener => listener());
+ });
+ expect(later).not.toHaveClass('scroll-reveal-enter');
+ expect(observers[0].disconnect).toHaveBeenCalled();
+ view.unmount();
+ observers[0].notify([{ target: later, isIntersecting: true }]);
+ expect(later).not.toHaveClass('scroll-reveal-enter');
+ expect(preferenceListeners.size).toBe(0);
+ });
+
+ it('does not replay seen cards when filtering and cancels motion for keyboard focus', () => {
+ const view = render();
+ expect(observers).toHaveLength(1);
+ const later = screen.getByRole('button', { name: '下方物品' });
+ observers[0].notify([{ target: later, isIntersecting: false }, { target: later, isIntersecting: true }]);
+ fireEvent.focusIn(later);
+ expect(later).not.toHaveClass('scroll-reveal-enter');
+ view.rerender();
+ const current = observers.at(-1);
+ current.notify([{ target: later, isIntersecting: false }, { target: later, isIntersecting: true }]);
+ expect(later).not.toHaveClass('scroll-reveal-enter');
+ });
+});