رویدادهای کامپوننت ​

در این صفحه فرض شده که شما از قبل مبانی کامپوننت‌ها را مطالعه کرده اید. اگر با کامپوننت‌ها آشنایی ندارید، ابتدا آن را بخوانید.

اِمیت کردن و گوش دادن به رویدادها ​

یک کامپوننت می‌تواند رویدادهای سفارشی را مستقیماً در عبارات تمپلیت (مثلاً در کنترل‌کننده رویداد v-on) با استفاده از متد داخلی ‎$emit منتشر کند:

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

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

والد بعدا می تواند با استفاده از v-on به آن گوش دهد:

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

پیراینده ‎.once در شنوندگان رویداد(event listeners) کامپوننت نیز پشتیبانی می‌شود:

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

مانند کامپوننت‌ها و پراپ‌ها، نام رویدادها یک تغییر حالت خودکار را ایجاد می‌کنند. توجه کنید که ما یک رویداد camelCase را منتشر کردیم، اما می‌توانیم آن را با استفاده از شنونده kebab-cased در والد گوش دهیم. مانند props casing، توصیه می‌کنیم از شنونده‌های رویداد kebab-cased در تمپلیت‌ها استفاده کنید.

آرگومان‌های رویداد ​

گاهی اوقات انتشار یک مقدار خاص همراه با یک رویداد مفید است. به عنوان مثال، ممکن است بخواهیم کامپوننت <BlogPost> مسئول میزان بزرگ‌نمایی متن باشد. در این موارد، می‌توانیم آرگومان‌های اضافی را به ‎$emit ارسال کنیم تا این مقدار را ارائه کنیم:

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

سپس، هنگامی که به رویداد در والد گوش می‌دهیم، می‌توانیم از یک arrow function درون خطی به عنوان شنونده استفاده کنیم که به ما امکان می‌دهد به آرگومان رویداد دسترسی پیدا کنیم:

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

یا اگر کنترل کننده رویداد(event handler) یک متد باشد:

<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 و ماکرو defineEmits()‎ همچنین از سینتکس آبجکت پشتیبانی می‌کنند. اگر از TypeScript استفاده می‌کنید، می‌توانید برای آرگومان‌ها تایپ قرار دهید که به ما اجازه اعتبارسنجی زمان اجرا روی payload رویدادهای ارسال شده می‌دهد:

<script setup lang="ts">
const emit = defineEmits({
  submit(payload: { email: string, password: string }) {
    // را برای نشان دادن `false` یا `true` مقدار
    // اعتبارسنجی موفقیت آمیز یا شکست خورده برمی‌گرداند
  }
})
</script>

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

export default {
  emits: {
    submit(payload: { email: string, password: string }) {
      // مقدار `true` یا `false` را برای نشان دادن
      // اعتبارسنجی موفقیت آمیز / شکست خورده برمی گرداند
    }
  }
}

اگر چه اختیاری است، پیشنهاد می‌شود همه رویدادهای اِمیت شده را تعریف کنید تا نحوه کار یک کامپوننت را بهتر مستند کنید. همچنین به Vue اجازه می‌دهد شنوندگان (listeners) شناخته شده را از اتریبیوت‌های fallthrough حذف کند، از موارد لبه‌ای که توسط کد شخص ثالث از طریق رویدادهای DOM ارسال می‌شوند، جلوگیری کند.

اعتبارسنجی رویدادها ​

مشابه اعتبارسنجی تایپ prop، یک رویداد اِمیت شده می‌تواند اعتبار سنجی شود اگر به جای سینتکس آرایه با سینتکس آبجکت تعریف شده باشد.

برای افزودن اعتبارسنجی، به رویداد تابعی اختصاص داده می‌شود که آرگومان‌های ارسال شده به فراخوانی this.$emitemit را دریافت می‌کند و برای نشان دادن معتبر بودن یا نبودن رویداد، یک boolean برمی‌گرداند.

<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 })
    }
  }
}