Ambiguidade do Tamanho do Conteúdo do UIScrollView: como corrigir em 10 minutos

Introdução: A "mágica" do UIScrollView que para de funcionar

Você já se deparou com a seguinte situação: adiciona um UIScrollView ao seu projeto em Swift, configura o Auto Layout, executa o aplicativo — e nada rola? Ou, pior ainda, o Xcode exibe um erro misterioso: "UIScrollView scrollable content size ambiguity"? Se sim — você não está sozinho. Essa questão acumulou milhares de visualizações no Stack Overflow, e hoje vamos entender de uma vez por todas qual é o problema.

Imagine: você cria uma tela com um longo formulário de registro ou um artigo que não cabe em uma única tela. Você adiciona um UIScrollView, coloca todos os elementos dentro, define as constraints — e... silêncio. A rolagem não funciona. Familiar? Bem-vindo ao clube dos desenvolvedores que amaldiçoaram o Auto Layout por sua "falta de compreensão".

Na verdade, o problema da Ambiguidade do Tamanho do Conteúdo não é um bug do iOS, mas uma armadilha lógica. O sistema simplesmente não sabe quão grande o seu conteúdo deve ser. Neste tutorial, vamos analisar a causa, três maneiras de resolver e escrever código funcional real. Vamos lá!

O que é a Ambiguidade do Tamanho do Conteúdo e por que ela ocorre?

O UIScrollView é uma fera especial no mundo do UIKit. Ao contrário das views comuns, ele não determina seu tamanho com base nas constraints dos elementos filhos. Em vez disso, ele usa a propriedade contentSize (tipo CGSize), que indica o quão grande é a "tela interna". Se o contentSize for menor ou igual ao tamanho do próprio UIScrollView, a rolagem... bem, não é necessária.

O erro Scrollable Content Size Ambiguity ocorre quando o Auto Layout não consegue calcular inequivocamente o contentSize com base nas constraints dentro da scroll view. Cenários típicos:

• Você não definiu constraints para a altura ou largura do conteúdo interno.
• As constraints são "flutuantes" (por exemplo, não há conexão com o topo e a base da scroll view).
• Você usa um UIStackView dentro de um UIScrollView, mas não configurou seus tamanhos.
• Você esqueceu que o UIScrollView requer uma cadeia completa de constraints de ponta a ponta.

No console do Xcode, você verá algo como:

Unable to simultaneously satisfy constraints.Will attempt to recover by breaking constraint....UIScrollView scrollable content size ambiguity

Parece assustador, mas a solução é simples. Vamos escrever o código.

Passo 1: Criar o projeto e adicionar o UIScrollView

Abra o Xcode, crie um novo projeto com o template App (iOS, Swift). Vamos chamá-lo, por exemplo, de ScrollFixDemo. Vá para ViewController.swift e substitua todo o código pelo seguinte:

import UIKit

class ViewController: UIViewController {        override func viewDidLoad() {        super.viewDidLoad()        setupScrollView()    }        private func setupScrollView() {        // 1. Criar o UIScrollView        let scrollView = UIScrollView()        scrollView.translatesAutoresizingMaskIntoConstraints = false        scrollView.backgroundColor = .systemGray6        view.addSubview(scrollView)                // 2. Constraints para o scrollView (preencher toda a tela)        NSLayoutConstraint.activate([            scrollView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),            scrollView.leadingAnchor.constraint(equalTo: view.leadingAnchor),            scrollView.trailingAnchor.constraint(equalTo: view.trailingAnchor),            scrollView.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)        ])                // 3. Criar o contentView - contêiner para todo o conteúdo        let contentView = UIView()        contentView.translatesAutoresizingMaskIntoConstraints = false        contentView.backgroundColor = .white