필드 작업
개요
Word 필드 – DATE, IF, DATABASE, REF, 그리고 수십 개의 다른 항목들 – 은(는) 다음에 표시됩니다 Aspose.Words FOSS for .NET 에 의해 Field 클래스와 그 하위 클래스는 모두 Aspose.Words.Fields 네임스페이스. 이 페이지에서는 핵심 필드 엔진을 다룹니다: 그 Field 객체 모델 자체, 필드가 수집되고 업데이트되는 방식, 그리고 필드 업데이트 중에 사용자 정의 데이터와 동작을 삽입할 수 있게 해주는 콜백 인터페이스를 포함합니다. 특정 필드 그룹 – 하이퍼링크 및 교차 참조, 날짜/시간 필드, 메일 병합 필드, 색인 및 목차 필드 – 각각은 전용 개발자 가이드 페이지를 가지고 있습니다.
필드 객체 모델
문서의 모든 필드는 Field 인스턴스로, 세 개의 마커 노드 – FieldStart, Separator, FieldEnd – 로 구성되며, 이들은 Field.Start, Field.Separator, Field.End 속성으로 노출됩니다. Field.Type 은 필드가 나타내는 FieldType 를 식별하고, Field.Result 와 Field.DisplayResult 은 마지막으로 계산된 값을 제공하며, Field.Format 은 필드 코드에 붙어 있는 스위치(예: 숫자 또는 날짜-시간 형식 문자열)를 보관합니다. Field.IsLocked 와 Field.IsDirty 은 필드의 잠금 및 오래된 상태를 보고합니다. Field.GetFieldCode() 를 호출하면 원시 필드 코드 텍스트를 읽을 수 있고, Field.Update() 로 결과를 다시 계산하며, Field.Unlink() 으로 필드를 정적 텍스트로 교체하고, Field.Remove() 로 완전히 삭제합니다.
문서에서 필드 접근 및 업데이트
Document.Range.Fields 은 FieldCollection 을 반환합니다 – 해당 범위에 포함된 필드들을 나타내며, Count, Remove(), RemoveAt(), Clear() 를 사용해 일괄 제거할 수 있습니다. Range.UpdateFields() 은 범위 내 모든 필드를 다시 계산하고, Range.UnlinkFields() 은 범위 내 모든 필드를 정적 텍스트로 변환하며, Range.NormalizeFieldTypes() 은 수동 편집 후 필드의 저장된 유형 코드를 실제 필드 코드와 일치시킵니다. DocumentBuilder.InsertField() 은 커서 위치에 새 필드를 삽입하며, 오버로드를 통해 새 필드의 결과를 즉시 업데이트하거나 나중에 Range.UpdateFields() 단계에서 업데이트하도록 할 수 있습니다.
필드 업데이트 옵션 및 문화
Document.FieldOptions은(는) 전체 문서의 필드가 업데이트될 때 동작을 관리하는 FieldOptions 인스턴스입니다: CurrentUser는 신원 필드에서 사용되는 UserInformation을 제공하고, DefaultDocumentAuthor는 작성자 관련 결과를 시드하며, LegacyNumberFormat와 UseInvariantCultureNumberFormat은 숫자 서식을 제어하고, PreProcessCulture와 FieldUpdateCultureSource(IFieldUpdateCultureProvider 콜백과 짝을 이룸)은 업데이트 중 날짜와 숫자 서식을 결정하는 문화권을 지정합니다. TemplateName, FileName, BuiltInTemplatesPaths는 템플릿 및 파일명 인식 필드가 다시 읽는 값을 제공합니다.
필드 업데이트 추적 및 사용자 지정
IFieldUpdatingCallback(FieldUpdating 및 FieldUpdated)을 FieldOptions에 구현하여 각 필드가 재계산되기 전후에 코드를 즉시 실행하도록 합니다 — 배치 작업에서 어떤 필드가 변경되었는지 감사하는 데 유용합니다. IFieldUpdatingProgressCallback(Notify)를 구현하여 대형 문서 전체 진행 상황을 추적합니다; 이는 FieldUpdatingProgressArgs을 받아 TotalFieldsCount, UpdatedFieldsCount, UpdateCompleted를 포함합니다. 필드의 숫자 또는 일반 결과가 텍스트로 렌더링되는 방식을 변경하려면 IFieldResultFormatter(Format(value, format) 및 FormatNumeric(value, format))을 구현하고 이를 FieldOptions.ResultFormatter에 할당합니다.
필드에 외부 데이터 제공
DATABASE 필드는 IFieldDatabaseProvider.GetQueryResult()을 통해 행을 읽으며, IFieldDatabaseProvider.GetQueryResult()은 FieldDatabaseDataRow(Values) 인스턴스로 구성된 FieldDatabaseDataTable(ColumnNames, Rows)를 반환합니다 — 구현을 FieldOptions.FieldDatabaseProvider에 할당하십시오. IF와 같은 비교 필드는 IComparisonExpressionEvaluator.Evaluate()를 통해 조건을 평가하며, IComparisonExpressionEvaluator.Evaluate()는 LeftExpression, ComparisonOperator, RightExpression을 포함하는 ComparisonExpression을 받아 Result, ErrorMessage을 포함하는 ComparisonEvaluationResult를 반환합니다; 기본 비교 로직을 재정의하려면 FieldOptions.ComparisonExpressionEvaluator에 사용자 정의 평가자를 할당하십시오. 업데이트 중 일반적으로 사용자 입력을 요청하는 필드 — 예: ASK 및 FILLIN — 는 FieldOptions.UserPromptRespondent에 할당될 때 IFieldUserPromptRespondent.Respond()을 호출하므로, 무인 업데이트가 대화형 입력을 기다리며 차단되지 않습니다.
필드를 위한 사용자 및 문서 신원
UserInformation(Name, Initials, Address, 그리고 정적 UserInformation.DefaultUser)은 작성자 및 사용자 이름 관련 필드가 읽는 신원을 제공합니다. 문서 작성자 또는 사용자 신원에 의존하는 필드를 업데이트하기 전에 Document.FieldOptions.CurrentUser에 인스턴스를 할당하십시오.
팁 및 모범 사례
- Aspose.Words FOSS는 Word와 달리 로드하거나 저장할 때 필드를 자동으로 재계산하지 않습니다 – 프로그래밍 방식으로 편집한 후 필드 결과에 반영되어야 할 경우
Range.UpdateFields()(또는 단일 필드의 경우Field.Update())를 명시적으로 호출하십시오. FieldStart,Separator,FieldEnd는 문서 트리의 실제 노드입니다; 마커 노드를 직접 삭제하지 말고Field.Remove()또는Field.Unlink()를 통해 필드를 제거하십시오. 그렇지 않으면 필드 구조가 일관성을 잃을 수 있습니다.- 페이지 레이아웃에 결과가 의존하는 필드 —
PAGE,NUMPAGES, 그리고 목차 페이지 번호 항목 — 은0자리표시자로 평가됩니다. 이 버전에는 페이지 레이아웃/렌더링 엔진이 포함되지 않기 때문입니다. - 큰 문서나 익숙하지 않은 문서에 대해
Range.UpdateFields()을 실행하기 전에IFieldUpdatingCallback를 등록하십시오. 이렇게 하면 어떤 필드가 변경되었는지 정확히 로그하거나 감사할 수 있습니다. - 무인 파이프라인에서 문서를 업데이트하기 전에
FieldOptions.UserPromptRespondent를 설정하거나 개별 프롬프트 기반 필드 클래스에DefaultResponse값을 제공하십시오. 이렇게 하면ASK/FILLIN필드가 인터랙티브 입력을 기다리며 멈추는 일을 방지할 수 있습니다.
일반적인 문제
| 문제 | 원인 | 수정 |
|---|---|---|
| 문서를 편집한 후 필드 결과가 최신이 아닙니다 | Aspose.Words FOSS는 로드하거나 저장할 때 필드를 자동으로 업데이트하지 않습니다 | 명시적으로 Range.UpdateFields() 또는 Field.Update()을 호출하십시오 |
PAGE, NUMPAGES 또는 TOC 페이지 번호가 0를 표시합니다 | 페이지 레이아웃/렌더링은 이 버전에 포함되지 않습니다 | 예상 동작 – 상용 버전을 사용하십시오 Aspose.Words (을/를) .NET에 사용 계산된 페이지 번호가 필요하면 |
DATABASE 필드가 행을 생성하지 않습니다 | FieldOptions.FieldDatabaseProvider에 IFieldDatabaseProvider가 할당되지 않았습니다 | IFieldDatabaseProvider를 구현하고 Range.UpdateFields()를 호출하기 전에 할당하십시오 |
| 배치 필드 업데이트가 멈춘 것처럼 보입니다 | 프롬프트 기반 필드 (ASK, FILLIN)에 IFieldUserPromptRespondent가 할당되지 않았습니다 | FieldOptions.UserPromptRespondent를 할당하거나 필드 인스턴스에 DefaultResponse를 설정하십시오 |
FAQ
Aspose.Words FOSS가 모든 Word 필드 유형을 평가합니까?
Field 객체 모델은 모든 FieldType 값을 나타내고 대부분을 업데이트하지만, 페이지 레이아웃에 따라 결과가 달라지는 필드—예를 들어 PAGE와 NUMPAGES—는 이 버전에는 레이아웃/렌더링 엔진이 포함되지 않으므로 자리표시자 0로 평가됩니다.
문서를 프로그래밍 방식으로 편집한 후 필드를 어떻게 다시 평가합니까?
편집된 내용을 포함하는 범위에 대해 Range.UpdateFields()를 호출하거나, 문서의 모든 필드를 업데이트하려면 Document.Range.UpdateFields()를 호출하십시오.
필드를 일반적인 정적 텍스트로 변환할 수 있습니까?
예 – Field.Unlink()는 필드를 마지막으로 계산된 결과를 일반 텍스트로 교체하여 기본 필드 코드를 제거합니다.
결과를 포함한 필드를 완전히 제거하려면 어떻게 해야 합니까?
Field.Remove()를 호출하십시오. 이는 FieldStart, Separator, FieldEnd 노드를 필드 코드와 결과 콘텐츠와 함께 삭제합니다.
DATABASE 필드에 사용자 정의 데이터를 제공하려면 어떻게 해야 합니까?
IFieldDatabaseProvider을(를) 구현하고 Document.FieldOptions.FieldDatabaseProvider에 할당하십시오. 귀하의 GetQueryResult() 구현은 FieldDatabaseDataRow 인스턴스로 구성된 FieldDatabaseDataTable을 반환합니다.
API Reference 요약
| 클래스 / 인터페이스 | 설명 |
|---|---|
Field | Word 필드의 기본 클래스; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | 범위 내 필드, Range.Fields을 통해; Count, Remove(), Clear() |
FieldType | 어떤 Word 필드를 Field 인스턴스가 나타내는지 식별하는 열거형 |
FieldOptions | 문서 전체 필드 업데이트 구성, Document.FieldOptions를 통해 |
IFieldUpdatingCallback | 각 필드 업데이트 주변에 FieldUpdating / FieldUpdated 훅 |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | 대량 필드 업데이트 전반에 걸친 진행 상황 보고 |
IFieldResultFormatter | 필드 계산 결과의 사용자 지정 서식 |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | DATABASE 필드에 대한 외부 데이터 소스 |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | 비교형 필드 식에 대한 맞춤 평가 |
IFieldUserPromptRespondent | 무인 업데이트 시 프롬프트 기반 필드에 대한 응답을 제공합니다 |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | 필드 업데이트 중 문화 선택 |
UserInformation | 작성자/사용자 ID (Name, Initials, Address)는 신원 필드에서 읽어옵니다 |