구조화된 문서 태그(콘텐츠 컨트롤) 사용하기

구 구조화된 문서 태그(콘텐츠 컨트롤) 작업

구조화된 문서 태그(SDT)는 Word UI에서 콘텐츠 컨트롤로 알려져 있으며, 문서 내용의 일부를 유형이 지정된 제약된 편집 동작—체크박스, 날짜 선택기, 드롭다운 목록, 또는 일반 텍스트 또는 서식 있는 텍스트 자리 표시자—으로 감싸습니다. Aspose.Words .NET용 FOSS 이를 통해 모델링합니다. Aspose.Words.Markup 네임스페이스, 다음이 머리글인 StructuredDocumentTag 클래스. 이 페이지에서는 콘텐츠 컨트롤 삽입, 각 유형 구성, 찾기 및 제거, 그리고 사용자 지정 XML 데이터에 바인딩하는 방법을 다룹니다.

구조화된 문서 태그 객체 모델

StructuredDocumentTag은(는) CompositeNode이며, 또한 IMarkupNode, ITrackableNode, IStructuredDocumentTag를 구현합니다. SdtType는 컨트롤의 종류를 식별합니다. Tag와 Title는 작성자가 Word에서 설정한 식별 문자열을 보유합니다; Placeholder(은/는 BuildingBlock)와 PlaceholderName은 컨트롤이 비어 있을 때 표시되는 프롬프트 텍스트를 제공하며, 이는 IsShowingPlaceholderText을 통해 보고됩니다. LockContentControl는 컨트롤이 삭제되는 것을 방지하고, LockContents는 내용이 편집되는 것을 각각 독립적으로 방지합니다.

콘텐츠 컨트롤 삽입

DocumentBuilder.InsertStructuredDocumentTag(SdtType)은(는) 커서 위치에 새 컨트롤을 삽입하지만, SdtType 값 중 일곱 가지만 지원합니다: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, 그리고 Date. RepeatingSection와 RepeatingSectionItem은 이 방식으로 텍스트 커서에 삽입할 수 없으며, 대신 전체 단락이나 표 행을 감싸게 됩니다. Word 파일에 나타나지만 Word UI에서 삽입 가능한 유형으로 제공되지 않는 나머지 SdtType 값들 – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group, 및 EntityPicker – 은(는) 이 삽입 방법으로 지원되지 않습니다.

유형별 콘텐츠

체크박스 컨트롤의 상태는 StructuredDocumentTag.Checked이며; SetCheckedSymbol() 및 SetUncheckedSymbol()는 각 상태에 표시되는 글리프를 설정합니다. 날짜 컨트롤은 값을 FullDate에 저장하며, DateDisplayFormat와 DateDisplayLocale가 렌더링 방식을 제어하고, DateStorageFormat(an SdtDateStorageFormat)은 XML 데이터에 바인딩될 때 저장 방식을 제어하며, CalendarType(an SdtCalendarType)은 달력 시스템을 선택합니다. 드롭다운 목록 또는 콤보 박스는 ListItems을 통해 선택지를 노출하고, 이는 SdtListItem의 SdtListItemCollection(DisplayText, Value)이며 SelectedValue을 포함합니다. 일반 텍스트 컨트롤의 Multiline 속성은 내부에서 줄 바꿈을 허용하거나 금지합니다.

모양 및 잠금

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

콘텐츠 컨트롤 찾기 및 제거

Range.StructuredDocumentTags은 해당 범위에 한정된 StructuredDocumentTagCollection을 반환하며, GetById(), GetByTag(), GetByTitle()는 Remove() 및 RemoveAt()와 함께 대상 조회에 사용됩니다. 개별 StructuredDocumentTag에 대해, Remove()은 컨트롤과 그 내용을 동시에 삭제하고, RemoveSelfOnly()은 래퍼만 삭제하여 내용은 문서에 남기며, Clear()은 컨트롤 자체는 유지하면서 내용만 비웁니다.

