โครงสร้างและการจัดรูปแบบข้อความ

จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

ใน Slides API ข้อความอาจอยู่ในรูปร่างหรือในเซลล์ตาราง คุณต้องเข้าใจโครงสร้างและวิธีการทํางานของข้อความก่อนจึงจะจัดการและจัดรูปแบบข้อความได้

หน้านี้อธิบายวิธีแสดงข้อความใน Slides API

ลำดับองค์ประกอบข้อความ

ข้อความที่อยู่ในรูปร่างหรือเซลล์ตารางประกอบด้วยลำดับโครงสร้าง TextElement ลำดับนี้แสดงโครงสร้างของข้อความตามลำดับที่ปรากฏตั้งแต่ต้นจนจบ

ตัวอย่างเช่น ลองดูเนื้อหาของสไลด์นี้ ซึ่งมีทั้งหมดอยู่ในกล่องข้อความเดียว

สไลด์ด้านบนมีกล่องข้อความ 1 กล่อง ซึ่งช่อง text มีลําดับองค์ประกอบข้อความดังที่แสดงในแผนภาพต่อไปนี้

กล่าวอย่างเป็นรูปธรรมคือ ลำดับข้อความนี้จะแสดงใน Slides API ดังนี้

"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": {} }
}]

เนื้อหา TextElement

องค์ประกอบข้อความแต่ละรายการมีดัชนีเริ่มต้นและดัชนีสิ้นสุดซึ่งนับจาก 0 ขึ้นไป ซึ่งอธิบายตําแหน่งขององค์ประกอบภายในข้อความแบบเต็มขององค์ประกอบหน้าเว็บ พร้อมกับออบเจ็กต์ข้อความประเภทใดประเภทหนึ่งต่อไปนี้

การแก้ไขเนื้อหาข้อความ

เมื่อต้องแก้ไขข้อความโดยใช้ Slides API คุณไม่จำเป็นต้องสร้างองค์ประกอบข้อความที่เหมาะสมทั้งหมดอย่างชัดเจน แต่คุณจะดำเนินการกับข้อความได้เช่นเดียวกับในเครื่องมือแก้ไขสไลด์ เช่น แทรกข้อความ ลบช่วง และอัปเดตสไตล์ในแถว การดำเนินการเหล่านี้จะสร้างองค์ประกอบ ParagraphMarker และ TextRun โดยปริยายตามที่จำเป็นเพื่อแสดงการเปลี่ยนแปลงของคุณ

การแทรกข้อความ

คุณสามารถแทรกข้อความที่ดัชนีได้โดยใช้คำขอ InsertTextRequest ในคําเรียก batchUpdate ฟิลด์ insertionIndex ของเมธอดนี้จะระบุตำแหน่งที่จะแทรกข้อความ คุณสามารถคํานวณดัชนีนี้โดยใช้ฟิลด์ดัชนีเริ่มต้นและสิ้นสุดภายในองค์ประกอบข้อความ

การแทรกข้อความมีผลข้างเคียงบางอย่างที่สอดคล้องกับลักษณะการทำงานของเครื่องมือแก้ไขสไลด์

• การป้อนอักขระขึ้นบรรทัดใหม่จะสร้างย่อหน้าใหม่โดยปริยาย ซึ่งจะสร้างParagraphMarkerองค์ประกอบข้อความที่เริ่มต้นที่ดัชนีขึ้นบรรทัดใหม่และสิ้นสุดที่ขึ้นบรรทัดใหม่ถัดไป ระบบจะคัดลอกรูปแบบย่อหน้า ซึ่งรวมถึงรายละเอียดหัวข้อย่อยและรายการ จากย่อหน้าปัจจุบันไปยังย่อหน้าใหม่
• ระบบจะกำหนดสไตล์ของอักขระที่แทรกโดยอัตโนมัติ โดยปกติแล้วจะใช้สไตล์ข้อความเดียวกับที่มีอยู่ในดัชนีการแทรก ด้วยเหตุนี้ โดยทั่วไประบบจะแทรกข้อความลงใน TextRun ที่มีอยู่ ณ ดัชนีนั้น คุณจะอัปเดตสไตล์นี้ในภายหลังได้โดยใช้คำขอ UpdateTextStyle

การลบข้อความ

คุณลบช่วงข้อความได้โดยใช้ข้อความ DeleteTextRequest ในคําเรียกbatchUpdate การลบข้อความมีความซับซ้อนอยู่บ้าง ดังนี้

