JavaScript에서 프레젠테이션 플레이스홀더 관리
개요
플레이스홀더는 프레젠테이션 템플릿에서 특정 유형의 콘텐츠를 위한 위치를 예약하는 도형입니다. 일반적인 예로는 제목, 본문, 그림, 차트 및 범용 콘텐츠 플레이스홀더가 있습니다. 일반 도형과 달리 플레이스홀더는 레이아웃 슬라이드 또는 마스터 슬라이드로부터 위치, 크기, 서식 및 기타 설정을 상속받을 수 있습니다.
Aspose.Slides는 Shape.getPlaceholder 메서드를 통해 플레이스홀더 정보를 제공합니다. 이 메서드는 일반 도형에 대해 null을 반환하거나 Placeholder 객체를 반환합니다. 플레이스홀더가 어떤 콘텐츠를 포함하도록 설계되었는지 확인하려면 Placeholder.getType 메서드를 사용합니다.
플레이스홀더 유형을 알게 된 후에도 도형 클래스는 여전히 중요합니다:
- 빈 텍스트, 그림, 차트 또는 콘텐츠 플레이스홀더는 일반적으로 AutoShape 로 표현됩니다.
- 채워진 그림 플레이스홀더는 PictureFrame 로 표현될 수 있습니다.
- 채워진 차트 플레이스홀더는 Chart 로 표현될 수 있습니다.
- 콘텐츠 플레이스홀더는 여러 종류의 콘텐츠를 포함할 수 있습니다. 모든 플레이스홀더가 AutoShape 라고 가정하지 말고 Placeholder.getType 과 런타임 도형 클래스를 함께 확인하세요.
Warning
Placeholder.getType 은 플레이스홀더의 역할을 설명하지만 도형의 런타임 유형을 보장하지는 않습니다. 텍스트, 그림, 차트, 표 또는 미디어와 관련된 멤버에 접근하기 전에 항상 유형 검사를 수행하세요.플레이스홀더 상속 이해
플레이스홀더는 계층 구조를 형성합니다:
- 마스터 슬라이드는 재사용 가능한 스타일을 정의하고 경우에 따라 마스터 수준의 플레이스홀더를 포함합니다.
- 레이아웃 슬라이드는 하나 이상의 일반 슬라이드가 사용하는 배치를 정의하며 마스터로부터 상속받을 수 있습니다.
- 일반 슬라이드는 해당 슬라이드의 플레이스홀더를 포함하고 레이아웃으로부터 상속받을 수 있습니다.
Shape.getBasePlaceholder 메서드를 호출하면 이 계층 구조를 한 단계 위로 이동합니다. 일반 슬라이드의 플레이스홀더는 보통 레이아웃 플레이스홀더를 반환하고, 레이아웃 플레이스홀더는 마스터 플레이스홀더를 반환할 수 있습니다. 도형에 기본 플레이스홀더가 없으면 메서드는 null을 반환합니다.
다음 예제는 첫 번째 슬라이드의 플레이스홀더를 나열하고 해당 기본 플레이스홀더를 보고합니다:
const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");
function getShapeClassName(shape) {
if (java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
return "AutoShape";
}
if (java.instanceOf(shape, "com.aspose.slides.IPictureFrame")) {
return "PictureFrame";
}
if (java.instanceOf(shape, "com.aspose.slides.IChart")) {
return "Chart";
}
return "Shape";
}
const presentation = new aspose.slides.Presentation("template.pptx");
try {
const slides = presentation.getSlides();
const slide = slides.get_Item(0);
const shapes = slide.getShapes();
for (let i = 0; i < shapes.size(); i++) {
const shape = shapes.get_Item(i);
const placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
const placeholderType = placeholder.getType();
const shapeClassName = getShapeClassName(shape);
const slidePlaceholderMessage = "Slide placeholder: " + placeholderType + "; shape class: " + shapeClassName;
console.log(slidePlaceholderMessage);
const layoutPlaceholder = shape.getBasePlaceholder();
if (layoutPlaceholder != null) {
const layoutPlaceholderInfo = layoutPlaceholder.getPlaceholder();
const layoutPlaceholderType = layoutPlaceholderInfo == null ? null : layoutPlaceholderInfo.getType();
const layoutPlaceholderMessage = " Layout placeholder: " + layoutPlaceholderType;
console.log(layoutPlaceholderMessage);
const masterPlaceholder = layoutPlaceholder.getBasePlaceholder();
if (masterPlaceholder != null) {
const masterPlaceholderInfo = masterPlaceholder.getPlaceholder();
const masterPlaceholderType = masterPlaceholderInfo == null ? null : masterPlaceholderInfo.getType();
const masterPlaceholderMessage = " Master placeholder: " + masterPlaceholderType;
console.log(masterPlaceholderMessage);
}
}
}
} finally {
presentation.dispose();
}
일반 슬라이드에서 플레이스홀더를 편집하면 해당 슬라이드에 대한 로컬 오버라이드가 생성되거나 변경됩니다. 관련 레이아웃이나 마스터를 편집하면 해당 설정을 상속받는 모든 슬라이드에 영향을 줄 수 있습니다. 로컬 일반 도형은 기본 플레이스홀더가 없으며 같은 좌표에 위치한다고 해서 자동으로 상속을 시작하지는 않습니다.
플레이스홀더 상태 제거
템플릿을 수정할 때 기존 객체를 일반 도형으로 유지하려면 Shape.removePlaceholder 를 사용합니다. 해당 도형의 getPlaceholder 메서드는 null을 반환하지만 도형은 슬라이드 컬렉션에 그대로 남습니다. 반면에 ShapeCollection.remove 은 해당 컬렉션에서 도형을 삭제합니다.
다음 예제는 첫 번째 슬라이드에 최소 하나의 슬라이드와 비어 있지 않은 텍스트 플레이스홀더가 있는 template.pptx 를 필요로 합니다. 레이아웃 또는 마스터에서 상속된 서식이 있는 플레이스홀더를 사용하면 관계 제거 효과를 확인할 수 있습니다. 예제는 동일한 도형이 남아 있는지 확인하고, 이제 일반 도형이 된 도형에 다시 메서드를 호출한 뒤 결과를 저장합니다.
Warning
플레이스홀더 상태를 제거한다고 해서 상속된 외관 설정이 자동으로 보존되지는 않습니다. 아래 예제는 이러한 설정을 의도적으로 변경하지 않기 때문에 출력이 다르게 보일 수 있습니다. 위치와 크기가 완전히 상속된 도형은 호출 후 좌표와 크기가 0이 되어 컬렉션에 남아 있어도 보이지 않을 수 있습니다.const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");
const presentation = new aspose.slides.Presentation("template.pptx");
try {
const slide = presentation.getSlides().get_Item(0);
const shapes = slide.getShapes();
let found = false;
for (let index = 0; index < shapes.size(); index++) {
const shape = shapes.get_Item(index);
if (!java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
continue;
}
const textFrame = shape.getTextFrame();
if (shape.getPlaceholder() == null || textFrame == null) {
continue;
}
const text = textFrame.getText();
if (text == null || text.length === 0) {
continue;
}
const shapeCount = shapes.size();
shape.removePlaceholder();
console.log("Placeholder removed: " + (shape.getPlaceholder() == null));
const retainedShape = shapes.get_Item(index);
console.log("Same shape retained: " + shape.equals(retainedShape));
console.log("Shape count unchanged: " + (shapes.size() === shapeCount));
// 일반 도형에서 메서드를 호출해도 효과가 없습니다.
shape.removePlaceholder();
found = true;
break;
}
if (found) {
presentation.save("placeholder-status-removed.pptx", aspose.slides.SaveFormat.Pptx);
} else {
console.log("No nonempty text placeholder was found on the first slide.");
}
} finally {
presentation.dispose();
}
일치하는 플레이스홀더에 대해 세 가지 검사 모두 true 를 출력합니다. 텍스트는 유지되지만, 상속된 위치, 크기, 회전, 글꼴, 단락 정렬, 텍스트 프레임 여백, 수직 고정, 채우기 및 선 설정은 플레이스홀더 관계가 제거될 때 변경될 수 있습니다. 예를 들어, 상속된 제목 서식은 일반 텍스트 서식으로 되돌아갈 수 있습니다. 레이아웃에 대한 자세한 내용은 Slide Layout 를 참고하세요.
예상된 외관을 유지하려면 호출 전에 해결된 위치, 크기 및 회전을 캡처하고, 필요한 실제 서식 값을 별도 변수에 복사하십시오. 이러한 값은 PortionFormat.getEffective, ParagraphFormat.getEffective, TextFrameFormat.getEffective, FillFormat.getEffective 및 LineFormat.getEffective 를 통해 가져올 수 있습니다. 실제 서식 객체만 보관하면 관계가 제거된 뒤 텍스트 서식 값이 변경될 수 있기 때문에 의존하지 마세요. 캡처한 값을 일반 도형에 명시적으로 적용하여 글꼴 패밀리, 크기, 스타일, 색상, 단락 설정, 텍스트 프레임 설정, 채우기 및 선을 템플릿과 일치시키세요.
상속된 도형 기하학도 GeometryShape.setShapeType 으로 명시적으로 지정해야 할 수 있습니다. 사각형 텍스트 플레이스홀더의 경우 ShapeType.Rectangle 를 지정해야 하며, 채우기와 선만 복원해서는 보이는 사각형이 복원되지 않을 수 있습니다. 추가 효과나 복잡한 서식이 포함된 템플릿은 해당 설정도 별도로 처리해야 합니다.
플레이스홀더 텍스트 변경
제목, 중앙 제목, 부제목, 본문 및 텍스트 플레이스홀더는 일반적으로 텍스트를 지원합니다. AutoShape 인지 확인한 뒤 getTextFrame 메서드를 사용하십시오.
다음 예제는 첫 번째 슬라이드의 첫 번째 제목 플레이스홀더를 업데이트하고 결과를 저장합니다:
const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");
const presentation = new aspose.slides.Presentation("template.pptx");
try {
const slides = presentation.getSlides();
const slide = slides.get_Item(0);
const shapes = slide.getShapes();
let titleShape = null;
for (let i = 0; i < shapes.size(); i++) {
const shape = shapes.get_Item(i);
if (!java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
continue;
}
const placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
const placeholderType = placeholder.getType();
if (placeholderType === aspose.slides.PlaceholderType.Title || placeholderType === aspose.slides.PlaceholderType.CenteredTitle) {
titleShape = shape;
break;
}
}
if (titleShape == null) {
throw new Error("The first slide does not contain a title placeholder.");
}
titleShape.getTextFrame().setText("Quarterly Business Review");
presentation.save("title-placeholder-updated.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
presentation.dispose();
}
이 패턴은 그림, 차트, 표 또는 미디어 플레이스홀더를 AutoShape 객체로 취급하지 않도록 방지합니다. 또한 취약한 도형 인덱스에 의존하지 않고 목적에 따라 플레이스홀더를 식별합니다.
레이아웃에 프롬프트 텍스트 설정
프롬프트 텍스트는 빈 플레이스홀더에 표시되는 디자인 시점 안내 메시지이며, 예를 들어 Click to add title 와 같습니다. 일반 슬라이드의 도형 컬렉션을 통해 접근하려고 시도하기보다 레이아웃 플레이스홀더에 사용자 정의 프롬프트 텍스트를 설정하십시오. Slide.getLayoutSlide 로 레이아웃에 접근하고, BaseSlide.getShapes 로 반환된 컬렉션을 순회합니다.
다음 예제는 첫 번째 슬라이드에 사용된 레이아웃의 제목 및 부제목 프롬프트를 변경합니다:
const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");
const presentation = new aspose.slides.Presentation("template.pptx");
try {
const slides = presentation.getSlides();
const firstSlide = slides.get_Item(0);
const layoutSlide = firstSlide.getLayoutSlide();
const shapes = layoutSlide.getShapes();
for (let i = 0; i < shapes.size(); i++) {
const shape = shapes.get_Item(i);
if (!java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
continue;
}
const placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
const placeholderType = placeholder.getType();
if (placeholderType === aspose.slides.PlaceholderType.Title || placeholderType === aspose.slides.PlaceholderType.CenteredTitle) {
shape.getTextFrame().setText("Enter a concise slide title");
} else if (placeholderType === aspose.slides.PlaceholderType.Subtitle) {
shape.getTextFrame().setText("Enter a subtitle or reporting period");
}
}
presentation.save("custom-placeholder-prompts.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
presentation.dispose();
}
프롬프트 텍스트는 일반 슬라이드 콘텐츠가 아닙니다. PowerPoint와 같은 편집 애플리케이션에서 빈 플레이스홀더에 표시되는 안내용이며, 사용자 또는 프로그램이 실제 콘텐츠를 제공하면 더 이상 표시되지 않습니다. 프롬프트를 변경해도 해당 레이아웃을 사용하는 기존 슬라이드의 텍스트가 교체되지 않습니다.
그림 플레이스홀더 업데이트
다음 두 경우를 처리해야 합니다:
- 그림 플레이스홀더가 이미 채워져 있고 PictureFrame 로 표시되는 경우, PictureFrame.getPictureFormat, PictureFillFormat.getPicture 및 Picture.setImage 를 사용해 이미지를 교체합니다.
- 아직 빈 플레이스홀더인 경우, ShapeCollection.addPictureFrame 로 플레이스홀더 좌표에 그림 프레임을 추가하고 빈 플레이스홀더를 제거합니다.
다음 예제는 두 경우를 모두 지원하고 프레젠테이션을 저장합니다:
const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");
const presentation = new aspose.slides.Presentation("picture-template.pptx");
try {
const slides = presentation.getSlides();
const slide = slides.get_Item(0);
const shapes = slide.getShapes();
let picturePlaceholder = null;
for (let i = 0; i < shapes.size(); i++) {
const shape = shapes.get_Item(i);
const placeholder = shape.getPlaceholder();
if (placeholder != null && placeholder.getType() === aspose.slides.PlaceholderType.Picture) {
picturePlaceholder = shape;
break;
}
}
if (picturePlaceholder == null) {
throw new Error("The first slide does not contain a picture placeholder.");
}
const sourceImage = aspose.slides.Images.fromFile("replacement.png");
try {
const image = presentation.getImages().addImage(sourceImage);
if (java.instanceOf(picturePlaceholder, "com.aspose.slides.IPictureFrame")) {
picturePlaceholder.getPictureFormat().getPicture().setImage(image);
} else {
const x = picturePlaceholder.getX();
const y = picturePlaceholder.getY();
const width = picturePlaceholder.getWidth();
const height = picturePlaceholder.getHeight();
const frameX = java.newFloat(x);
const frameY = java.newFloat(y);
const frameWidth = java.newFloat(width);
const frameHeight = java.newFloat(height);
shapes.addPictureFrame(aspose.slides.ShapeType.Rectangle, frameX, frameY, frameWidth, frameHeight, image);
shapes.remove(picturePlaceholder);
}
} finally {
sourceImage.dispose();
}
presentation.save("picture-placeholder-updated.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
presentation.dispose();
}
빈 플레이스홀더에 대해 생성된 교체물은 로컬 그림 프레임이며 새로운 플레이스홀더가 아닙니다. 이는 Shape.getPlaceholder 에 설정자가 없기 때문입니다. 예약된 위치는 유지하지만 더 이상 플레이스홀더 전용 동작을 상속하지 않습니다. 플레이스홀더 관계를 유지해야 한다면 먼저 PowerPoint에서 플레이스홀더를 준비하고 채운 뒤, Aspose.Slides 로 해당 PictureFrame 을 업데이트하십시오.
이미지 투명도, 자르기 및 기타 그림 전용 효과에 대해서는 Manage Picture Frames 를 참고하십시오. 이러한 작업은 그림 프레임 또는 그림 채우기에 해당하며 플레이스홀더 메타데이터와는 별개입니다.
차트 및 콘텐츠 플레이스홀더 작업
채워진 차트 플레이스홀더는 Chart 로 표현될 수 있습니다. 다음 예제는 플레이스홀더 유형과 런타임 클래스를 모두 확인하여 차트를 찾아 제목을 변경하고 파일을 저장합니다:
const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");
const presentation = new aspose.slides.Presentation("chart-template.pptx");
try {
const slides = presentation.getSlides();
const slide = slides.get_Item(0);
const shapes = slide.getShapes();
let placeholderChart = null;
for (let i = 0; i < shapes.size(); i++) {
const shape = shapes.get_Item(i);
if (!java.instanceOf(shape, "com.aspose.slides.IChart")) {
continue;
}
const placeholder = shape.getPlaceholder();
if (placeholder != null && placeholder.getType() === aspose.slides.PlaceholderType.Chart) {
placeholderChart = shape;
break;
}
}
if (placeholderChart == null) {
throw new Error("The first slide does not contain a populated chart placeholder.");
}
placeholderChart.setTitle(true);
placeholderChart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue");
presentation.save("chart-placeholder-updated.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
presentation.dispose();
}
일반 콘텐츠 플레이스홀더는 보통 PlaceholderType.Object 를 가지고 있습니다. PowerPoint에서는 차트, 표, 다이어그램, 그림 및 미디어 등 여러 콘텐츠 유형을 시작하는 런처 역할을 합니다. 채워진 후 실제 도형 클래스를 검사하여 어떤 콘텐츠가 포함되어 있는지 파악하십시오. 특수 레이아웃은 PlaceholderType.Chart, PlaceholderType.Table, PlaceholderType.Picture, PlaceholderType.Media 또는 PlaceholderType.Diagram 을 노출할 수 있습니다.
Aspose.Slides는 Placeholder.getType 을 변경한다고 해서 빈 AutoShape 플레이스홀더가 자동으로 Chart 로 변환되지 않으며, 유형은 객체를 통해 변경할 수 없습니다. 빈 차트 또는 콘텐츠 영역을 프로그래밍 방식으로 채우려면 해당 좌표에 필요한 객체를 추가한 뒤 빈 플레이스홀더를 삭제하십시오. 다음 예제는 차트에 대해 이를 수행합니다:
const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");
const presentation = new aspose.slides.Presentation("content-template.pptx");
try {
const slides = presentation.getSlides();
const slide = slides.get_Item(0);
const shapes = slide.getShapes();
let targetPlaceholder = null;
for (let i = 0; i < shapes.size(); i++) {
const shape = shapes.get_Item(i);
const placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
const placeholderType = placeholder.getType();
if (placeholderType === aspose.slides.PlaceholderType.Chart || placeholderType === aspose.slides.PlaceholderType.Object) {
targetPlaceholder = shape;
break;
}
}
if (targetPlaceholder == null) {
throw new Error("The first slide does not contain a chart or content placeholder.");
}
const x = targetPlaceholder.getX();
const y = targetPlaceholder.getY();
const width = targetPlaceholder.getWidth();
const height = targetPlaceholder.getHeight();
const chartX = java.newFloat(x);
const chartY = java.newFloat(y);
const chartWidth = java.newFloat(width);
const chartHeight = java.newFloat(height);
const chart = shapes.addChart(aspose.slides.ChartType.ClusteredColumn, chartX, chartY, chartWidth, chartHeight);
chart.setTitle(true);
chart.getChartTitle().addTextFrameForOverriding("Quarterly Revenue");
shapes.remove(targetPlaceholder);
presentation.save("content-placeholder-replaced-with-chart.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
presentation.dispose();
}
추가된 차트는 일반 로컬 차트이며, 플레이스홀더 영역을 차지하지만 레이아웃 플레이스홀더로부터 상속되지 않습니다. 차트의 범주, 시리즈 또는 워크북 데이터를 교체해야 할 경우 전용 chart management articles 를 사용하십시오.
전체 예제: 텍스트 또는 이미지 콘텐츠 업데이트
다음 끝‑끝 예제는 템플릿을 열고 첫 번째 슬라이드에서 제목 또는 그림 플레이스홀더를 검색한 뒤, 플레이스홀더와 도형 유형을 확인하고 적절한 콘텐츠를 업데이트한 뒤 결과를 저장합니다. 이 예제는 도형 인덱스에 의존하거나 모든 플레이스홀더를 동일 클래스라고 가정하는 것을 의도적으로 피합니다.
const aspose = { slides: require("aspose.slides.via.java") };
const java = require("java");
const presentation = new aspose.slides.Presentation("template.pptx");
try {
const slides = presentation.getSlides();
const slide = slides.get_Item(0);
const shapes = slide.getShapes();
let updated = false;
for (let i = 0; i < shapes.size(); i++) {
const shape = shapes.get_Item(i);
const placeholder = shape.getPlaceholder();
if (placeholder == null) {
continue;
}
const placeholderType = placeholder.getType();
const isTitlePlaceholder = placeholderType === aspose.slides.PlaceholderType.Title || placeholderType === aspose.slides.PlaceholderType.CenteredTitle;
if (isTitlePlaceholder && java.instanceOf(shape, "com.aspose.slides.IAutoShape")) {
shape.getTextFrame().setText("Quarterly Business Review");
updated = true;
break;
}
if (placeholderType === aspose.slides.PlaceholderType.Picture) {
const sourceImage = aspose.slides.Images.fromFile("replacement.png");
try {
const image = presentation.getImages().addImage(sourceImage);
if (java.instanceOf(shape, "com.aspose.slides.IPictureFrame")) {
shape.getPictureFormat().getPicture().setImage(image);
} else {
const x = shape.getX();
const y = shape.getY();
const width = shape.getWidth();
const height = shape.getHeight();
const frameX = java.newFloat(x);
const frameY = java.newFloat(y);
const frameWidth = java.newFloat(width);
const frameHeight = java.newFloat(height);
shapes.addPictureFrame(aspose.slides.ShapeType.Rectangle, frameX, frameY, frameWidth, frameHeight, image);
shapes.remove(shape);
}
} finally {
sourceImage.dispose();
}
updated = true;
break;
}
}
if (!updated) {
throw new Error("No supported title or picture placeholder was found on the first slide.");
}
presentation.save("placeholder-content-updated.pptx", aspose.slides.SaveFormat.Pptx);
} finally {
presentation.dispose();
}
FAQ
기본 플레이스홀더란 무엇인가요?
기본 플레이스홀더는 레이아웃 또는 마스터에 있는 해당 도형으로, 다른 플레이스홀더가 상속받는 대상입니다. Shape.getBasePlaceholder 를 사용해 가져올 수 있습니다. 일반 로컬 도형은 플레이스홀더 계층에 포함되지 않으므로 null을 반환합니다.
레이아웃 플레이스홀더를 편집해 모든 슬라이드 제목을 변경할 수 있나요?
레이아웃을 통해 상속된 서식이나 프롬프트 텍스트는 변경할 수 있지만, 기존 제목 내용은 일반 슬라이드에 저장됩니다. 프레젠테이션 전체의 실제 제목 텍스트를 교체하려면 슬라이드를 순회하면서 각 제목 플레이스홀더를 업데이트해야 합니다.
날짜, 슬라이드 번호, 머리글 및 바닥글 플레이스홀더는 어떻게 관리하나요?
해당 슬라이드, 레이아웃, 마스터, 노트 또는 유인물 범위에서 머리글 및 바닥글 관리자를 사용하십시오. 자세한 예제는 Manage Presentation Header and Footer 를 참고하세요.