Composables функции

Краткое описание

Модуль/Функция	Назначение	Принимает	Возвращает
`useActionsButton`	Список действий для кнопок в глобальном рабочем пространстве	–	`ComputedRef<MenuItem[]>`
`useAutoSlug`	Автоматическая генерация уникального slug на основе других полей	`AutoSlugOptions`	`{ regenerateSlug(): void }`
`useBreadcrumbs`	Возвращает список элементов для выпадающего меню хлебных крошек в тулбаре	–	`{ breadcrumbsMenuItems: Ref<MenuItem[]> }`
`useDebugMode`	Управление режимом отладки через localStorage	–	`debugStatus: Ref<boolean>, toggleDebugMode: () => void`
`useEntitiesRequests`	Списки сущностей и функции их загрузки	–	`Ref[] + updateAllEntities()`
`useFillFormFields`	Заполнение реактивных полей формы из объекта	`fields: Record<string, any>`	`inputData: Record<string, any>`
`useFormatFormData`	Форматирование данных из полей формы для отправки	`fields: Record<string, any>`	`Record<string, any>`
`useGroupFields`	Группировка полей формы по конфигурации блоков	`fields: Record<string>, blocksConfig: GroupConfig[]`	`ComputedRef<{ blocks: any[] }>`
`useRenderFields`	Генерация рендер-функций для UI-компонентов	`Зависит от типа рендера (см. подробное описание)`	`Функция-рендер для таблицы`
`useRowActions`	Генерация действий для строки таблицы	–	`{ getRowItems }`
`useSaveShortcuts`	Назначение горячих клавиш для сохранения	`onFormSubmit: Function`	`void`
`useSidebar`	Состояние боковой панели и элементы меню	–	`isCollapsed`, `toggleSidebar` и др.
`useSites`	Управление выбранным сайтом и данными сайтов	–	`selectedSite`, `computedSubLink`, `isGlobal` и др.
`useSummary`	Элементы сводки для главной страницы	–	`workspaceSummaryItems`
`useTableHeader`	Управление кнопками в заголовках таблицы	–	`{ addControlButton }`
`useTableEditableFormattedData`	Возвращает отформатированные данные для компонента `TableEditableCustom.vue`	Принимает `props.data` из компонента `TableEditableCustom.vue`	Возвращает отформатированные данные
`useCheckingPromoPriceAndPriceFields`	Возвращает две функции, которые используются в форме товара для блока `Цены`.	-	Возвращает `ifBasePriceIs0PromotionalPriceShouldBe0`, `promotionalPriceMustBeLessThanBasePrice`
`useActivateTabWithErrors`	Используется для замены базовой формы на форму с табами в компоненте `components/common/BaseForm.vue`	-	-

Подробное описание

`useActionsButton`

Модуль предоставляет список элементов меню для кнопок создания сущностей. Используется в глобальном рабочем пространстве. Ссылки формируются динамически на основе текущего маршрута (computedSubLink)

Пример использования:

vue


<script setup>
	import { globalWorkspaceButtonActionsItems } from '@/composables/useActionsButton' // Импорт отображён для наглядности, не надо делать так в проекте, там работает автоимпорт
</script>

<template>
	<UDropdownMenu :items="globalWorkspaceButtonActionsItems">
		<UButton
			icon="i-lucide-plus"
			size="md"
		/>
	</UDropdownMenu>
</template>

`useAutoSlug`

Модуль, предназначенный для автоматической генерации и проверки уникальности slug на основе заголовка. Поддерживает работу как для глобальных, так и для локальных полей названия. Используется при создании/редактировании сущностей с slug

Параметры

interface AutoSlugOptions {
	fields: Record<string, { value: string }>
	data: { slug?: string }
	sourceKeyGlobal?: string // default: 'menutitle'
	sourceKeyLocal?: string // default: 'pagetitle'
	debounceDelay?: number // default: 400
}

Возвращает

{
	regenerateSlug: () => Promise<void>
}

Метод regenerateSlug можно вызывать вручную для повторной генерации slug, если пользователь, например, стер его вручную и хочет пересоздать

Поведение

