0Pricing
React Academy · Aula

Escrevendo histórias CSF3

Exporte um objeto meta padrão e histórias nomeadas usando o Component Story Format 3.

Escrevendo histórias CSF3 é uma aula grátis de React Academy no CoddyKit. Esta é a aula 2 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 que é CSF3

O Component Story Format 3 (CSF3) é o formato atual de histórias do Storybook. As histórias são objetos simples de JavaScript/TypeScript — não é necessária uma função de renderização nos casos simples.

A exportação Meta

Todo arquivo de história deve ter uma exportação padrão — o objeto Meta — que descreve o componente e define a configuração compartilhada da história.

import type { Meta } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'UI/Button',     // Storybook sidebar path
  component: Button,
  tags: ['autodocs'],     // enables auto-generated docs page
};

export default meta;

Exportações de histórias nomeadas

Cada exportação nomeada do arquivo é uma história. No CSF3, uma história é um objeto com uma propriedade args, que contém as propriedades do componente.

import type { StoryObj } from '@storybook/react';

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: { label: 'Click me', variant: 'primary' },
};

export const Secondary: Story = {
  args: { label: 'Cancel', variant: 'secondary' },
};

export const Disabled: Story = {
  args: { label: 'Unavailable', disabled: true },
};

Herança de histórias

As histórias herdam os argumentos do objeto meta. Defina os valores padrão compartilhados em meta.args e substitua-os por história quando necessário.

const meta: Meta<typeof Button> = {
  component: Button,
  args: {
    onClick: fn(), // from @storybook/test
    disabled: false,
  },
};

export const Large: Story = {
  args: { size: 'large', label: 'Large Button' }, // merges with meta args
};

Substituição da função de renderização

Forneça uma função render em uma história para casos complexos que precisem de um envolvimento JSX personalizado ou de várias instâncias.

export const WithIcon: Story = {
  render: (args) => (
    <div style={{ display: 'flex', gap: 8 }}>
      <Button {...args} icon={<StarIcon />} />
      <Button {...args} icon={<HeartIcon />} />
    </div>
  ),
  args: { label: 'Action' },
};

Decoradores em histórias individuais

Adicione uma matriz decorators a uma história para envolvê-la em provedores ou layouts adicionais somente nessa história.

export const InsideCard: Story = {
  decorators: [
    (Story) => (
      <div style={{ padding: 24, background: '#f5f5f5' }}>
        <Story />
      </div>
    ),
  ],
  args: { label: 'Card Button' },
};

Parâmetros nas histórias

Use parameters para configurar complementos por história, como definir o plano de fundo ou a área de visualização para um estado específico.

export const DarkMode: Story = {
  parameters: {
    backgrounds: { default: 'dark' },
  },
  args: { label: 'Dark Button', variant: 'primary' },
};

A tag de documentação automática

Adicionar tags: ['autodocs'] ao meta gera uma página de documentação automática com uma tabela de propriedades e exemplos interativos de todas as histórias nomeadas.

Uma história para cada estado

Escreva uma história para cada estado significativo do componente: vazio, carregando, erro, um item, vários itens, disposição RTL etc.

export const Loading: Story = { args: { isLoading: true } };
export const Error: Story = { args: { error: 'Failed to load' } };
export const Empty: Story = { args: { items: [] } };
export const WithData: Story = { args: { items: mockUsers } };

Convenções de nomenclatura

Use nomes de histórias em PascalCase que descrevam o estado. Evite nomes genéricos como Default — seja específico: PrimaryDisabled, SecondaryWithIcon.

Agrupando histórias com title

O title no meta usa a notação com barras para criar grupos aninhados na barra lateral do Storybook: 'Forms/Input' cria um grupo Forms com o subgrupo Input.

const meta: Meta<typeof TextInput> = {
  title: 'Forms/TextInput',
  component: TextInput,
};
// Sidebar: Forms → TextInput → Primary, Error, Disabled...

Reutilizando histórias nos testes

As histórias do CSF3 são objetos simples, portanto você pode importá-las e compô-las em testes unitários ou em outras histórias.

import { Primary } from './Button.stories';

test('renders primary button', () => {
  render(<Button {...Primary.args} />);
  expect(screen.getByText('Click me')).toBeInTheDocument();
});

Verificação rápida

No CSF3, como você define as propriedades ou o estado de uma história?

Recapitulação

As histórias do CSF3 são objetos tipados com args. Defina os valores padrão compartilhados em meta.args, substitua-os por história, use render para JSX personalizado e adicione tags: ['autodocs'] para gerar documentação automaticamente. Escreva uma história para cada estado significativo do componente.

Perguntas Frequentes

A aula “Escrevendo histórias CSF3” é grátis?

Sim — o texto completo de “Escrevendo histórias CSF3” é 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 “Escrevendo histórias CSF3”?

Exporte um objeto meta padrão e histórias nomeadas usando o Component Story Format 3. 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 2 de 4.

Quanto tempo leva a aula “Escrevendo histórias CSF3”?

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. Configurando o Storybook em um projeto React
  2. Escrevendo histórias CSF3
  3. Args, controles e o complemento Actions
  4. Testes do Storybook e regressão visual
← Voltar para React Academy