[Nuxt3] 레이아웃 프레임워크

정리

레이아웃	유형	사용 방법 예제
기본 레이아웃	모든 페이지에 자동 적용	layouts/default.vue
네임드 레이아웃	특정 페이지에 적용	definePageMeta({ layout: "custom" })
동적 레이아웃 변경	런타임에 따라 변경	<NuxtLayout :name="layout">
setPageLayout 활용	프로그래밍 방식으로 변경	setPageLayout('custom')

레이아웃 사용 시 주의할 점

1. 레이아웃은 반드시 layouts/ 폴더에 위치해야 합니다.
2. 레이아웃 파일명은 .vue 확장자를 사용해야 하며, Nuxt에서 자동으로 인식합니다.
3. 동적 레이아웃 변경 시 definePageMeta()보다 :layout 바인딩을 활용하면 더 유연한 설정이 가능합니다.
4. 레이아웃 내에서 NuxtPage를 직접 사용하면 무한 루프가 발생할 수 있으므로, 레이아웃에는 <slot />을 사용해야 합니다.
5. 다른 컴포넌트와 달리 레이아웃에는 Nuxt가 레이아웃 변경 간에 전환을 적용할 수 있도록 단일 루트 요소가 있어야 하며 이 루트 요소는 <slot />일 수 없습니다.
6. 애플리케이션에 단일 레이아웃만 있는 경우, app.vue를 사용하는 것이 좋습니다.

 

---

기본 레이아웃(Default Layout)

기본 레이아웃은 layouts/default.vue 파일을 생성하여 정의합니다. 모든 페이지는 명시적으로 레이아웃을 지정하지 않으면 자동으로 default.vue를 사용합니다.

기본 레이아웃 설정하기

<!-- layouts/default.vue -->
<template>
  <div>
    <header>공통 헤더</header>
    <slot />
    <footer>공통 푸터</footer>
  </div>
</template>

• <slot /> 태그는 각 페이지의 콘텐츠가 렌더링될 자리입니다.
• 모든 페이지에 이 레이아웃이 기본 적용됩니다.

기본 레이아웃이 적용된 페이지 예제

<!-- pages/index.vue -->
<template>
  <div>홈 페이지</div>
</template>

이 페이지는 자동으로 layouts/default.vue의 구조를 따르게 됩니다.

네임드 레이아웃(Named Layout)

기본 레이아웃이 아닌 특정 페이지에 맞는 맞춤형 레이아웃을 적용하려면 네임드 레이아웃을 사용할 수 있습니다.

❗ 레이아웃 이름은 kebab-case로 정규화되므로 someLayout은 some-layout이 됩니다.

새로운 레이아웃 정의하기

<!-- layouts/custom.vue -->
<template>
  <div>
    <nav>맞춤 네비게이션</nav>
    <slot />
  </div>
</template>

• layouts/ 폴더에 custom.vue를 생성하면 기본 레이아웃과는 다른 구조를 사용할 수 있습니다.

페이지에서 네임드 레이아웃 적용하기

<!-- pages/profile.vue -->
<script setup>
definePageMeta({ layout: "custom" });
</script>

<template>
  <div>프로필 페이지</div>
</template>

• 이 페이지는 layouts/custom.vue를 사용하게 됩니다.
  
  

동적 레이아웃 변경(Dynamic Layout Switching)

페이지에 따라 동적으로 레이아웃을 변경해야 하는 경우 definePageMeta()를 사용할 수도 있지만, 컴포넌트 내부에서 동적으로 설정할 수도 있습니다.

동적으로 레이아웃 변경하기

<!-- pages/dynamic.vue -->
<script setup>
import { ref } from "vue";
const layout = ref("default");
</script>

<template>
  <select v-model="layout">
    <option value="default">기본 레이아웃</option>
    <option value="custom">커스텀 레이아웃</option>
  </select>
  <NuxtPage :layout="layout" />
</template>

• layout 변수를 사용하여 사용자가 선택한 레이아웃으로 변경할 수 있습니다.
• <NuxtPage :layout="layout" />를 사용하면 런타임에 동적으로 변경이 가능합니다.

setPageLayout을 활용한 레이아웃 변경

Nuxt 3에서는 setPageLayout을 활용하여 프로그래매틱하게 레이아웃을 변경할 수 있습니다.

<script setup>
import type { LayoutKey } from '#build/types/layouts'
import { setPageLayout } from '#app'

const changePageLayout = (layout: LayoutKey) => {
  setPageLayout(layout)
}
</script>

<template>
  <button @click="changePageLayout('custom')">커스텀 레이아웃 적용</button>
  <button @click="changePageLayout('default')">기본 레이아웃 적용</button>
</template>

• setPageLayout(layout)을 호출하면 현재 페이지의 레이아웃이 변경됩니다.
• LayoutKey 타입을 사용하여 안전한 타입 체크를 수행할 수 있습니다.

URL에 따라 레이아웃 변경하기

URL 파라미터나 특정 조건에 따라 레이아웃을 변경할 수도 있습니다.

<!-- pages/special.vue -->
<script setup>
import { useRoute } from 'vue-router';
const route = useRoute();

const layout = route.query.layout === "custom" ? "custom" : "default";
</script>

<template>
  <NuxtLayout :name="layout">
    <p>이 페이지는 URL 쿼리 파라미터에 따라 레이아웃이 변경됩니다.</p>
  </NuxtLayout>
</template>

• ?layout=custom을 추가하면 custom.vue 레이아웃이 적용됩니다.
• 파라미터를 제거하면 기본 레이아웃(default.vue)을 사용합니다.