Props и их типизация

В Naive UI компоненты активно используют механизм props для передачи данных и конфигурации. Каждый компонент имеет набор заранее определённых свойств, которые контролируют его внешний вид, поведение и функциональность. Пропсы позволяют отделить логику компонента от его состояния и сделать его переиспользуемым.

Пропсы объявляются с помощью объекта props при определении компонента через defineComponent. В Naive UI используется строгая типизация, что особенно важно при работе с TypeScript, так как это обеспечивает автодополнение и защиту от ошибок во время компиляции.

import { defineComponent, ref } from 'vue';
import { NButton } from 'naive-ui';

export default defineComponent({
  components: { NButton },
  setup() {
    const count = ref(0);
    return { count };
  },
  props: {
    label: {
      type: String,
      required: true
    },
    size: {
      type: String,
      default: 'medium'
    }
  }
});

Типы данных для Props

Naive UI строго придерживается типизации Vue 3, и каждый пропс может иметь следующие типы:

  • String — текстовые значения, часто используются для названий, меток, сообщений.
  • Number — числовые значения, например, для размеров, индексов или таймеров.
  • Boolean — логические значения, например, disabled, loading.
  • Array — массивы элементов, например, список опций.
  • Object — сложные объекты, передающие конфигурацию или дополнительные параметры.
  • Function — обработчики событий или колбэки.

Типизация через TypeScript делает использование этих пропсов ещё более надёжным:

import { PropType, defineComponent } from 'vue';
import { NInput } from 'naive-ui';

export default defineComponent({
  components: { NInput },
  props: {
    value: {
      type: String as PropType<string>,
      required: true
    },
    onChange: Function as PropType<(val: string) => void>
  }
});

Обязательные и необязательные Props

Каждый пропс может быть обязательным (required: true) или необязательным. Для необязательных пропсов можно задавать значение по умолчанию через свойство default. Это особенно важно при создании UI-библиотеки или кастомных компонентов, чтобы избежать ошибок, когда разработчик забудет передать конкретный пропс.

props: {
  theme: {
    type: String,
    default: 'light'
  },
  showIcon: {
    type: Boolean,
    default: true
  }
}

Комплексная типизация через PropType

Для более сложных пропсов используется PropType в сочетании с TypeScript. Это позволяет задавать точные структуры объектов, массивов или функций.

interface Option {
  label: string;
  value: number;
}

props: {
  options: {
    type: Array as PropType<Option[]>,
    required: true
  },
  onSelect: Function as PropType<(option: Option) => void>
}

Такой подход предотвращает передачу некорректных данных и обеспечивает статическую проверку типов ещё на этапе разработки.

Валидаторы Props

Naive UI поддерживает кастомные валидаторы, которые позволяют проверять значения пропсов перед использованием. Валидатор — это функция, которая возвращает true для корректного значения и false для некорректного:

props: {
  size: {
    type: String,
    default: 'medium',
    validator: (value) => ['small', 'medium', 'large'].includes(value)
  }
}

Это особенно полезно для пропсов с ограниченным набором допустимых значений.

Работа с реактивными Props

Prop в Naive UI автоматически становится реактивным, если используется внутри setup. Это значит, что при изменении значения родительского компонента, дочерний компонент обновит своё состояние автоматически.

export default defineComponent({
  props: {
    visible: Boolean
  },
  setup(props) {
    const isVisible = computed(() => props.visible);
    return { isVisible };
  }
});

Деструктуризация и реактивность

Важно помнить, что при деструктуризации props в setup реактивность теряется. Для сохранения реактивности следует использовать toRefs:

import { toRefs } from 'vue';

setup(props) {
  const { visible, label } = toRefs(props);
  return { visible, label };
}

Использование Default и Required вместе

Можно комбинировать default и required, однако это имеет смысл только для случаев, когда пропс должен быть передан в определённых сценариях, а для остальных можно использовать дефолтное значение.

props: {
  color: {
    type: String,
    default: 'blue',
    required: false
  }
}

Резюме ключевых практик

  • Строгая типизация пропсов через TypeScript повышает надёжность кода.
  • Валидаторы обеспечивают контроль допустимых значений.
  • Обязательные и необязательные пропсы помогают управлять интерфейсом и поведением компонентов.
  • PropType используется для сложных объектов, массивов и функций.
  • Реактивность пропсов сохраняется при правильной работе с props и toRefs.

Props в Naive UI — это не просто способ передачи данных, а инструмент строгой типизации и контроля поведения компонентов, что делает интерфейсы гибкими, безопасными и предсказуемыми.

Оглавление