Java에서 프레젠테이션 플레이스홀더 관리
개요
플레이스홀더는 프레젠테이션 템플릿에서 특정 종류의 콘텐츠 위치를 예약하는 도형입니다. 일반적인 예로는 제목, 본문, 그림, 차트 및 일반용 콘텐츠 플레이스홀더가 있습니다. 일반 도형과 달리 플레이스홀더는 레이아웃 슬라이드 또는 마스터 슬라이드로부터 위치, 크기, 서식 및 기타 설정을 상속받을 수 있습니다.
Aspose.Slides는 플레이스홀더 정보를 IShape.getPlaceholder 메서드를 통해 제공합니다. 이 메서드는 일반 도형의 경우 null 대신 IPlaceholder 객체를 반환합니다. 플레이스홀더가 어떤 내용을 포함하도록 설계되었는지 확인하려면 IPlaceholder.getType을 사용하십시오.
플레이스홀더 유형을 알게 된 후에도 도형 인터페이스는 여전히 중요합니다:
- 빈 텍스트, 그림, 차트 또는 콘텐츠 플레이스홀더는 일반적으로 IAutoShape 로 표시됩니다.
- 채워진 그림 플레이스홀더는 IPictureFrame 로 표시될 수 있습니다.
- 채워진 차트 플레이스홀더는 IChart 로 표시될 수 있습니다.
- 콘텐츠 플레이스홀더는 여러 종류의 콘텐츠를 포함할 수 있습니다. 모든 플레이스홀더가 IAutoShape 라고 가정하는 대신 IPlaceholder.getType 과 런타임 도형 인터페이스를 모두 확인하십시오.
Warning
IPlaceholder.getType 은 플레이스홀더의 역할을 설명하지만 도형의 런타임 유형을 보장하지 않습니다. 텍스트, 그림, 차트, 표 또는 미디어 관련 멤버에 접근하기 전에 항상 유형 검사를 수행하십시오.플레이스홀더 상속 이해
플레이스홀더는 계층 구조를 형성합니다:
- 마스터 슬라이드는 재사용 가능한 스타일을 정의하고 경우에 따라 마스터 수준의 플레이스홀더를 정의합니다.
- 레이아웃 슬라이드는 하나 이상의 일반 슬라이드에서 사용되는 배치를 정의하며 마스터로부터 상속될 수 있습니다.
- 일반 슬라이드는 해당 슬라이드의 플레이스홀더를 포함하고 레이아웃으로부터 상속받을 수 있습니다.
IShape.getBasePlaceholder 를 호출하면 이 계층 구조에서 한 단계 위로 이동합니다. 슬라이드 플레이스홀더는 일반적으로 해당 레이아웃 플레이스홀더를 반환하고, 레이아웃 플레이스홀더는 마스터 플레이스홀더를 반환할 수 있습니다. 도형에 기본 플레이스홀더가 없을 경우 메서드는 null을 반환합니다.
다음 예제는 첫 번째 슬라이드의 플레이스홀더를 나열하고 해당 기본 플레이스홀더를 보고합니다:
import com.aspose.slides.*;
Presentation presentation = new Presentation("template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
for (IShape shape : slide.getShapes()) {
IPlaceholder placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
String typeName = shape.getClass().getSimpleName();
String slidePlaceholderMessage = "Slide placeholder: " + placeholderType + "; shape interface: " + typeName;
System.out.println(slidePlaceholderMessage);
IShape layoutPlaceholder = shape.getBasePlaceholder();
if (layoutPlaceholder != null) {
IPlaceholder layoutPlaceholderInfo = layoutPlaceholder.getPlaceholder();
Byte layoutPlaceholderType = layoutPlaceholderInfo == null ? null : layoutPlaceholderInfo.getType();
String layoutPlaceholderMessage = " Layout placeholder: " + layoutPlaceholderType;
System.out.println(layoutPlaceholderMessage);
IShape masterPlaceholder = layoutPlaceholder.getBasePlaceholder();
if (masterPlaceholder != null) {
IPlaceholder masterPlaceholderInfo = masterPlaceholder.getPlaceholder();
Byte masterPlaceholderType = masterPlaceholderInfo == null ? null : masterPlaceholderInfo.getType();
String masterPlaceholderMessage = " Master placeholder: " + masterPlaceholderType;
System.out.println(masterPlaceholderMessage);
}
}
}
} finally {
presentation.dispose();
}
일반 슬라이드에서 플레이스홀더를 편집하면 해당 슬라이드에 대한 로컬 오버라이드가 생성되거나 변경됩니다. 관련 레이아웃이나 마스터를 편집하면 해당 설정을 계속 상속하는 모든 슬라이드에 영향을 미칠 수 있습니다. 로컬 일반 도형은 기본 플레이스홀더가 없으며 동일한 좌표에 위치한다고 해서 상속이 시작되지 않습니다.
플레이스홀더 상태 제거
템플릿을 수정할 때는 IShape.removePlaceholder 를 사용하여 기존 객체를 일반 도형으로 유지합니다. 해당 객체의 getPlaceholder 메서드는 null을 반환하지만 도형은 슬라이드 컬렉션에 남아 있습니다. 반면에 IShapeCollection.remove 은 해당 컬렉션에서 도형을 삭제합니다.
다음 예제는 최소 하나의 슬라이드와 첫 번째 슬라이드에 비어 있지 않은 텍스트 플레이스홀더가 포함된 template.pptx 파일이 필요합니다. 레이아웃 또는 마스터로부터 서식을 상속받은 플레이스홀더를 사용하여 해당 관계를 제거했을 때의 효과를 확인하십시오. 예제는 동일한 도형이 남아 있는지를 확인하고, 이제 일반 도형이 된 후 다시 메서드를 호출한 뒤 결과를 저장합니다.
Warning
플레이스홀더 상태를 제거한다고 해서 상속된 외관 설정이 자동으로 유지되지는 않습니다. 아래 예제는 이러한 설정을 의도적으로 변경하지 않으므로 출력이 다르게 보일 수 있습니다. 위치와 크기가 완전히 상속된 도형은 호출 후 좌표와 차원이 0이 되어 컬렉션에 남아 있더라도 보이지 않게 될 수 있습니다.import com.aspose.slides.*;
Presentation presentation = new Presentation("template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
boolean found = false;
for (int index = 0; index < slide.getShapes().size(); index++) {
IShape candidate = slide.getShapes().get_Item(index);
if (!(candidate instanceof IAutoShape)) {
continue;
}
IAutoShape shape = (IAutoShape) candidate;
ITextFrame textFrame = shape.getTextFrame();
if (shape.getPlaceholder() == null ||
textFrame == null ||
textFrame.getText() == null ||
textFrame.getText().isEmpty()) {
continue;
}
int shapeCount = slide.getShapes().size();
shape.removePlaceholder();
System.out.println("Placeholder removed: " + (shape.getPlaceholder() == null));
System.out.println("Same shape retained: " + (slide.getShapes().get_Item(index) == shape));
System.out.println("Shape count unchanged: " + (slide.getShapes().size() == shapeCount));
// 일반 도형에서 메서드를 호출해도 영향을 주지 않습니다.
shape.removePlaceholder();
found = true;
break;
}
if (found) {
presentation.save("placeholder-status-removed.pptx", SaveFormat.Pptx);
} else {
System.out.println("No nonempty text placeholder was found on the first slide.");
}
} finally {
presentation.dispose();
}
일치하는 플레이스홀더에 대해 세 가지 검사 모두 true를 출력합니다. 텍스트는 그대로 유지되지만, 플레이스홀더 관계가 제거될 때 상속된 위치, 크기, 회전, 글꼴, 단락 정렬, 텍스트 프레임 여백, 수직 고정, 채우기 및 선 설정이 변경될 수 있습니다. 예를 들어, 상속된 제목 서식이 일반 텍스트 서식으로 되돌아갈 수 있습니다. 레이아웃에 대한 자세한 내용은 Slide Layout을 참조하십시오.
원래 의도된 외관을 유지하려면 호출 전에 해석된 위치, 크기 및 회전을 캡처하고 필요한 유효 서식 값을 별도의 변수에 복사하십시오. 이러한 값은 IPortionFormat.getEffective, IParagraphFormat.getEffective, ITextFrameFormat.getEffective, IFillFormat.getEffective, ILineFormat.getEffective 를 통해 가져올 수 있습니다. 관계가 제거된 후 텍스트 서식 값이 변경될 수 있기 때문에 유효 서식 객체만 유지하는 것에 의존하지 마십시오. 캡처한 값을 이후에 일반 도형에 명시적으로 적용하고, 템플릿에서 사용되는 글꼴 패밀리, 크기, 스타일, 색상, 단락 설정, 텍스트 프레임 설정, 채우기 및 선을 포함하십시오.
상속된 도형 기하학도 IGeometryShape.setShapeType 을 통해 명시적으로 할당해야 할 수 있습니다. 직사각형 텍스트 플레이스홀더의 경우 이는 ShapeType.Rectangle 를 할당하는 것을 의미합니다. 채우기와 선만 복원한다고 보이는 사각형이 복원되지 않을 수 있습니다. 추가 효과나 보다 복잡한 서식이 적용된 템플릿은 이러한 설정도 처리해야 합니다.
플레이스홀더 텍스트 변경
제목, 가운데 제목, 부제목, 본문 및 텍스트 플레이스홀더는 일반적으로 텍스트를 지원합니다. 해당 도형의 getTextFrame 메서드를 사용하기 전에 IAutoShape 인지 확인하십시오.
다음 예제는 첫 번째 슬라이드의 첫 번째 제목 플레이스홀더를 업데이트하고 결과를 저장합니다:
import com.aspose.slides.*;
Presentation presentation = new Presentation("template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
IAutoShape titleShape = null;
for (IShape shape : slide.getShapes()) {
if (!(shape instanceof IAutoShape)) {
continue;
}
IAutoShape autoShape = (IAutoShape) shape;
IPlaceholder placeholder = autoShape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
if (placeholderType == PlaceholderType.Title || placeholderType == PlaceholderType.CenteredTitle) {
titleShape = autoShape;
break;
}
}
if (titleShape == null) {
throw new IllegalStateException("The first slide does not contain a title placeholder.");
}
titleShape.getTextFrame().setText("Quarterly Business Review");
presentation.save("title-placeholder-updated.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
이 패턴은 그림, 차트, 표 또는 미디어 플레이스홀더를 IAutoShape 으로 캐스팅하는 것을 방지합니다. 또한 불안정한 도형 인덱스에 의존하는 대신 목적에 따라 플레이스홀더를 식별합니다.
레이아웃에 프롬프트 텍스트 설정
프롬프트 텍스트는 빈 플레이스홀더에 표시되는 디자인 타임 지시문으로, 예: 제목을 추가하려면 클릭 와 같습니다. 일반 슬라이드의 도형 컬렉션을 통해 접근하려 하지 말고 레이아웃 플레이스홀더에 사용자 지정 프롬프트 텍스트를 설정하십시오. 레이아웃은 ISlide.getLayoutSlide 로 접근하고, ILayoutSlide.getShapes 로 반환된 컬렉션을 순회하십시오.
다음 예제는 첫 번째 슬라이드에 사용되는 레이아웃의 제목 및 부제목 프롬프트를 변경합니다:
import com.aspose.slides.*;
Presentation presentation = new Presentation("template.pptx");
try {
ILayoutSlide layoutSlide = presentation.getSlides().get_Item(0).getLayoutSlide();
for (IShape shape : layoutSlide.getShapes()) {
if (!(shape instanceof IAutoShape)) {
continue;
}
IAutoShape autoShape = (IAutoShape) shape;
IPlaceholder placeholder = autoShape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
if (placeholderType == PlaceholderType.Title || placeholderType == PlaceholderType.CenteredTitle) {
autoShape.getTextFrame().setText("Enter a concise slide title");
} else if (placeholderType == PlaceholderType.Subtitle) {
autoShape.getTextFrame().setText("Enter a subtitle or reporting period");
}
}
presentation.save("custom-placeholder-prompts.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
프롬프트 텍스트는 일반 슬라이드 콘텐츠가 아닙니다. PowerPoint와 같은 편집 애플리케이션에서 빈 플레이스홀더를 위한 것입니다. 사용자가 실제 콘텐츠를 제공하면 프롬프트는 더 이상 표시되지 않습니다. 프롬프트를 변경해도 해당 레이아웃을 사용하는 슬라이드의 기존 텍스트가 교체되지 않습니다.
그림 플레이스홀더 업데이트
다음 두 경우를 처리합니다:
- 그림 플레이스홀더가 이미 채워져 있고 IPictureFrame 로 표시된 경우, IPictureFillFormat.getPicture 및 ISlidesPicture.setImage 를 사용하여 이미지를 교체합니다.
- 아직 빈 플레이스홀더인 경우, IShapeCollection.addPictureFrame 로 플레이스홀더 좌표에 그림 프레임을 추가하고 빈 플레이스홀더를 제거합니다.
다음 예제는 두 경우 모두를 지원하고 프레젠테이션을 저장합니다:
import com.aspose.slides.*;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
Presentation presentation = new Presentation("picture-template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
IShape picturePlaceholder = null;
for (IShape shape : slide.getShapes()) {
IPlaceholder placeholder = shape.getPlaceholder();
if (placeholder != null && placeholder.getType() == PlaceholderType.Picture) {
picturePlaceholder = shape;
break;
}
}
if (picturePlaceholder == null) {
throw new IllegalStateException("The first slide does not contain a picture placeholder.");
}
Path imagePath = Paths.get("replacement.png");
byte[] imageBytes = Files.readAllBytes(imagePath);
IPPImage image = presentation.getImages().addImage(imageBytes);
if (picturePlaceholder instanceof IPictureFrame) {
IPictureFrame pictureFrame = (IPictureFrame) picturePlaceholder;
pictureFrame.getPictureFormat().getPicture().setImage(image);
} else {
slide.getShapes().addPictureFrame(ShapeType.Rectangle, picturePlaceholder.getX(), picturePlaceholder.getY(), picturePlaceholder.getWidth(), picturePlaceholder.getHeight(), image);
slide.getShapes().remove(picturePlaceholder);
}
presentation.save("picture-placeholder-updated.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
빈 플레이스홀더에 대해 생성된 대체물은 새로운 플레이스홀더가 아니라 로컬 그림 프레임이며, 이는 IShape.getPlaceholder 이 setter를 제공하지 않기 때문입니다. 예약된 위치는 유지되지만 플레이스홀더 전용 동작은 더 이상 상속되지 않습니다. 플레이스홀더 관계를 유지해야 한다면 먼저 PowerPoint에서 플레이스홀더를 준비하고 채운 뒤, Aspose.Slides를 사용해 결과 IPictureFrame 을 업데이트하십시오.
이미지 투명도, 자르기 및 기타 그림 전용 효과에 대해서는 Manage Picture Frames 를 참조하십시오. 이러한 작업은 그림 프레임 또는 그림 채우기에 해당하며 플레이스홀더 메타데이터와는 관련이 없습니다.
차트 및 콘텐츠 플레이스홀더 작업
채워진 차트 플레이스홀더는 IChart 로 표시될 수 있습니다. 이 예제는 플레이스홀더 유형과 런타임 인터페이스를 모두 사용해 해당 차트를 찾아 제목을 변경하고 파일을 저장합니다:
import com.aspose.slides.*;
Presentation presentation = new Presentation("chart-template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
IChart placeholderChart = null;
for (IShape shape : slide.getShapes()) {
if (!(shape instanceof IChart)) {
continue;
}
IChart chart = (IChart) shape;
IPlaceholder placeholder = chart.getPlaceholder();
if (placeholder != null && placeholder.getType() == PlaceholderType.Chart) {
placeholderChart = chart;
break;
}
}
if (placeholderChart == null) {
throw new IllegalStateException("The first slide does not contain a populated chart placeholder.");
}
placeholderChart.setTitle(true);
placeholderChart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue");
presentation.save("chart-placeholder-updated.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
일반 콘텐츠 플레이스홀더는 보통 PlaceholderType.Object 를 가집니다. PowerPoint에서는 차트, 표, 다이어그램, 그림 및 미디어 등 여러 콘텐츠 유형을 시작하는 역할을 합니다. 채워진 후에는 실제 도형 인터페이스를 검사하여 무엇이 포함되어 있는지 확인하십시오. 특수 레이아웃은 또한 PlaceholderType.Chart, PlaceholderType.Table, PlaceholderType.Picture, PlaceholderType.Media, PlaceholderType.Diagram 을 노출할 수 있습니다.
Aspose.Slides는 빈 IAutoShape 플레이스홀더를 IPlaceholder.getType 을 변경한다는 이유만으로 IChart 로 변환하지 않습니다; 인터페이스를 통해 유형을 변경할 수 없습니다. 프로그래밍 방식으로 빈 차트 또는 콘텐츠 영역을 채우려면 플레이스홀더 좌표에 필요한 객체를 추가하고 빈 플레이스홀더를 제거하십시오. 다음 예제는 차트에 대해 이를 수행합니다:
import com.aspose.slides.*;
Presentation presentation = new Presentation("content-template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
IShape targetPlaceholder = null;
for (IShape shape : slide.getShapes()) {
IPlaceholder placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
if (placeholderType == PlaceholderType.Chart || placeholderType == PlaceholderType.Object) {
targetPlaceholder = shape;
break;
}
}
if (targetPlaceholder == null) {
throw new IllegalStateException("The first slide does not contain a chart or content placeholder.");
}
IChart chart = slide.getShapes().addChart(ChartType.ClusteredColumn, targetPlaceholder.getX(), targetPlaceholder.getY(), targetPlaceholder.getWidth(), targetPlaceholder.getHeight());
chart.setTitle(true);
chart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue");
slide.getShapes().remove(targetPlaceholder);
presentation.save("content-placeholder-replaced-with-chart.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
추가된 차트는 일반 로컬 차트입니다. 플레이스홀더 영역을 차지하지만 레이아웃 플레이스홀더를 상속하지 않습니다. 차트의 범주, 시리즈 또는 워크북 데이터를 교체해야 할 경우 전용 chart management articles 를 사용하십시오.
전체 예제: 텍스트 또는 이미지 콘텐츠 업데이트
다음 엔드‑투‑엔드 예제는 템플릿을 열고, 첫 번째 슬라이드에서 제목 또는 그림 플레이스홀더를 검색하며, 플레이스홀더 및 도형 유형을 확인하고 적절한 콘텐츠를 업데이트한 뒤 결과를 저장합니다. 예제는 도형 인덱스를 가정하거나 모든 플레이스홀더를 동일한 인터페이스로 캐스팅하는 것을 의도적으로 피합니다.
import com.aspose.slides.*;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
Presentation presentation = new Presentation("template.pptx");
try {
ISlide slide = presentation.getSlides().get_Item(0);
boolean updated = false;
for (IShape shape : slide.getShapes()) {
IPlaceholder placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
byte placeholderType = placeholder.getType();
if ((placeholderType == PlaceholderType.Title || placeholderType == PlaceholderType.CenteredTitle) && shape instanceof IAutoShape) {
IAutoShape titleShape = (IAutoShape) shape;
titleShape.getTextFrame().setText("Quarterly Business Review");
updated = true;
break;
}
if (placeholderType == PlaceholderType.Picture) {
Path imagePath = Paths.get("replacement.png");
byte[] imageBytes = Files.readAllBytes(imagePath);
IPPImage image = presentation.getImages().addImage(imageBytes);
if (shape instanceof IPictureFrame) {
IPictureFrame pictureFrame = (IPictureFrame) shape;
pictureFrame.getPictureFormat().getPicture().setImage(image);
} else {
slide.getShapes().addPictureFrame(ShapeType.Rectangle, shape.getX(), shape.getY(), shape.getWidth(), shape.getHeight(), image);
slide.getShapes().remove(shape);
}
updated = true;
break;
}
}
if (!updated) {
throw new IllegalStateException("No supported title or picture placeholder was found on the first slide.");
}
presentation.save("placeholder-content-updated.pptx", SaveFormat.Pptx);
} finally {
presentation.dispose();
}
FAQ
기본 플레이스홀더란 무엇입니까?
기본 플레이스홀더는 다른 플레이스홀더가 상속받는 레이아웃 또는 마스터에 있는 해당 도형을 의미합니다. 이를 가져오려면 IShape.getBasePlaceholder 를 사용하십시오. 일반 로컬 도형은 플레이스홀더 계층 구조에 속하지 않으므로 null을 반환합니다.
레이아웃 플레이스홀더를 편집하여 모든 슬라이드 제목을 변경할 수 있나요?
레이아웃을 통해 상속된 서식이나 프롬프트 텍스트를 변경할 수 있지만, 기존 제목 내용은 일반 슬라이드에 저장됩니다. 프레젠테이션 전체의 실제 제목 텍스트를 교체하려면 슬라이드를 순회하며 각 제목 플레이스홀더를 업데이트하십시오.
날짜, 슬라이드 번호, 머리글 및 바닥글 플레이스홀더를 어떻게 관리합니까?
해당 슬라이드, 레이아웃, 마스터, 노트 또는 핸드아웃 범위에서 헤더 및 풋터 관리자를 사용하십시오. 전체 예제는 Manage Presentation Header and Footer 를 참조하십시오.