Vue script setupの書き方｜defineProps等マクロ早見表

script setup とは、Vue の単一ファイルコンポーネント（.vue ファイル、以下 SFC）で Composition API を短く書くための構文です。 script タグに setup 属性を付けるだけで、トップレベルに書いた変数・関数・import がそのままテンプレートから使えるようになり、props やイベントは defineProps などの「コンパイラマクロ」で宣言します。

この記事では、7つのマクロ（defineProps / defineEmits / defineModel / defineExpose / defineSlots / defineOptions / withDefaults）を「用途・導入バージョン・型の書き方・最小コード」の早見表にまとめました。掲載したコードは Vue 3.5.43 でコンパイルして動かし、出力とエラー文をそのまま載せています。Vue 3.5 の props 分割代入、ジェネリックコンポーネント、v-model の複数指定と修飾子、Options API との対応表まで1ページで確認できます。

script setup マクロの早見表

マクロは import せずにそのまま書けます。コンパイル時に通常のコンポーネント定義へ変換されるため、実行時には関数として残りません。

3.3〜・3.4〜・3.5〜の表記は、今回公式の API リファレンス（SFC script setup のページ）を開いて確認しました。3.2〜の行は script setup そのものが正式機能になった版で、一般に知られた仕様として記載しています。

この記事の検証環境

SFC は @vue/compiler-sfc の compileScript でコンパイルし、Node.js 上の jsdom にマウントして動作を確かめました。ブラウザと Vite の開発サーバーでの表示は未実行です。型エラーは vue-tsc --noEmit の出力です。

script setup の基本形をコピペで確認する

まずは props・イベント・v-model を1つずつ持つカウンターです。lang="ts" を付けると型引数で宣言できます。

<!-- Counter.vue -->
<script setup lang="ts">
import { computed } from 'vue'

const props = defineProps<{
  label: string
  step?: number
}>()

const emit = defineEmits<{
  change: [value: number]
}>()

const count = defineModel<number>({ default: 0 })
const doubled = computed(() => count.value * 2)

function add() {
  count.value += props.step ?? 1
  emit('change', count.value)
}
</script>

<template>
  <button @click="add">{{ label }}: {{ count }} (x2 = {{ doubled }})</button>
</template>

親から label="在庫"、:step="3"、v-model に 5 を渡してボタンを1回クリックした結果です。

在庫: 5 (x2 = 10)
change イベント: 5
在庫: 8 (x2 = 16) / 親の値 = 8

change イベントの時点で 5 と表示されているのは、defineModel の値は代入した直後ではなく、親が値を更新して props が流れ直したあとに変わるためです。更新後の値をすぐ使いたい場合は、const next = count.value + step のように自分で計算した値を代入と emit の両方に使うと意図どおりになります。

script setup で押さえる4つのルール

Options API と script setup の対応表

Options API で書かれたコンポーネントを読み替えるときの対応です。

script setup には this がありません。そのぶん、値の出どころが import と変数宣言だけで追えるようになります。

defineProps：props を宣言する3つの書き方

型ベースで書いても、コンパイラが実行時の props 定義を生成します。そのため、必須の props を渡さなかったり型が合わなかったりすると、開発時は次の警告が出ます（label を渡さず、step に文字列 "3" を渡した実行結果）。

[Vue warn]: Missing required prop: "label" 
  at <Counter step="3" ref="VTU_COMPONENT" > 
  at <VTUROOT>
[Vue warn]: Invalid prop: type check failed for prop "step". Expected Number with value 3, got String with value "3". 
  at <Counter step="3" ref="VTU_COMPONENT" > 
  at <VTUROOT>

型引数と実行時宣言を併用するとコンパイルエラーになる

型引数とオブジェクトの両方を渡すと、コンパイルの段階で止まります。

<script setup lang="ts">
const props = defineProps<{ label: string }>({
  label: { type: String, required: true },
})
</script>

[@vue/compiler-sfc] defineProps() cannot accept both type and non-type arguments at the same time. Use one or the other.

