Опции: Состояние ​

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, rawProps: object) => boolean
  }
  
  type PropType<T> = { new (): T } | { new (): T }[]

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

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

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

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

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

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

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

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

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

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

• Пример

  Базовое описание:

  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: {
      // только для чтения
      aDouble() {
        return this.a * 2
      },
      // с возможностью записи
      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 ​

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

• Тип

  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), а значениями - соответствующие коллбэки. Коллбэк получает новое значение и старое значение наблюдаемого источника.

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

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

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

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

• Пример

  js

  export default {
    data() {
      return {
        a: 1,
        b: 2,
        c: {
          d: 4
        },
        e: 5,
        f: 6
      }
    },
    watch: {
      // наблюдение за свойством корневого уровня
      a(val, oldVal) {
        console.log(`новое: ${val}, старое: ${oldVal}`)
      },
      // передача метода в качестве строки
      b: 'someMethod',
      // коллбэк будет вызываться при изменении любого из свойств наблюдаемого объекта, независимо от глубины вложенности
      c: {
        handler(val, oldVal) {
          console.log('c изменено')
        },
        deep: true
      },
      // наблюдение за одноим вложенным свойством:
      'c.d': function (val, oldVal) {
        // сделать что-нибудь
      },
      // коллбэк будет вызван сразу после начала наблюдения
      e: {
        handler(val, oldVal) {
          console.log('e изменено')
        },
        immediate: true
      },
      // можно передать массив коллбэков, они будут вызываться поочередно
      f: [
        'handle1',
        function handle2(val, oldVal) {
          console.log('сработал handle2')
        },
        {
          handler: function handle3(val, oldVal) {
            console.log('сработал handle3')
          }
          /* ... */
        }
      ]
    },
    methods: {
      someMethod() {
        console.log('b изменено')
      },
      handle1() {
        console.log('сработал handle1')
      }
    },
    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: {
      // no validation
      click: null,
  
      // with validation
      submit: (payload) => {
        if (payload.email && payload.password) {
          return true
        } else {
          console.warn(`Invalid submit event payload!`)
          return false
        }
      }
    }
  }

• См. также

  • Руководство — Передача обычных атрибутов
  • Руководство — Типизирование генерируемых компонентом событий

expose ​

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

• Тип

  ts

  interface ComponentOptions {
    expose?: string[]
  }

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

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

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

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

• Пример

  js

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