본문으로 건너뛰기

Word.Shape

Word.Shape은 Word 모듈(Office.word(iframe))의 객체 타입입니다. 메서드 18개.

Generated from the SDK type definitions

Word · 객체 타입 14개 · 메서드 259개 · 네임스페이스 Word. 이 레퍼런스는 SDK 빌드와 함께 생성된 API 문서 아티팩트(sdk-api-doc.html)에서 생성됩니다. 설명은 게시된 편집기 API 주석 그대로입니다. SDK와 Office 버전을 함께 고정하고, 둘 중 하나가 바뀌면 다시 생성하십시오.

비고​

메서드​

메서드설명
delete()도형을 삭제한다.
getBody()도형 내부의 텍스트 영역을 반환한다.
getFill()도형의 현재 채우기 설정을 반환한다.
getHyperlink()도형에 연결된 하이퍼링크 정보를 반환한다.
getLine()도형의 현재 선 설정을 반환한다.
getRange()도형이 놓인 자리 범위를 반환한다.
insertHyperlink(url, options)도형에 하이퍼링크를 설정한다.
move(options)글 앞·뒤에 배치한 도형의 위치를 변경한다.
removeHyperlink()도형의 하이퍼링크를 제거한다.
resize(options)도형의 크기를 변경한다.
setFill(fill)도형 채우기를 설정한다.
setLine(options)도형 선을 설정한다.
setText(text)도형의 텍스트 내용을 교체한다.
setTextMargin(options)도형 텍스트 영역의 안쪽 여백을 설정한다.
setTextVerticalAlign(align)도형 텍스트의 세로 정렬을 설정한다.
setWrap(wrap)도형의 배치 방식을 변경한다.
setZOrder(order)글 앞·뒤에 배치한 도형의 앞뒤 순서를 변경한다.
updateHyperlink(options)도형에 연결된 하이퍼링크의 주소나 설명을 수정한다.

메서드 상세​

delete()​

도형을 삭제한다. - 글자처럼 배치한 도형과 글 앞·뒤에 배치한 도형 모두 삭제할 수 있다.

delete(): Promise<void>;

반환값

Promise<void>

getBody()​

도형 내부의 텍스트 영역을 반환한다.

getBody(): Promise<Body>;

반환값

Promise<Body> - 텍스트 영역 컨테이너, 텍스트박스가 아니면 null

getFill()​

도형의 현재 채우기 설정을 반환한다.
반환값은 setFill()에 그대로 전달할 수 있다.
테마색 채우기와 방사형 그라데이션 채우기는 type 만 반환하므로, 그 값을 그대로 setFill()에 전달하면 오류가 발생한다.

getFill(): Promise<ShapeFill | null>;

반환값

Promise<ShapeFill | null> - 채우기 정보(setFill 입력과 동형), fill 정보가 없으면 null

도형에 연결된 하이퍼링크 정보를 반환한다. - 도형 하나에는 하나의 하이퍼링크를 연결할 수 있다.

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="이름"

getLine()​

도형의 현재 선 설정을 반환한다. - 반환값은 setLine()에 그대로 전달할 수 있다.

getLine(): Promise<ShapeLine | null>;

반환값

Promise<ShapeLine | null> - 선 정보(setLine 입력과 동형), line 정보가 없으면 null

getRange()​

도형이 놓인 자리 범위를 반환한다. - 글자 한 칸을 차지하는 자리라 시작=끝이다.

getRange(): Promise<Range>;

반환값

Promise<Range> - 도형 자리 범위(도형이 없으면 사용 시점에 오류)

도형에 하이퍼링크를 설정한다. - 기존 링크가 있으면 교체한다. 웹 주소·이메일·책갈피는 URL 형식으로 구분하며, 프로토콜 없는 웹 주소에는 https://를 붙인다.

insertHyperlink(url: string, options?: { tooltip?: string }): Promise<void>;

매개변수

