Campos de Formulário Legados

Aspose.Words FOSS para .NET lê e manipula os campos de formulário legados (pré-controle-de-conteúdo) do Word — campos de entrada de texto, caixa de seleção e lista suspensa — através da classe FormField e suas três subclasses de campo especializadas em Aspose.Words.Fields.

Lendo Valores de Campos de Formulário

Document.Range.FormFields (um FormFieldCollection) fornece acesso direto a cada campo de formulário legado em um intervalo sem percorrer manualmente a árvore de nós. Cada FormField expõe Name (o identificador no estilo de marcador usado para referenciar o campo), Type (um valor FieldType que identifica que tipo de campo de formulário é), Result (o valor atual), Enabled, e texto de ajuda/estado via HelpText/OwnHelp e StatusText/OwnStatus. SetTextInputValue(newValue) define um novo valor para um campo de entrada de texto diretamente. Indexe em FormFieldCollection pelo nome do marcador (por exemplo, formFields["BookmarkName"]) para recuperar um campo específico, e Remove(formField) / RemoveAt(index) exclui campos da coleção.

Tipos de Campo de Texto, Caixa de Seleção e Lista Suspensa

Os três tipos de campo de formulário legados cada um tem uma classe dedicada: FieldFormText (o campo FORMTEXT, correspondente a FieldType.FieldFormTextInput) para entrada de texto livre, FieldFormCheckBox (o campo FORMCHECKBOX) para um alternador booleano, e FieldFormDropDown (o campo FORMDROPDOWN) para uma lista de seleção. No nó subjacente FormField, TextInputType (um valor TextFormFieldType — Regular, Number, Date, CurrentDate, CurrentTime ou Calculated) e TextInputFormat controlam como o valor de um campo de texto é interpretado e formatado; MaxLength delimita o comprimento da entrada; TextInputDefault fornece seu valor padrão. Checked e Default aplicam-se a campos de caixa de seleção, com IsCheckBoxExactSize/CheckBoxSize controlando seu tamanho renderizado. Campos de lista suspensa carregam sua lista de opções em DropDownItems, um DropDownItemCollection que suporta Add, Insert, Remove, Contains e IndexOf, além de DropDownSelectedIndex para o item atualmente selecionado.

Dicas e Melhores Práticas

Use Document.Range.FormFields em vez de filtrar manualmente Document.Range.Fields por tipo — é o ponto de entrada direto e tipado para campos de formulário legados.
Defina CalculateOnExit quando o valor de um campo de formulário deve acionar o recálculo de campos dependentes assim que o usuário o deixar.
FormField.EntryMacro / ExitMacro referenciam nomes de macros VBA configurados no documento original — lê-los não executa nenhum código de macro.
Verifique TextInputType antes de analisar o Result de um campo de texto como número ou data — campos Regular não impõem restrição de formato.

Problemas comuns

Problema	Causa	Correção
Indexar `FormFieldCollection` pelo nome do marcador retorna null	O nome do marcador do campo de formulário não corresponde, ou o campo não existe no intervalo pesquisado	Confirme o nome exato do marcador via `FormField.Name` durante a enumeração
O estado da caixa de seleção não é refletido após definir `Checked`	Documento não salvo após a modificação	Salve o documento após a modificação; `Checked` é lido no próximo acesso
Lista suspensa `DropDownSelectedIndex` fora do intervalo	O índice não corresponde a um item em `DropDownItems`	Valide o índice em relação a `DropDownItems.Count` antes de definir
Valor do campo de texto não aplicado	Usou atribuição direta de propriedade em vez de `SetTextInputValue`	Chame `SetTextInputValue(newValue)` no `FormField`

FAQ

Qual é a diferença entre `FormField` e `FieldFormText`/`FieldFormCheckBox`/`FieldFormDropDown`?

FormField é o nó genérico que representa qualquer campo de formulário legado, acessado através de Document.Range.FormFields. FieldFormText, FieldFormCheckBox e FieldFormDropDown são as classes específicas de campo (derivadas de Field) para cada tipo de campo ao trabalhar através da coleção geral Field.

Como obtenho todos os valores dos campos de formulário em um documento?

Enumere Document.Range.FormFields e leia Name/Result em cada FormField.

Posso adicionar opções a um campo de formulário suspenso?

Sim — FormField.DropDownItems é um DropDownItemCollection com Add(value), Insert(index, value) e Remove(name).

Esses são os mesmos que os controles de conteúdo modernos?

Não. Campos de formulário legados (FORMTEXT, FORMCHECKBOX, FORMDROPDOWN) antecedem o modelo de tags de documento estruturado (controle de conteúdo) do Word; ambos podem aparecer no mesmo documento.

API Reference Resumo

Classe / Método	Descrição
`Document.Range.FormFields`	Acesso direto a todos os campos de formulário legados em um intervalo
`FormField`	Nó genérico de campo de formulário legado: nome, tipo, resultado, estado habilitado
`FormFieldCollection`	Coleção de objetos `FormField`; indexador por nome de marcador, `Remove()`
`FieldFormText`	classe de campo `FORMTEXT`
`FieldFormCheckBox`	`FORMCHECKBOX` classe de campo
`FieldFormDropDown`	`FORMDROPDOWN` classe de campo
`TextFormFieldType`	Enum para formato de entrada de campo de texto (`Regular`, `Number`, `Date`, etc.)
`DropDownItemCollection`	Lista editável das opções de um campo suspenso

Ver também

Aspose.Words for .NET — Enterprise Documentation

Campos de Formulário Legados