コンポーネントのイベント ​

このページは、すでにコンポーネントの基礎を読んでいることを前提にしています。初めてコンポーネントに触れる方は、まずそちらをお読みください。

イベントの発行と購読 ​

コンポーネントは、組み込みの $emit メソッドを使用して、テンプレート式（例: v-on ハンドラー内）で直接カスタムイベントを発行できます:

<!-- MyComponent -->
<button @click="$emit('someEvent')">click me</button>

export default {
  methods: {
    submit() {
      this.$emit('someEvent')
    }
  }
}

そして、親コンポーネントは v-on を使ってイベントを購読できます:

<MyComponent @some-event="callback" />

.once 修飾子は、コンポーネントのイベントリスナーでもサポートされています:

<MyComponent @some-event.once="callback" />

コンポーネントやプロパティと同様に、イベント名も自動的な大文字・小文字の変換を提供します。キャメルケースのイベントを発行しましたが、親ではケバブケースのリスナーを使用して購読できることに注意してください。プロパティ名での大文字・小文字の使い分けと同様に、テンプレートではケバブケースのイベントリスナーを使用することをお勧めします。

イベントの引数 ​

イベントで特定の値を発行すると便利な場合があります。例えば、 <BlogPost> コンポーネントに、テキストをどれだけ拡大するかを担当させたい場合があります。そのような場合、$emit に追加の引数を渡して値を提供できます:

<button @click="$emit('increaseBy', 1)">
  Increase by 1
</button>

次に、親でイベントを購読する際に、リスナーとしてインラインのアロー関数を使用することで、イベントの引数にアクセスできます:

<MyButton @increase-by="(n) => count += n" />

または、イベントハンドラーがメソッドの場合は:

<MyButton @increase-by="increaseCount" />

その値はそのメソッドの最初のパラメーターとして渡されます:

methods: {
  increaseCount(n) {
    this.count += n
  }
}

function increaseCount(n) {
  count.value += n
}

発行するイベントの宣言 ​

defineEmits() マクロemits オプションを使用して、コンポーネントが発行するイベントを明示的に宣言できます:

<script setup>
defineEmits(['inFocus', 'submit'])
</script>

<script setup>
const emit = defineEmits(['inFocus', 'submit'])

function buttonClick() {
  emit('submit')
}
</script>

export default {
  emits: ['inFocus', 'submit'],
  setup(props, ctx) {
    ctx.emit('submit')
  }
}

export default {
  emits: ['inFocus', 'submit'],
  setup(props, { emit }) {
    emit('submit')
  }
}

export default {
  emits: ['inFocus', 'submit']
}

emits オプションはオブジェクト構文もサポートしており、発行されたイベントのペイロードのランタイムバリデーションを実行できます:

<script setup>
const emit = defineEmits({
  submit(payload) {
    // バリデーションの合格/不合格を示す
    // `true` または `false` を返す
  }
})
</script>

<script setup lang="ts">
const emit = defineEmits<{
  (e: 'change', id: number): void
  (e: 'update', value: string): void
}>()
</script>

export default {
  emits: {
    submit(payload) {
      // バリデーションの合格/不合格を示す
      // `true` または `false` を返す
    }
  }
}

任意ですが、コンポーネントがどのように動作すべきかをよりよく文書化するために、発行されるすべてのイベントを定義することが推奨されます。また、これにより Vue は既知のリスナーをフォールスルー属性から除外し、サードパーティのコードによって手動でディスパッチされた DOM イベントによって起こるエッジケースを回避できます。

イベントのバリデーション ​

発行するイベントは、プロパティの型バリデーションと同様に、配列構文ではなくオブジェクト構文で定義されている場合にバリデーションできます。

バリデーションを追加するには、「this.$emitemit の呼び出しに渡された引数」を受け取り、「イベントが正当かどうかを示す真偽値」を返す関数をイベントに割り当てます。

<script setup>
const emit = defineEmits({
  // バリデーションなし
  click: null,

  // submit イベントをバリデーション
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('Invalid submit event payload!')
      return false
    }
  }
})

function submitForm(email, password) {
  emit('submit', { email, password })
}
</script>

export default {
  emits: {
    // バリデーションなし
    click: null,

  // submit イベントをバリデーション
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('Invalid submit event payload!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}