React
import { StickySidebar, useStickySidebar } from 'dynamic-sticky-sidebar/react';
يتطلب React 16.8 أو أحدث. المدخل معلَّم بـ "use client"، لذا يعمل مع App Router في Next.js كما هو.
المكوّن <StickySidebar>
يعرض عنصر <aside> (غيّره عبر as) ويربط به سلوك الشريط الجانبي:
import { StickySidebar } from 'dynamic-sticky-sidebar/react';
export function Layout({ children }: { children: React.ReactNode }) {
return (
<div className="layout">
<StickySidebar header=".site-header" gap={16} media="(min-width: 768px)" className="sidebar">
<Filters />
</StickySidebar>
<main>{children}</main>
</div>
);
}
- يقبل كل خيار بوصفه خاصية (prop).
- تحدد
asالعنصر المعروض، وقيمتها الافتراضية'aside'. - كل خاصية أخرى (
classNameوidوaria-*ومعالجات الأحداث…) تُمرَّر إلى العنصر. - يُمرَّر
refإلى عنصر DOM.
الخطاف useStickySidebar
يُعيد callback ref تضعه على عنصرك الخاص:
import { useRef } from 'react';
import { useStickySidebar } from 'dynamic-sticky-sidebar/react';
export function Page() {
const headerRef = useRef<HTMLElement>(null);
const sidebarRef = useStickySidebar({
header: headerRef,
gap: 16,
media: '(min-width: 768px)',
});
return (
<>
<header ref={headerRef} className="site-header">…</header>
<div className="layout">
<nav ref={sidebarRef}>…</nav>
<main>…</main>
</div>
</>
);
}
تُنشأ النسخة حين يُركَّب العنصر (mount) وتُدمَّر حين يُزال (unmount).
المراجع (refs) بوصفها خيارات
يقبل header وscroller كائن RefObject إضافةً إلى قيم العنصر أو المحدِّد المعتادة. ويُقرأ المرجع حين تُطبَّق الخيارات.
الخيارات التفاعلية
تُطبَّق التغييرات على header وscroller وmedia وgap وعلى offsetTop / offsetBottom الرقمية عند إعادة العرض (re-render). يُفضَّل استخدام أرقام عادية للإزاحات المستمدة من الحالة:
const [bannerOpen, setBannerOpen] = useState(true);
<StickySidebar header=".site-header" offsetTop={bannerOpen ? 48 : 0}>
الخيارات التي هي دوال (offsetTop وoffsetBottom وsubscribe) تُقرأ دائمًا من أحدث عرض، لذا لا تعيد الدوال السهمية المضمّنة تشغيل النسخة أبدًا. وتُقرأ دالة الجلب عند كل إعادة حساب (تمرير، تغيّر حجم، تغيّر الترويسة). تغيير الحالة التي تعتمد عليها لا يطلق إعادة حساب بحد ذاته، لذا استخدم رقمًا أو subscribe حين يهمك ذلك.
ترويسات تتحكم فيها الحالة
إذا كانت إزاحة الترويسة موجودة في مخزن حالة (store)، فاربطه عبر subscribe:
<StickySidebar
header=".site-header"
subscribe={(update) => useHeaderStore.subscribe(update)}
>
تتلقى subscribe دالة التحديث ويجب أن تُعيد دالة لإلغاء الاشتراك. وهي تُقرأ دائمًا من أحدث عرض، لذا لا تعيد الدالة المضمّنة تشغيل النسخة عند كل عرض.
الأنواع
import type {
StickySidebarProps,
UseStickySidebarOptions,
StickySidebarOptions,
HeaderInput,
Px,
} from 'dynamic-sticky-sidebar/react';