template

تاریخ آخرین به‌روزرسانی: ۵ مارس ۲۰۲۶

فایل template.js مشابه layout است، با این تفاوت که یک صفحه یا layout را می‌پوشاند. برخلاف layoutها که در مسیرهای مختلف پایدار مانده و state را حفظ می‌کنند، templateها دارای یک کلید منحصر‌به‌فرد هستند، به این معنی که کامپوننت‌های کلاینت فرزند در هنگام ناوبری، state خود را بازنشانی می‌کنند.

این ویژگی در موارد زیر مفید است:

• همگام‌سازی مجدد useEffect در هنگام ناوبری

• بازنشانی state کامپوننت‌های کلاینت فرزند در هنگام ناوبری (مثلاً یک فیلد ورودی)

• تغییر رفتار پیش‌فرض فریم‌ورک (مثلاً مرزهای Suspense داخل layoutها فقط در بار اول fallback نشان می‌دهند، در حالی که templateها در هر ناوبری آن را نشان می‌دهند)

قرارداد

یک template را می‌توان با خروجی گرفتن یک کامپوننت React پیش‌فرض از فایل template.js تعریف کرد. کامپوننت باید prop children را بپذیرد.

فایل ویژه template.js

// app/template.tsx
export default function Template({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>
}

از نظر تودرتو بودن، template.js بین یک layout و فرزندان آن رندر می‌شود. در اینجا یک خروجی ساده شده آورده شده است:

خروجی

<Layout>
  {/* توجه داشته باشید که template یک کلید منحصر‌به‌فرد دریافت می‌کند */}
  <Template key={routeParam}>{children}</Template>
</Layout>

در سلسله‌مراتب کامپوننت‌ها، template.js بین layout.js و error.js رندر می‌شود. این فایل error.js، loading.js، not-found.js و page.js را می‌پوشاند، اما layout.js را در همان سگمنت نمی‌پوشاند.

Props

children (اجباری)

Template یک prop به نام children می‌پذیرد.

خروجی

<Layout>
  {/* توجه داشته باشید که template به‌طور خودکار یک کلید منحصر‌به‌فرد دریافت می‌کند */}
  <Template key={routeParam}>{children}</Template>
</Layout>

رفتار

• کامپوننت‌های سرور: به‌طور پیش‌فرض، templateها کامپوننت‌های سرور هستند.

• ناوبری: templateها یک کلید منحصر‌به‌فرد برای سطح سگمنت خود دریافت می‌کنند. زمانی که آن سگمنت (شامل پارامترهای داینامیک آن) تغییر کند، دوباره سوار (mount) می‌شوند. ناوبری در سگمنت‌های عمیق‌تر باعث سوار شدن مجدد templateهای سطح بالاتر نمی‌شود. پارامترهای جستجو (Search params) باعث سوار شدن مجدد نمی‌شوند.

• بازنشانی state: هر کامپوننت کلاینت داخل template، state خود را در هنگام ناوبری بازنشانی می‌کند.

• اجرای مجدد Effect: افکت‌هایی مانند useEffect با سوار شدن مجدد کامپوننت، دوباره همگام‌سازی می‌شوند.

• بازنشانی DOM: عناصر DOM داخل template به‌طور کامل بازآفرینی می‌شوند.

رفتار templateها در هنگام ناوبری و سوار شدن مجدد

این بخش نحوه رفتار templateها را در هنگام ناوبری نشان می‌دهد. به‌طور گام‌به‌گام نشان می‌دهد که کدام templateها در هر تغییر مسیر دوباره سوار می‌شوند و دلیل آن.

با استفاده از این ساختار پروژه:

app
├── about
│   ├── page.tsx
├── blog
│   ├── [slug]
│   │   └── page.tsx
│   ├── page.tsx
│   └── template.tsx
├── layout.tsx
├── page.tsx
└── template.tsx

شروع از مسیر /، درخت React تقریباً به این شکل خواهد بود:

توجه: مقادیر کلید نشان داده شده در مثال‌ها فقط برای توضیح هستند و مقادیر در برنامه شما ممکن است متفاوت باشد.

خروجی

<RootLayout>
  {/* app/template.tsx */}
  <Template key="/">
    <Page />
  </Template>
</RootLayout>

ناوبری به /about (سگمنت اول تغییر می‌کند)، کلید template ریشه تغییر کرده و دوباره سوار می‌شود:

خروجی

<RootLayout>
  {/* app/template.tsx */}
  <Template key="/about">
    <AboutPage />
  </Template>
</RootLayout>

ناوبری به /blog (سگمنت اول تغییر می‌کند)، کلید template ریشه تغییر کرده و دوباره سوار می‌شود و template سطح blog نیز سوار می‌شود:

خروجی

<RootLayout>
  {/* app/template.tsx (ریشه) */}
  <Template key="/blog">
    {/* app/blog/template.tsx */}
    <Template key="/blog">
      <BlogIndexPage />
    </Template>
  </Template>
</RootLayout>

ناوبری در همان سگمنت اول به /blog/first-post (سگمنت فرزند تغییر می‌کند)، کلید template ریشه تغییر نمی‌کند، اما کلید template سطح blog تغییر کرده و دوباره سوار می‌شود:

خروجی

<RootLayout>
  {/* app/template.tsx (ریشه) */}
  <Template key="/blog">
    {/* app/blog/template.tsx */}
    {/* دوباره سوار می‌شود زیرا سگمنت فرزند در این سطح تغییر کرده است */}
    <Template key="/blog/first-post">
      <BlogPostPage slug="first-post" />
    </Template>
  </Template>
</RootLayout>

ناوبری به /blog/second-post (همان سگمنت اول، سگمنت فرزند متفاوت)، کلید template ریشه تغییر نمی‌کند، اما کلید template سطح blog تغییر کرده و دوباره سوار می‌شود:

خروجی

<RootLayout>
  {/* app/template.tsx (ریشه) */}
  <Template key="/blog">
    {/* app/blog/template.tsx */}
    {/* به دلیل تغییر سگمنت فرزند، دوباره سوار می‌شود */}
    <Template key="/blog/second-post">
      <BlogPostPage slug="second-post" />
    </Template>
  </Template>
</RootLayout>