ErrBoth.vue
1  |  <script setup lang="ts">
2  |  const props = defineProps<{ label: string }>({
   |                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3  |    label: { type: String, required: true },
   |  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4  |  })
   |  ^^

defineEmits でも同じです。

[@vue/compiler-sfc] defineEmits() cannot accept both type and non-type arguments at the same time. Use one or the other.

直し方は「どちらか一方に寄せる」です。TypeScript なら型引数だけにして、既定値は次の節の方法で付けます。また、defineProps を1つのコンポーネントで2回呼ぶと duplicate defineProps() call というエラーになるので、props は1つの型にまとめます。

既定値の付け方：withDefaults と props 分割代入（3.5）

型ベースの宣言には default を書く場所がないため、既定値は別の方法で指定します。

withDefaults（3.4 以前からある書き方）

<!-- WithDefaults.vue -->
<script setup lang="ts">
interface Props {
  title?: string
  tags?: string[]
}
const props = withDefaults(defineProps<Props>(), {
  title: '無題',
  tags: () => ['未分類'],
})
</script>

<template>
  <p>{{ props.title }} / {{ props.tags.join(',') }}</p>
</template>

props なしでマウントした場合と、両方渡した場合の結果です。

無題 / 未分類
議事録 / 会議

配列やオブジェクトの既定値は、インスタンス間で同じ参照を共有しないよう関数で返します。

props 分割代入と既定値（Vue 3.5〜）

Vue 3.5 からは、defineProps の戻り値を分割代入した変数がリアクティブなまま使えます。既定値は JavaScript の分割代入の構文で書けます。

<!-- Destructure.vue -->
<script setup lang="ts">
import { watch, watchEffect } from 'vue'

const { count = 0, label = '件数' } = defineProps<{
  count?: number
  label?: string
}>()

watchEffect(() => console.log(`[watchEffect] ${label} = ${count}`))
watch(() => count, (v, old) => console.log(`[watch getter] ${old} -> ${v}`))
</script>

<template>
  <p>{{ label }}: {{ count }}</p>
</template>

props なしでマウントし、count を 3 に、続けて label を「在庫数」に変えたときの出力です。

[watchEffect] 件数 = 0
件数: 0
[watchEffect] 件数 = 3
[watch getter] 0 -> 3
件数: 3
[watchEffect] 在庫数 = 3
在庫数: 3

変数なのに追従できるのは、コンパイラが count を __props.count に書き換えているからです。コンパイル後のコードを見ると確認できます。

watchEffect(() => console.log(`[watchEffect] ${__props.label} = ${__props.count}`));
watch(() => __props.count, (v, old) => console.log(`[watch getter] ${old} -> ${v}`));

分割代入した変数を watch にそのまま渡すとエラーになる

書き換えの結果、watch(count, ...) は「数値そのもの」を渡すことになるため、コンパイラが先に知らせてくれます。

[@vue/compiler-sfc] "count" is a destructured prop and should not be passed directly to watch(). Pass a getter () => count instead.

ErrWatch.vue
2  |  import { watch } from 'vue'
3  |  const { count = 0 } = defineProps<{ count?: number }>()
4  |  watch(count, (v) => console.log(v))
   |        ^^^^^

直し方は watch(() => count, ...) とゲッター関数で包むことです。自作のコンポーザブルに渡すときも同じで、useSomething(() => count) の形にします。

分割代入した props へ代入しようとした場合も、コンパイル時に止まります。

[@vue/compiler-sfc] Cannot assign to destructured props as they are readonly.

