Ao criar um app com Swift, talvez você já tenha capturado um erro com do-catch e depois percebido que a mensagem exibida na tela não ajudava muito.
Se você usar error.localizedDescription diretamente, é fácil acabar exibindo ao usuário mensagens enigmáticas como “The operation couldn’t be completed…”.
Vamos começar pela conclusão.
Para definir mensagens de erro personalizadas que serão exibidas ao usuário no Swift, adote o protocolo
LocalizedErrorem vez deErrore implemente a propriedadeerrorDescription.
Hoje vamos explicar esse método passo a passo, com exemplos.
Por que Error não é suficiente?
Muita gente definiria o erro desta forma.
enum LoginError: Error {
case invalidPassword
case userNotFound
}Se você deixar apenas isso e imprimir error.localizedDescription, verá a mensagem genérica criada pelo sistema, e não a esperada “A senha está incorreta”.
Isso acontece porque o próprio protocolo Error não oferece um lugar para definir uma mensagem legível para as pessoas.
É aí que entra o LocalizedError.
Como definir mensagens de erro personalizadas no Swift?
É simples: adote LocalizedError e implemente errorDescription.
Este é um exemplo que adiciona uma mensagem para o usuário a erros de login.
extension LoginError: LocalizedError {
var errorDescription: String? {
switch self {
case .invalidPassword:
return "A senha está incorreta."
case .userNotFound:
return "O usuário não existe."
}
}
}Agora, ao chamar error.localizedDescription, a mensagem que definimos será exibida exatamente como está.
O ponto principal é que o tipo de retorno de errorDescription é String?, ou seja, um opcional.
Se você retornar nil aqui, voltará à mensagem padrão do sistema. Por isso, é importante preencher um valor para todos os casos.
Existe algo além de errorDescription? (failureReason e recoverySuggestion)
Sim. O LocalizedError também tem outras propriedades que podem ser implementadas opcionalmente.
As funções ficam resumidas nesta tabela.
| Propriedade | Função | Mensagem de exemplo |
|---|---|---|
errorDescription |
O que deu errado | “Falha no login.” |
failureReason |
Por que aconteceu | “A senha foi digitada incorretamente 5 vezes.” |
recoverySuggestion |
Como resolver | “Tente novamente mais tarde.” |
Em especial, recoverySuggestion é útil para orientar o usuário sobre o que fazer em seguida.
Na prática, o SwiftUI, o Alert e os ambientes AppKit podem ler esses valores automaticamente e colocá-los na tela.
Para erros voltados ao usuário, costumo garantir pelo menos errorDescription e recoverySuggestion.
Não confunda logs de desenvolvimento com mensagens para o usuário
Só quero acrescentar mais um ponto.
Recomendo separar a explicação voltada ao desenvolvedor que você quer registrar durante a depuração como CustomStringConvertible (ou seja, description),
e a mensagem traduzida exibida ao usuário como LocalizedError.
Os objetivos são diferentes: uma serve para mim, e a outra, para o usuário.
Ao separar essas responsabilidades, também fica muito mais fácil adicionar NSLocalizedString quando chegar a hora de oferecer suporte a vários idiomas.
Resumindo em uma frase: “Se o erro será exibido ao usuário, vamos começar preenchendo errorDescription de LocalizedError”.
Um pequeno hábito pode transformar a experiência do usuário, então experimente aplicá-lo no seu próximo projeto. Torcendo por você! 🙌
Materiais de referência
- Create A Custom Swift Error [and override localizedDescription]
- Defining Custom Errors With Advanced Descriptions In Swift – SerialCoder.dev
- Alert and LocalizedError in SwiftUI – Augmented Code