guia completo · pt-BR

Construindo um questionário
do zero, célula por célula.

XLSForm é o padrão que transforma uma planilha comum em um formulário digital completo — com lógica de pulo, validação, GPS, fotos e vários idiomas — pronto para rodar em ODK Collect, KoboToolbox ou Enketo. Este guia constrói uma pesquisa domiciliar passo a passo e documenta todos os tipos de pergunta e configurações, com exemplos que você pode copiar e converter com rxform.

1 · Anatomia de um XLSForm

Um XLSForm é um arquivo .xlsx (ou .xls/.ods) com até três abas principais:

• survey — as perguntas, na ordem em que aparecem. Colunas mínimas: type, name e label.
• choices — as listas de opções das perguntas de múltipla escolha. Colunas mínimas: list_name, name e label.
• settings — título, identificador, versão, idioma padrão e outras configurações do formulário (uma única linha de dados).

Regras de ouro para a coluna name (vale para perguntas, grupos e opções):

2 · O primeiro formulário

O menor formulário útil tem três linhas na aba survey:

A pergunta da linha 4 usa a lista sim_nao, definida na aba choices:

E a aba settings dá identidade ao formulário:

Converta e pronto:

$ rxform pesquisa_domiciliar.xlsx
pesquisa_domiciliar.xml

3 · Todos os tipos de pergunta

Texto e números

• text — texto livre. Para caixas maiores, use parameters = rows=5.
• integer / decimal — números com teclado numérico no aparelho.
• range — controle deslizante; limites via parameters = start=0 end=10 step=1. Com appearance = rating vira estrelas.

Datas e horas

Aparências úteis para date: month-year, year e no-calendar.

Escolhas e listas

• select_one LISTA — uma resposta. appearance: minimal (menu suspenso), likert, quick (avança sozinho), columns…
• select_multiple LISTA — várias respostas; gravadas separadas por espaço, por isso os name das opções não podem conter espaço.
• rank LISTA — o respondente ordena as opções.
• select_one LISTA or_other — acrescenta a opção “Other” e uma pergunta automática “Specify other.”.

Colunas extras na aba choices são permitidas e viram dados da opção — a base dos filtros em cascata:

Seleções em cascata (choice_filter)

No filtro, colunas da lista aparecem pelo nome (uf) e respostas anteriores como ${uf}. Para embaralhar opções: parameters = randomize=true (com seed=42 para ordem reproduzível).

Localização

geopoint captura um ponto (com precisão-alvo em metros via parameters); geotrace, uma linha; geoshape, um polígono fechado.

Mídia e arquivos

image com appearance = signature vira campo de assinatura; draw, desenho livre. max-pixels reduz o tamanho das fotos no aparelho.

Notas e confirmações

• note — texto exibido, sem resposta. Aceita ${referências}: “Obrigado, ${entrevistador}!”. É o único tipo que dispensa name (o rxform gera um automaticamente).
• acknowledge — exige um “ok” explícito de quem responde.

Campos invisíveis

calculate computa um valor com XPath (funções como if(), concat(), selected(), count(), round()…); hidden guarda um valor preenchível por default ou por integrações.

Metadados — coletados sozinhos

• start/end — carimbo de início/fim do preenchimento; today — a data; deviceid, username, phonenumber, email — identificação do aparelho/conta.
• audit — trilha de auditoria do preenchimento; com parameters = location-priority=balanced location-min-interval=60 location-max-age=120 registra também a localização ao longo da entrevista.
• start-geopoint — captura silenciosa da localização ao abrir; background-audio grava o áudio da entrevista; background-geopoint captura a localização quando a pergunta do trigger for respondida.

4 · Lógica do formulário

Toda a lógica usa ${nome} para referenciar respostas anteriores.

relevant — pular perguntas

A pergunta só aparece quando a expressão é verdadeira. Combine condições com and/or; para múltipla escolha use selected(${servicos}, 'agua').

constraint — validar respostas

O ponto . é a própria resposta. A mensagem aparece quando a regra falha.

