---
title: "Пользовательское поле"
description: "Создайте поле рейтинга на PHP и Vue, свяжите значение с формой и добавьте отдельное отображение для просмотра и таблицы."
canonical_url: "https://frame.qubeek.io/ru/developers/fields/custom"
---
# Пользовательское поле

> Создайте поле рейтинга на PHP и Vue, свяжите значение с формой и добавьте отдельное отображение для просмотра и таблицы.

Кастомное (пользовательское) поле связывает серверный `type` с Vue-компонентом. На примере рейтинга `0…5` добавим PHP-класс, редактор и регистрацию. Такой редактор и отдельный preview есть в UI demo: `apps/demo/src/components/RatingField.vue` и `RatingPreview.vue`. Ниже — самостоятельный пример без зависимости от стилей demo.

Если нужен URL-идентификатор, используйте готовый серверный [Slug](https://frame.qubeek.io/ru/developers/fields/slug). Новый PHP-класс для него не нужен.

## Сервер: тип, метаданные и значение

Создайте класс в Laravel-приложении. `Field` даёт `make()`, чтение и заполнение атрибута, валидацию и сериализацию. Контракт `Frame\Core\Contracts\Resolvable` отмечает поле со значением.

```php [app/Frame/Fields/Rating.php]
<?php

declare(strict_types=1);

namespace App\Frame\Fields;

use Frame\Core\Contracts\Resolvable;
use Frame\Laravel\Fields\Field;

final class Rating extends Field implements Resolvable
{
    public string $type = 'rating';

    protected function boot(): void
    {
        $this->withMeta(['max' => 5]);
        $this->default(0);
        $this->rules(['integer', 'between:0,5']);
    }
}
```

В примере предполагается существующая модель `App\Models\Post` с целочисленной колонкой `rating`, принимающей значения `0…5`, и cast `rating` в `integer`. Создайте колонку своей миграцией до сохранения записей. `default(0)` задаёт значение для отображения, а не SQL-default колонки.

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

```php [app/Frame/Resources/PostResource.php]
<?php

declare(strict_types=1);

namespace App\Frame\Resources;

use App\Frame\Fields\Rating;
use App\Models\Post;
use Frame\Laravel\Resources\Resource;

class PostResource extends Resource
{
    public static string $model = Post::class;

    public function fields(): array
    {
        return [
            Rating::make('rating', 'Оценка')->required(),
        ];
    }
}
```

Не заменяйте рабочую схему ресурса целиком: перенесите импорт и элемент массива в своё `fields()`.

Без переопределений поле читает `rating` из модели, а при заполнении берёт `rating` из запроса и вызывает `forceFill()` для своего ключа. Сохранение модели выполняет ресурсный pipeline. Сервер проверяет `integer`, диапазон и обязательность **до** заполнения.

`withMeta()` объединяет ключи с верхним уровнем JSON поля: компонент получит prop `max`, а не `meta.max`. Дополнительные ключи формы попадают в `componentProps`; имена `snake_case` преобразуются в `camelCase`. Не используйте для своих настроек зарезервированные `type`, `field`, `value`, `readonly` и другие ключи схемы.

## Клиент: редактор рейтинга

В Vite-приложении создайте компонент в `src/components/fields/RatingField.vue`. Значение приходит через `modelValue`, изменение отправляется событием `update:modelValue`. Подпись, подсказку и сообщения валидации выводит обёртка формы.

```vue [src/components/fields/RatingField.vue]
<script setup lang="ts">
import { computed } from 'vue'

const props = withDefaults(
  defineProps<{
    modelValue?: number | null
    max?: number
    disabled?: boolean
    readonly?: boolean
  }>(),
  { max: 5 },
)

const emit = defineEmits<{
  'update:modelValue': [value: number]
}>()

const current = computed(() => props.modelValue ?? 0)
const locked = computed(() => props.disabled || props.readonly)

function select(value: number): void {
  if (locked.value) return
  emit('update:modelValue', value === current.value ? 0 : value)
}
</script>

<template>
  <span>
    <button
      v-for="value in max"
      :key="value"
      type="button"
      :disabled="locked"
      :aria-label="`Оценка ${value} из ${max}`"
      :aria-pressed="value === current"
      @click="select(value)"
    >
      {{ value <= current ? '★' : '☆' }}
    </button>
    <span>{{ current }} / {{ max }}</span>
  </span>
</template>
```

Повторное нажатие сбрасывает оценку в `0`. Компонент не меняет props напрямую. В ресурсной форме серверный `readonly` преобразуется в `disabled`; отдельный prop `readonly` оставлен для прямого использования компонента.

Отключённая кнопка не защищает API. Серверные правила, авторизация ресурса и серверный readonly должны работать независимо от интерфейса.

## Регистрация после FramePlugin

Добавьте импорт и регистрацию в точку входа приложения. Ключ `rating` должен совпадать с PHP-свойством `$type`.

```ts [src/main.ts]
import { createApp } from 'vue'
import { FieldRegistry, Frame, FramePlugin } from '@frame/vue'
import RatingField from './components/fields/RatingField.vue'

const app = createApp(Frame)

app.use(FramePlugin, {
  path: '/',
  endpoint: '/api/frame',
})

FieldRegistry.register('rating', { component: RatingField })

app.mount('#app')
```

Сохраните свои адрес API, конфигурацию и подключение стилей. Регистрируйте пользовательские поля **после** `app.use(FramePlugin, …)` и **до** `mount()`. Установка плагина подключает стандартные renderer-ы, previews и ячейки; раннее переопределение стандартного типа может быть затёрто. Последняя регистрация одного ключа побеждает.

`FieldRegistry` и `FieldPreviewRegistry` импортируются из `@frame/vue`, не из `@frame/core`. Для нестандартного `v-model` запись реестра поддерживает `modelProp` и `modelEvent`; для этого примера достаточно стандартных имён.

## Другое хранение: resolveUsing и fillUsing

Если UI-поле не совпадает с колонкой БД, задайте оба направления. Например, `rating` в форме хранится в `meta.rating`; у модели должна быть JSON-колонка `meta` с cast в массив. Это альтернативная схема, а не дополнение к колонке `rating` из первого примера.

```php [app/Frame/Resources/PostResource.php]
<?php

declare(strict_types=1);

namespace App\Frame\Resources;

use App\Frame\Fields\Rating;
use App\Models\Post;
use Frame\Laravel\Http\Requests\FrameRequest;
use Frame\Laravel\Resources\Resource;
use Illuminate\Database\Eloquent\Model;

class PostResource extends Resource
{
    public static string $model = Post::class;

    public function fields(): array
    {
        return [
            Rating::make('rating', 'Оценка')
                ->required()
                ->resolveUsing(
                    static fn (FrameRequest $request, ?Model $model): int =>
                        (int) data_get($model, 'meta.rating', 0),
                )
                ->fillUsing(
                    static function (
                        FrameRequest $request,
                        Model $model,
                        mixed $value,
                    ): void {
                        $model->forceFill(['meta->rating' => (int) $value]);
                    },
                ),
        ];
    }
}
```

Порядок аргументов `fillUsing`: **запрос, модель, значение**, затем необязательные relation и collection связанных записей. Callback сам меняет модель; возвращённое значение не записывается автоматически. Здесь запрос валидируется до приведения к `int`.

`resolveUsing` получает запрос и модель (в том числе `null` при создании), возвращает значение для UI. Пользовательский resolver отключает сортировку и фильтрацию по умолчанию. Не включайте их без подходящего SQL-ключа и стратегии.

<warning>

Объявленный в ресурсе `fillUsing()` выполняется и для серверного readonly-поля, но получает `$value = null`. Для такого сценария пишите отдельную серверную логику, а не используйте callback выше: приведение `null` к `int` сбросит рейтинг в `0`. Не читайте клиентское значение из запроса в обход readonly.

</warning>

## Просмотр и таблица — разные каналы

Редактор не становится preview или ячейкой автоматически. Для страницы просмотра создайте компонент с prop `value`, а не `modelValue`.

```vue [src/components/fields/RatingPreview.vue]
<script setup lang="ts">
withDefaults(
  defineProps<{ value?: number | null; max?: number }>(),
  { max: 5 },
)
</script>

<template>
  <span>{{ value ?? '—' }} / {{ max }}</span>
</template>
```

Добавьте в свою точку входа импорты, а регистрацию разместите после `FramePlugin`:

```ts [src/main.ts]
import { FieldPreviewRegistry } from '@frame/vue'
import RatingPreview from './components/fields/RatingPreview.vue'

FieldPreviewRegistry.register('rating', { component: RatingPreview })
```

Preview получает `value` и контекст поля, включая дополнительные `componentProps`. Для этого рейтинга `max` приходит из метаданных detail-схемы. Статические props регистрации задаются через `props`, а не `defaultProps` редактора.

Для списка используйте отдельный `CellRegistry`. Ячейка получает `{ column, row }`; значение лежит в `row.fields[column.field].value`. Метаданные detail-поля вроде `max` **не переносятся автоматически** в `toIndexScheme()`. Поэтому здесь formatter показывает число без знаменателя.

```vue [src/components/fields/RatingCell.vue]
<script setup lang="ts">
import { computed } from 'vue'

defineOptions({ inheritAttrs: false })

const props = defineProps<{
  column: { field: string }
  row: { fields?: Record<string, { value?: unknown }> }
}>()

const text = computed(() => {
  const value = props.row.fields?.[props.column.field]?.value
  return typeof value === 'number' || typeof value === 'string' ? value : '—'
})
</script>

<template>
  <span>{{ text }}</span>
</template>
```

Зарегистрируйте ячейку после плагина тем же ключом типа:

```ts [src/main.ts]
import { CellRegistry } from '@frame/vue'
import RatingCell from './components/fields/RatingCell.vue'

CellRegistry.register('rating', { component: RatingCell })
```

`CellRegistry` выбирает ячейку по `type` колонки или `display_as`. Серверный `displayUsing(FrameRequest $request, mixed $value)` меняет сериализованное значение, а не регистрирует UI-компонент. Если форматируете только список, проверяйте `isResourceIndexRequest()` и оставляйте числовое значение формы неизменным.

## Проверка в своём приложении

На изолированном стенде проверьте полный путь значения, а не только отрисовку звёзд:

- В detail-схеме есть `type: 'rating'`, `field: 'rating'`, `max: 5` и числовой `value`.
- На создании начальное значение — `0`; выбор `3` отправляет `rating: 3`, повторный выбор — `rating: 0`.
- После сохранения и повторного открытия значение совпадает с БД; отдельно проверьте JSON-вариант, если выбрали его.
- Прямой запрос со значениями `6`, `-1` или `'wrong'` отклоняется серверной валидацией. Пустое обязательное поле тоже отклоняется.
- Readonly блокирует редактор. Подменённый HTTP-запрос не должен менять серверное readonly-поле без явно объявленной серверной логики.
- Preview получает `value`, ячейка — `row` и `column`. Их регистрация не ломает форму и не требует отсутствующего `meta.max`.

Запустите существующие тесты PHP и Vue вашего проекта на тестовой БД. Имена команд берите из его manifest и конфигурации тестов: универсальной команды Frame для проверки нового поля нет.

## Что дальше

- [Slug](https://frame.qubeek.io/ru/developers/fields/slug) — готовая серверная генерация и отдельный клиентский preview.
- [Валидация](https://frame.qubeek.io/ru/developers/fields/validation) — правила и сообщения об ошибках.
- [Общие методы](https://frame.qubeek.io/ru/developers/fields/methods) — настройки поля.
- [Видимость полей](https://frame.qubeek.io/ru/developers/fields/visibility) — где показывать поле, отдельно от серверных прав.


## Sitemap

See the full [sitemap](https://frame.qubeek.io/sitemap.md) for all pages.
