Advanced Repeats
Padrões avançados para grupos de repetição: contagens dinâmicas, repetições aninhadas, resumo de dados repetidos e referência a valores entre repetições.
Esta página aborda padrões avançados para trabalhar com grupos de repetição no rtSurvey. Para os conceitos básicos de configuração de um grupo de repetição, consulte Agrupamento e Repetições.
Contagem dinâmica de repetições
Por predefinição, o enumerador decide quantas vezes repetir. Pode fixar o número de repetições usando repeat_count:
| type | name | label | repeat_count |
|---|---|---|---|
| begin_repeat | household_members | Membro do agregado familiar | ${num_members} |
| text | member_name | Nome do membro | |
| integer | member_age | Idade | |
| end_repeat |
A repetição é executada exatamente ${num_members} vezes, onde num_members foi recolhido anteriormente no formulário. O enumerador não pode adicionar ou remover instâncias.
Acesso indexado: indexed-repeat()
Aceda ao valor de campo de uma instância de repetição específica de fora do grupo de repetição usando indexed-repeat(repeatedField, repeatGroup, index):
| type | name | label | calculation |
|---|---|---|---|
| calculate | first_name | indexed-repeat(${member_name}, ${household_members}, 1) | |
| calculate | second_name | indexed-repeat(${member_name}, ${household_members}, 2) |
Isto é útil para construir campos de resumo ou referenciar os dados do membro “principal” após a repetição.
Posição da instância atual: index()
Dentro de um grupo de repetição, index() devolve a posição baseada em 1 da instância atual. Use-o para rotular cada repetição ou criar identificadores únicos:
| type | name | label |
|---|---|---|
| begin_repeat | plots | Parcela |
| note | plot_label | Parcela número ${index()} |
| text | plot_id | ID da parcela |
| end_repeat |
Referenciar campos na mesma instância
Dentro de uma repetição, use ${fieldname} para referenciar outro campo na mesma instância de repetição. Não é necessário indexed-repeat() dentro do mesmo ciclo:
| type | name | label | relevant |
|---|---|---|---|
| begin_repeat | members | Membro | |
| text | member_name | Nome | |
| integer | member_age | Idade | |
| text | school_name | Nome da escola | ${member_age} < 18 |
| end_repeat |
Referenciar campos pai de dentro de uma repetição
Os campos fora (acima) do grupo de repetição podem ser referenciados normalmente com ${fieldname}:
| type | name | label |
|---|---|---|
| text | village | Nome da aldeia |
| begin_repeat | plots | Parcela agrícola |
| note | plot_context | Parcelas em ${village} |
| end_repeat |
Resumir dados de repetição
Use funções de agregação de repetição fora do grupo de repetição para resumir:
| Função | Exemplo | Descrição |
|---|---|---|
count(group) | count(${household_members}) | Número de instâncias |
sum(field) | sum(${loan_amount}) | Soma de um campo numérico |
min(field) | min(${member_age}) | Valor mínimo |
max(field) | max(${member_age}) | Valor máximo |
join(sep, field) | join(', ', ${member_name}) | Lista separada por vírgulas |
count-if(group, expr) | count-if(${members}, ${member_age} < 18) | Contagem condicional |
sum-if(field, expr) | sum-if(${loan_amount}, ${loan_amount} > 500) | Soma condicional |
join-if(sep, field, expr) | join-if(', ', ${name}, ${age} >= 18) | Junção condicional |
Exemplo: Resumo do agregado familiar
| type | name | label | calculation |
|---|---|---|---|
| integer | num_members | Quantos membros? | |
| begin_repeat | members | Membro | ${num_members} |
| text | member_name | Nome | |
| integer | member_age | Idade | |
| end_repeat | |||
| calculate | total_members | count(${members}) | |
| calculate | children_count | count-if(${members}, ${member_age} < 18) | |
| calculate | adult_names | join-if(', ', ${member_name}, ${member_age} >= 18) | |
| note | summary | ${total_members} membros; ${children_count} com menos de 18 anos. Adultos: ${adult_names} |
Repetições aninhadas
Um grupo de repetição pode conter outro grupo de repetição. Use isto com cuidado — as repetições aninhadas adicionam complexidade e podem ser confusas para os enumeradores.
| type | name | label |
|---|---|---|
| begin_repeat | households | Agregado familiar |
| text | hh_id | ID do agregado familiar |
| begin_repeat | hh_members | Membro |
| text | member_name | Nome do membro |
| end_repeat | ||
| end_repeat |
Para referenciar um campo numa repetição exterior a partir da repetição interior, use ${fieldname} — resolve para o ancestral correspondente mais próximo:
Dentro da repetição hh_members, ${hh_id} devolve o ID do agregado familiar atual, não de todos os agregados.
Rank dentro de grupos de repetição: rank-index()
Quando um campo rank existe dentro de uma repetição, use rank-index(instanceNumber, repeatedField) de fora para obter a classificação ordinal de uma instância específica:
| type | name | label | calculation |
|---|---|---|---|
| calculate | top_scorer | rank-index(1, ${score}) |
rank-index(1, ${score}) devolve o índice de instância da pontuação mais alta.
Melhores Práticas
- Use sempre
repeat_countquando o número de repetições é conhecido antecipadamente — evita que os enumeradores adicionem ou removam instâncias acidentalmente. - Mantenha os grupos de repetição focados — uma repetição com 20+ perguntas por instância é difícil de navegar.
- Nomeie os grupos de repetição claramente (por ex.,
household_members, nãorepeat1) — o nome aparece em chamadas de função e dados exportados. - Teste com o número máximo esperado de instâncias para verificar o desempenho.
- Use a aparência
field-listno grupo de repetição para mostrar todos os campos num ecrã por instância (móvel).
Limitações
indexed-repeat()requer um índice válido (1 até contagem de instâncias) — índices fora do intervalo devolvem vazio.- As repetições aninhadas além de 2 níveis não são recomendadas e podem causar problemas de exibição em alguns clientes.
- As funções de agregação (
sum,count, etc.) operam em todo o grupo de repetição — não pode agregar um subconjunto de instâncias sem variantes*-if.