Автоматически следит за pagetitle или menutitle (в зависимости от isGlobal) и создает slug, если пользователь ещё не начал редактировать его вручную
Используется generateSlugFromText() для создания slug и запрос к API для проверки его уникальности
Если пользователь редактирует slug вручную — автоматическая генерация отключается
Все изменения происходят с задержкой (debounce) в 400 мс (или переданной)

Пример использования:

vue


<script setup>
	const { regenerateSlug } = useAutoSlug({
		fields: props.fields,
		data: props.data,
	})
</script>

<template>
	<UButton
		aria-label="Перегенерировать slug"
		@click="regenerateSlug()"
	/>
</template>

`useBreadcrumbsMenuItems`

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

Меню зависит от типа рабочего пространства (глобальное или локальное)
Используется на странице, где отображаются хлебные крошки с меню переходов

В зависимости от isGlobal.value, возвращает либо:

globalWorkspaceBreadcrumbsMenuItems — для глобального контекста (с пользователями, регионами и т.д.)
regularWorkspaceBreadcrumbsMenuItems — для обычного магазина (без сущностей пользователей и регионов)

Пример использования:

vue


<script setup>
	const { breadcrumbsMenuItems } = useBreadcrumbsMenuItems()
</script>

<template>
	<UBreadcrumb :items="breadcrumbsMenuItems"></UBreadcrumb>
</template>

`useDebugMode`

Простой composable для включения/отключения режима отладки. Сохраняет состояние в localStorage под ключом debugStatus, чтобы сохранялось между сессиями

debugStatus — реактивное значение, указывающее включён ли режим отладки (true или false)
toggleDebugMode — функция для переключения значения debugStatus

Пример использования:

vue


<script setup>
	import { debugStatus, toggleDebugMode } from '@/composables/useDebugMode' // Импорт отображён для наглядности, не надо делать так в проекте, там работает автоимпорт
</script>

<template>
	<div>
		<p>Статус режима отладки: {{ debugStatus ? 'Включен' : 'Выключен' }}</p>
		<UButton
			@click="toggleDebugMode()"
			label="Переключить режим отладки"
		/>
	</div>
</template>

`useEntitiesRequests`

Модуль, предоставляющий предопределённые списки (единицы измерения, статусы, страны и др.) в виде реактивных ссылок Ref
Также экспортирует функции для асинхронной загрузки данных с сервера:
- getCategoryItems()
- getBrandItems()
- getCityItems()
- ...
- updateAllEntities() — загружает все сущности параллельно

Примеры использования:

Для загрузки всех сущностей параллельно

vue


<script setup>
	await updateAllEntities()
</script>

Для использования загруженных данных в конфигах форм

...
category: {
	value: categoryItems.value[0],
		items
:
	categoryItems.value,
		type
:
	'select',
		label
:
	'Категория товара',
}
,
...

`useFillFormFields()`

Функция заполняет поля формы (fields) значениями из объекта inputData, опираясь на соответствие ключей

Аргументы

fields: Объект реактивных полей формы (обычно находится во всех useForm в /composables/forms/)
inputData: Объект с входными данными с бэкенда

Пример использования:

vue


<script setup>
	const fields = {
		menutitle: {
			value: '',
			type: 'text',
			label: 'Название',
		},
		price: {
			value: '',
			type: 'number',
			label: 'Цена',
		},
	}

	const inputData = {
		menutitle: 'Товар 1',
		price: 100,
	}

	useFillFormFields(fields, inputData) // После вызова поля формы будут заполнены соответствующими значениями
</script>

`useFormatFormData()`

Формирует объект для отправки на сервер, преобразуя значения из реактивных полей формы по определённым правилам

Аргументы

fields: Объект с описанием полей формы и их значениями

Особенности обработки

Игнорирует поля с disabled, readonly или hidden
switch: значение преобразуется в boolean
number: значение преобразуется в Number (или null, если пустое)
select:
- Если массив (multiple), возвращает массив id или самих значений
- Если одиночное значение — возвращает id, либо null, если id === 0
file: возвращает name или само значение
table: каждое значение преобразуется в объект с учётом типа number у подполей
dataset: возвращает объект с ключами и значениями из field.values

Пример

vue


