Form · Tinyrack Design System

Flutter 폼 필드를 검증하고 활성화된 Tinyrack 이름 값을 한 번에 모아요.

핵심 속성

속성	설명
값 수집	`values`는 이름이 있는 필드의 불변 `TRFormValues` 스냅샷을 반환하고, `save()`는 네이티브 `FormState.save()`를 먼저 실행한 뒤 같은 스냅샷을 반환해요.
비활성 필드와 읽기 전용 필드	`enabled: false`인 필드는 `TRFormValues`에서 빠져요. `readOnly: true`인 필드는 값을 그대로 담아요.
검증	`validate()`는 모든 필드 검증기가 통과했는지 반환해요. `validateGranularly()`는 네이티브 세부 검증을 실행하고 오류 집합이 비었을 때 true를 반환하며, 집합 자체는 노출하지 않아요. 폼에 아직 `FormState`가 없으면 둘 다 true를 반환해요.
검증 시점	`autovalidateMode`의 기본값은 null이라 검증을 실행할 때만 오류가 나타나요. 입력하는 동안 검증하려면 `AutovalidateMode.onUserInteraction`을 넘기세요.
변경과 초기화	필드가 바뀔 때마다 `onChanged`가 새 스냅샷과 함께 호출돼요. `reset()`은 네이티브 필드 값을 되돌린 뒤 `onChanged`를 다시 호출하고, 제출 결과 같은 애플리케이션 상태는 따로 지워야 해요.

TRFormState에는 직접 보관한 GlobalKey<TRFormState>로 접근하거나, 하위 위젯에서 TRForm.maybeOf(context)로 접근하세요. name을 선언한 필드만 TRFormValues에 담겨요.

설치

패키지를 추가한 뒤 공개 라이브러리를 가져오세요.

flutter pub add tinyrack_ui

import 'package:tinyrack_ui/tinyrack_ui.dart';

플레이그라운드

Flutter 미리보기를 불러오는 중이에요

사용법

import 'package:material_ui/material_ui.dart';
import 'package:tinyrack_ui/tinyrack_ui.dart';

class RackForm extends StatefulWidget {
  const RackForm({super.key});

  @override
  State<RackForm> createState() => _RackFormState();
}

class _RackFormState extends State<RackForm> {
  final GlobalKey<TRFormState> formKey = GlobalKey<TRFormState>();
  String submitted = '';

  @override
  Widget build(BuildContext context) => TRForm(
    key: formKey,
    child: Column(
      mainAxisSize: MainAxisSize.min,
      spacing: TRSpacing.medium,
      children: [
        TRTextField(
          name: 'rack',
          label: '랙 이름',
          validator: (value) =>
              (value ?? '').trim().isEmpty ? '랙 이름을 입력하세요.' : null,
        ),
        TRButton(
          onPressed: () {
            final state = formKey.currentState!;
            if (!state.validate()) return;
            final values = state.save();
            setState(() => submitted = values['rack']?.toString() ?? '');
          },
          child: const Text('저장'),
        ),
        if (submitted.isNotEmpty)
          TRText(submitted, variant: TRTextVariant.bodySm),
      ],
    ),
  );
}

예시

값 수집과 초기화 고유 링크

제출하면 `save()`로 이름 있는 필드를 읽어요. 초기화는 초기값을 되돌리고, 제출 결과는 애플리케이션이 직접 지워요.

Flutter 미리보기를 불러오는 중이에요

필수 제출과 복구 고유 링크

비운 채로 제출하면 검증 메시지가 보이고, 랙 이름을 입력한 뒤 다시 제출하면 통과해요. `validate()`가 `save()` 읽기를 막아 줘요.

Flutter 미리보기를 불러오는 중이에요

서버 오류와 복구 고유 링크

거절된 이름은 검증기 대신 `errorText`로 돌아와요. 입력하는 동안 `onChanged`가 오류를 지우고, `reset()`은 필드를 되돌리며 결과는 애플리케이션이 직접 지워요.

Flutter 미리보기를 불러오는 중이에요

실시간 스냅샷과 세부 검증 고유 링크

입력하면 `onChanged`가 스냅샷을 알려줘요. 비활성 리전 필드는 `TRFormValues`에서 빠지고, `validateGranularly()`는 제출을 만들지 않고 검증해요.

Flutter 미리보기를 불러오는 중이에요

API

TRForm 속성

Prop	타입 / 기본값	용도
`child`	`Widget (required)`	폼 필드를 담는 하위 트리예요.
`autovalidateMode`	`AutovalidateMode?`	네이티브 폼이 다시 검증하는 시점을 정해요. null이면 명시적으로 호출할 때만 검증해요.
`onChanged`	`ValueChanged<TRFormValues>?`	필드가 바뀐 뒤와 `reset()` 뒤에 새 스냅샷과 함께 호출돼요.
`canPop`	`bool?`	저장하지 않은 입력이 있을 때 라우트 팝을 막도록 네이티브 `Form`에 전달돼요.
`onPopInvokedWithResult`	`PopInvokedWithResultCallback<Object?>?`	네이티브 `Form`에 전달되어 팝 시도 뒤에 호출돼요.

TRFormState 멤버

Prop	타입 / 기본값	용도
`values`	`TRFormValues`	`save()`를 실행하지 않고 가져오는, 활성화된 이름 있는 필드의 스냅샷이에요.
`save()`	`TRFormValues`	`FormState.save()`를 실행하고 그 결과 스냅샷을 반환해요.
`validate()`	`bool`	모든 필드 검증기를 실행하고 전부 통과했는지 반환해요.
`validateGranularly()`	`bool`	네이티브 세부 검증 API로 검증하고, 오류를 보고한 필드가 없으면 true를 반환해요.
`reset()`	`void`	네이티브 필드 값을 되돌리고 새 스냅샷으로 `onChanged`를 호출해요.
`TRForm.maybeOf`	`TRFormState? Function(BuildContext)`	하위 위젯에서 감싸는 폼 상태를 찾고, `TRForm` 밖에서는 null을 반환해요.

TRFormValues 멤버

Prop	타입 / 기본값	용도
`operator []`	`Object? Function(String name)`	이름으로 필드 값 하나를 읽고, 이름이 없으면 null을 반환해요.
`contains`	`bool Function(String name)`	스냅샷이 그 이름을 담고 있는지 알려줘요. 비활성 필드는 화면에 있어도 빠져 있어요.
`entries`	`Iterable<MapEntry<String, Object?>>`	수집한 이름과 값 쌍을 순회해요.
`toMap()`	`Map<String, Object?>`	인코딩이나 전송을 위해 스냅샷을 일반 맵으로 복사해요.