---
title: ✍️ Entrada de texto
description: "## ✍️ Escribir cun `TextField` No Tema 3.3 utilizamos un campo de texto para editar un nome. Agora veremos como **recoller o texto que escribe o usuario e utilizalo na nosa aplicación**. Para iso empregamos `TextField`, un widget que permite…"
url: "https://www.drodicio.com/docs/flutter/tema-5-navegacion/inputs/"
updated: "2026-10-12"
category: Tema 5. Interaccion, formularios e navegacion
---

# ✍️ Entrada de texto

## ✍️ Escribir cun `TextField`

No Tema 3.3 utilizamos un campo de texto para editar un nome. Agora veremos como **recoller o texto que escribe o usuario e utilizalo na nosa aplicación**.

Para iso empregamos `TextField`, un widget que permite introducir texto mediante o teclado.

![Campo de texto para introducir un nome e botón Saudar](https://www.drodicio.com/wp-content/uploads/2026/10/textfield.png)
Campo de texto para introducir un nome e botón Saudar

Por defecto, o campo permite escribir nunha soa liña, pero podemos utilizar `maxLines` para permitir varias.

Estas son algunhas das súas propiedades máis importantes:

| Propiedade | Para que serve? |
| --- | --- |
| `controller` | Permite consultar ou modificar o texto desde o código. |
| `decoration` | Permite engadir unha etiqueta (`labelText`), unha pista (`hintText`) ou un bordo. |
| `keyboardType` | Indica o tipo de teclado que queremos mostrar, por exemplo, numérico. Non valida o contido. |
| `obscureText` | Oculta visualmente o texto introducido, por exemplo, nun contrasinal. |
| `onChanged` | Executa unha función cada vez que o usuario modifica o texto. |
| `onSubmitted` | Executa unha función cando o usuario confirma a entrada desde o teclado. |

## 🎛️ Para que serve o controlador?

O `TextField` permite escribir texto, pero necesitamos unha forma de **recuperar ese texto desde o noso código**.

Para iso utilizamos un `TextEditingController`.

Primeiro creamos o controlador:

```dart
final _controlador = TextEditingController(text: 'Diego');
```

Neste caso, o campo comezará mostrando o texto «Diego».

Despois asociámolo ao `TextField` mediante a propiedade `controller`:

```dart
TextField(
  controller: _controlador,
)
```

A partir dese momento podemos consultar o texto introducido mediante:

```dart
_controlador.text
```

Por exemplo, se o usuario escribe «Iria», `_controlador.text` conterá o texto `'Iria'`.

Tamén podemos modificar o contido do campo desde o código:

- **`_controlador.text = 'Xurxo'`** substitúe o texto actual por «Xurxo».
- **`_controlador.clear()`** borra todo o texto do campo.

> 💡 **Lembra:** o controlador créase como atributo do `State`, fóra de `build`, e libérase mediante `dispose()` cando ese estado se elimina. Así evitamos crear un controlador novo cada vez que se reconstrúe a interface.

## 🧪 Ler o texto ao premer un botón

Neste exemplo crearemos unha aplicación cun campo para introducir un nome e un botón «Saudar».

Cando prememos o botón:

1. Recuperamos o texto introducido mediante `_controlador.text`.
2. Eliminamos os espazos que poida haber ao principio ou ao final.
3. Comprobamos se o usuario escribiu algún nome.
4. Mostramos un saúdo ou unha mensaxe indicando que debe escribir un nome.

![Campo de texto para introducir un nome e botón Saudar](https://www.drodicio.com/wp-content/uploads/2026/10/textfield.png)
Campo de texto para introducir un nome e botón Saudar

Para iso utilizamos o seguinte método:

```dart
void _saudar() {
  final nome = _controlador.text.trim();

  setState(() {
    if (nome.isEmpty) {
      _saudo = 'Escribe un nome';
    } else {
      _saudo = 'Ola, $nome!';
    }
  });
}
```

Neste código utilizamos dúas operacións:

- **`.trim()`** elimina os espazos que haxa ao principio e ao final do texto.
- **`.isEmpty`** comproba se o texto está baleiro.

Por exemplo, se o usuario introduce só espazos, `trim()` elimínaos e `isEmpty` permite detectar que non escribiu ningún nome.

Finalmente, `setState()` actualiza a interface para mostrar a mensaxe correspondente.

### 🧪 Exemplo completo

> 🔗 DartPad:
>
>
>
> - [`https://dartpad.dev/?id=844e47227983d770ea746749b07b616b`](https://dartpad.dev/?id=844e47227983d770ea746749b07b616b).

[https://dartpad.dev/embed-inline.html?id=844e47227983d770ea746749b07b616b](https://dartpad.dev/embed-inline.html?id=844e47227983d770ea746749b07b616b)

![Lectura do nome cun controlador e presentación do saúdo](https://www.drodicio.com/wp-content/uploads/2026/10/textfield_exemplo.png)
Lectura do nome cun controlador e presentación do saúdo

### 🔍 Que sucede ao premer «Saudar»?

1. O campo comeza mostrando o texto **«Diego»**, porque así o indicamos ao crear o controlador.
2. O usuario pode borrar ese texto e escribir outro nome, por exemplo, «Iria».
3. Ao premer «Saudar», executamos o método `_saudar()`.
4. Recuperamos o texto mediante `_controlador.text` e eliminamos os espazos dos extremos con `trim()`.
5. Se o texto está baleiro, mostramos «Escribe un nome». En caso contrario, mostramos **«Ola, Iria!»**.
6. `setState()` actualiza a interface para mostrar a nova mensaxe.

## 🔔 Reaccionar mentres se escribe

No exemplo anterior utilizamos un controlador para recuperar o texto cando prememos un botón.

Pero tamén podemos facer que a aplicación **reaccione automaticamente cada vez que o usuario escribe ou borra un carácter**.

Para iso utilizamos a propiedade `onChanged`:

```dart
TextField(
  decoration: const InputDecoration(labelText: 'Nome'),
  onChanged: (nome) {
    setState(() {
      _saudo = 'Ola, $nome!';
    });
  },
)
```

Neste exemplo:

- **`onChanged`** executa a función cada vez que o usuario modifica o texto.
- **`nome`** contén o texto que hai no campo nese momento.
- **`setState()`** actualiza a interface para mostrar o novo saúdo.

Por exemplo, se o usuario escribe «Roi», a mensaxe irá cambiando mentres introduce os caracteres:

```plain
R     → Ola, R!
Ro    → Ola, Ro!
Roi   → Ola, Roi!
```

Neste caso non necesitamos un `TextEditingController`, porque `onChanged` xa nos proporciona o texto introducido.

Para probar esta alternativa, podemos substituír o `TextField` do exemplo anterior polo novo campo e eliminar o botón «Saudar». Tamén debemos eliminar o controlador e o método `_saudar()`, xa que non os necesitamos. Retiramos ademais o método `dispose()` deste exemplo: só liberaba ese controlador, que xa non existe. Mantemos a variable `_saudo` e o `Text(_saudo)` para mostrar a mensaxe.

## 🔍 Cando utilizamos cada mecanismo?

Podemos recuperar o texto dun `TextField` de diferentes maneiras:

| Mecanismo | Cando utilizalo? |
| --- | --- |
| `TextEditingController` | Cando necesitamos consultar o texto desde o código, por exemplo, ao premer un botón. |
| `onChanged` | Cando queremos reaccionar automaticamente mentres o usuario escribe. |

Ambos os mecanismos poden utilizarse nunha mesma aplicación, pero nos exemplos anteriores empregamos cada un por separado para comprender mellor o seu funcionamento.

> 📚 Consulta:
>
>
>
> - [TextField → `https://api.flutter.dev/flutter/material/TextField-class.html`](https://api.flutter.dev/flutter/material/TextField-class.html).
> - [TextEditingController → `https://api.flutter.dev/flutter/widgets/TextEditingController-class.html`](https://api.flutter.dev/flutter/widgets/TextEditingController-class.html).