이름타입설명
urlstring링크 목적지
options (선택){ tooltip?: string }추가 옵션
options.tooltip (선택)string마우스오버 툴팁 (기본값: url)

반환값

Promise<void>

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). 생략 필드는 현재값 유지

반환값

Promise<void>

도형의 하이퍼링크를 제거한다. - 도형 자체는 유지한다. getHyperlink()로 링크 유무를 확인할 수 있다.

removeHyperlink(): Promise<void>;

반환값

Promise<void>

resize(options)​

도형의 크기를 변경한다. - 너비 또는 높이를 하나 이상 지정한다. 지정하지 않은 방향의 크기는 유지한다.

resize(options: Size): Promise<void>;

매개변수

이름타입설명
optionsSize변경할 크기(pt). 각 생략 가능·최소 하나, 생략 축은 현재값 유지

반환값

Promise<void>

setFill(fill)​

도형 채우기를 설정한다.
blipFill 의 image 는 { src }(서버에 올라가 있는 파일 이름) / { url }(바깥 이미지 주소) / { base64 } 중 하나를 준다. url·base64 는 서버에 먼저 올린 다음 채우므로, 무엇을 주든 결과를 기다려야 한다 - 항상 await 로 호출한다.
입력은 getFill() 반환과 같은 형태(ShapeFill) - 읽은 값을 그대로 다시 적용할 수 있다.

setFill(fill: ShapeFill): Promise<void>;

매개변수

이름타입설명
fillShapeFill채우기 정보 (종류별 유효 필드는 type 이 결정)

반환값

Promise<void> - 반환값 없음

setLine(options)​

도형 선을 설정한다. - 생략 = 변경 없음, null(color/dash/compound) = 제거. width 의 null/비숫자는 거부한다(제거 의미 없음).

setLine(options: ShapeLine): Promise<void>;

매개변수

이름타입설명
optionsShapeLine선 옵션. 생략=변경없음, color/dash/compound 의 null=제거

반환값

Promise<void>

setText(text)​

도형의 텍스트 내용을 교체한다.
일반 도형에는 텍스트 영역을 새로 만든다. 이미지 등 텍스트를 담을 수 없는 도형에는 오류가 발생한다.
빈 문자열은 내용을 비운다.

setText(text: string): Promise<void>;

매개변수

이름타입설명
textstring채울 텍스트 ("" 이면 비우기)

반환값

Promise<void>

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 이상)

반환값

Promise<void>

setTextVerticalAlign(align)​

도형 텍스트의 세로 정렬을 설정한다. - 텍스트 영역이 있는 도형에만 적용한다. 영역이 없으면 setText()로 텍스트를 먼저 추가한다.

setTextVerticalAlign(align: TextVerticalAlign): Promise<void>;

매개변수

이름타입설명
alignTextVerticalAlign"top"(위)|"middle"(가운데)|"bottom"(아래)

반환값

Promise<void>

setWrap(wrap)​

도형의 배치 방식을 변경한다. - 글자처럼 배치하거나 글 앞·뒤에 배치하도록 전환한다.

setWrap(wrap: ShapeWrap): Promise<void>;

매개변수

이름타입설명
wrapShapeWrap"inline"(글자처럼)|"infront"(글 앞)|"behind"(글 뒤)

반환값

Promise<void>

setZOrder(order)​

글 앞·뒤에 배치한 도형의 앞뒤 순서를 변경한다. - 이미 맨 앞이나 맨 뒤에 있는 도형에 같은 위치를 지정하면 변경하지 않는다.

setZOrder(order: ShapeZOrder): Promise<void>;

매개변수

이름타입설명
orderShapeZOrder"front"(맨 앞)|"back"(맨 뒤)|"forward"(한 단계 앞)|"backward"(한 단계 뒤)

반환값

Promise<void>

도형에 연결된 하이퍼링크의 주소나 설명을 수정한다. - 기존 링크가 없으면 오류가 발생한다. 지정하지 않은 필드는 유지한다.

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)

반환값

Promise<void>