<script setup>
	const fields = {
		menutitle: {
			value: 'Пример',
			type: 'text',
		},
		is_publish: {
			value: 1,
			type: 'switch',
		},
		price: {
			value: 1200,
			type: 'number',
		},
		category_id: {
			value: 5,
			type: 'select',
		},
	}

	useFormatFormData(fields)
	/*
    Возвращаемый объект готов для отправки на сервер
    {
      menutitle: 'Пример',
      is_publish: true,
      price: 1200,
      category_id: 5
    }
    */
</script>

`useGroupFields()`

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

Аргументы

fields: Объект с описанием полей формы.
blocksConfig: Массив конфигураций блоков, каждый из которых содержит список групп

Логика группировки

Кастомные группы

Если у поля указано поле groups: string[], оно попадает в указанные кастомные группы

Дефолтные группы

Если поле не участвует в кастомных группах, оно автоматически попадает в одну из дефолтных:

switches — переключатели switch, кроме readonly
readonlys — все поля readonly
texts — поля типа text, number, slug
selects — выпадающие списки
tables — таблицы
datasets — наборы данных
textareas — многострочные поля
files — файловые поля

Возвращаемое значение

Возвращается computed объект:

blocks — массив блоков, каждый содержит:
- title, hint, view, disabled — как в blocksConfig
- groups — массив сгруппированных полей для рендера
switches — отдельный список переключателей
readonlys — отдельный список readonly полей

Пример использования:

const fields = reactive({
	menutitle: {
		type: 'text',
		label: 'Название',
	},
	category_id: {
		type: 'select',
		label: 'Категория товара',
	},
})

const blocks: GroupConfig[] = [
	{
		title: 'Основные данные',
		groups: ['texts', 'selects'],
		view: 'grid',
	},
]

const groupedFields = useGroupFields(fields, blocks)

`useRenderFields`

Модуль предоставляет функции для отрисовки ячеек таблиц с поддержкой биндинга данных и корректной генерацией имён полей. Все функции возвращают рендер-функцию, которая используется в конфигурации таблицы

`renderTextField(fieldKey, inputName, disabled = false)`

Рендерит текстовое поле с использованием UInput.

fieldKey — ключ в объекте строки таблицы
inputName — имя поля формы
disabled — отключение поля (по умолчанию false)

`renderNumberField(fieldKey, inputName, decimalPart = 0, step = 0.1, disabled = false)`

Рендерит числовое поле с использованием UInputNumber.

decimalPart — число знаков после запятой
step — шаг изменения значения
Остальные параметры аналогичны renderTextField

`renderSelectField(fieldKey, inputName, items = [], disabled = false)`

Рендерит селект с использованием USelectMenu.

items — массив опций селекта
Остальные параметры аналогичны renderTextField

Пример использования:

const fields = reactive({
	options: {
		fields: [
			{
				accessorKey: 'key',
				header: 'Ключ',
				cell: renderTextField('key', 'options'),
			},
			{
				accessorKey: 'value',
				header: 'Значение',
				cell: renderNumberField('value', 'options', 2),
			},
			{
				accessorKey: 'unit',
				header: 'Единица измерения',
				cell: renderSelectField('unit', 'options', Object.values({})),
			},
		],
	},
})

`useRowActions()`

Модуль предоставляет вспомогательные функции для генерации массива действий в выпадающем меню управления строкой таблицы (контекстного меню). Поддерживает как стандартные действия (Редактировать, Скопировать ID, Скопировать ссылку), так и настраиваемые (через объект copyItems)

`getRowItems(row, pageName, copyItems = {})`

Возвращает массив объектов-действий (items) для строки таблицы

row — строка таблицы (row.original)
pageName — используется для формирования URL перехода на редактирование и ссылки
copyItems — объект, в котором ключи — это пути до значений в row.original, а значения — человекочитаемые подписи

Поведение:

Добавляет пункт "Редактировать" с переходом на /admin/${pageName}/${id}/edit/
Добавляет "Скопировать ID"
Рекурсивно добавляет пункты на основе copyItems, поддерживает вложенные ключи (например, { category: { name: 'Категория' } })
В конце добавляет "Скопировать ссылку"

Внутренние вспомогательные функции:

copyToClipboard(text, message) — копирует значение в буфер обмена и показывает toast-уведомление
formatLabel(text) — приводит первую букву подписи к нижнему регистру
getNestedValue(obj, path) — безопасно извлекает вложенное значение по строке пути (a.b.c)

