Word.Body
Word.Body은 Word 모듈(Office.word(iframe))의 객체 타입입니다. 메서드 24개.
Word · 객체 타입 14개 · 메서드 259개 · 네임스페이스 Word. 이 레퍼런스는 SDK 빌드와 함께 생성된 API 문서 아티팩트(sdk-api-doc.html)에서 생성됩니다. 설명은 게시된 편집기 API 주석 그대로입니다. SDK와 Office 버전을 함께 고정하고, 둘 중 하나가 바뀌면 다시 생성하십시오.
비고
- 모듈: Word ·
Office.word(iframe)· 네임스페이스Word - 얻는 방법:
Document.getBody(),Section.getBody(),Section.getFooter(type),Section.getHeader(type),Paragraph.getParentBody(),Shape.getBody(),Image.getBody() - 모든 메서드는
Promise를 반환하며, 시그니처는 TypeScript 표기입니다.
메서드
| 메서드 | 설명 |
|---|---|
acceptChangeTrackings() | 이 영역 안의 모든 변경 추적 항목을 수락한다. |
clear() | 이 영역의 내용을 비우고 빈 단락 하나를 남긴다. |
exists() | 이 콘텐츠 영역이 실제로 존재하는지 확인한다. |
getChangeTrackings() | 이 영역 안의 변경 추적 항목 목록을 문서 순서로 반환한다. |
getComments() | 이 영역의 댓글 목록을 반환한다. |
getContentHtml() | 이 영역의 전체 내용을 서식이 포함된 HTML로 반환한다. |
getEndnotes() | 본문 안의 미주 목록을 반환한다. |
getFootnotes() | 본문 안의 각주 목록을 반환한다. |
getNotes() | 본문 안의 각주/미주 목록을 반환한다. |
getParagraph(index) | 이 영역에서 지정한 인덱스의 단락을 반환한다. |
getParagraphs() | 이 영역의 단락 목록을 반환한다. |
getRange(range) | 이 영역 안의 지정한 위치 또는 좌표에 해당하는 범위를 반환한다. |
getStoryId() | 이 영역의 식별자를 반환한다. |
getStructure(options) | 이 영역의 단락/표 구조를 반환한다. |
getText() | 이 영역의 전체 내용을 일반 텍스트로 반환한다. |
insertHtml(html, options) | HTML을 삽입하고 삽입된 내용의 범위를 반환한다. |
insertParagraph(text, options) | 새 단락을 삽입하며, 위치를 생략하면 영역 맨 끝에 추가한다. |
insertTable(rows, columns, options) | 표를 삽입하며, 위치를 생략하면 영역 맨 끝에 추가한다. |
insertText(text, options) | 이 영역에 텍스트를 넣는다. |
rejectChangeTrackings() | 이 영역 안의 모든 변경 추적 항목을 거부한다. |
replaceAll(findText, replaceText, options) | 이 영역 안에서 일치하는 텍스트를 모두 찾아 교체한다. |
replaceParagraphs(items) | 여러 단락을 한 번에 제자리 교체한다. |
search(query, options) | 이 영역에서 텍스트 또는 특수 문자를 찾아 편집 가능한 범위 목록을 반환한다. |
select(mode) | 이 영역 전체를 화면 선택 영역으로 지정한다(문서 내용은 바꾸지 않는다). |
메서드 상세
acceptChangeTrackings()
이 영역 안의 모든 변경 추적 항목을 수락한다.
acceptChangeTrackings(): Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }>;
반환값
Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }> - 처리 결과
clear()
이 영역의 내용을 비우고 빈 단락 하나를 남긴다. - 콘텐츠 영역 자체는 유지한다.
clear(): Promise<boolean>;
반환값
Promise<boolean> - 영역이 존재하면 true(이미 빈 영역도 포함), 영역이 없으면 false
exists()
이 콘텐츠 영역이 실제로 존재하는지 확인한다. - 아직 만들어지지 않은 머리글·바닥글은 첫 콘텐츠 삽입 시 생성한다.
exists(): Promise<boolean>;
반환값
Promise<boolean> - 영역이 존재하면 true, 아직 생성되지 않았으면 false
getChangeTrackings()
이 영역 안의 변경 추적 항목 목록을 문서 순서로 반환한다.
getChangeTrackings(): Promise<WordChangeTracking[]>;
반환값
Promise<WordChangeTracking[]> - 변경 추적 proxy 배열
getComments()
이 영역의 댓글 목록을 반환한다. 본문 영역에서만 동작하며, 그 외 영역은 빈 배열을 반환한다.
getComments(): Promise<WordComment[]>;
반환값
Promise<WordComment[]> - 댓글 proxy 배열
getContentHtml()
이 영역의 전체 내용을 서식이 포함된 HTML로 반환한다. - 단락은 <p> 요소로 표현한다.
getContentHtml(): Promise<{ html: string; paragraphCount: number }>;
반환값
Promise<{ html: string; paragraphCount: number }> - HTML과 단락 수. 영역이 없으면 빈 문자열과 0
getEndnotes()
본문 안의 미주 목록을 반환한다. (본문 영역 한정)
getEndnotes(): Promise<WordNote[]>;
반환값
Promise<WordNote[]> - 미주 proxy 배열
getFootnotes()
본문 안의 각주 목록을 반환한다. (본문 영역 한정)
getFootnotes(): Promise<WordNote[]>;
반환값
Promise<WordNote[]> - 각주 proxy 배열
getNotes()
본문 안의 각주/미주 목록을 반환한다. (본문 영역 한정)
getNotes(): Promise<WordNote[]>;
반환값
Promise<WordNote[]> - note proxy 배열
getParagraph(index)
이 영역에서 지정한 인덱스의 단락을 반환한다.
getParagraph(index?: number): Promise<Paragraph>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
index (선택) | number | 0부터 시작하는 단락 인덱스 (기본값: 0) |
반환값
Promise<Paragraph> - 조회·편집 가능한 단락. 영역 또는 해당 단락이 없으면 null
getParagraphs()
이 영역의 단락 목록을 반환한다.
getParagraphs(): Promise<Paragraph[]>;
반환값
Promise<Paragraph[]> - 조회·편집 가능한 단락 목록. 영역이 없으면 빈 배열
getRange(range)
이 영역 안의 지정한 위치 또는 좌표에 해당하는 범위를 반환한다.
getRange(range?: (RangeData | RangePosition)): Promise<Range>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
range (선택) | (RangeData | RangePosition) | 좌표 RangeData 객체, 또는 영역 위치 RangePosition("whole"/"start"/"end"/"content"); 생략하면 영역 전체(whole) (기본값: RangePosition.WHOLE) |
반환값
Promise<Range> - 이 영역 안에서 조회·편집할 수 있는 범위
getStoryId()
이 영역의 식별자를 반환한다.
getStoryId(): Promise<string>;
반환값
Promise<string> - 콘텐츠 영역의 ID
getStructure(options)
이 영역의 단락/표 구조를 반환한다. 영역이 없으면 빈 목록. - 단락 entry 의 text 는 끝 경계 개행을 담는다 - 끝의 "\n" 은 항상 단락 경계라 그 단락 안 글자 수는 text.length - 1 이고, 중간의 "\n" 은 줄 나눔 개체(수동 줄바꿈·페이지 나눔·단 나눔) 한 칸이다.
getStructure(options?: { type?: StructureFilter }): Promise<{ paragraphs: { index: number; type: string; id: string; storyId: string; text?: string; rows?: number; columns?: number }[] }>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
options (선택) | { type?: StructureFilter } | 조회 옵션. 대상 영역은 이 body 에 고정된다. |
options.type (선택) | StructureFilter | 특정 타입만 조회(table=표만 / list=목록 단락만), 기본 전체 (기본값: all) |
반환값
Promise<{ paragraphs: { index: number; type: string; id: string; storyId: string; text?: string; rows?: number; columns?: number }[] }> - 단락·표 entry 목록(문서 순서). id 는 공통 식별자(type 로 종류 판별), type="p"면 text·table 이면 rows/columns 포함
getText()
이 영역의 전체 내용을 일반 텍스트로 반환한다. - 각주/미주는 자동 번호 마커와 구분 공백을 제외한다.
getText(): Promise<string>;
반환값
Promise<string> - 읽기용 전체 텍스트. 영역이 없으면 빈 문자열
insertHtml(html, options)
HTML을 삽입하고 삽입된 내용의 범위를 반환한다.
위치를 생략하면 영역 맨 끝에 새 단락을 만들어 삽입한다.
<img> 가 포함되면 먼저 업로드하고 src 를 치환한다. 업로드에 실패한 이미지는 제외되고 나머지는 삽입된다.
태그가 없는 평문("hello")·블록 아닌 태그("\<div\>abc\</div\>")도 단락 안의 텍스트로 정규화되고, 여러 단락짜리 HTML("\<p\>a\</p\>\<p\>b\</p\>")은 그 단락 전체를 포함하는 범위를 돌려준다.
붙여넣기(paste)와 같은 경로로 들어가므로 붙여넣기가 지원하지 않는 것은 삽입되지 않는다:
목록 스타일이 붙지 않는다 - \<ul\>/\<ol\>/\<li\> 는 번호·불릿 없는 일반 단락으로 들어간다(목록은 WordParagraph.setList 로 따로 지정).
제목 스타일도 붙지 않는다 - \<h1\>~\<h6\> 은 스타일 없는 일반 단락으로 들어간다(스타일은 WordRange.setStyle 로 따로 지정).
문서 콘텐츠가 아닌 태그(\<script\>/\<style\>/\<iframe\> 등)는 내부 텍스트까지 함께 버린다.
변경 추적(track changes)을 켜 두면 일반 붙여넣기와 같이 삽입 내용이 revision 으로 남는다(메모 안은 제외).
블록 HTML(\<p\>·\<h1\> 등)은 블록마다 단락 나누기를 함께 넣기 때문에 마지막 블록 뒤에 빈 단락이 하나 남는다(평문·인라인은 안 남는다).
insertHtml(
html: string,
options?: { paragraphId?: string; position?: InsertAt }
): Promise<Range>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
html | string | 삽입할 HTML. 빈 문자열(공백만도 동일)이면 문서를 바꾸지 않고 삽입 지점의 빈 범위만 반환 |
options (선택) | { paragraphId?: string; position?: InsertAt } | 삽입 위치 옵션 |
options.paragraphId (선택) | string | 기준 단락 ID |
options.position (선택) | InsertAt | 기준 단락이 없으면 "start"(영역 맨 앞)/"end"(영역 맨 끝)에 새 단락을 만들어 그 안에 넣는다. 기준 단락이 있으면 형제 위치가 아니라 삽입 지점이다 - "after"는 그 단락의 끝 지점, "before"는 그 단락의 시작 지점. "after"는 앵커 단락 끝에 이어붙으므로 첫 내용이 그 단락에 합쳐지고(\<p\>A\</p\>\<p\>B\</p\> = 앵커에 A 합침 + B 는 새 단락), "before"는 블록이면 앵커 앞 새 단락이 되고 인라인이면 앵커 맨 앞에 합쳐진다. 기본값은 기준 단락 있으면 after·없으면 end (기본값: after if a reference paragraph is given, otherwise end) |
반환값
Promise<Range> - 삽입된 내용의 범위. 넣을 내용이 없으면(빈 HTML·내용 없는 HTML) 삽입 지점의 빈 범위(collapsed). 삽입 실패는 예외로 알린다.
insertParagraph(text, options)
새 단락을 삽입하며, 위치를 생략하면 영역 맨 끝에 추가한다.
영역이 없으면 자동 생성한다. 새 단락은 기준 단락의 정렬·여백·들여쓰기 등 직접 단락 서식을 상속한다.
paragraphId를 생략하면 삽입 위치에 따라 영역의 첫 단락 또는 마지막 단락을 기준으로 한다.
상속한 직접 서식을 초기화하려면 반환된 단락의 clearFormat()을 호출한다.
insertParagraph(
text: string,
options?: { paragraphId?: string; position?: InsertAt }
): Promise<Paragraph>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
text | string | 새 단락 텍스트 |
options (선택) | { paragraphId?: string; position?: InsertAt } | 삽입 옵션 |
options.paragraphId (선택) | string | 기준 단락 ID |
options.position (선택) | InsertAt | 기준 단락이 있으면 그 단락 기준 "before"(위)/"after"(아래), 없으면 영역 위치 "start"(맨 앞)/"end"(맨 끝). 기본값은 기준 단락 있으면 after·없으면 end (기본값: after if a reference paragraph is given, otherwise end) |
반환값
Promise<Paragraph> - 삽입 후 조회·편집할 수 있는 새 단락
insertTable(rows, columns, options)
표를 삽입하며, 위치를 생략하면 영역 맨 끝에 추가한다. - 표 셀 안에는 삽입할 수 없다. 삽입 지점이 셀 안이면 오류가 발생한다.
insertTable(
rows: number,
columns: number,
options?: { paragraphId?: string; position?: InsertAt; values?: string[][] }
): Promise<Table>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
rows | number | 행 수 |
columns | number | 열 수 |
options (선택) | { paragraphId?: string; position?: InsertAt; values?: string[][] } | 삽입 옵션 |
options.paragraphId (선택) | string | 기준 단락 ID |
options.position (선택) | InsertAt | 기준 단락이 있으면 그 단락 기준 "before"(위)/"after"(아래), 없으면 영역 위치 "start"(맨 앞)/"end"(맨 끝). 기본값은 기준 단락 있으면 after·없으면 end (기본값: after if a reference paragraph is given, otherwise end) |
options.values (선택) | string[][] | 생성 직후 채울 셀 값(2차원 배열, 표 크기 초과 시 발행 전 throw) |
반환값
Promise<Table> - 삽입된 표 proxy
insertText(text, options)
이 영역에 텍스트를 넣는다. 맨 앞에 추가하거나 내용 전체를 교체한다.
replace 를 주지 않으면 영역 맨 앞에 텍스트를 넣고 기존 내용은 그대로 둔다.
replace 를 주면 내용 전체를 교체하고 단락 하나만 남으므로, 여러 단락이던 내용은 한 단락이 된다.
영역이 아직 없으면 영역을 만들고 이 텍스트를 첫 내용으로 넣는다.
각주·미주 영역에서 replace 는 자동 번호 마커와 그 뒤 공백을 그대로 두고, 뒤따르는 텍스트만 교체한다.
텍스트만 바뀌고 영역의 서식은 그대로다. 서식이 필요하면 반환된 범위에 적용한다.
insertText(text: string, options?: { replace?: boolean }): Promise<Range>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
text | string | 넣을 텍스트. 빈 문자열에 replace 를 주면 영역이 비워진다 |
options (선택) | { replace?: boolean } | 삽입 옵션 |
options.replace (선택) | boolean | true 면 영역 내용 전체를 교체하고, 생략하면 맨 앞에 추가한다 (기본값: false) |
반환값
Promise<Range> - 넣은 텍스트의 범위. 각주·미주 replace 는 번호 마커를 포함한 첫 단락 범위다. 각주·미주에 교체할 내용이 없으면 null
rejectChangeTrackings()
이 영역 안의 모든 변경 추적 항목을 거부한다.
rejectChangeTrackings(): Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }>;
반환값
Promise<{ processedCount: number; remainingCount: number; failedIds: string[] }> - 처리 결과
replaceAll(findText, replaceText, options)
이 영역 안에서 일치하는 텍스트를 모두 찾아 교체한다. - 본문에서 부르면 본문 전체, 머리글/바닥글 등에서 부르면 그 영역 안으로 범위가 한정된다.
replaceAll(
findText: string,
replaceText: string,
options?: { caseSensitive?: boolean }
): Promise<{ replacedCount: number }>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
findText | string | 찾을 텍스트 |
replaceText | string | 바꿀 텍스트 |
options (선택) | { caseSensitive?: boolean } | 교체 옵션 |
options.caseSensitive (선택) | boolean | 대소문자 구분 (기본값: false) |
반환값
Promise<{ replacedCount: number }> - 실제로 교체된 건수(매치가 없으면 0)
replaceParagraphs(items)
여러 단락을 한 번에 제자리 교체한다. 텍스트만 바꾸며, keepFormat 이 아니면 교체 범위 서식을 초기화한다.
replaceParagraphs(items: { paragraphId: string; text: string; keepFormat?: boolean }[]): Promise<number>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
items | { paragraphId: string; text: string; keepFormat?: boolean }[] | 교체할 단락 목록(이 영역 안에서 찾는다). keepFormat 기본 false(서식 초기화) |
반환값
Promise<number> - 교체 성공 개수
search(query, options)
이 영역에서 텍스트 또는 특수 문자를 찾아 편집 가능한 범위 목록을 반환한다.
search(
query: string | { character: SpecialCharacter },
options?: { caseSensitive?: boolean; wholeWord?: boolean }
): Promise<Range[]>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
query | string | { character: SpecialCharacter } | 문자열이면 텍스트 검색, \{ character \} 객체이면 특수 문자 검색 |
options (선택) | { caseSensitive?: boolean; wholeWord?: boolean } | 텍스트 검색 옵션(특수 문자 검색은 무시) |
options.caseSensitive (선택) | boolean | 대소문자 구분 (기본값: false) |
options.wholeWord (선택) | boolean | 단어 단위 검색 (기본값: false) |
반환값
Promise<Range[]> - 매칭된 범위 proxy 목록 (없으면 빈 배열)
select(mode)
이 영역 전체를 화면 선택 영역으로 지정한다(문서 내용은 바꾸지 않는다).
select(mode?: SelectionMode): Promise<void>;
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
mode (선택) | SelectionMode | "select"(영역 전체) / "start"(영역 시작에 커서) / "end"(영역 끝에 커서) (기본값: SelectionMode.SELECT) |
반환값
Promise<void>