XML 데이터 바인딩

StructuredDocumentTag.XmlMapping은 문서 내 사용자 정의 XML 파트에 대한 바인딩을 설명하는 XmlMapping 인스턴스입니다: CustomXmlPart, XPath, PrefixMappings, StoreItemId, 및 IsMapped. SetMapping()은 기존 사용자 정의 XML 파트에 바인딩을 설정하고, Delete()은 이를 제거합니다.

다중 섹션(범위) 콘텐츠 컨트롤

여러 섹션에 걸치는 콘텐츠 컨트롤은 IsMultiSection에 의해 보고되며 단일 StructuredDocumentTag 노드가 아니라 StructuredDocumentTagRangeStart와 StructuredDocumentTagRangeEnd 노드 한 쌍으로, StructuredDocumentTagRangeStart.RangeEnd를 통해 연결됩니다. 단일 노드 형태와 범위 형태 모두 공통 IStructuredDocumentTag 인터페이스를 구현하므로, Tag, Title, SdtType, Placeholder 및 유사한 식별 속성만 필요로 하는 코드는 두 형태를 동일하게 사용할 수 있습니다.

팁 및 모범 사례

• DocumentBuilder.InsertStructuredDocumentTag()의 지원 유형 목록을 확인한 후에 사용하세요 – 커서에 삽입할 수 있는 것은 PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, Date뿐이며, 다른 유형은 예외를 발생시킵니다.
• 콘텐츠 컨트롤을 “플랫하게” 만들고 싶을 때는 Remove() 대신 RemoveSelfOnly()을 사용하세요 – 내용은 문서에 유지하되 컨트롤 래퍼는 제거합니다.
• DropDownList 또는 ComboBox 컨트롤이 선택지를 표시하기 전에 ListItems을 채우고, SelectedValue을 설정하여 활성 항목을 선택하도록 합니다.
• 코드가 일반 콘텐츠 컨트롤과 다중 섹션(범위) 콘텐츠 컨트롤을 동일하게 처리해야 한다면 StructuredDocumentTag을 직접 사용하기보다 IStructuredDocumentTag을 대상으로 프로그래밍하세요.
• XmlMapping.SetMapping()은 문서의 사용자 정의 XML 데이터 저장소에 이미 존재해야 하는 맞춤형 XML 파트에 바인딩됩니다 – 컨트롤을 매핑하기 전에 XML 데이터를 추가하거나 로드하세요.

일반적인 문제

FAQ

어떤 콘텐츠 컨트롤 유형을 DocumentBuilder으로 직접 삽입할 수 있나요?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, 및 Date. 다른 SdtType 값은 InsertStructuredDocumentTag()에서 지원되지 않습니다.

특정 태그가 있는 모든 콘텐츠 컨트롤을 어떻게 찾나요?

Range.StructuredDocumentTags.GetByTag()을 사용하고, 대신 해당 태그와 일치시키려면 GetByTitle() / GetById()를 사용하세요.

콘텐츠 컨트롤을 제거하고 내용은 유지하려면 어떻게 해야 하나요?

Remove() 대신 StructuredDocumentTag.RemoveSelfOnly()을 호출하세요.

콘텐츠 컨트롤을 사용자 정의 XML 데이터에 바인딩하려면 어떻게 하나요?

XmlMapping.SetMapping()을(를) 컨트롤에 호출하고, 기존 사용자 정의 XML 파트와 그 안의 XPath 식을 지정합니다.

일반 StructuredDocumentTag와 범위가 지정된 StructuredDocumentTag의 차이점은 무엇인가요?

여러 문서 섹션에 걸치는 콘텐츠 컨트롤은 단일 노드 대신 StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd 쌍으로 표시됩니다; 두 형태 모두 IStructuredDocumentTag를 구현합니다.

API Reference 요약

참조

• Aspose.Words for .NET — Enterprise Documentation