Пример использования:

vue


<script setup>
	const { getRowItems } = useRowActions()

	const tableColumns = ref([
		{
			id: 'actions',
			header: ({ column }) => h('div', addControlButton(column, 'Управление', 'right')),
			cell: ({ row }) => {
				return h(
					'div',
					h(
						UDropdownMenu,
						{
							items: getRowItems(row, 'entity', {
								menutitle: 'Название',
							}),
						},
						() => h(UButton, {}),
					),
				)
			},
		},
	])
</script>

`useShortcuts()`

Модуль регистрирует горячие клавиши, которые вызывают переданную функцию onFormSubmit. Используется в формах для удобства отправки данных с клавиатуры. Поддерживаются как стандартные, так и локализованные сочетания клавиш

🔧 Горячие клавиши:

Enter — стандартное подтверждение (подходит для всех пользователей)
Ctrl + S — сохранение для Windows
Cmd + S (Meta + S) — сохранение для Mac
Ctrl + Ы — для пользователей Windows с русской раскладкой
Cmd + Ы (Meta + Ы) — для пользователей Mac с русской раскладкой

💡 Пример использования

vue


<script setup>
	const onFormSubmit = () => {
		// логика сохранения
	}

	useShortcuts(onFormSubmit)
</script>

`useSidebar`

Модуль управляет состоянием боковой панели (sidebar) и возвращает список пунктов меню в зависимости от режима ( глобальный/локальный)

🔘 Переменные и функции

isCollapsed — ref<boolean>, указывает, свернута ли панель
toggleSidebar() — переключает состояние isCollapsed

Содержит

adminMenuItems Содержит структуру меню для администраторов
globalWorkspaceMenuItems Содержит структуру меню для глобального режима:
- collapsed — иконки без подписей
- expanded — структурированные списки с группировками
siteWorkspaceMenuItems Содержит структуру меню для локального режима (аналогично globalWorkspaceMenuItems, но с иным набором элементов)

Пример использования:

vue


<script setup>
	const { sidebarMenuItemsCollapsed, sidebarMenuItemsNotCollapsed } = useSidebarItems()
</script>

<template>
	<div :class="['sidebar', isCollapsed ? 'w-auto' : 'w-[270px]']">
		<UNavigationMenu :items="isCollapsed ? sidebarMenuItemsCollapsed : sidebarMenuItemsNotCollapsed" />
		<UDropdownMenu :items="adminMenuItems"></UDropdownMenu>
	</div>
</template>

`useSites`

Модуль управляет состоянием текущего выбранного сайта (или глобального режима), а также предоставляет данные для выпадающего списка сайтов

Переменные

sitesDropdownItems — элементы для выпадающего меню сайтов
sitesItems — плоский список сайтов, полученный с сервера
globalSite — объект глобального сайта (режим "Общее хранилище")
selectedSite — текущий выбранный сайт
selectedSiteLabel — название выбранного сайта
isGlobal — computed, определяет, активен ли глобальный режим
computedSubLink — computed, базовый префикс для ссылок /admin/global/ или /admin/site/{id}/
globalSubLink — ссылка на глобальное пространство (по умолчанию '/admin/global/')

Функции

`handleSelectSite(item)`

Устанавливает выбранный сайт по элементу из меню:

vue


<script setup>
	handleSelectSite({
		id: 'abc123',
		label: 'example.com',
		isGlobal: false,
	})
</script>

`setSelectedSiteByID(siteID)`

Находит и устанавливает выбранный сайт по ID. Если сайт не найден, переключается на globalSite

vue


<script setup>
	await setSelectedSiteByID('123')
</script>

`transformResponseSitesData(responseData)`

Преобразует список сайтов от сервера в формат, пригодный для меню:

vue


<script setup>
	transformResponseSitesData([{ id: '1', domain: 'example.com' }])

// Результат:

		[
		[{ type: 'label', label: 'Глобальные пространства' }, { ... }],
			[{ type: 'label', label: 'Сайты' }, { id: '1', label: 'example.com', ... }],
			[{ type: 'label', label: 'Управление сайтами' }, { label: 'Добавить новый', ... }]
		]
</script>

`getSitesItems()`

Получает список сайтов с сервера и сохраняет их в sitesDropdownItems и sitesItems