• การลบที่ข้ามขอบเขตย่อหน้าจะผสานย่อหน้า 2 ย่อหน้าเข้าด้วยกัน โดยลบองค์ประกอบข้อความ ParagraphMarker ที่แยกกัน
• ย่อหน้าใหม่ที่ผสานจะใช้รูปแบบย่อหน้าแบบรวม ซึ่งจะทํางานในลักษณะเดียวกับในเครื่องมือแก้ไขสไลด์
• การลบที่มีช่วงครอบคลุมการเรียกใช้ข้อความจะนำเนื้อหาทั้งหมดออกจากการเรียกใช้ข้อความ และลบการเรียกใช้ข้อความนั้นด้วย
• การลบที่มีช่วงครอบคลุมองค์ประกอบ AutoText จะลบองค์ประกอบ AutoText

การอัปเดตรูปแบบข้อความ

ลักษณะที่แสดงผลของข้อความในสไลด์จะกำหนดโดยพร็อพเพอร์ตี้รูปแบบข้อความ ดังนี้

• สไตล์ย่อหน้า เช่น การเยื้อง การกึ่งกลาง และสัญลักษณ์หัวข้อ กำหนดโดยพร็อพเพอร์ตี้ในเครื่องหมายย่อหน้า
• รูปแบบอักขระ เช่น ตัวหนา ตัวเอียง และขีดเส้นใต้ จะกำหนดโดยพร็อพเพอร์ตี้ในข้อความแต่ละชุด

อัปเดตสไตล์ตัวละคร

คุณสามารถอัปเดตรูปแบบอักขระได้โดยใช้ข้อความ UpdateTextStyleRequest ในคําเรียกbatchUpdate

เช่นเดียวกับการดำเนินการกับข้อความอื่นๆ รูปแบบอักขระจะมีผลกับช่วงข้อความและสร้างออบเจ็กต์ TextRun ใหม่โดยปริยายตามความจำเป็น

การตั้งค่ารูปแบบอักขระบางอย่างจะอัปเดตสไตล์อื่นๆ ที่เกี่ยวข้องโดยปริยายให้ตรงกับลักษณะการทำงานในตัวแก้ไขสไลด์ เช่น การเพิ่มลิงก์จะเปลี่ยนสีพื้นหน้าของข้อความและพร็อพเพอร์ตี้ขีดเส้นใต้โดยอัตโนมัติ ดูรายละเอียดเพิ่มเติมในเอกสารอ้างอิงTextStyle

การอัปเดตรูปแบบย่อหน้า

คุณสามารถอัปเดตรูปแบบย่อหน้าได้โดยใช้ข้อความ UpdateParagraphStyleRequest ในคําเรียกbatchUpdate

Slides API รองรับ CreateParagraphBulletsRequest ที่แสดงฟังก์ชันการทำงานของหัวข้อย่อยที่กำหนดล่วงหน้าในเครื่องมือแก้ไขสไลด์สำหรับการสร้างรายการหัวข้อย่อยและรายการตัวเลข ในทํานองเดียวกัน DeleteParagraphBulletsRequest จะนําหัวข้อย่อยที่มีอยู่ในย่อหน้าออก

รูปแบบที่รับมา

รูปร่างบางรูปที่เรียกว่าตัวยึดตำแหน่งสามารถรับค่ารูปแบบข้อความจากรูปร่างหลักอื่นๆ ได้โดยดูข้อมูลเพิ่มเติมเกี่ยวกับการรับค่ารูปร่างโดยทั่วไปได้ที่ตัวยึดตำแหน่ง

ส่วนนี้จะเน้นที่วิธีการรับค่ารูปแบบเพื่อสร้างรูปแบบข้อความที่แสดงผลขั้นสุดท้ายซึ่งแสดงในสไลด์

การแสดงสไตล์ในตัวยึดตําแหน่ง

ส่วนตัวยึดตําแหน่งอธิบายวิธีการทำงานของการสืบทอดระหว่างรูปร่างหลักและรูปร่างย่อย ฟีเจอร์เพิ่มเติมภายในรูปแบบการสืบทอดจะจัดการการสืบทอดรูปแบบข้อความ ดังนี้

• พร็อพเพอร์ตี้ของ ParagraphMaker องค์ประกอบข้อความจะกำหนดการจัดรูปแบบย่อหน้า
• คุณสมบัติของ TextRun องค์ประกอบข้อความจะกำหนดการจัดรูปแบบอักขระ
• เนื้อหาของตัวยึดตําแหน่งหลักมีคู่ ParagraphMarker/TextRun 8 คู่ (เพื่อรองรับการฝังรายการ 8 ระดับ)
• ตัวยึดตําแหน่งย่อยจะรับค่าพร็อพเพอร์ตี้ข้อความเริ่มต้นจากองค์ประกอบข้อความเหล่านี้ในเนื้อหาข้อความของรายการหลัก

แผนภาพต่อไปนี้แสดงวิธีหนึ่งในการแสดงให้เห็นความสัมพันธ์เหล่านี้

