구조 수정 규칙 및 동작
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 섹션에서는 Google Docs API를 사용하여 문서를 수정할 때 이해해야 하는 동작과 제한사항을 설명합니다.
일반적으로 문서 내 요소의 구조가 잘못되는 수정사항은 실행할 수 없습니다. 각 documents.batchUpdate 요청 메서드를 검토하여 해당 요청에 적용되는 제약 조건과 규칙을 확인합니다.
다음 섹션에서는 이러한 방법 전반의 주요 규칙을 요약합니다.
텍스트 삽입
- 줄바꿈 문자를 삽입하면 해당 색인에
Paragraph이 암시적으로 생성됩니다. 새 단락의 단락 스타일은 목록과 글머리 기호를 포함하여 현재 삽입 색인의 단락에서 복사됩니다.
- 텍스트는 기존
Paragraph의 경계 내에 삽입해야 합니다. 예를 들어 표의 시작 색인에는 텍스트를 삽입할 수 없습니다. 텍스트는 앞 단락에 삽입해야 합니다.
- API는 유니코드 그래핀 클러스터 내 삽입을 방지하기 위해 위치를 암시적으로 조정할 수 있습니다. 이 경우 텍스트는 그라피미 클러스터 바로 뒤에 삽입됩니다.
- 삽입된 텍스트의 텍스트 스타일은 자동으로 결정되며 일반적으로 인접한 텍스트의 스타일이 유지됩니다. 일반적으로 삽입된 텍스트의 텍스트 스타일은 삽입 색인 바로 앞의 텍스트와 일치합니다.
- 일부 제어 문자 (
U+0000-U+0008, U+000C-U+001F)와 유니코드 기본 다국어 평면 비공개 사용 영역 (U+E000-U+F8FF)의 문자는 삽입된 텍스트에서 삭제됩니다.
- 자세한 내용은 텍스트 삽입, 삭제, 이동하기를 참고하세요.
인라인 이미지 삽입
- 이미지 크기는 50MB 미만이어야 하고, 2, 500만 화소를 초과할 수 없으며, PNG, JPEG 또는 GIF 형식 중 하나여야 합니다.
- 제공된 URI는 공개적으로 액세스할 수 있어야 하며 길이가 최대 2KB여야 합니다.
- 이미지는 기존
Paragraph의 경계 내에 삽입해야 합니다. 예를 들어 표의 시작 색인에는 텍스트를 삽입할 수 없습니다.
- 이미지는 각주나 수식 내부에 삽입할 수 없습니다.
- 자세한 내용은 인라인 이미지 삽입을 참고하세요.
텍스트 서식 지정
- 범위에 단락 수준 서식을 적용하면 해당 범위와 부분적으로 또는 완전히 겹치는 모든 단락에 서식이 적용됩니다.
- 범위가 인접한 줄바꿈을 포함하도록 확장될 수 있습니다.
- 범위에 목록에 속하는 단락이 완전히 포함된 경우 단락의 글머리 기호도 일치하는 텍스트 스타일로 업데이트됩니다.
- 자세한 내용은 텍스트 서식 지정을 참고하세요.
단락 글머리기호 만들기
- 지정된 범위와 겹치는 모든 단락에 글머리 기호를 만듭니다.
- 각 단락의 중첩 수준은 각 단락 앞에 있는 선행 탭의 수에 따라 결정됩니다.
- 글머리 기호를 만들 때 선행 탭이 삭제되어 텍스트 부분의 색인이 변경될 수 있습니다.
- 대상 단락 바로 앞에 목록의 글머리 기호와 일치하는 단락 글머리 기호를 추가하면 단락이 목록에 추가됩니다.
- 자세한 내용은 목록 작업을 참고하세요.
텍스트 삭제
단락 경계를 교차하는 텍스트를 삭제하면 두 단락이 병합되므로 단락 스타일, 목록, 위치가 지정된 객체, 북마크가 변경될 수 있습니다.
문서 구조가 유효하지 않게 되는 삭제는 허용되지 않습니다. 잘못된 삭제 요청의 예는 다음과 같습니다.
자세한 내용은 텍스트 삽입, 삭제, 이동하기를 참고하세요.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
[null,null,["최종 업데이트: 2025-08-29(UTC)"],[],[],null,["# Structural edit rules and behavior\n\nThis section describes behaviors and limitations that you must understand when\nyou edit documents using the Google Docs API.\n\nIn general, you cannot execute edits that cause the invalid structure of\nelements within a document. Review each\n[`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate)\nrequest method for constraints and rules that apply to those\n[requests](/workspace/docs/api/reference/rest/v1/documents/request).\n\nThe following sections summarize the key rules across these methods.\n\nInsert text\n-----------\n\n- Inserting a newline character implicitly creates a [`Paragraph`](/workspace/docs/api/reference/rest/v1/documents#paragraph) at that index. The paragraph style of the new paragraph is copied from the paragraph at the current insertion index, including lists and bullets.\n- Text must be inserted within the bounds of an existing `Paragraph`. For example, text cannot be inserted at a table's start index. The text must be inserted in the preceding paragraph.\n- The API may implicitly adjust the location to prevent insertions within Unicode grapheme clusters. When this happens, the text is inserted immediately after the grapheme cluster.\n- Text styles for inserted text are determined automatically, generally preserving the styling of neighboring text. Typically, the text style for the inserted text matches the text immediately before the insertion index.\n- Some control characters (`U+0000-U+0008, U+000C-U+001F`) and characters from the Unicode Basic Multilingual Plane Private Use Area (`U+E000-U+F8FF`) are stripped out of inserted text.\n- For more information, see [Insert, delete, and move\n text](/workspace/docs/api/how-tos/move-text).\n\nInsert inline images\n--------------------\n\n- Image must be less than 50 MB in size, cannot exceed 25 megapixels, and must be in one of PNG, JPEG, or GIF formats.\n- The provided URI must be publicly accessible and at most 2 KB in length.\n- Image must be inserted within the bounds of an existing `Paragraph`. For example, text cannot be inserted at a table's start index.\n- Images can't be inserted inside a footnote or equation.\n- For more information, see [Insert inline\n images](/workspace/docs/api/how-tos/images).\n\nFormat text\n-----------\n\n- When you apply paragraph-level formatting to a range, the formatting is applied to any paragraph that's partially or completely overlapped by that range.\n- The range might be extended to include adjacent newlines.\n- If the range fully contains a paragraph belonging to a list, the paragraph's bullet is also updated with the matching text style.\n- For more information, see [Format\n text](/workspace/docs/api/how-tos/format-text).\n\nCreate paragraph bullets\n------------------------\n\n- Creates bullets for all paragraphs that overlap with the given range.\n- The nesting level of each paragraph is determined by the number of leading tabs before each paragraph.\n- The leading tabs are removed when creating the bullets, which might change the indexes of parts of the text.\n- If you add paragraph bullets that match those of a list immediately before the target paragraph, the paragraph is joined to the list.\n- For more information, see [Work with lists](/workspace/docs/api/how-tos/lists).\n\nDelete text\n-----------\n\n- Deleting text that crosses a paragraph boundary might cause changes to\n paragraph styles, lists, positioned objects, and bookmarks as the two\n paragraphs are merged.\n\n- Deletions that cause an invalid document structure are not permitted. Some\n examples of invalid delete requests include:\n\n - Deleting one code unit of a surrogate pair.\n\n - Deleting the last newline character of a\n [`Body`](/workspace/docs/api/reference/rest/v1/documents#body),\n [`Header`](/workspace/docs/api/reference/rest/v1/documents#header),\n [`Footer`](/workspace/docs/api/reference/rest/v1/documents#footer),\n [`Footnote`](/workspace/docs/api/reference/rest/v1/documents#footnote),\n [`TableCell`](/workspace/docs/api/reference/rest/v1/documents#tablecell), or\n [`TableOfContents`](/workspace/docs/api/reference/rest/v1/documents#tableofcontents).\n\n - Deleting the start or end of a\n [`Table`](/workspace/docs/api/reference/rest/v1/documents#table),\n `TableOfContents`, or\n [`Equation`](/workspace/docs/api/reference/rest/v1/documents#equation)\n without deleting the entire element.\n\n - Deleting the newline character before a `Table`, `TableOfContents`, or\n [`SectionBreak`](/workspace/docs/api/reference/rest/v1/documents#sectionbreak)\n without deleting the element.\n\n - Deleting individual rows or cells of a table. Deleting the content in a\n table cell is allowed.\n\n- For more information, see [Insert, delete, and move\n text](/workspace/docs/api/how-tos/move-text).\n\nRelated topics\n--------------\n\n- [Structure of a Google Docs document](/workspace/docs/api/concepts/structure)\n- [Requests and responses](/workspace/docs/api/concepts/request-response)"]]
