Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Phần này mô tả những hành vi và giới hạn mà bạn phải nắm rõ khi chỉnh sửa tài liệu bằng Google Docs API.
Nhìn chung, bạn không thể thực hiện các thao tác chỉnh sửa khiến cấu trúc của các phần tử trong tài liệu trở nên không hợp lệ. Xem xét từng phương thức yêu cầu documents.batchUpdate để biết các quy tắc và ràng buộc áp dụng cho những yêu cầu đó.
Các phần sau đây tóm tắt các quy tắc chính trong các phương thức này.
Chèn văn bản
Việc chèn một ký tự dòng mới sẽ ngầm tạo một Paragraph tại chỉ mục đó. Kiểu đoạn văn của đoạn văn mới được sao chép từ đoạn văn tại chỉ mục chèn hiện tại, bao gồm cả danh sách và dấu đầu dòng.
Bạn phải chèn văn bản trong phạm vi của một Paragraph hiện có. Ví dụ: bạn không thể chèn văn bản vào chỉ mục bắt đầu của bảng. Bạn phải chèn văn bản vào đoạn văn trước đó.
API có thể điều chỉnh vị trí một cách ngầm định để ngăn việc chèn trong các cụm chữ cái Unicode. Khi điều này xảy ra, văn bản sẽ được chèn ngay sau cụm chữ.
Kiểu văn bản cho văn bản được chèn sẽ được xác định tự động, thường là giữ nguyên kiểu của văn bản lân cận. Thông thường, kiểu văn bản cho văn bản được chèn sẽ khớp với văn bản ngay trước chỉ mục chèn.
Một số ký tự điều khiển (U+0000-U+0008, U+000C-U+001F) và ký tự trong Vùng sử dụng riêng của Mặt phẳng đa ngôn ngữ cơ bản Unicode (U+E000-U+F8FF) sẽ bị xoá khỏi văn bản được chèn.
Tạo dấu đầu dòng cho tất cả các đoạn văn trùng lặp với phạm vi đã cho.
Cấp độ lồng của mỗi đoạn văn được xác định bằng số lượng thẻ tab ở đầu trước mỗi đoạn văn.
Các thẻ ở đầu sẽ bị xoá khi bạn tạo dấu đầu dòng, điều này có thể làm thay đổi chỉ mục của các phần trong văn bản.
Nếu bạn thêm dấu đầu dòng của đoạn văn trùng khớp với dấu đầu dòng của một danh sách ngay trước đoạn văn đích, thì đoạn văn đó sẽ được nối vào danh sách.
Việc xoá văn bản vượt quá ranh giới đoạn có thể khiến các kiểu đoạn, danh sách, đối tượng được định vị và dấu trang thay đổi khi hai đoạn được hợp nhất.
Bạn không được phép xoá nội dung gây ra cấu trúc tài liệu không hợp lệ. Sau đây là một số ví dụ về yêu cầu xoá không hợp lệ:
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 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)"]]
