Options: Состояние ​

data ​

Функция, возвращающая начальное реактивное состояние для экземпляра компонента.

• Тип

  ts

  interface ComponentOptions {
    data?(
      this: ComponentPublicInstance,
      vm: ComponentPublicInstance
    ): object
  }

• Подробности

  Ожидается, что функция вернет обычный объект JavaScript, который Vue сделает реактивным. После создания экземпляра к объекту реактивных данных можно получить доступ через this.$data. Экземпляр компонента также передает все свойства объекта данных, поэтому this.a будет эквивалентен this.$data.a.

  Все свойства данных верхнего уровня должны быть включены в возвращаемый объект данных. Добавление новых свойств в this.$data возможно, но не рекомендуется. Если нужное значение свойства ещё недоступно, то в качестве заполнителя следует включить пустое значение, например undefined или null, чтобы Vue знал о существовании свойства.

  Свойства, начинающиеся с _ или $, не будут проксироваться на экземпляр компонента, поскольку они могут конфликтовать с внутренними свойствами и методами API Vue. Вам придется обращаться к ним через this.$data._property.

  Не рекомендуется возвращать объекты с собственным поведением в состоянии, например, объекты API браузера и свойства прототипов. В идеале возвращаемый объект должен быть простым объектом, который представляет только состояние компонента.

• Пример

  js

  export default {
    data() {
      return { a: 1 }
    },
    created() {
      console.log(this.a) // 1
      console.log(this.$data) // { a: 1 }
    }
  }

  Обратите внимание, что если вы используете стрелочную функцию со свойством data, this не будет экземпляром компонента, но вы всё равно сможете получить доступ к экземпляру в качестве первого аргумента функции:

  js

  data: (vm) => ({ a: vm.myProp })

• Смотрите также Реактивность в деталях

props ​

Объявление параметров компонента.

• Тип

  ts

  interface ComponentOptions {
    props?: ArrayPropsOptions | ObjectPropsOptions
  }
  
  type ArrayPropsOptions = string[]
  
  type ObjectPropsOptions = { [key: string]: Prop }
  
  type Prop<T = any> = PropOptions<T> | PropType<T> | null
  
  interface PropOptions<T> {
    type?: PropType<T>
    required?: boolean
    default?: T | ((rawProps: object) => T)
    validator?: (value: unknown) => boolean
  }
  
  type PropType<T> = { new (): T } | { new (): T }[]

  Типы упрощены для удобства чтения.

• Подробности

  В Vue все параметры компонентов должны быть явно объявлены. Это можно сделать в двух формах:

  • Простая форма с использованием массива строк.
  • Полная форма с использованием объекта, где каждое свойство-ключ — это имя параметра, а значение — тип параметра (функция-конструктор) или дополнительные опции.

  С помощью объектно-ориентированного синтаксиса каждый параметр может дополнительно определять следующие параметры:

  • type: Может быть одним из следующих собственных конструкторов: String, Number, Boolean, Array, Object, Date, Function, Symbol, любая пользовательская функция-конструктор или их массив. В режиме разработки Vue проверит, соответствует ли значение параметра объявленному типу, и выдаст предупреждение, если это не так. Более подробную информацию см. в разделе Валидация пропсов.

    Также обратите внимание, что параметр с типом Boolean влияет на поведение приведения значений как в разработке, так и в продакшене. Подробнее см. в разделе Приведение к булевому типу.

  • default: Определяет значение по умолчанию для свойства, если оно не передано родителем или имеет значение undefined. Объект или массив по умолчанию должны быть возвращены с помощью фабричной функции. Функция фабрики также получает в качестве аргумента необработанный объект параметра.

  • required: Определяет, требуется ли параметр. В непродакшен-среде будет выдано консольное предупреждение, если это значение истинно, а параметр не передан.

  • validator: Пользовательская функция-валидатор принимает значение пропа и объект всех пропсов в качестве аргументов. В режиме разработки, если эта функция возвращает ложное значение (т. е. валидация не проходит), Vue выдаст предупреждение в консоли.

• Пример

  Простая декларация:

  js

  export default {
    props: ['size', 'myMessage']
  }

  Объявление объекта с валидацией:

  js

  export default {
    props: {
      // проверка типа
      height: Number,
      // проверка типа плюс другие проверки
      age: {
        type: Number,
        default: 0,
        required: true,
        validator: (value) => {
          return value >= 0
        }
      }
    }
  }

• Смотрите также

  • Руководство - Пропсы
  • Руководство - Типизация пропсов компонента

computed ​

Объявляем вычисляемые свойства, которые должны быть открыты для экземпляра компонента.