ErrAssign.vue
2  |  const { count = 0 } = defineProps<{ count?: number }>()
3  |  function reset() {
4  |    count = 0
   |    ^^^^^

値を変えたいときは、親へイベントを送るか、次に紹介する defineModel を使います。

なお、分割代入と withDefaults を同時に書くと、次の警告が出て分割代入のリアクティブな扱いが無効になります。どちらか一方を選びます。

[@vue/compiler-sfc] withDefaults() is unnecessary when using destructure with defineProps().
Reactive destructure will be disabled when using withDefaults().
Prefer using destructure default values, e.g. const { foo = 1 } = defineProps(...). 

分割代入でリアクティブ性が消える例と直し方

リアクティブなまま使えるのは、defineProps() の戻り値をその場で分割代入した場合だけです。いったん props に受けてから分割代入すると、ふつうの JavaScript の分割代入になり、その時点の値のコピーになります。

<!-- LostReactivity.vue -->
<script setup lang="ts">
import { computed, toRefs } from 'vue'

const props = defineProps<{ count: number }>()

const { count } = props                    // (A) ふつうの分割代入：その時点の値のコピー
const doubledA = computed(() => count * 2)

const { count: countRef } = toRefs(props)  // (B) toRefs：ref として取り出す
const doubledB = computed(() => countRef.value * 2)

const doubledC = computed(() => props.count * 2) // (C) props.count を直接読む
</script>

<template>
  <p>A={{ doubledA }} B={{ doubledB }} C={{ doubledC }}</p>
</template>

count を 1 でマウントし、5 に変えたときの結果です。

count=1: A=2 B=2 C=2
count=5: A=2 B=10 C=10

A だけが 2 のまま変わりません。書き方ごとの違いをまとめます。

defineEmits：イベントを型つきで宣言する

// 3.3〜の短い書き方（名前つきタプル）
const emit = defineEmits<{
  change: [value: number]
  remove: []                          // 引数なし
  rename: [id: number, name: string]  // 引数2つ
}>()

// 関数の呼び出しシグネチャで書く形（3.2 から使える）
const emit2 = defineEmits<{
  (e: 'change', value: number): void
}>()

// 実行時宣言（JavaScript でも使える）
const emit3 = defineEmits(['change', 'remove'])

型で宣言しておくと、親が受け取るハンドラの引数の型まで検査されます。型エラーの例は後半の「型エラーを vue-tsc で確認する」に載せました。

defineModel：v-model を1行で受け取る（3.4〜）

defineModel は、props の modelValue とイベント update:modelValue をまとめて宣言し、ref として返します。model.value に代入すると親の値が更新されます。

v-model を複数指定し、修飾子も受け取る

<!-- RangeField.vue -->
<script setup lang="ts">
// v-model:min / v-model:max の2つと、v-model:keyword.trim.upper の修飾子
const min = defineModel<number>('min', { required: true })
const max = defineModel<number>('max', { required: true })

const [keyword, keywordModifiers] = defineModel<string, 'trim' | 'upper'>('keyword', {
  default: '',
  set(value) {
    let v = value
    if (keywordModifiers.trim) v = v.trim()
    if (keywordModifiers.upper) v = v.toUpperCase()
    return v
  },
})
</script>

<template>
  <input class="min" type="number" v-model.number="min" />
  <input class="max" type="number" v-model.number="max" />
  <input class="kw" v-model="keyword" />
</template>

<!-- RangeParent.vue -->
<script setup lang="ts">
import { ref } from 'vue'
import RangeField from './RangeField.vue'

const min = ref(1)
const max = ref(10)
const keyword = ref('')
</script>

<template>
  <RangeField v-model:min="min" v-model:max="max" v-model:keyword.trim.upper="keyword" />
  <p class="out">{{ min }}〜{{ max }} / [{{ keyword }}]</p>
</template>

入力欄に 3、8、前後に空白を付けた「 vue 」を入れる前と後の、親の表示です。

1〜10 / []
3〜8 / [VUE]

upper は Vue に組み込みの修飾子ではなく、この例で独自に決めた名前です。独自の修飾子は defineModel の2つ目の戻り値で有無を調べ、set オプションで値を加工します（読むときに加工する get もあります）。

defineModel に default を付け、親が v-model を指定しなかった場合、子は既定値、親は undefined という食い違いが起きることがあります。親でも同じ初期値を持つか、required: true にしておくと状態がそろいます。

defineExpose・defineSlots・defineOptions を1つの例で確認する

ダイアログのコンポーネントで3つをまとめて使います。

<!-- Dialog.vue -->
<script setup lang="ts">
import { ref } from 'vue'

defineOptions({ name: 'AppDialog', inheritAttrs: false })

defineSlots<{
  default(props: { close: () => void }): any
  footer?(props: { opened: boolean }): any
}>()

const opened = ref(false)
const secret = ref('外からは見えない値')
function open() { opened.value = true }
function close() { opened.value = false }

defineExpose({ open, close, opened })
</script>

<template>
  <section v-if="opened" class="dialog" v-bind="$attrs">
    <slot :close="close" />
    <footer><slot name="footer" :opened="opened">既定のフッター</slot></footer>
  </section>
</template>

<!-- DialogParent.vue -->
<script setup lang="ts">
import { useTemplateRef } from 'vue'
import Dialog from './Dialog.vue'

const dialog = useTemplateRef('dialog')
defineExpose({ dialog })
</script>

<template>
  <button class="opener" @click="dialog?.open()">開く</button>
  <Dialog ref="dialog" data-test="d1">
    <template #default="{ close }">
      <button class="closer" @click="close">閉じる</button>
    </template>
  </Dialog>
</template>

「開く」を押し、公開された内容を調べ、「閉じる」を押したときの実行結果です。

name: AppDialog / inheritAttrs: false
開く前: "<button class=\"opener\">開く</button>\n<!--v-if-->"
開いた後: <section class="dialog" data-test="d1"><button class="closer">閉じる</button> <footer>既定のフッター</footer> </section>
公開されたキー: [ 'open', 'close', 'opened' ] / secret: undefined / opened: true
閉じた後 section: false

defineOptions には props・emits・expose・slots は書けません。それぞれ専用のマクロで宣言します。

ジェネリックコンポーネント：generic 属性の書き方（3.3〜）

script タグの generic 属性に型引数を書くと、渡された props から型が推論されるコンポーネントを作れます。

<!-- SelectList.vue -->
<script setup lang="ts" generic="T extends { id: number }">
const { items } = defineProps<{ items: T[] }>()
const selected = defineModel<T | null>({ default: null })
const emit = defineEmits<{ pick: [item: T] }>()

function pick(item: T) {
  selected.value = item
  emit('pick', item)
}
</script>

<template>
  <ul>
    <li v-for="item in items" :key="item.id" :class="{ on: selected?.id === item.id }" @click="pick(item)">
      <slot :item="item">{{ item.id }}</slot>
    </li>
  </ul>
</template>

items に [{ id: 1, name: '椅子' }, { id: 2, name: '机' }] を渡し、スロットで item.name を表示して2件目をクリックした結果です。

<ul> <li class="">椅子</li> <li class="on">机</li> </ul>
pick: [[{"id":2,"name":"机"}]] update: [[{"id":2,"name":"机"}]]

generic は lang="ts" と組み合わせて使います。props・emit・v-model・スロットのすべてで同じ T が共有されるので、親側では pick イベントの引数やスロットの item に、渡した配列の要素の型がそのまま付きます。

型エラーを vue-tsc で確認する

テンプレートの型検査は vue-tsc で行います。次の親コンポーネントには、わざと合わない指定を4つ入れてあります。

<!-- TypeErr.vue -->
<script setup lang="ts">
import { ref } from 'vue'
import Counter from './Counter.vue'
import SelectList from './SelectList.vue'

const n = ref(0)
const names = ['椅子', '机']
function onChange(value: string) {}
</script>

<template>
  <Counter v-model="n" />
  <Counter label="在庫" :step="'3'" v-model="n" />
  <Counter label="在庫" v-model="n" @change="onChange" />
  <SelectList :items="names" />
</template>

npx vue-tsc --noEmit -p tsconfig.json

TypeErr.vue(12,4): error TS2345: Argument of type '{ modelValue: number; }' is not assignable to parameter of type '{ readonly label: string; readonly step?: number | undefined; readonly modelValue?: number | undefined; readonly onChange?: ((value: number) => any) | undefined; readonly "onUpdate:modelValue"?: ((value: number) => any) | undefined; } & VNodeProps & AllowedComponentProps & ComponentCustomProps & Record<...>'.
  Property 'label' is missing in type '{ modelValue: number; }' but required in type '{ readonly label: string; readonly step?: number | undefined; readonly modelValue?: number | undefined; readonly onChange?: ((value: number) => any) | undefined; readonly "onUpdate:modelValue"?: ((value: number) => any) | undefined; }'.
TypeErr.vue(13,24): error TS2322: Type 'string' is not assignable to type 'number'.
TypeErr.vue(14,36): error TS2322: Type '(value: string) => void' is not assignable to type '(value: number) => any'.
  Types of parameters 'value' and 'value' are incompatible.
    Type 'number' is not assignable to type 'string'.
TypeErr.vue(15,16): error TS2322: Type 'string[]' is not assignable to type '{ id: number; }[]'.
  Type 'string' is not assignable to type '{ id: number; }'.

1行目のエラー文から、defineModel と defineEmits が props 側に modelValue・onUpdate:modelValue・onChange として現れていることも読み取れます。マクロが何を生成しているかを知る手がかりになります。

エラー文から直し方を引く逆引き表

この記事で再現したメッセージの一覧です。

よくある質問

Q. script setup と通常の script は同じファイルに書けますか？ A. 書けます。通常の script ブロックはモジュールの読み込み時に1回だけ実行されるので、名前つき export や、1回だけ行いたい初期化を置く場所として使えます。2つのブロックの lang はそろえます。name や inheritAttrs を指定したいだけなら、defineOptions で script setup の中に書けます。

Q. props の既定値は withDefaults と分割代入のどちらで書けばよいですか？ A. Vue 3.5 以上なら分割代入の既定値が短く書けます。3.4 以前にも対応させるコードや、props.xxx の形で統一したいコードでは withDefaults が合います。両方を同時に書くと警告が出るので、コンポーネントごとにどちらかへ寄せます。

Q. defineModel と、defineProps＋defineEmits の組み合わせはどう使い分けますか？ A. 「親の値を子から書き換える」用途は defineModel が向いています。modelValue と update:modelValue の宣言が1行にまとまります。子からは通知だけを送り、値をどうするかは親に任せたい場合は、defineProps と defineEmits の組み合わせがわかりやすくなります。

Q. defineProps の中でローカル変数を参照できますか？ A. マクロの引数は setup の外へ移されてコンパイルされるため、setup 内で宣言した変数に依存する書き方はコンパイルエラーの対象になります（公式の API リファレンスに記載。import した値は参照できます）。今回の確認では、const fallback = 10 のようなリテラルの定数はエラーにならずコンパイルできました。既定値に使う値は、import するかリテラルで書くと確実です。

まとめ

• script setup は、トップレベルの変数・関数・import がそのままテンプレートで使える構文。props やイベントは import 不要のマクロで宣言する
• props は defineProps の型引数で宣言。型引数と実行時宣言の併用はコンパイルエラーになるので、どちらか一方にする
• 既定値は、Vue 3.5 以上なら分割代入（const { count = 0 } = defineProps()）、それ以前は withDefaults
• 分割代入した props を watch やコンポーザブルに渡すときは () => count。const { count } = props はその時点のコピーになり追従しない
• v-model は defineModel。名前を付ければ複数並べられ、修飾子は2つ目の戻り値と set で扱う
• 親に公開するのは defineExpose に渡したものだけ。スロットの型は defineSlots、name と inheritAttrs は defineOptions
• generic 属性で、props・emit・スロットに同じ型引数を通せる。型の検査は vue-tsc --noEmit で行う

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。