.NET에서 구조화된 문서 태그를 사용하는 방법

1단계: 패키지 설치

Aspose.Words FOSS for .NET는 아직 NuGet 패키지를 배포하지 않으므로, 대신 소스에서 라이브러리를 빌드하십시오. https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git를 복제한 다음, .NET SDK를 사용하여 Release 구성으로 Aspose.Words.sln을 빌드하고, 생성된 Aspose.Words 어셈블리를 프로젝트에 참조합니다. 이 라이브러리는 .NET Standard 2.0을 대상으로 하므로 .NET Framework 4.6.2+ 및 .NET 6/8/10에서 실행됩니다.

2단계: 필요한 클래스 가져오기

Document과 DocumentBuilder에 대한 using Aspose.Words; 지시문을 추가하고, StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping 및 이 가이드에서 다루는 다른 콘텐츠 컨트롤 클래스에 대한 using Aspose.Words.Markup; 지시문을 추가합니다.

3단계: 삽입할 수 있는 콘텐츠 컨트롤 유형 확인

삽입하기 전에, 대상 SdtType이(가) DocumentBuilder.InsertStructuredDocumentTag(SdtType)에서 허용하는 일곱 가지 유형 중 하나인지 확인하십시오: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, 및 Date. RepeatingSection와 RepeatingSectionItem은 이 방법으로 텍스트 커서에 삽입할 수 없습니다 — 대신 전체 단락이나 표 행을 둘러싸게 됩니다. Word 파일에 나타날 수 있지만 Word UI에서 삽입 가능한 유형으로 표시되지 않는 나머지 SdtType 값들 — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group, 및 EntityPicker — 은 이 삽입 방법에서 전혀 허용되지 않습니다.

4단계: 커서 위치에 콘텐츠 컨트롤 삽입

DocumentBuilder.InsertStructuredDocumentTag(SdtType)을(를) 일곱 가지 지원 유형 중 하나와 함께 호출하여 빌더의 현재 커서 위치에 새 컨트롤을 삽입합니다; 호출은 새로운 StructuredDocumentTag을 반환합니다. 반환된 컨트롤에 Tag와 Title을 설정하여 저자가 Word에서 보는 식별 문자열을 지정하고, 컨트롤이 비어 있을 때 Word가 표시하는 프롬프트 텍스트를 위해 PlaceholderName( Placeholder BuildingBlock에 의해 지원됨)를 설정합니다 — IsShowingPlaceholderText은 해당 프롬프트가 현재 표시되는지 여부를 보고합니다.

5단계: 유형별 콘텐츠 구성

체크박스 컨트롤의 경우, StructuredDocumentTag.Checked을 읽거나 설정하고, 각 상태에 표시되는 글리프를 사용자 정의하려면 SetCheckedSymbol() / SetUncheckedSymbol()를 호출합니다. 날짜 컨트롤의 경우, FullDate을 설정하며, DateDisplayFormat와 DateDisplayLocale가 표시 방식을 제어하고, DateStorageFormat(SdtDateStorageFormat)가 XML 데이터에 바인드될 때 저장 방식을 제어하며, CalendarType(SdtCalendarType)은 달력 시스템을 선택합니다. 드롭다운 목록 또는 콤보 박스의 경우, ListItems을 채웁니다 — SdtListItem(DisplayText, Value)의 SdtListItemCollection이며 — 그런 다음 SelectedValue를 설정하여 활성 선택을 지정합니다. 일반 텍스트 컨트롤의 경우, Multiline은 StructuredDocumentTag에 있는 bool 속성으로, 컨트롤을 구성하기 위해 설정할 수 있습니다.

6단계: 컨트롤 외형 및 잠금 설정

Appearance(SdtAppearance)을 설정하여 Word에서 컨트롤이 시각적으로 구분되는 방식을 제어하고, Color를 설정하여 강조 색상을 지정합니다. ContentsFont과 EndCharacterFont는 컨트롤 내용과 끝 문자에 적용되는 글꼴을 제어합니다. LockContentControl와 LockContents은 독립적인 스위치이며 — LockContentControl을 설정하면 컨트롤 자체의 삭제를 차단하고, LockContents을 설정하면 내부 내용을 편집하는 것을 차단하지만 서로에게 영향을 주지 않습니다.

7단계: 콘텐츠 컨트롤 찾기 및 제거

Read Range.StructuredDocumentTags – 그 범위에 대해 StructuredDocumentTagCollection된 Range.StructuredDocumentTags을(를) 읽고, 특정 컨트롤을 찾으려면 GetById(), GetByTag() 또는 GetByTitle()를 호출하고, 컬렉션에서 참조 또는 인덱스로 하나를 제거하려면 Remove() / RemoveAt()을(를) 사용합니다. 개별 컨트롤에 대해, 컨트롤과 그 내용을 함께 삭제하려면 Remove()을(를) 호출하고, 내용은 유지하면서 래퍼만 삭제하려면 RemoveSelfOnly()을(를) 호출하며, 컨트롤은 그대로 두고 내용을 비우려면 Clear()을(를) 호출합니다.

8단계: 컨트롤을 사용자 정의 XML 데이터에 바인딩

Read StructuredDocumentTag.XmlMapping – XmlMapping 인스턴스 – 그리고 SetMapping(customXmlPart, xPath, prefixMapping)를 호출하여 컨트롤을 문서의 사용자 정의 XML 데이터 저장소에 이미 존재하는 사용자 정의 XML 파트에 바인딩합니다. 바인딩된 요소를 선택하려면 XPath 식을 사용합니다. XmlMapping.IsMapped는 현재 바인딩이 활성화되어 있는지 보고하고, CustomXmlPart와 StoreItemId은 바인딩된 데이터 파트를 식별하며, Delete()은 매핑을 제거합니다.

9단계: 여러 섹션에 걸치는 콘텐츠 컨트롤 처리

여러 문서 섹션에 걸치는 콘텐츠 컨트롤은 – IsMultiSection이(가) 보고한 바와 같이 – 단일 StructuredDocumentTag 노드가 아니라 StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd 쌍으로 표시되며, StructuredDocumentTagRangeStart.RangeEnd를 통해 연결됩니다. 코드가 단일 노드 형태와 범위 형태를 모두 균일하게 처리해야 할 때는, 구체적인 유형에 따라 분기하지 않고 공유 IStructuredDocumentTag 인터페이스(Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly())를 사용하여 프로그래밍하십시오.