• Тип

  ts

  interface ComponentOptions {
    computed?: {
      [key: string]: ComputedGetter<any> | WritableComputedOptions<any>
    }
  }
  
  type ComputedGetter<T> = (
    this: ComponentPublicInstance,
    vm: ComponentPublicInstance
  ) => T
  
  type ComputedSetter<T> = (
    this: ComponentPublicInstance,
    value: T
  ) => void
  
  type WritableComputedOptions<T> = {
    get: ComputedGetter<T>
    set: ComputedSetter<T>
  }

• Подробности

  Опция принимает объект, где ключ — это имя вычисляемого свойства, а значение — либо вычисляемый геттер, либо объект с методами get и set (для вычисляемых свойств с возможностью записи).

  Все геттеры и сеттеры имеют контекст this, автоматически привязанный к экземпляру компонента.

  Обратите внимание, что если вы используете стрелочную функцию с вычисляемым свойством, this не будет указывать на экземпляр компонента, но вы всё равно сможете получить доступ к нему в качестве первого аргумента функции:

  js

  export default {
    computed: {
      aDouble: (vm) => vm.a * 2
    }
  }

• Пример

  js

  export default {
    data() {
      return { a: 1 }
    },
    computed: {
      // readonly
      aDouble() {
        return this.a * 2
      },
      // writable
      aPlus: {
        get() {
          return this.a + 1
        },
        set(v) {
          this.a = v - 1
        }
      }
    },
    created() {
      console.log(this.aDouble) // => 2
      console.log(this.aPlus) // => 2
  
      this.aPlus = 3
      console.log(this.a) // => 2
      console.log(this.aDouble) // => 4
    }
  }

• Смотрите также

  • Руководство - Вычисляемые свойства
  • Руководство - Типизация вычисляемых свойств

methods ​

Объявляем методы, которые будут смешиваться с экземпляром компонента.

• Тип

  ts

  interface ComponentOptions {
    methods?: {
      [key: string]: (this: ComponentPublicInstance, ...args: any[]) => any
    }
  }

• Подробности

  К объявленным методам можно обращаться непосредственно к экземпляру компонента или использовать их в шаблонных выражениях. Все методы автоматически привязывают свой контекст this к экземпляру компонента, даже если он передается по кругу.

  Избегайте использования стрелочных функций при объявлении методов, так как они не будут иметь доступа к экземпляру компонента через this.

• Пример

  js

  export default {
    data() {
      return { a: 1 }
    },
    methods: {
      plus() {
        this.a++
      }
    },
    created() {
      this.plus()
      console.log(this.a) // => 2
    }
  }

• Смотрите также Обработка событий

watch ​

Объявляем обратные вызовы watch, которые будут вызываться при изменении данных.

• Тип

  ts

  interface ComponentOptions {
    watch?: {
      [key: string]: WatchOptionItem | WatchOptionItem[]
    }
  }
  
  type WatchOptionItem = string | WatchCallback | ObjectWatchOptionItem
  
  type WatchCallback<T> = (
    value: T,
    oldValue: T,
    onCleanup: (cleanupFn: () => void) => void
  ) => void
  
  type ObjectWatchOptionItem = {
    handler: WatchCallback | string
    immediate?: boolean // по умолчанию: false
    deep?: boolean // по умолчанию: false
    flush?: 'pre' | 'post' | 'sync' // по умолчанию: 'pre'
    onTrack?: (event: DebuggerEvent) => void
    onTrigger?: (event: DebuggerEvent) => void
  }

  Типы упрощены для удобства чтения.

• Подробности

  Опция watch ожидает объект, в котором ключами являются свойства экземпляра реактивного компонента, за которыми нужно следить (например, свойства, объявленные через data или computed) — а values — это соответствующие обратные вызовы. Обратный вызов получает новое значение и старое значение наблюдаемого источника.

  Помимо свойства корневого уровня, ключом может быть простой путь, разделённый точками, например a.b.c. Обратите внимание, что это использование не поддерживает сложные выражения — поддерживаются только пути, разделённые точками. Если вам нужно следить за сложными источниками данных, используйте вместо этого императивный API $watch().

  Значение также может быть строкой имени метода (объявленного через methods) или объектом, содержащим дополнительные опции. При использовании объектного синтаксиса обратный вызов должен быть объявлен в поле handler. Дополнительные опции включают:

  • immediate: запускаем обратный вызов непосредственно при создании наблюдателя. При первом вызове старое значение будет undefined.
  • deep: принудительный глубокий обход источника, если он является объектом или массивом, чтобы обратный вызов срабатывал при глубоких мутациях. Смотрите Глубокие наблюдатели.
  • flush: настройка времени обратного вызова для сброса. Смотрите Время сброса обратного вызова и watchEffect().
  • onTrack / onTrigger: отладка зависимостей наблюдателя. Смотрите Отладка наблюдателей.

  Избегайте использования стрелочных функций при объявлении обратных вызовов watch, так как они не будут иметь доступа к экземпляру компонента через this.

