Word.Chart
Word.Chart은 Word 모듈(Office.word(iframe))의 객체 타입입니다. 메서드 34개.
비고
- 모듈: Word ·
Office.word(iframe)· 네임스페이스Word - 얻는 방법:
Document.getChart(shapeId),Document.getCharts(options) - 모든 메서드는
Promise를 반환하며, 시그니처는 TypeScript 표기입니다.
메서드
| 메서드 | 설명 |
|---|---|
delete() | 도형을 삭제한다. |
getAxisTitle(axis) | 지정한 축의 제목을 반환한다. |
getBody() | 도형 내부의 텍스트 영역을 반환한다. |
getChartInfo() | 차트의 서식 상태를 한 번에 반환한다. |
getDataLabelPosition() | 데이터레이블 위치를 반환한다. |
getFill() | 도형의 현재 채우기 설정을 반환한다. |
getGridLine(axis) | 지정한 축의 눈금선 종류를 반환한다. |
getHyperlink() | 도형에 연결된 하이퍼링크 정보를 반환한다. |
getId() | 차트 도형 ID를 반환한다. |
getLegendPosition() | 범례 위치를 반환한다. |
getLine() | 도형의 현재 선 설정을 반환한다. |
getRange() | 도형이 놓인 자리 범위를 반환한다. |
getTitle() | 차트 제목을 반환한다. |
getType() | 차트 종류를 반환한다. |
insertHyperlink(url, options) | 도형에 하이퍼링크를 설정한다. |
isEditable() | 이 차트를 편집할 수 있는지 반환한다. |
move(options) | 글 앞·뒤에 배치한 도형의 위치를 변경한다. |
removeHyperlink() | 도형의 하이퍼링크를 제거한다. |
resize(options) | 도형의 크기를 변경한다. |
setAxisTitle(axis, title) | 지정한 축의 제목을 설정한다. |
setDataLabelPosition(position) | 데이터레이블 위치를 설정한다. |
setFill(fill) | 도형 채우기를 설정한다. |
setGridLine(axis, gridType) | 지정한 축의 눈금선을 설정한다. |
setLegendPosition(position) | 범례 위치를 설정한다. |
setLine(options) | 도형 선을 설정한다. |
setStyle(style) | 차트의 프리셋 스타일을 바꾼다. |
setText(text) | 도형의 텍스트 내용을 교체한다. |
setTextMargin(options) | 도형 텍스트 영역의 안쪽 여백을 설정한다. |
setTextVerticalAlign(align) | 도형 텍스트의 세로 정렬을 설정한다. |
setTitle(title) | 차트 제목을 설정한다. |
setType(chartType) | 차트 종류를 바꾼다. |
setWrap(wrap) | 도형의 배치 방식을 변경한다. |
setZOrder(order) | 글 앞·뒤에 배치한 도형의 앞뒤 순서를 변경한다. |
updateHyperlink(options) | 도형에 연결된 하이퍼링크의 주소나 설명을 수정한다. |
메서드 상세
delete()
도형을 삭제한다. - 글자처럼 배치한 도형과 글 앞·뒤에 배치한 도형 모두 삭제할 수 있다.
delete(): Promise<void>;
반환값
none
getAxisTitle(axis)
지정한 축의 제목을 반환한다. 제목을 설정하지 않았으면 빈 문자열이고, 축 제목을 갖지 않는 차트 종류(원형 계열·도넛·방사형)는 null 을 반환한다.
getAxisTitle(axis: ChartAxis): Promise<string | null>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
axis | ChartAxis | 제목을 읽을 축(가로축 또는 세로축) |
반환값
Promise<string | null>
getBody()
도형 내부의 텍스트 영역을 반환한다.
getBody(): Promise<Body>;
반환값
Promise<Body> - 텍스트 영역 컨테이너, 텍스트박스가 아니면 null
getChartInfo()
차트의 서식 상태를 한 번에 반환한다. 각 값은 이름이 같은 조회 메서드와 같다.
getChartInfo(): Promise<ChartFormatInfo>;
반환값
Promise<ChartFormatInfo>
getDataLabelPosition()
데이터레이블 위치를 반환한다. 데이터레이블이 설정되지 않은 차트는 "none" 이고, 데이터레이블을 갖지 않는 차트 종류(표면형)는 null 을 반환한다.
getDataLabelPosition(): Promise<ChartDataLabelPosition | null>;
반환값
Promise<ChartDataLabelPosition | null>
getFill()
도형의 현재 채우기 설정을 반환한다.
반환값은 setFill()에 그대로 전달할 수 있다.
테마색 채우기와 방사형 그라데이션 채우기는 type 만 반환하므로, 그 값을 그대로 setFill()에 전달하면 오류가 발생한다.
getFill(): Promise<ShapeFill | null>;
반환값
Promise<ShapeFill | null> - 채우기 정보(setFill 입력과 동형), fill 정보가 없으면 null
getGridLine(axis)
지정한 축의 눈금선 종류를 반환한다. 눈금선을 꺼 둔 축은 "none" 이고, 그 축의 눈금선을 갖지 않는 차트 종류(원형 계열·도넛은 양축, 방사형은 세로축)는 null 을 반환한다.
getGridLine(axis: ChartAxis): Promise<ChartGridLineType | null>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
axis | ChartAxis | 눈금선을 읽을 축(가로축 또는 세로축) |
반환값
Promise<ChartGridLineType | null>
getHyperlink()
도형에 연결된 하이퍼링크 정보를 반환한다. - 도형 하나에는 하나의 하이퍼링크를 연결할 수 있다.
getHyperlink(): Promise<{ url: string; tooltip: string | null; linkType: HyperlinkType; anchor?: string } | null>;
반환값
Promise<{ url: string; tooltip: string | null; linkType: HyperlinkType; anchor?: string } | null> - 링크 정보, 없으면 null. 북마크면 url="#이름"·anchor="이름"
getId()
차트 도형 ID를 반환한다.
getId(): Promise<string>;
반환값
Promise<string> - 차트 도형 ID (영구 GUID)
getLegendPosition()
범례 위치를 반환한다. 범례를 숨긴 차트는 "none" 이고, 위치를 알아낼 수 없는 차트는 "right" 로 보고한다.
getLegendPosition(): Promise<ChartLegendPosition>;
반환값
Promise<ChartLegendPosition>
getLine()
도형의 현재 선 설정을 반환한다. - 반환값은 setLine()에 그대로 전달할 수 있다.
getLine(): Promise<ShapeLine | null>;
반환값
Promise<ShapeLine | null> - 선 정보(setLine 입력과 동형), line 정보가 없으면 null
getRange()
도형이 놓인 자리 범위를 반환한다. - 글자 한 칸을 차지하는 자리라 시작=끝이다.
getRange(): Promise<Range>;
반환값
Promise<Range> - 도형 자리 범위(도형이 없으면 사용 시점에 오류)
getTitle()
차트 제목을 반환한다. 제목을 설정하지 않았으면 빈 문자열을 반환한다.
getTitle(): Promise<string>;
반환값
Promise<string>
getType()
차트 종류를 반환한다. 파일에서 읽은 100% 누적 막대형·거품형 차트는 ChartType 에 없는 그 종류의 이름을, 그 밖에 ChartType 에 없는 종류는 "unknown" 을 반환한다.
getType(): Promise<ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown">;
반환값
Promise<ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown">
insertHyperlink(url, options)
도형에 하이퍼링크를 설정한다. - 기존 링크가 있으면 교체한다. 웹 주소·이메일·책갈피는 URL 형식으로 구분하며, 프로토콜 없는 웹 주소에는 https://를 붙인다.
insertHyperlink(url: string, options?: { tooltip?: string }): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
url | string | 링크 목적지 |
options (선택) | { tooltip?: string } | 추가 옵션 |
options.tooltip (선택) | string | 마우스오버 툴팁 (기본값: url) |
반환값
none
isEditable()
이 차트를 편집할 수 있는지 반환한다. 외부 데이터를 소스로 하는 차트는 조회만 되고 편집은 되지 않는다.
isEditable(): Promise<boolean>;
반환값
Promise<boolean>
move(options)
글 앞·뒤에 배치한 도형의 위치를 변경한다.
x·y는 relativeFromH·relativeFromV 기준의 pt 좌표이며, 지정하지 않은 필드는 유지한다.
기준점을 변경하면 좌표의 의미도 바뀌므로 기준점은 반드시 해당 좌표와 함께 지정해야 한다.
anchorParagraphId를 지정하면 도형을 해당 단락으로 옮긴다. 지정하지 않으면 현재 단락 안에서 위치만 변경한다.
move(options: { x?: number; y?: number; relativeFromH?: PositionRelativeFromH; relativeFromV?: PositionRelativeFromV; anchorParagraphId?: string }): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
options | { x?: number; y?: number; relativeFromH?: PositionRelativeFromH; relativeFromV?: PositionRelativeFromV; anchorParagraphId?: string } | 이동 옵션(x/y 는 pt). 생략 필드는 현재값 유지 |
반환값
none
removeHyperlink()
도형의 하이퍼링크를 제거한다. - 도형 자체는 유지한다. getHyperlink()로 링크 유무를 확인할 수 있다.
removeHyperlink(): Promise<void>;
반환값
none
resize(options)
도형의 크기를 변경한다. - 너비 또는 높이를 하나 이상 지정한다. 지정하지 않은 방향의 크기는 유지한다.
resize(options: Size): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
options | Size | 변경할 크기(pt). 각 생략 가능·최소 하나, 생략 축은 현재값 유지 |
반환값
none
setAxisTitle(axis, title)
지정한 축의 제목을 설정한다. 축 제목은 원형 계열·도넛·방사형을 뺀 차트 종류에서 지원한다. 빈 문자열을 넘기면 축 제목을 비운다.
setAxisTitle(axis: ChartAxis, title: string): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
axis | ChartAxis | 제목을 설정할 축(가로축 또는 세로축) |
title | string | 축에 표시할 제목. 255자까지 지원한다 |
반환값
none
setDataLabelPosition(position)
데이터레이블 위치를 설정한다. "none" 을 넘기면 데이터레이블을 없앤다. 데이터레이블 설정은 2차원 차트(원형 대 원형·주식형·표면형 제외)에서만 쓸 수 있고, 3차원 차트는 현재 지원하지 않는다. 쓸 수 있는 위치는 차트 종류마다 다르다.
setDataLabelPosition(position: ChartDataLabelPosition): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
position | ChartDataLabelPosition | 데이터레이블을 놓을 자리 |
반환값
none
setFill(fill)
도형 채우기를 설정한다.
blipFill 의 image 는 { src }(서버에 올라가 있는 파일 이름) / { url }(바깥 이미지 주소) / { base64 } 중 하나를 준다. url·base64 는 서버에 먼저 올린 다음 채우므로, 무엇을 주든 결과를 기다려야 한다 - 항상 await 로 호출한다.
입력은 getFill() 반환과 같은 형태(ShapeFill) - 읽은 값을 그대로 다시 적용할 수 있다.
setFill(fill: ShapeFill): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
fill | ShapeFill | 채우기 정보 (종류별 유효 필드는 type 이 결정) |
반환값
none - 반환값 없음
setGridLine(axis, gridType)
지정한 축의 눈금선을 설정한다. "none" 을 넘기면 그 축의 눈금선을 숨긴다. 눈금선은 그 축의 눈금선을 갖는 차트 종류에서 지원한다(원형 계열·도넛은 양축, 방사형은 세로축이 없다).
setGridLine(axis: ChartAxis, gridType: ChartGridLineType): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
axis | ChartAxis | 눈금선을 설정할 축(가로축 또는 세로축) |
gridType | ChartGridLineType | 표시할 눈금선 종류 |
반환값
none
setLegendPosition(position)
범례 위치를 설정한다. "none" 을 넘기면 범례를 숨긴다.
setLegendPosition(position: ChartLegendPosition): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
position | ChartLegendPosition | 범례를 놓을 자리 |
반환값
none
setLine(options)
도형 선을 설정한다. - 생략 = 변경 없음, null(color/dash/compound) = 제거. width 의 null/비숫자는 거부한다(제거 의미 없음).
setLine(options: ShapeLine): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
options | ShapeLine | 선 옵션. 생략=변경없음, color/dash/compound 의 null=제거 |
반환값
none
setStyle(style)
차트의 프리셋 스타일을 바꾼다. 번호에 대응하는 실제 색은 문서 테마를 따른다.
setStyle(style: number): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
style | number | 스타일 번호(1 |
반환값
none
setText(text)
도형의 텍스트 내용을 교체한다.
일반 도형에는 텍스트 영역을 새로 만든다. 이미지 등 텍스트를 담을 수 없는 도형에는 오류가 발생한다.
빈 문자열은 내용을 비운다.
setText(text: string): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
text | string | 채울 텍스트 ("" 이면 비우기) |
반환값
none
setTextMargin(options)
도형 텍스트 영역의 안쪽 여백을 설정한다. - 텍스트 영역이 있는 도형에 네 방향의 여백을 모두 지정한다.
setTextMargin(options: { left: number; top: number; right: number; bottom: number }): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
options | { left: number; top: number; right: number; bottom: number } | 네 방향 여백(pt, 각 0 이상) |
반환값
none
setTextVerticalAlign(align)
도형 텍스트의 세로 정렬을 설정한다. - 텍스트 영역이 있는 도형에만 적용한다. 영역이 없으면 setText()로 텍스트를 먼저 추가한다.
setTextVerticalAlign(align: TextVerticalAlign): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
align | TextVerticalAlign | "top"(위)|"middle"(가운데)|"bottom"(아래) |
반환값
none
setTitle(title)
차트 제목을 설정한다. 빈 문자열을 넘기면 제목을 비운다.
setTitle(title: string): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
title | string | 차트에 표시할 제목. 255자까지 지원한다 |
반환값
none
setType(chartType)
차트 종류를 바꾼다. 지금 종류와 같은 값을 넘기면 아무것도 바뀌지 않는다.
setType(chartType: ChartType): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
chartType | ChartType | 바꿀 차트 종류(enum 문자열, 예: "clustered_column") |
반환값
none
setWrap(wrap)
도형의 배치 방식을 변경한다. - 글자처럼 배치하거나 글 앞·뒤에 배치하도록 전환한다.
setWrap(wrap: ShapeWrap): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
wrap | ShapeWrap | "inline"(글자처럼)|"infront"(글 앞)|"behind"(글 뒤) |
반환값
none
setZOrder(order)
글 앞·뒤에 배치한 도형의 앞뒤 순서를 변경한다. - 이미 맨 앞이나 맨 뒤에 있는 도형에 같은 위치를 지정하면 변경하지 않는다.
setZOrder(order: ShapeZOrder): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
order | ShapeZOrder | "front"(맨 앞)|"back"(맨 뒤)|"forward"(한 단계 앞)|"backward"(한 단계 뒤) |
반환값
none
updateHyperlink(options)
도형에 연결된 하이퍼링크의 주소나 설명을 수정한다. - 기존 링크가 없으면 오류가 발생한다. 지정하지 않은 필드는 유지한다.
updateHyperlink(options: { url?: string; tooltip?: string }): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
options | { url?: string; tooltip?: string } | 수정할 항목 (url/tooltip 중 최소 하나) |
options.url (선택) | string | 새 URL (웹 http(s):// · 이메일 mailto: · 북마크 #name), 기본 현재값 (기본값: current value) |
options.tooltip (선택) | string | 새 툴팁, 기본 현재값 (기본값: current value) |
반환값
none