required, default, read_only

• required = yes (ou uma expressão) impede avançar sem resposta.
• default aceita valor fixo (42) ou expressão dinâmica (today(), ${uf}) avaliada ao abrir o formulário — inclusive ${last-saved#setor} para herdar o valor do último envio.
• read_only = yes mostra sem permitir edição.

trigger — recalcular quando algo muda

Com trigger, o campo é (re)definido sempre que a pergunta referenciada mudar — aqui, limpando criancas quando moradores é alterado. Se houver calculation, ela roda nesse momento (em vez de continuamente).

5 · Grupos, repetições e loops

Grupos

• appearance = field-list mostra todas as perguntas do grupo numa tela só.
• table-list — para uma sequência de select_one com a mesma lista, exibe formato de matriz (linhas × colunas).
• O relevant do grupo vale para tudo dentro dele.

Repetições

O bloco se repete uma vez por morador. Sem repeat_count, o entrevistador adiciona repetições manualmente; com uma expressão (ou número fixo), a quantidade é automática. Dentro da repetição, use position(..) para saber o índice atual e indexed-repeat() para ler valores de outra repetição.

Loops sobre uma lista

Gera um bloco por opção da lista servicos, substituindo %(label)s e %(name)s pelo rótulo/nome de cada opção — uma pergunta “Como avalia o serviço de Água?”, outra “…de Esgoto?”, e assim por diante.

6 · Múltiplos idiomas

Basta sufixar as colunas traduzíveis com ::Idioma (código): funciona para label, hint, guidance_hint, constraint_message, required_message, image, audio e video — nas abas survey e choices. Defina o idioma inicial em settings → default_language = Português (pt). O aplicativo ganha um menu para alternar idiomas.

Mídia por pergunta: as colunas image/audio/video associam arquivos (ex.: cartao_resposta.jpg) enviados junto com o formulário.

7 · Aparências (appearance)

8 · Parâmetros (parameters)

A coluna parameters recebe pares chave=valor separados por espaço:

9 · A aba settings

10 · Dados externos e entities

Listas grandes em arquivo

O CSV precisa de colunas name e label (ou indique outras com parameters = value=codigo label=descricao); GeoJSON usa id/title e habilita appearance = map. O arquivo é enviado ao servidor junto com o formulário.

Consultas com pulldata()

Busca em metas.csv a coluna meta da linha em que setor = resposta. Há ainda ${last-saved#campo} (valor do último envio salvo) e a aba entities, que permite ao formulário criar e atualizar cadastros compartilhados entre formulários (ex.: cadastrar domicílios numa visita e reencontrá-los na seguinte) — com save_to nas perguntas e create_if/update_if/label na aba.

11 · Erros comuns — e como o rxform avisa

• Tipo digitado errado → [sheet 'survey', row 3, column 'type'] unknown question type 'integr' — did you mean 'integer'?
• Referência quebrada → '${idadde}' does not match… — did you mean 'idade'?
• Lista inexistente → aponta a linha e sugere a lista mais parecida.
• Grupo sem fechar → aponta a linha do begin_group e pede o end_group.
• Nomes duplicados entre irmãos, nome com espaço/acento, pergunta visível sem label, opções repetidas na lista — todos com aba, linha, coluna e causa provável.

12 · Converter e publicar

# converter
$ rxform pesquisa_domiciliar.xlsx
pesquisa_domiciliar.xml

# conferir erros de autoria é só rodar — a mensagem aponta a célula
$ rxform pesquisa_domiciliar.xlsx --stdout > /dev/null

1. KoboToolbox: você pode subir o próprio .xlsx (o Kobo converte no servidor com pyxform — o rxform gera exatamente o mesmo XML, então serve como validação local instantânea) ou implantar o XML via API.
2. ODK Central: publique o .xlsx ou o .xml gerado; anexe os CSVs/GeoJSON de listas externas.
3. Enketo: os formulários publicados ganham link web automaticamente.

guia · rxform — voltar ao início · referência oficial xlsform.org