• Пример

  js

  export default {
    data() {
      return {
        a: 1,
        b: 2,
        c: {
          d: 4
        },
        e: 5,
        f: 6
      }
    },
    watch: {
      // наблюдение за свойством верхнего уровня
      a(val, oldVal) {
        console.log(`new: ${val}, old: ${oldVal}`)
      },
      // строковое имя метода
      b: 'someMethod',
      // обратный вызов будет вызываться каждый раз, когда любое из наблюдаемых свойств объекта изменится, независимо от глубины вложенности
      c: {
        handler(val, oldVal) {
          console.log('c changed')
        },
        deep: true
      },
      // наблюдение за одним вложенным свойством:
      'c.d': function (val, oldVal) {
        // делаем что-то
      },
      // обратный вызов будет вызван сразу после начала наблюдения
      e: {
        handler(val, oldVal) {
          console.log('e changed')
        },
        immediate: true
      },
      // вы можете передать массив обратных вызовов, они будут вызываться по очереди
      f: [
        'handle1',
        function handle2(val, oldVal) {
          console.log('handle2 triggered')
        },
        {
          handler: function handle3(val, oldVal) {
            console.log('handle3 triggered')
          }
          /* ... */
        }
      ]
    },
    methods: {
      someMethod() {
        console.log('b changed')
      },
      handle1() {
        console.log('handle 1 triggered')
      }
    },
    created() {
      this.a = 3 // => новое значение: 3, старое значение: 1
    }
  }

• Смотрите также Наблюдатели

emits ​

Объявляем пользовательские события, испускаемые компонентом.

• Тип

  ts

  interface ComponentOptions {
    emits?: ArrayEmitsOptions | ObjectEmitsOptions
  }
  
  type ArrayEmitsOptions = string[]
  
  type ObjectEmitsOptions = { [key: string]: EmitValidator | null }
  
  type EmitValidator = (...args: unknown[]) => boolean

• Подробности

  Испускаемые события могут быть объявлены в двух формах:

  • Простая форма с использованием массива строк.
  • Полная форма с использованием объекта, где каждое свойство-ключ — это имя события, а значение — либо null, либо функция валидатора.

  Функция проверки получит дополнительные аргументы, переданные в вызов компонента $emit. Например, если вызвать this.$emit('foo', 1), то соответствующий валидатор для foo получит аргумент 1. Функция валидатора должна возвращать логическое значение, указывающее на то, являются ли аргументы события действительными.

  Обратите внимание, что опция emits влияет на то, какие слушатели событий будут считаться слушателями событий компонента, а не собственными слушателями событий DOM. Слушатели объявленных событий будут удалены из объекта $attrs компонента, поэтому они не будут передаваться в корневой элемент компонента. Дополнительные сведения см. в главе Передаваемые атрибуты.

• Пример

  Синтаксис массива:

  js

  export default {
    emits: ['check'],
    created() {
      this.$emit('check')
    }
  }

  Синтаксис объекта:

  js

  export default {
    emits: {
      // без валидации
      click: null,
  
      // с валидацией
      submit: (payload) => {
        if (payload.email && payload.password) {
          return true
        } else {
          console.warn(`Неверная полезная нагрузка события submit!`)
          return false
        }
      }
    }
  }

• Смотрите также

  • Руководство - Передаваемые атрибуты
  • Руководство - Типизация событий компонента

expose ​

Объявляйте открытые публичные свойства, когда к экземпляру компонента обращается родитель через ссылки на элементы шаблона.

• Тип

  ts

  interface ComponentOptions {
    expose?: string[]
  }

• Подробности

  По умолчанию экземпляр компонента раскрывает все свойства экземпляра родителю при обращении к нему через $parent, $root или ссылки на элементы шаблона. Это может быть нежелательно, поскольку компонент, скорее всего, имеет внутреннее состояние или методы, которые должны быть приватными, чтобы избежать тесной связи.

  Опция expose ожидает список строк с именами свойств. Когда используется expose, только свойства, явно перечисленные в списке, будут открыты для публичного экземпляра компонента.

  expose действует только на пользовательские свойства — он не отфильтровывает встроенные свойства экземпляров компонентов.

• Пример

  js

  export default {
    // только `publicMethod` будет доступен для публичного экземпляра
    expose: ['publicMethod'],
    methods: {
      publicMethod() {
        // ...
      },
      privateMethod() {
        // ...
      }
    }
  }