vue


<script setup>
	await getSitesItems()
</script>

Пример использования:

vue


<script setup>
	await getSitesItems()

	handleSelectSite({
		id: '1',
		label: 'example.com',
		to: '/admin/site/1/',
		isGlobal: false,
	})

	console.log(isGlobal.value) // false
	console.log(computedSubLink.value) // '/admin/site/1/'
</script>

`useWorkspaceSummaryItems`

Модуль формирует список элементов для отображения сводки по сайту. Список различается для глобального и локального пространства (isGlobal)

Переменные

`globalWorkspaceSummaryItems`

Список объектов для глобального пространства. Каждый объект содержит:

title — название блока
count — числовой индикатор (например, количество товаров)
to — ссылка на соответствующий раздел

Пример:

{
	title: 'Товары',
		count
:
	2150,
		to
:
	'/admin/global/products/'
}

`regularWorkspaceSummaryItems`

Упрощённая версия списка для локального пространства

`useWorkspaceSummaryItems()`

Возвращает актуальный список элементов в зависимости от текущего режима (глобальный или локальный):

Пример использования:

vue


<script setup>
	const { workspaceSummaryItems } = useWorkspaceSummaryItems()
</script>

<template>
	<CommonContentWrapper>
		<CommonSummaryList :items="workspaceSummaryItems" />
	</CommonContentWrapper>
</template>

`useTableHeader`

Модуль предоставляет вспомогательную функцию addControlButton, которая используется для отрисовки кнопки управления закреплением столбца таблицы

`addControlButton(column, label, position)`

Генерирует кнопку (с помощью компонента UButton) для закрепления/открепления столбца таблицы:

Аргумент	Тип	Описание
`column`	Object	Объект столбца таблицы из библиотеки `Nuxt UI`
`label`	String	Текст кнопки
`position`	String	Позиция закрепления (`'left'` или `'right'`)

При клике:

если текущая позиция совпадает с position, открепляет столбец (pin(false))
иначе — закрепляет столбец в указанную сторону

Отображает иконку:

i-lucide-pin — если столбец не закреплён
i-lucide-pin-off — если столбец уже закреплён

Пример использования:

vue


<script setup>
	const { addControlButton } = useTableHeader()

	const tableColumns = ref([
		{
			id: 'actions',
			header: ({ column }) => h('div', addControlButton(column, 'Управление', 'right')),
		},
	])
</script>

`useTableEditableFormattedData`

Предназначен для форматирования данных компонента components/common/TableEditableCustom.vue и используется исключительно в рамках этого компонента.

Возвращает

{
	formattedData: ComputedRef
}

Поведение

На вход принимает data: ComputedRef<any>. data содержит набор полей, на основе которых рендерится внутреннее содержимое компонента.
Возвращает отформатированные ComputedRef данные.

Пример использования:

См. components/common/TableEditableCustom.vue

`useCheckingPromoPriceAndPriceFields`

Предназначен для логических проверок в components/common/TableEditableCustom.vue и используется исключительно в рамках этого компонента.

Возвращает

{
	ifBasePriceIs0PromotionalPriceShouldBe0: (fields: any) => boolean
	promotionalPriceMustBeLessThanBasePrice: (fields: any) => boolean
}

Поведение

ifBasePriceIs0PromotionalPriceShouldBe0 принимает на вход набор полей формы и проверяет, что fields.price === 0 && fields.promo_price > fields.price. В случае ложного результата отображает toast с текстом «При базовой цене 0, акционная также должна быть равна 0».
promotionalPriceMustBeLessThanBasePrice принимает на вход набор полей формы и проверяет, что fields.price > 0 && fields.promo_price >= fields.price. В случае ложного результата отображает toast с текстом «Акционная цена должна быть меньше базовой».

Пример использования:

См. components/common/TableEditableCustom.vue

`useActivateTabWithErrors`

Используется для замены базовой формы на форму с табами в компоненте components/common/BaseForm.vue и используется исключительно в рамках этого компонента. Формирует набор табов на основе поля blocks, описанного в конфигурационных файлах configs/forms/{*.ts}.

Аргументы

{
	(validator: ReturnType<typeof useVuelidate>, blocks: any[]) => ({})
}

Возвращает

