Dynamic question type
O tipo de pergunta dinâmico permite que o tipo de widget de um campo seja determinado em tempo de execução com base numa resposta de API ou valor calculado.
A funcionalidade Tipo de Pergunta Dinâmico permite que o widget de entrada e o comportamento de validação de um campo sejam determinados em tempo de execução em vez de no momento do design do formulário. Esta é uma extensão avançada do rtSurvey usada quando o tipo de dados a recolher depende de uma configuração do lado do servidor, resposta de API ou valor de campo precedente.
Um caso de uso comum é uma lista de verificação de inspeção configurável onde o servidor define quais campos são obrigatórios, que tipo são (texto, inteiro, seleção, etc.) e que opções estão disponíveis — sem reconstruir o formulário para cada configuração.
Como funciona
Um campo marcado como tipo de pergunta dinâmico usa callapi() para obter a sua configuração de uma API. A resposta da API define:
- O tipo de entrada a renderizar (text, integer, select_one, etc.)
- As escolhas disponíveis (para tipos de seleção)
- Regras de validação
O campo é marcado internamente com specialFeature: isDynamicQuestionType, o que indica ao motor do formulário para usar a resposta da API para construir o widget em vez da definição estática do formulário.
Configuração
Passo 1: Obter a configuração do campo
Use um campo calculate com callapi() para recuperar a configuração dinâmica:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | field_config | callapi | callapi('POST', 'https://api.example.com/field-config', 1, 2, 0, '$.config', 10000, 0, '', '', '{"form_id": "##form_id##", "field_id": "inspection_result"}') |
Passo 2: Referenciar a configuração no campo dinâmico
O campo dinâmico usa callapi-verify() na sua appearance ou constraint para ligar à configuração obtida:
| type | name | label | appearance |
|---|---|---|---|
| text | inspection_result | Resultado da inspeção | callapi-verify(dynamicParams) |
O motor do formulário lê field_config e determina dinamicamente se renderiza inspection_result como um campo text, integer ou select_one.
Formato de resposta da API
A API deve devolver um objeto JSON descrevendo a configuração do campo. Uma resposta típica:
{
"config": {
"type": "select_one",
"choices": [
{"value": "pass", "label": "Aprovado"},
{"value": "fail", "label": "Reprovado"},
{"value": "na", "label": "N/A"}
],
"required": true,
"constraint": ". != ''"
}
}
Exemplo: Formulário de inspeção configurável
Um formulário de inspeção onde os itens da lista de verificação e os seus tipos de resposta são obtidos de um servidor com base na categoria de inspeção:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| select_one inspection_type | insp_type | Tipo de inspeção | ||
| calculate | checklist_config | callapi | callapi('POST', 'https://api.example.com/checklist', 1, 2, 0, '$.items', 10000, 0, '', '', '{"type": "##insp_type##"}') | |
| text | item_1 | Item 1 | callapi-verify(dynamicParams) | |
| text | item_2 | Item 2 | callapi-verify(dynamicParams) | |
| text | item_3 | Item 3 | callapi-verify(dynamicParams) |
O servidor devolve o tipo de widget correto, etiqueta, escolhas e validação para cada item com base em insp_type.
Melhores Práticas
- Use tipos de perguntas dinâmicos apenas quando a estrutura do campo varia genuinamente em tempo de execução — para formulários estáticos, use tipos de perguntas padrão.
- Certifique-se de que a API de configuração responde rapidamente (menos de 2 segundos) e está disponível na rede de campo.
- Defina sempre uma alternativa sensata no formulário para o caso em que a API está inacessível — um campo
textsimples com uma nota é melhor do que um widget quebrado. - Versione o esquema de resposta da sua API — alterações ao formato de resposta afetarão todos os formulários ativos que usam esse endpoint.
- Teste cada combinação de tipos de campo que a API pode devolver antes da implementação.
Limitações
- Os tipos de perguntas dinâmicos requerem conectividade de rede para obter a configuração.
- A gama completa de tipos de widget disponíveis dinamicamente depende da versão do cliente rtSurvey — teste a sua versão alvo.
- Esta é uma extensão avançada do rtSurvey sem equivalente na especificação XLSForm padrão.
- Os erros de depuração são mais difíceis de rastrear pois a definição do campo existe parcialmente no formulário e parcialmente na resposta da API.