소개
Word 문서는 이미지, 텍스트 상자 및 기타 자유 부동 객체를 단락과 표의 일반 흐름과 별개인 그리기 레이어에 배치합니다. Aspose.Words FOSS for .NET은 Shape 및 ShapeBase 클래스를 통해 이 그리기 레이어를 노출하여 Word 자체가 내부적으로 사용하는 동일한 AutoShape, 그림, 텍스트 상자 및 OLE 객체 모델에 프로그래밍 방식으로 접근할 수 있게 합니다. 이 가이드는 라이브러리가 이러한 그리기 객체—위치 지정, 채우기 및 외곽선 서식, 삽입된 그림, 그리고 도형 내부에 배치된 텍스트—를 DOCX, DOCM, DOTX 및 DOTM 문서 전반에 걸쳐 어떻게 표현하고 조작하는지 보여줍니다.
이는 로고나 그래픽을 위치시킨 보고서 또는 레터헤드 템플릿을 생성하고, 떠다니는 텍스트 상자와 호출 상자를 포함한 문서를 생성하거나, 업로드된 문서에 이미 존재하는 도형을 검사하는 코드에 유용합니다 — 삽입된 그림의 바이트를 추출하고, 서명 라인의 서명자 이름을 읽으며, 기존 이미지를 재배치하는 작업 등에 활용됩니다.
Aspose.Words FOSS for .NET은 MIT 라이선스로 배포되며 .NET Standard 2.0을 목표로 하므로 .NET Framework 4.6.2+ 및 .NET 6, 8, 10에서 네이티브 종속성 없이 실행됩니다. NuGet을 통해 설치하거나 소스에서 빌드하세요(아래 빠른 시작 참고). 이는 상업적으로 사용되는 동일한 Aspose.Words 문서 엔진이며, 재작성이나 래퍼가 아니라 여기 설명된 Shape 및 그리기 레이어 클래스는 실제 제작 API입니다.
핵심 기능
도형 및 ShapeBase 객체 모델
Word 문서에 고정된 모든 AutoShape, 텍스트 상자, 삽입된 그림, OLE 객체 또는 ActiveX 컨트롤은 Shape 클래스로 표현됩니다 — sealed이며 추상 ShapeBase 기본 클래스를 기반으로 구축됩니다. 두 클래스는 동일한 위치 지정 및 서식 표면을 공유합니다: 기하학을 위한 Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation, Shape.ZOrder와, 해당 인스턴스가 어떤 종류의 객체를 포함하는지 설명하는 Shape.IsGroup, Shape.IsImage, Shape.IsWordArt, Shape.IsInline 플래그. ShapeType 열거형은 Word가 인식하는 구체적인 도형 종류—Rectangle, Ellipse, Line, Arrow, 다양한 호출 및 연결자 유형, TextBox, Image, OleObject 등 80개가 넘는 값을 나열합니다 — 따라서 문서의 도형을 순회하는 코드는 Shape.ShapeType을 기반으로 각 도형을 어떻게 처리할지 분기할 수 있습니다. 여러 도형은 하나의 GroupShape로 결합될 수 있으며, 이는 ShapeBase 하위 클래스 자체로서 도형 집합을 함께 위치시키고 크기를 조정합니다; DocumentBuilder.InsertGroupShape(shapes)은 기존 도형 배열에서 이를 생성합니다.
텍스트 상자 및 WordArt
어떤 Shape든 TextBox 클래스를 통해 자체 텍스트를 가질 수 있으며, 이는 Shape.TextBox로 노출됩니다. TextBox 속성은 텍스트가 도형 내부에 배치되는 방식을 제어합니다: 패딩을 위한 TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop, TextBox.InternalMarginBottom, 도형이 내용에 따라 성장하도록 하는 TextBox.FitShapeToText, 텍스트 방향을 위한 LayoutFlow, 상자 내부에서 텍스트가 어떻게 줄 바꿈되는지를 지정하는 TextBoxWrapMode, 그리고 수직 정렬을 위한 TextBox.VerticalAnchor — TextBoxAnchor 값으로 Top, Middle, BottomCentered, TopBaseline 등이 있습니다. 오버플로 텍스트가 두 번째 상자로 이어지는 연결된 텍스트 상자는 TextBox.Next 및 TextBox.Previous로 모델링됩니다. 관련되지만 별개의 클래스인 TextPath는 도형 내부가 아니라 윤곽을 따라가는 WordArt 스타일 텍스트를 정의하며, TextPath.Text, TextPath.FontFamily, TextPath.Bold, TextPath.RotateLetters와 같은 속성을 가지고, 또한 Stretch, Center 및 LetterJustify와 같은 값을 갖는 TextPathAlignment 열거형을 포함합니다.
그림 및 임베디드 이미지
도형이 그림을 포함하고 있을 때, Shape.HasImage는 true이며 Shape.ImageData은 ImageData 객체를 반환합니다. ImageData은 원시 바이트를 ImageData.ImageBytes를 통해, 감지된 형식을 ImageType를 통해 (Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps 및 WebP 포함), 픽셀 크기와 해상도를 ImageSize을 통해, 그리고 ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft, ImageData.CropRight을 통해 자르기를 노출합니다. 색상 조정 — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel, ImageData.ChromaKey — 은 동일 객체의 속성이며, ImageData.IsLink/ImageData.IsLinkOnly은 임베디드 그림과 외부 파일 경로만 참조하는 그림을 구분합니다. DocumentBuilder.InsertImage()은 이미지, 파일 경로, 바이트 배열 또는 스트림을 받아들이는 오버로드를 제공하며, 삽입 시 명시적인 너비, 높이, 수평 및 수직 위치, 그리고 WrapType을 설정하는 변형도 포함합니다.
채우기, 선, 및 도형 효과
모든 Shape와 GroupShape은 내부와 외곽을 위한 Fill 객체와 Stroke 객체를 포함합니다. Fill는 FillType를 통해 Solid, Patterned, Gradient, Textured, Background, Picture를 포함한 여섯 가지 채우기 유형을 지원하며, Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) 또는 Fill.SetImage(fileName)과 같은 메서드로 설정됩니다. Stroke은 외곽을 제어합니다: Stroke.Weight, DashStyle, JoinStyle, EndCap, 및 Stroke.LineStyle (ShapeLineStyle 값) 은 선 자체를 담당하고, Stroke.StartArrowType와 Stroke.EndArrowType는 ArrowWidth 및 ArrowLength 열거형과 함께 연결선 및 직선 도형의 화살표 머리를 구성합니다. 채우기와 선을 넘어 Shape는 네 개의 추가 효과 객체 — ShadowFormat, ReflectionFormat, GlowFormat, SoftEdgeFormat — 를 노출하며, 각각은 해당 시각 효과를 위한 색상 및 투명도 속성을 가지고 있습니다.
위치 지정 및 텍스트 래핑
페이지 또는 단락에 상대적으로 떠 있는 도형은 RelativeHorizontalPosition와 RelativeVerticalPosition을 사용해 자신을 고정합니다(예: 여백, 페이지, 열에 고정). 크기 고정을 위해 RelativeHorizontalSize와 RelativeVerticalSize을 결합하고, 좌/중/우 또는 상/중/하 간단 배치를 위해 HorizontalAlignment와 VerticalAlignment를 사용합니다. 주변 텍스트가 도형에 어떻게 반응하는지는 WrapType에 의해 제어되며, 값에는 Inline, Square, Tight, TopBottom, None이 있습니다; Square 및 Tight 래핑의 경우 WrapSide는 이를 Left, Right, Both, Largest로 더욱 세분화합니다. FlipOrientation은 좌표를 변경하지 않고 도형을 수평 또는 수직으로 반사하며, Shape.AllowOverlap/Shape.BehindText 플래그는 도형이 다른 떠 있는 콘텐츠 및 그 아래 텍스트 레이어와 어떻게 상호 작용하는지를 제어합니다.
서명 라인 및 수평 구분선
같은 드로잉 모델에 두 개의 더 특수한 도형 종류가 존재합니다. SignatureLine는 SignatureLineOptions을 통해 삽입 시 구성되며(속성에는 SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate, 그리고 SignatureLineOptions.AllowComments이 포함됩니다), 인쇄 가능한 문서에서 보이는 시각적 서명 블록을 렌더링하고 서명이 적용된 후 SignatureLine.IsSigned와 SignatureLine.IsValid를 노출합니다 — 이는 다른 곳에서 다루는 암호화 디지털 서명 검증과는 구별되며, 해당 검증은 도형 자체가 아니라 서명된 문서 부분과 작동합니다. HorizontalRuleFormat은 DocumentBuilder.InsertHorizontalRule()으로 삽입된 일반 구분선을 다루며, HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color, 그리고 HorizontalRuleFormat.Alignment 속성을 가집니다(마지막은 HorizontalRuleAlignment 값입니다).
빠른 시작
Aspose.Words FOSS for .NET은 NuGet을 통해 사용할 수 있습니다:
dotnet add package Aspose.Words.FOSS대신 소스에서 빌드하려면:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
애플리케이션에서 Aspose.Words.csproj에 대한 프로젝트 참조를 추가합니다. 여기서부터는 드로잉 레이어 작업이 이 게시물 전반에 걸쳐 사용된 패턴을 따릅니다: Document을 로드하거나 생성하고, Document.GetChildNodes(NodeType.Shape, true)으로 그 도형들을 순회하거나 DocumentBuilder 메서드(예: DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape(), DocumentBuilder.InsertHorizontalRule())를 사용해 새 도형을 삽입한 다음, 반환된 Shape의 속성을 읽거나 설정합니다 — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType 및 기타 속성들 — 마지막으로 Document.Save()를 호출합니다.
지원되는 형식
| 형식 | 확장자 | 읽기 | 쓰기 |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (모든 변형) | (다양함) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
이 버전은 페이지 레이아웃 및 렌더링을 의도적으로 제외합니다 — PDF, XPS, 이미지 내보내기 및 인쇄가 없습니다 — 따라서 도형의 Shape.Bounds 및 레이아웃 종속 기하학은 계산된 페이지 레이아웃이 아니라 문서에 저장된 값을 반영합니다. 추가 형식 변환기(DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, 및 WordML)는 읽거나 쓰지 않으며; 이는 상용 코드베이스에서 이 버전을 무료로 유지하기 위해 제거된 동일한 하위 시스템입니다.
오픈 소스 & 라이선스
Aspose.Words FOSS for .NET은 MIT 라이선스로 출시되며, 상업적 및 개인적 사용 모두에 대해 로열티나 재배포 제한 없이 무료입니다. 전체 소스는 GitHub의 Aspose.Words FOSS for .NET 리포지토리에서 사용할 수 있습니다.
