레거시 양식 필드

Aspose.Words FOSS for .NET는 Word의 레거시(컨텐츠 컨트롤 이전) 양식 필드—텍스트 입력, 체크박스, 드롭다운 필드—를 FormField 클래스와 Aspose.Words.Fields에 있는 세 가지 특수 필드 서브클래스를 통해 읽고 조작합니다.

양식 필드 값 읽기

Document.Range.FormFields (a FormFieldCollection)는 노드 트리를 수동으로 탐색하지 않고도 범위 내 모든 레거시 양식 필드에 직접 접근할 수 있게 합니다. 각 FormField는 Name(필드를 참조하는 데 사용되는 북마크 스타일 식별자), Type(어떤 종류의 양식 필드인지 식별하는 FieldType 값), Result(현재 값), Enabled, 그리고 HelpText/OwnHelp 및 StatusText/OwnStatus을 통한 도움말/상태 텍스트를 노출합니다. SetTextInputValue(newValue)는 텍스트 입력 필드의 새 값을 직접 설정합니다. FormFieldCollection을 북마크 이름(예: formFields["BookmarkName"])으로 인덱싱하여 특정 필드를 가져올 수 있으며, Remove(formField)/RemoveAt(index)을 사용해 컬렉션에서 필드를 삭제합니다.

텍스트, 체크박스 및 드롭다운 필드 유형

세 가지 레거시 양식 필드 유형마다 전용 클래스가 있습니다: FieldFormText(FORMTEXT 필드, FieldType.FieldFormTextInput에 해당)은 자유 텍스트 입력을 위해, FieldFormCheckBox(FORMCHECKBOX 필드)는 불리언 토글을 위해, 그리고 FieldFormDropDown(FORMDROPDOWN 필드)는 선택 목록을 위해 사용됩니다. 기본 FormField 노드에서는 TextInputType(a TextFormFieldType 값 — Regular, Number, Date, CurrentDate, CurrentTime, 또는 Calculated)와 TextInputFormat이 텍스트 필드 값의 해석 및 형식을 제어합니다; MaxLength은 입력 길이를 제한하고; TextInputDefault은 기본 값을 제공합니다. Checked와 Default은 체크박스 필드에 적용되며, IsCheckBoxExactSize/CheckBoxSize가 렌더링 크기를 제어합니다. 드롭다운 필드는 옵션 목록을 DropDownItems에 보관하며, 이는 DropDownItemCollection로서 Add, Insert, Remove, Contains, IndexOf를 지원하고, 현재 선택된 항목을 위한 DropDownSelectedIndex을 포함합니다.

팁 및 모범 사례

Document.Range.FormFields을(를) 사용하고 Document.Range.Fields을(를) 유형별로 수동 필터링하지 마세요 — 레거시 폼 필드에 대한 직접적인, 타입이 지정된 진입점입니다.
사용자가 필드를 떠날 때 즉시 종속 필드 재계산을 트리거해야 하는 경우 CalculateOnExit을(를) 설정하세요.
FormField.EntryMacro / ExitMacro은 원본 문서에 구성된 VBA 매크로 이름을 참조합니다 — 이를 읽는다고 매크로 코드가 실행되지는 않습니다.
텍스트 필드의 Result을(를) 숫자나 날짜로 파싱하기 전에 TextInputType을(를) 확인하세요 — Regular 필드는 형식 제약을 두지 않습니다.

일반적인 문제

문제	원인	수정
북마크 이름으로 `FormFieldCollection`을(를) 색인화하면 null이 반환됩니다	양식 필드의 북마크 이름이 일치하지 않거나, 검색 범위에 해당 필드가 존재하지 않습니다	열거하는 동안 `FormField.Name`을(를) 통해 정확한 북마크 이름을 확인하세요
`Checked`을(를) 설정한 후 체크박스 상태가 반영되지 않습니다	수정 후 문서가 저장되지 않습니다	수정 후 문서를 저장하십시오; `Checked`은 다음 접근 시 읽어집니다
드롭다운 `DropDownSelectedIndex`이(가) 범위를 벗어났습니다	인덱스가 `DropDownItems`의 항목과 일치하지 않습니다	설정하기 전에 인덱스를 `DropDownItems.Count`와(과) 비교하여 검증하십시오
텍스트 필드 값이 적용되지 않았습니다	`SetTextInputValue` 대신 직접 속성 할당을 사용했습니다	`FormField`에 `SetTextInputValue(newValue)`을(를) 호출하십시오

FAQ

`FormField`와 `FieldFormText`/`FieldFormCheckBox`/`FieldFormDropDown`의 차이점은 무엇인가요?

FormField은(는) 모든 레거시 폼 필드를 나타내는 일반 노드이며, Document.Range.FormFields을 통해 접근합니다. FieldFormText, FieldFormCheckBox, FieldFormDropDown는 각각의 필드 유형을 작업할 때 일반 Field 컬렉션을 대신 사용하여, Field에서 파생된 필드별 클래스입니다.

문서에서 모든 양식 필드 값을 어떻게 가져오나요?

Document.Range.FormFields을 열거하고 각 FormField에서 Name/Result를 읽습니다.

드롭다운 양식 필드에 옵션을 추가할 수 있나요?

예 — FormField.DropDownItems은 DropDownItemCollection이며 Add(value), Insert(index, value), 그리고 Remove(name)를 포함합니다.

이것들이 최신 content controls와 동일한가요?

아니요. 레거시 양식 필드(FORMTEXT, FORMCHECKBOX, FORMDROPDOWN)는 Word의 구조화된 문서 태그(content control) 모델보다 이전에 존재했습니다; 두 가지 모두 동일한 문서에 나타날 수 있습니다.

API Reference 요약

클래스 / 메서드	설명
`Document.Range.FormFields`	범위 내 모든 레거시 폼 필드에 직접 액세스
`FormField`	일반 레거시 폼 필드 노드: 이름, 유형, 결과, 활성화 상태
`FormFieldCollection`	`FormField` 객체의 컬렉션; 북마크 이름으로 인덱싱, `Remove()`
`FieldFormText`	`FORMTEXT` 필드 클래스
`FieldFormCheckBox`	`FORMCHECKBOX` 필드 클래스
`FieldFormDropDown`	`FORMDROPDOWN` 필드 클래스
`TextFormFieldType`	텍스트 필드 입력 형식에 대한 열거형 (`Regular`, `Number`, `Date` 등)
`DropDownItemCollection`	드롭다운 필드 옵션의 편집 가능한 목록

참조

Aspose.Words for .NET — Enterprise Documentation

레거시 양식 필드