ParagraphMarker/TextRun แรกในรูปร่างหลักจะเป็นตัวกำหนดการจัดรูปแบบข้อความส่วนใหญ่ที่รับค่ามา การจัดรูปแบบในคู่ที่เหลืออีก 7 คู่จะส่งผลต่อย่อหน้าในระดับหัวข้อที่ฝังอยู่ลึกมากขึ้นเท่านั้น

หากต้องการเข้าถึงองค์ประกอบข้อความคู่เหล่านี้ ให้ใช้ดัชนีที่ชัดเจนภายในช่อง textElements ดังที่แสดงในข้อมูลโค้ดด้านล่าง ซึ่งแสดงการตั้งค่าการจัดรูปแบบเริ่มต้น (ที่รับค่ามา) สำหรับย่อหน้าระดับ 0 และย่อหน้าแบบไม่จัดรายการ

"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"  }  },  }
     }
   },{
     ...
   } ]
 }

โปรดทราบว่าช่อง content ของ TextRun ของรูปร่างหลักจะมีอักขระขึ้นบรรทัดใหม่เพียงตัวเดียวเสมอ

รูปแบบที่รับค่ามาสามารถลบล้างได้

รูปร่างย่อยสามารถระบุพร็อพเพอร์ตี้การจัดสไตล์ในองค์ประกอบ ParagraphMarker และ TextRun ในเนื้อหา พร็อพเพอร์ตี้ที่ระบุในเครื่องเหล่านี้จะลบล้างพร็อพเพอร์ตี้ที่รับค่ามาภายในขอบเขตในเครื่อง องค์ประกอบที่ไม่ได้ระบุรูปแบบใดๆ จะใช้รูปแบบที่เกี่ยวข้องซึ่งรับช่วงมาจากองค์ประกอบหลัก

การนำพร็อพเพอร์ตี้สไตล์ที่ชัดเจนออกจากรูปร่างย่อยเพื่อไม่ให้มีการตั้งค่าอีกต่อไปจะทำให้รูปร่างนั้นรับค่าจากรูปร่างหลัก

ตัวอย่าง

เมื่อพิจารณาการสืบทอดที่แสดงในแผนภาพด้านบน สมมติว่ารูปร่าง ParentPlaceholderมีเนื้อหาข้อความดังต่อไปนี้

"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"} }, ...}
      }
    },
   ...
  ]
}

และสมมติว่ารูปร่าง ChildPlaceholder มีเนื้อหาข้อความดังต่อไปนี้

"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": {},
        ...
      }
    }
  ]
}

ซึ่งส่งผลให้เกิดผลลัพธ์ตามที่อธิบายไว้ในย่อหน้าต่อไปนี้

การสืบทอดสไตล์สำหรับย่อหน้าธรรมดา

ย่อหน้าแรกของรูปร่างย่อยซึ่งมีข้อความ "This is my first paragraph" เป็นย่อหน้าธรรมดา (ไม่ได้อยู่ในรายการ) ไม่มีองค์ประกอบใดในเนื้อหาข้อความที่ระบุพร็อพเพอร์ตี้สไตล์ ดังนั้นจึงรับค่ารูปแบบอักขระและรูปแบบย่อหน้าทั้งหมดมาจากองค์ประกอบหลัก ซึ่งจะทำให้เกิดการแสดงผลต่อไปนี้

• ข้อความ: "This is my first paragraph" คือข้อความที่แสดงผล ระบบจะไม่รับค่าข้อความ
• การจัดแนว: ข้อความจะแสดงผลโดยจัดแนว START ซึ่งรับค่ามาจาก ParagraphMarker แรกขององค์ประกอบหลัก
• สีพื้นหน้า: ระบบจะแสดงผลข้อความด้วยสีพื้นหน้า DARK1 ซึ่งรับค่ามาจาก TextRun แรกในองค์ประกอบหลัก

การรับค่ารูปแบบสำหรับย่อหน้ารายการ

ย่อหน้าถัดไปซึ่งมีข้อความ "ย่อหน้านี้อยู่ในรายการ" อยู่ในรายการหัวข้อย่อยที่ฝังในระดับ 1 เนื่องจาก ParagraphMarker ที่เกี่ยวข้องมีการตั้งค่าช่อง bullet เป็นระดับนี้ ด้วยเหตุนี้ องค์ประกอบจึงรับค่าข้อความและรูปแบบย่อหน้ามาจากระดับการฝัง 1 ในองค์ประกอบหลัก ซึ่งจะแสดงผลเป็นดังนี้