{
	tabs: Ref<TabsItem[]>
	activeTab: string
	goToTabWithErrors: () => void
}

Пример использования:

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

Beget

Сервера

Production

Staging

Панель администратора

Кабинет партнёра

NPM-пакеты

Composables функции ​

Краткое описание ​

Подробное описание ​

useActionsButton ​

Пример использования: ​

useAutoSlug ​

Параметры ​

Возвращает ​

Поведение ​

Пример использования: ​

useBreadcrumbsMenuItems ​

Пример использования: ​

useDebugMode ​

Пример использования: ​

useEntitiesRequests ​

useFillFormFields() ​

Аргументы ​

Пример использования: ​

useFormatFormData() ​

Аргументы ​

Особенности обработки ​

Пример ​

useGroupFields() ​

Аргументы ​

Логика группировки ​

Кастомные группы ​

Дефолтные группы ​

Возвращаемое значение ​

Пример использования: ​

useRenderFields ​

renderTextField(fieldKey, inputName, disabled = false) ​

renderNumberField(fieldKey, inputName, decimalPart = 0, step = 0.1, disabled = false) ​

renderSelectField(fieldKey, inputName, items = [], disabled = false) ​

Пример использования: ​

useRowActions() ​

getRowItems(row, pageName, copyItems = {}) ​

Поведение: ​

Внутренние вспомогательные функции: ​

Пример использования: ​

useShortcuts() ​

🔧 Горячие клавиши: ​

💡 Пример использования ​

useSidebar ​

🔘 Переменные и функции ​

Содержит ​

Пример использования: ​

useSites ​

Переменные ​

Функции ​

handleSelectSite(item) ​

setSelectedSiteByID(siteID) ​

transformResponseSitesData(responseData) ​

getSitesItems() ​

Пример использования: ​

useWorkspaceSummaryItems ​

Переменные ​

globalWorkspaceSummaryItems ​

regularWorkspaceSummaryItems ​

useWorkspaceSummaryItems() ​

Пример использования: ​

useTableHeader ​

addControlButton(column, label, position) ​

Пример использования: ​

useTableEditableFormattedData ​

Возвращает ​

Поведение ​

Пример использования: ​

useCheckingPromoPriceAndPriceFields ​

Возвращает ​

Поведение ​

Пример использования: ​

useActivateTabWithErrors ​

Аргументы ​

Composables функции

Краткое описание

Подробное описание

`useActionsButton`

Пример использования:

`useAutoSlug`

Параметры

Возвращает

Поведение

Пример использования:

`useBreadcrumbsMenuItems`

Пример использования:

`useDebugMode`

Пример использования:

`useEntitiesRequests`

`useFillFormFields()`

Аргументы

Пример использования:

`useFormatFormData()`

Аргументы

Особенности обработки

Пример

`useGroupFields()`

Аргументы

Логика группировки

Кастомные группы

Дефолтные группы

Возвращаемое значение

Пример использования:

`useRenderFields`

`renderTextField(fieldKey, inputName, disabled = false)`

`renderNumberField(fieldKey, inputName, decimalPart = 0, step = 0.1, disabled = false)`

`renderSelectField(fieldKey, inputName, items = [], disabled = false)`

Пример использования:

`useRowActions()`

`getRowItems(row, pageName, copyItems = {})`

Поведение:

Внутренние вспомогательные функции:

Пример использования:

`useShortcuts()`

🔧 Горячие клавиши:

💡 Пример использования

`useSidebar`

🔘 Переменные и функции

Содержит

Пример использования:

`useSites`

Переменные

Функции

`handleSelectSite(item)`

`setSelectedSiteByID(siteID)`

`transformResponseSitesData(responseData)`

`getSitesItems()`

Пример использования:

`useWorkspaceSummaryItems`

Переменные

`globalWorkspaceSummaryItems`

`regularWorkspaceSummaryItems`

`useWorkspaceSummaryItems()`

Пример использования:

`useTableHeader`

`addControlButton(column, label, position)`

Пример использования:

`useTableEditableFormattedData`

Возвращает

Поведение

Пример использования:

`useCheckingPromoPriceAndPriceFields`

Возвращает

Поведение

Пример использования:

`useActivateTabWithErrors`

Аргументы

Возвращает

Пример использования: