Cấu trúc và định kiểu văn bản

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.

Trong API Trang trình bày, văn bản có thể nằm trong các hình dạng hoặc trong các ô bảng. Trước khi có thể thao tác và tạo kiểu văn bản, bạn cần hiểu cấu trúc của văn bản và cách tạo kiểu.

Trang này mô tả cách văn bản được biểu thị trong API Trang trình bày.

Trình tự các phần tử văn bản

Văn bản chứa trong một hình dạng hoặc ô bảng được tạo thành từ một trình tự của các cấu trúc TextElement. Trình tự này thể hiện cấu trúc của văn bản, theo thứ tự xuất hiện từ đầu đến cuối.

Ví dụ: hãy xem xét nội dung của trang trình bày này – tất cả đều nằm trong một hộp văn bản:

Trang trình bày ở trên có một hộp văn bản, trong đó trường text chứa một trình tự các phần tử văn bản như minh hoạ trong sơ đồ sau:

Cụ thể hơn, trình tự văn bản này được biểu thị trong API Trang trình bày như sau:

"textElements": [ {
    "endIndex": 224,
    "paragraphMarker": { "style": {} }
  }, {
    "endIndex": 130,
    "textRun": { "content": "Li lingues differe in li grammatica e li vocabules. Omnicos directe al desirabilite de un nov ", "style": {} }
  }, {
    "endIndex": 143,
    "startIndex": 130,
    "textRun": { "content": "lingua franca", "style": { "italic": True } }
  }, {
    "endIndex": 224,
    "startIndex": 143,
    "textRun": { "content": ": solmen va esser necessi far:\n", "style": {} }
  }, {
    "endIndex": 243,
    "startIndex": 224,
    "paragraphMarker": {
      "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
      "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
  }, {
    "endIndex": 243,
    "startIndex": 224,
    "textRun": { "content": "uniform grammatica\n", "style": {} }
  }, {
    "endIndex": 257,
    "startIndex": 243,
    "paragraphMarker": {
        "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
        "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
}, {
    "endIndex": 257,
    "startIndex": 243,
    "textRun": { "content": "Pronunciation\n", "style": {} }
}, {
    "endIndex": 277,
    "startIndex": 257,
    "paragraphMarker": {
        "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
        "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
}, {
    "endIndex": 277,
    "startIndex": 257,
    "textRun": { "content": "plu sommun paroles.\n", "style": {} }
}, {
    "endIndex": 500,
    "startIndex": 277,
    "paragraphMarker": { "style": {} }
}, {
    "endIndex": 500,
    "startIndex": 277,
    "textRun": { "content": "Ka swu thefognay, tay waddeant varpa u inzo.\n", "style": {} }
}]

Nội dung TextElement

Mỗi phần tử văn bản chứa một chỉ mục bắt đầu và chỉ mục kết thúc dựa trên số 0, mô tả vị trí của phần tử trong toàn bộ văn bản của phần tử trang, cùng với một trong các loại đối tượng văn bản sau:

Sửa đổi nội dung văn bản

Khi cần sửa đổi văn bản bằng API Trang trình bày, bạn không cần phải tạo rõ ràng tất cả các phần tử văn bản thích hợp. Thay vào đó, bạn có thể thao tác trên văn bản như trong trình chỉnh sửa Trang trình bày: bằng cách chèn văn bản, xoá dải ô và cập nhật kiểu trên dải ô. Các thao tác này ngầm tạo các phần tử ParagraphMarker và TextRun nếu cần để phản ánh các thay đổi của bạn.

Chèn văn bản

Bạn có thể chèn văn bản tại một chỉ mục bằng cách sử dụng yêu cầu InsertTextRequest trong lệnh gọi đến batchUpdate. Trường insertionIndex của phương thức này chỉ định vị trí chèn văn bản; bạn có thể tính toán chỉ mục này bằng cách sử dụng các trường chỉ mục bắt đầu và kết thúc bên trong các phần tử văn bản.

Thao tác chèn văn bản có một số tác dụng phụ phản ánh hành vi của trình chỉnh sửa Trang trình bày:

• Việc chèn ký tự dòng mới sẽ ngầm tạo một đoạn văn bản mới, tạo một phần tử văn bản ParagraphMarker bắt đầu tại chỉ mục của dòng mới và kết thúc tại dòng mới sau. Kiểu đoạn văn (bao gồm cả dấu đầu dòng và chi tiết danh sách) được sao chép từ đoạn văn hiện tại sang đoạn văn mới.
• Kiểu của các ký tự được chèn được xác định tự động, thường là giữ nguyên kiểu văn bản đã tồn tại tại chỉ mục chèn. Do đó, văn bản thường được chèn vào TextRun hiện có tại chỉ mục đó. Bạn có thể cập nhật kiểu này sau bằng cách sử dụng yêu cầu UpdateTextStyle.

Xoá văn bản

Bạn có thể xoá một dải văn bản bằng cách sử dụng thông báo DeleteTextRequest trong lệnh gọi đến batchUpdate. Việc xoá văn bản có một số điểm cần lưu ý:

• Thao tác xoá vượt qua ranh giới đoạn văn sẽ hợp nhất hai đoạn văn, xoá phần tử văn bản ParagraphMarker phân tách.
• Đoạn văn bản mới được hợp nhất sẽ sử dụng kiểu đoạn văn bản kết hợp, khớp với hành vi trong trình chỉnh sửa Trang trình bày.
• Thao tác xoá có phạm vi bao gồm một dòng văn bản sẽ xoá tất cả nội dung khỏi dòng văn bản đó và cũng xoá chính dòng văn bản đó.
• Thao tác xoá có phạm vi bao gồm phần tử AutoText sẽ xoá phần tử AutoText.

Cập nhật kiểu văn bản

Giao diện hiển thị của văn bản trong một trang trình bày được xác định bằng các thuộc tính kiểu văn bản:

• Kiểu đoạn văn như thụt lề, căn chỉnh và ký tự dấu đầu dòng được xác định bằng các thuộc tính trên điểm đánh dấu đoạn văn.
• Kiểu ký tự như in đậm, in nghiêng và gạch dưới được xác định bằng các thuộc tính trên từng dòng văn bản.

Cập nhật kiểu ký tự

Bạn có thể cập nhật kiểu ký tự bằng cách sử dụng thông báo UpdateTextStyleRequest trong lệnh gọi đến batchUpdate.

Giống như các thao tác văn bản khác, kiểu ký tự được áp dụng cho một dải văn bản và ngầm tạo các đối tượng TextRun mới nếu cần.

Việc đặt một số kiểu ký tự sẽ tự động cập nhật các kiểu liên quan khác để khớp với hành vi trong trình chỉnh sửa Trang trình bày. Ví dụ: việc thêm đường liên kết sẽ tự động thay đổi màu nền trước của văn bản và các thuộc tính gạch dưới. Hãy xem tài liệu tham khảo về TextStyle để biết thêm thông tin chi tiết.

Cập nhật kiểu đoạn văn

Bạn có thể cập nhật kiểu đoạn văn bằng cách sử dụng thông báo UpdateParagraphStyleRequest trong lệnh gọi đến batchUpdate.

API Trang trình bày hỗ trợ CreateParagraphBulletsRequest phản ánh chức năng của các giá trị đặt trước dấu đầu dòng trong trình chỉnh sửa Trang trình bày để tạo danh sách có dấu đầu dòng và có số. Tương tự, DeleteParagraphBulletsRequest sẽ xoá mọi dấu đầu dòng hiện có trên các đoạn văn bản.

Kiểu kế thừa

Một số hình dạng, được gọi là phần giữ chỗ, có thể kế thừa kiểu văn bản từ các hình dạng mẹ khác: xem phần giữ chỗ để tìm hiểu thêm về việc kế thừa hình dạng nói chung.

Phần này tập trung vào cách hoạt động của tính năng kế thừa kiểu để tạo các kiểu văn bản kết xuất cuối cùng hiển thị trong một trang trình bày.

Biểu thị kiểu trong phần giữ chỗ

Phần về phần giữ chỗ mô tả cách hoạt động của tính kế thừa giữa các hình mẹ và con. Tính năng kế thừa kiểu văn bản được xử lý bằng các tính năng bổ sung trong mô hình kế thừa:

• Các thuộc tính của phần tử văn bản ParagraphMaker xác định định dạng đoạn văn.
• Các thuộc tính của phần tử văn bản TextRun xác định định dạng ký tự.
• Nội dung của phần giữ chỗ mẹ chứa 8 cặp ParagraphMarker/TextRun như vậy (để hỗ trợ 8 cấp độ lồng danh sách).
• Phần giữ chỗ con kế thừa các thuộc tính văn bản mặc định từ các phần tử văn bản này trong nội dung văn bản của phần tử mẹ.

Sơ đồ sau đây cho thấy một cách để hình dung các mối quan hệ này:

ParagraphMarker/TextRun đầu tiên trong hình mẹ xác định hầu hết kiểu văn bản được kế thừa; kiểu trong 7 cặp còn lại chỉ ảnh hưởng đến các đoạn văn bản ở các cấp độ dấu đầu dòng lồng ghép sâu hơn:

Để truy cập vào các cặp phần tử văn bản này, hãy sử dụng chỉ mục rõ ràng của chúng trong trường textElements như minh hoạ trong đoạn mã dưới đây. Đoạn mã này cho thấy cách thiết lập kiểu mặc định (có thể kế thừa) cho cấp 0 và các đoạn văn bản không phải danh sách:

"text": {
  "textElements": [  {
     "startIndex": 0,
     "endIndex": 1,
     "paragraphMarker": {
       "style": {  "alignment": "START",  ...  },
       "bullet": {  "nestingLevel": 0,  ...  }
     }
   },{
     "startIndex": 0,
     "endIndex": 1,
     "textRun": {
       "content": "\n",
       "style": {  "foregroundColor": {  "opaqueColor": {  "themeColor": "DARK1"  }  },  }
     }
   },{
     ...
   } ]
 }

Xin lưu ý rằng trường content của TextRun của hình dạng mẹ luôn bao gồm một ký tự dòng mới.

Có thể ghi đè các kiểu kế thừa

Một hình dạng con có thể chỉ định các thuộc tính kiểu trên các phần tử ParagraphMarker và TextRun trong nội dung của hình dạng đó. Các thuộc tính được chỉ định cục bộ này sẽ ghi đè mọi thuộc tính kế thừa trong phạm vi cục bộ của chúng. Các phần tử không chỉ định kiểu nào sẽ sử dụng kiểu tương ứng được kế thừa từ phần tử mẹ.

Việc xoá một thuộc tính kiểu rõ ràng khỏi một hình dạng con để thuộc tính đó không còn được đặt sẽ khiến thuộc tính đó kế thừa từ hình dạng mẹ.

Ví dụ:

Với tính năng kế thừa hiển thị trong sơ đồ trên, giả sử hình dạng ParentPlaceholder có nội dung văn bản sau:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {"alignment": "START", ...},
        "bullet": {"nestingLevel": 0, ...}
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, }
        ...
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {"alignment": "END", ...},
        "bullet": {"nestingLevel": 1, ...}
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "LIGHT1"} }, ...}
      }
    },
   ...
  ]
}

Và giả sử hình dạng ChildPlaceholder có nội dung văn bản sau:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {},
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "This is my first paragraph\n",
        "style": {},
      }
      ...
    },
    {  "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {},
        "bullet": {
          "nestingLevel": 1,
          "listId": "someListId",
          "glyph": "●"
        }
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "This paragraph is in a list\n",
        "style": {},
        ...
      }
    }
  ]
}

Điều này dẫn đến các kết quả được mô tả trong các đoạn sau.

Kế thừa kiểu cho một đoạn văn bản thuần tuý

Đoạn văn đầu tiên của hình dạng con (bao gồm văn bản "Đây là đoạn văn đầu tiên của tôi") là một đoạn văn thuần tuý (không nằm trong danh sách). Không có phần tử nào trong nội dung văn bản chỉ định thuộc tính kiểu nào, vì vậy, phần tử này kế thừa tất cả kiểu ký tự và kiểu đoạn văn từ phần tử mẹ. Điều này dẫn đến kết quả hiển thị sau:

• Văn bản: "This is my first paragraph" (Đây là đoạn văn đầu tiên của tôi) là văn bản được hiển thị. Bản thân văn bản không bao giờ được kế thừa.
• Căn chỉnh: Văn bản được kết xuất bằng cách căn chỉnh START, kế thừa từ ParagraphMarker đầu tiên của thành phần mẹ.
• Màu nền trước: Văn bản được kết xuất bằng màu nền trước DARK1, kế thừa từ TextRun đầu tiên của thành phần mẹ.

Tính kế thừa kiểu cho đoạn văn danh sách

Đoạn văn tiếp theo, bao gồm văn bản "Đoạn văn này nằm trong danh sách", nằm trong danh sách có dấu đầu dòng ở cấp lồng 1, vì ParagraphMarker tương ứng của nó có trường bullet được đặt thành cấp này. Do đó, lớp này kế thừa văn bản và kiểu đoạn văn bản từ lớp lồng cấp 1 trong lớp mẹ. Điều này dẫn đến kết quả hiển thị sau:

• Văn bản: "This paragraph is in a list" (Đoạn văn này nằm trong danh sách) là văn bản được hiển thị. Bản thân văn bản không bao giờ được kế thừa.
• Căn chỉnh: Văn bản được hiển thị bằng kiểu căn chỉnh "END" (KẾT THÚC), kế thừa từ ParagraphMarker thứ hai của thành phần mẹ.
• Màu nền trước: Văn bản được kết xuất bằng màu nền trước của văn bản LIGHT1, kế thừa từ TextRun thứ hai của thành phần mẹ.

Các hoạt động tương tác giữa việc cập nhật và kế thừa kiểu văn bản và đoạn văn bản

Các kiểu văn bản không được đặt trong hình dạng con sẽ kế thừa các giá trị từ hình dạng mẹ. Các kiểu văn bản được đặt trong phần tử con sẽ "ghi đè" các giá trị mẹ trong một số phạm vi cục bộ.

Bạn có thể sử dụng UpdateTextStyleRequest để huỷ đặt kiểu văn bản của hình dạng con, để hình dạng con không còn chế độ ghi đè cục bộ và do đó kế thừa kiểu từ hình dạng mẹ. Ngoài ra, việc cập nhật kiểu văn bản của thành phần con để khớp với giá trị kế thừa từ thành phần mẹ sẽ tự động huỷ đặt kiểu để sử dụng giá trị kế thừa.

Điều này không ảnh hưởng đến giao diện văn bản ngay sau khi cập nhật, nhưng có thể ảnh hưởng nếu sau này bạn cập nhật một đoạn văn bản hoặc kiểu văn bản trong phần giữ chỗ mẹ. Hành vi kế thừa này khớp với hành vi của trình chỉnh sửa Trang trình bày, vì vậy, bạn có thể thử nghiệm với kết quả của các thay đổi về kiểu trước khi làm việc với API.

Ví dụ:

Hãy xem xét các định nghĩa trong ví dụ trước cho ChildPlaceholder và ParentPlaceholder.

Bây giờ, giả sử bạn gửi UpdateTextStyleRequest này:

{ "updateTextStyle": {
    "objectId": "ChildPlaceholder",
    "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
    "textRange": { "type": "ALL" },
    "fields": "foregroundColor"
  }
}

Yêu cầu này cố gắng đặt foregroundColor DARK1 thành tất cả văn bản của ChildPlaceholder, sử dụng mặt nạ trường để chỉ định rằng chỉ màu nền trước của phần tử mới thay đổi. Yêu cầu này có các kết quả sau:

• Đoạn đầu tiên: foregroundColor mới khớp với foregroundColor kế thừa, vì vậy, kiểu này không thay đổi và vẫn kế thừa.
• Đoạn văn thứ hai: foregroundColor mới không khớp với foregroundColor kế thừa, vì vậy, màu nền trước của đoạn văn thứ hai được cập nhật thành DARK1.

Nội dung văn bản của ChildPlaceholder hiện là:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {},
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "This is my first paragraph\n",
        "style": {},
      }
      ...
    },
    { "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {},
        "bullet": {"nestingLevel": 1, "listId": "someListId", "glyph": "●" }
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "This paragraph is in a list\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
        ...
      }
    }
  ]
}

Kiểu văn bản ký tự dấu đầu dòng

Giống như văn bản thông thường, các ký tự dấu đầu dòng có kiểu văn bản kiểm soát cách hiển thị ký tự. Bạn không thể sửa đổi các kiểu văn bản này bằng cách sử dụng trực tiếp API Trang trình bày. Tuy nhiên, nếu bạn sử dụng UpdateTextStyleRequest để cập nhật một đoạn văn bản hoàn chỉnh có dấu đầu dòng, thì API Trang trình bày sẽ cập nhật kiểu văn bản của dấu đầu dòng cho phù hợp.

Kiểu văn bản ký hiệu dấu đầu dòng tuân theo hệ phân cấp kế thừa hơi khác so với các kiểu văn bản thông thường.

1. Trước tiên, dấu đầu dòng ở một cấp độ lồng ghép nhất định sẽ kế thừa từ tập hợp TextStyle trong trường NestingLevel.bullet_style bên trong đối tượng List của dấu đầu dòng.
2. Tiếp theo, phần tử này kế thừa từ NestingLevel.bullet_style tương ứng trong List của phần giữ chỗ mẹ.
3. Cuối cùng, đối tượng này sẽ tìm cách kế thừa từ các đối tượng phần giữ chỗ mẹ còn lại.