0Pricing
React Academy · Aula

Uniões discriminadas para variantes de componentes

Modele propriedades de variantes com uniões discriminadas para que o TypeScript imponha combinações válidas de propriedades.

Uniões discriminadas para variantes de componentes é uma aula grátis de React Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de React Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de React Academy inclui 4 aulas no total.

O problema das propriedades de variante

Um componente com propriedades opcionais para diferentes modos (por exemplo, um botão que pode ser um link ou um botão) pode ter combinações inválidas de propriedades. O TypeScript não consegue identificá-las sem uniões discriminadas.

O que é uma união discriminada?

Uma união discriminada é uma união de tipos que compartilham um campo de tipo literal comum (o discriminador). O TypeScript restringe o tipo com base no valor desse campo.

type Shape =
  | { kind: 'circle'; radius: number }
  | { kind: 'rectangle'; width: number; height: number };

function area(shape: Shape): number {
  if (shape.kind === 'circle') return Math.PI * shape.radius ** 2;
  return shape.width * shape.height; // TS knows width/height exist here
}

Variante de botão versus link

Modele um componente polimórfico com uma união discriminada em um campo as ou variant para impor as propriedades corretas em cada caso.

type ButtonProps =
  | { as: 'button'; onClick: () => void; disabled?: boolean; children: React.ReactNode }
  | { as: 'a'; href: string; target?: string; children: React.ReactNode };

function ActionButton(props: ButtonProps) {
  if (props.as === 'button') {
    return <button onClick={props.onClick} disabled={props.disabled}>{props.children}</button>;
  }
  return <a href={props.href} target={props.target}>{props.children}</a>;
}

Variantes do componente de alerta

Modele um alerta com dados obrigatórios diferentes para cada tipo de gravidade.

type AlertProps =
  | { type: 'success'; message: string }
  | { type: 'error'; message: string; onRetry: () => void }
  | { type: 'warning'; message: string; details?: string };

function Alert(props: AlertProps) {
  if (props.type === 'error') {
    return (
      <div className="alert error">
        <p>{props.message}</p>
        <button onClick={props.onRetry}>Retry</button>
      </div>
    );
  }
  return <div className={`alert ${props.type}`}>{props.message}</div>;
}

Restrição em manipuladores de eventos

As uniões discriminadas também funcionam com dados orientados por eventos — são excelentes para máquinas de estado ou estados baseados em ações.

type LoadingState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };

function DataView<T>({ state }: { state: LoadingState<T> }) {
  if (state.status === 'loading') return <Spinner />;
  if (state.status === 'error') return <p>{state.error.message}</p>;
  if (state.status === 'success') return <pre>{JSON.stringify(state.data)}</pre>;
  return null;
}

Verificações exaustivas com never

Adicione uma verificação de never no ramo padrão para obter um erro do TypeScript caso um novo membro da união seja adicionado, mas não seja tratado.

function assertNever(x: never): never {
  throw new Error('Unhandled case: ' + x);
}

function renderIcon(type: AlertProps['type']) {
  switch (type) {
    case 'success': return <CheckIcon />;
    case 'error': return <XIcon />;
    case 'warning': return <WarnIcon />;
    default: return assertNever(type); // TS error if a case is missing
  }
}

Uniões discriminadas para respostas de API

Modele os formatos das respostas da API como uniões discriminadas para que os chamadores tratem os caminhos de sucesso e de erro sem conversão forçada.

type ApiResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: string; code: number };

async function fetchUser(id: string): Promise<ApiResult<User>> {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) return { ok: false, error: 'Not found', code: res.status };
  return { ok: true, data: await res.json() };
}

Proteções de tipo para restrição

Use proteções de tipo personalizadas para restringir uniões em cenários mais complexos, nos quais o discriminador não é uma simples verificação de igualdade.

function isSuccess<T>(result: ApiResult<T>): result is { ok: true; data: T } {
  return result.ok === true;
}

const result = await fetchUser('1');
if (isSuccess(result)) {
  console.log(result.data.name); // TS knows data exists
}

Evitando o excesso de propriedades opcionais

Sem uniões discriminadas, os componentes acumulam propriedades opcionais que só são válidas em determinadas combinações — algo confuso e sem tipagem. As uniões discriminadas eliminam estados impossíveis.

// Bad: optional prop soup — invalid combos allowed:
interface BadProps {
  href?: string;
  onClick?: () => void;
  disabled?: boolean;
}

// Good: only valid combos via discriminated union:
type GoodProps =
  | { as: 'a'; href: string }
  | { as: 'button'; onClick: () => void; disabled?: boolean };

Compondo uniões

Use & (interseção) para adicionar propriedades compartilhadas a todos os membros de uma união.

type BaseProps = { className?: string; children: React.ReactNode };

type ButtonVariant =
  | (BaseProps & { variant: 'primary'; onClick: () => void })
  | (BaseProps & { variant: 'link'; href: string });

Discriminação em tempo de execução

O React usa o discriminador em tempo de execução para renderizar a interface correta. O TypeScript usa-o em tempo de compilação para impor o uso correto das propriedades. Ambas as camadas ficam protegidas.

Verificação rápida

O que é o discriminador em uma união discriminada?

Recapitulação

As uniões discriminadas modelam componentes com conjuntos de propriedades mutuamente exclusivos ao compartilhar um campo discriminador com tipo literal. Use never no ramo padrão para verificações exaustivas. Elas eliminam combinações inválidas de propriedades permitidas por propriedades opcionais, tornando os componentes autodocumentados e seguros quanto aos tipos.

Perguntas Frequentes

A aula “Uniões discriminadas para variantes de componentes” é grátis?

Sim — o texto completo de “Uniões discriminadas para variantes de componentes” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de React Academy, atualize para CoddyKit PRO. O curso de React Academy inclui 4 aulas no total.

O que vou aprender em “Uniões discriminadas para variantes de componentes”?

Modele propriedades de variantes com uniões discriminadas para que o TypeScript imponha combinações válidas de propriedades. Você pratica React Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar React Academy?

Nenhuma experiência prévia é necessária. React Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Uniões discriminadas para variantes de componentes”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de React Academy?

Sim. Cada aula de React Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Uniões discriminadas para variantes de componentes
  2. Tipos condicionais e mapeados no React
  3. Componentes polimórficos com a propriedade 'as'
  4. Formulários seguros quanto aos tipos e contratos de respostas de API
← Voltar para React Academy