• ข้อความ: "ย่อหน้านี้อยู่ในรายการ" คือข้อความที่แสดงผล ระบบจะไม่รับค่าข้อความ
• การจัดแนว: ข้อความแสดงผลโดยจัดแนว "END" ซึ่งรับค่ามาจาก ParagraphMarker ตัวที่ 2 ขององค์ประกอบหลัก
• สีพื้นหน้า: ระบบจะแสดงผลข้อความด้วยLIGHT1สีพื้นหน้าของข้อความ ซึ่งรับค่ามาจาก TextRun ลำดับที่ 2 ของรายการหลัก

การโต้ตอบระหว่างการอัปเดตและการรับค่ารูปแบบข้อความและย่อหน้า

รูปแบบข้อความที่ไม่ได้ตั้งค่าไว้ในรูปร่างย่อยจะรับค่ามาจากรูปร่างหลัก รูปแบบข้อความที่ตั้งค่าไว้ในรายการย่อยจะ "ลบล้าง" ค่าของรายการหลักในขอบเขตที่เฉพาะเจาะจงบางอย่าง

คุณสามารถใช้ UpdateTextStyleRequest เพื่อยกเลิกการตั้งค่ารูปแบบข้อความของรูปร่างย่อย เพื่อไม่ให้มีการลบล้างในเครื่องอีกต่อไป และรับรูปแบบจากรูปร่างหลัก นอกจากนี้ การอัปเดตสไตล์ข้อความของรายการย่อยให้ตรงกับค่าที่รับค่ามาจากรายการหลักจะตั้งค่าสไตล์โดยนัยเพื่อให้ใช้ค่าที่รับค่ามา

ซึ่งจะไม่ส่งผลต่อลักษณะที่ปรากฏของข้อความทันทีหลังจากการอัปเดต แต่อาจส่งผลหากคุณอัปเดตย่อหน้าหรือสไตล์ข้อความในตัวยึดตำแหน่งหลักในภายหลัง ลักษณะการสืบทอดนี้ตรงกับลักษณะการทำงานของเครื่องมือแก้ไขสไลด์ คุณจึงทดสอบผลลัพธ์ของการเปลี่ยนแปลงสไตล์ก่อนใช้งาน API ได้

ตัวอย่าง

ลองดูคําจํากัดความในตัวอย่างก่อนหน้าสําหรับ ChildPlaceholder และ ParentPlaceholder

สมมติว่าคุณส่ง UpdateTextStyleRequest นี้

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

คําขอนี้พยายามตั้งค่า DARK1 foregroundColor เป็นข้อความทั้งหมดของ Text โดยใช้ field mask เพื่อระบุว่าควรเปลี่ยนเฉพาะสีพื้นหน้าขององค์ประกอบ คำขอนี้มีผลลัพธ์ดังต่อไปนี้

• ย่อหน้าแรก: foregroundColor ใหม่ตรงกับ foregroundColor ที่รับค่ามา ดังนั้นรูปแบบนี้จึงไม่มีการเปลี่ยนแปลงและยังคงรับค่ามา
• ย่อหน้า 2: foregroundColor ใหม่ไม่ตรงกับ foregroundColor ที่รับค่ามา ระบบจึงอัปเดตสีพื้นหน้าของย่อหน้า 2 เป็น DARK1

เนื้อหาข้อความของ ChildPlaceholder ตอนนี้คือ

"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"} }, },
        ...
      }
    }
  ]
}

รูปแบบข้อความสัญลักษณ์หัวข้อย่อย

เช่นเดียวกับข้อความปกติ สัญลักษณ์หัวข้อจะมีรูปแบบข้อความที่ควบคุมวิธีแสดงผลสัญลักษณ์ รูปแบบข้อความเหล่านี้ไม่สามารถแก้ไขโดยใช้ Slides API ได้โดยตรง อย่างไรก็ตาม หากคุณใช้ UpdateTextStyleRequest เพื่ออัปเดตย่อหน้าที่มีหัวข้อย่อย Slides API จะอัปเดตรูปแบบข้อความของสัญลักษณ์หัวข้อย่อยให้ตรงกัน

สไตล์ข้อความแบบสัญลักษณ์หัวข้อจะเป็นไปตามลําดับชั้นการสืบทอดที่แตกต่างจากสไตล์ข้อความปกติเล็กน้อย

1. หัวข้อในระดับการฝังหนึ่งๆ จะรับค่าจากชุด TextStyle ในช่อง NestingLevel.bullet_style ภายในออบเจ็กต์ List ของหัวข้อก่อน
2. จากนั้นจะรับค่าจาก NestingLevel.bullet_style ที่เกี่ยวข้องใน List ของตัวยึดตําแหน่งหลัก
3. สุดท้าย ระบบจะพยายามรับค่าจากออบเจ็กต์ตัวยึดตำแหน่งหลักที่เหลืออยู่