מבנה וסטייל של טקסט

ב-Slides API, טקסט יכול להופיע בצורות או בתאים בטבלה. כדי לשנות ולעצב טקסט, צריך להבין את המבנה שלו ואת אופן העיצוב של הטקסט.

בדף זה נתאר איך טקסט מיוצג ב-Slides API.

רצפים של רכיבי טקסט

הטקסט בצורה או בתא בטבלה מורכב מרצף של מבני TextElement. הרצף הזה מייצג את מבנה הטקסט, לפי הסדר שבו הוא מופיע מתחילתו ועד סופו.

לדוגמה, נניח שהתוכן של השקף מופיע בתיבת טקסט אחת:

בשקף שלמעלה יש תיבת טקסט אחת, שהשדה 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

כל רכיב טקסט מכיל אינדקס התחלה ואינדקס סיום המבוססים על אפסים, שמתארים את מיקום הרכיב בטקסט המלא של רכיב הדף, יחד עם אחד מהסוגים הבאים של אובייקט טקסט:

סוג הטקסט	התיאור
ParagraphMarker	רכיב הטקסט הזה מייצג את ההתחלה של פסקה חדשה. אינדקס ההתחלה והסיום של רכיב הטקסט מייצג את כל אורך הפסקה, כולל תו השורה החדשה שמסתיימת בפסקה. פסקה אף פעם לא חופפת לפיסקה אחרת. פסקאות מסתיימות תמיד בתו חדש, כך שתמיד יש שורה חדשה בסוף תוכן הטקסט של צורה או תא טבלה. פסקאות יכולות להשתייך לרשימות עם תבליטים או רשימות ממוספרות. במקרה כזה, תוכן השדה ParagraphMarker.bullet יכלול מזהה רשימה. המזהה הזה מפנה לרכיב רשימה שקיים בתוך TextContent לצד הרצף TextElement. פסקאות באותה רשימה לוגית יתייחסו לאותו מזהה רשימה.
TextRun	רכיב הטקסט הזה מייצג מחרוזת טקסט רציפה שלכלה יש אותו סגנון טקסט. הטקסט אף פעם לא חוצה גבולות של פסקאות: גם אם הטקסט שמסתיים בפסקה אחת זהה לזה של הטקסט שמתחיל בפסקה הבאה, התוכן מתפצל אחרי התו בשורה החדשה כדי ליצור רצפי טקסט נפרדים. כדי לעבד את מחרוזת הטקסט המלאה בתוך רכיב בדף, צריך לחזור על כל רכיבי הטקסט ולשרשר את המחרוזות שנמצאות בכל הפעלות הטקסט.
AutoText	טקסט אוטומטי מתייחס למקומות בטקסט שמשתנים באופן דינמי בהתאם להקשר. ב-Slides, משמש לייצוג מספר השקף הנוכחי בתוך טקסט.

בעתיד ה-API של Slides עשוי לכלול עוד סוגים של רכיבי טקסט. קוד שמעבד טקסט צריך לטפל בסוגים חדשים של רכיבי טקסט בחינניות, בדרך כלל תוך התעלמות מסוגים לא ידועים.

שינוי תוכן הטקסט

אם צריך לשנות טקסט באמצעות Slides API, אין צורך ליצור באופן מפורש את כל רכיבי הטקסט המתאימים. במקום זאת, אפשר לבצע פעולות על טקסט כמו שהייתם עושים בעורך Slides: על ידי הוספת טקסט, מחיקת טווחים ועדכון סגנונות בטווחים. הפעולות האלה יוצרות באופן לא מפורש רכיבי ParagraphMarker ו-TextRun לפי הצורך כדי לשקף את השינויים שלכם.

הוספת טקסט

תוכלו להוסיף טקסט לאינדקס באמצעות הבקשה InsertTextRequest בשיחה אל batchUpdate. השדה insertionIndex בשיטה הזו מציין איפה להוסיף את הטקסט. אפשר לחשב את האינדקס באמצעות השדות של תאריך ההתחלה והסיום שבתוך רכיבי הטקסט.

יש כמה תופעות לוואי להוספת טקסט שמשקפות את ההתנהגות של עורך Slides:

• הוספת תו של שורה חדשה יוצרת באופן לא מפורש פסקה חדשה, ויוצרת רכיב טקסט ParagraphMarker שמתחיל באינדקס של השורה החדשה ומסתיים בשורה החדשה הבאה. הסגנון של הפסקה, כולל תבליטים ופרטי רשימה, מועתק מהפסקה הנוכחית לפסקה החדשה.
• הסגנון של התווים שנוספו נקבע באופן אוטומטי, תוך שמירה על אותו סגנון טקסט שהיה קיים באינדקס ההוספה. כתוצאה מכך, בדרך כלל הטקסט מוכנס ל-TextRun הקיים באינדקס הזה. תוכלו לעדכן את הסגנון הזה מאוחר יותר באמצעות בקשת UpdateTextStyle.

מחיקת טקסט

תוכלו למחוק טווח טקסטים באמצעות ההודעה DeleteTextRequest בשיחה אל batchUpdate. מחיקת טקסט כרוכה בכמה דקויות:

• מחיקה שחוצה את הגבול של פסקה ממזגת את שתי הפסקאות, ומוחקת את רכיב הטקסט המפריד ParagraphMarker.
• הפסקה החדשה הממוזגת תשתמש בסגנון משולב של פסקה, בהתאם להתנהגות בעורך Slides.
• מחיקה שהטווח שלה כולל הרצת טקסט מסירה את כל התוכן מהרצת טקסט, וגם מוחקת את הטקסט עצמו.
• מחיקה שהטווח שלה כולל רכיב AutoText מוחקת את הרכיב AutoText.

סגנון הטקסט מתעדכן

המראה של הטקסט בשקף נקבע לפי מאפייני סגנון הטקסט:

• סגנונות של פסקאות כמו כניסות פסקה, יישור וגליפים של תבליטים מוגדרים לפי מאפיינים בסמני פסקה.
• סגנונות של תווים, כמו גופן מודגש, נטוי וקו תחתון, מוגדרים באמצעות מאפיינים בכל הרצות טקסט.

מתבצע עדכון של סגנון התווים

תוכלו לעדכן את סגנונות התווים באמצעות ההודעה UpdateTextStyleRequest בשיחה לביצוע batchUpdate.

בדומה לפעולות טקסט אחרות, סגנון התווים מוחל על טווח טקסטים ויוצר באופן לא מפורש אובייקטי TextRun חדשים לפי הצורך.

הגדרה של סגנונות תווים מסוימים מעדכנת באופן לא מפורש סגנונות קשורים אחרים כך שיתאימו להתנהגות בעורך Slides. לדוגמה, הוספת קישור משנה באופן אוטומטי את הצבע החזית של הטקסט ואת המאפיינים של הקו התחתון. לפרטים נוספים, עיינו במסמכי התיעוד בנושא TextStyle.

מתבצע עדכון של סגנון הפסקה

תוכלו לעדכן סגנונות של פסקאות באמצעות ההודעה UpdateParagraphStyleRequest בשיחה אל batchUpdate.

Slides API תומך ב-CreateParagraphBulletsRequest, המשקף את הפונקציונליות של ההגדרות הקבועות מראש של תבליטים בעורך Slides, לצורך יצירה של רשימות עם תבליטים ורשימות ממוספרות. באופן דומה, DeleteParagraphBulletsRequest מסיר את כל התבליטים הקיימים בפסקאות.

סגנונות שעברו בירושה

צורות מסוימות, שנקראות placeholders, יכולות לרשת סגנונות טקסט מצורות הורה אחרות: קראו את המאמר placeholders כדי לקבל מידע נוסף על ירושה של צורות באופן כללי.

הקטע הזה מתמקד באופן שבו פועלת ירושה של סגנונות כדי ליצור את סגנונות הטקסט הסופיים המעובדים שמוצגים בשקף.

ייצוג סגנון ב-placeholders

בקטע placeholders מוסבר איך פועלת הורשה בין צורות הורה וצורות צאצא. הירושה של סגנונות טקסט מטופלת על ידי תכונות נוספות בתוך מודל הירושה:

• המאפיינים של רכיבי הטקסט ParagraphMaker מגדירים את העיצוב של פסקאות.
• המאפיינים של רכיבי הטקסט TextRun מגדירים את עיצוב התווים.
• התוכן של ה-placeholders שמוגדרים כהורה מכיל שמונה צמדים כאלה של ParagraphMarker/TextRun (לצורך תמיכה בשמונה רמות של קינון רשימות).
• placeholder מסוג צאצא יורש את מאפייני הטקסט שמוגדרים כברירת מחדל מרכיבי הטקסט האלה בתוכן הטקסט של ההורה.

התרשים הבא מראה דרך אחת להצגה חזותית של הקשרים האלה:

העיצוב הראשון של ParagraphMarker/TextRun בצורת ההורה קובע את רוב סגנון הטקסט שעובר בירושה. הסגנון בשבעת הזוגות הנותרים משפיע רק על פסקאות ברמות תבליטים שמוצבות באופן מעמיק יותר ויותר:

זוג של רכיבי טקסט ברמת ההורה	עיצוב הצאצא שנקבע
פרק הזמן ParagraphMarker הראשונה TextRun	סגנון טקסט ברמה 0 (החיצונית ביותר) ברשימה של פסקאות וכל הפסקאות שאינן רשימה.
השנייה ParagraphMarker השנייה TextRun	סגנון הטקסט של שאר רמות הרשימה (מוטמעות) ברשימה 1-7
TextRun ParagraphMarker השלישי
הרביעי ParagraphMarker הרביעי TextRun
סיבוב חמישי ParagraphMarker החמישי TextRun
שישי ParagraphMarker שישי TextRun
שביעי ParagraphMarker שביעי TextRun
שמינית ParagraphMarker שמינית TextRun

כדי לגשת לצמדים האלה של רכיבי טקסט, צריך להשתמש באינדקס המפורש שלהם בתוך השדה 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", היא פסקה פשוטה (לא ברשימה). אף רכיב בתוכן הטקסט לא מציין מאפייני סגנון כלשהם, ולכן הוא יורש את כל סגנונות התווים והפסקאות שלו מהורה. פעולה זו גורמת לעיבוד הבא:

• טקסט: "זו הפסקה הראשונה שלי" הוא הטקסט שעבר עיבוד. הטקסט עצמו אף פעם לא עובר בירושה.
• יישור: הטקסט מעובד ביישור START, שעובר בירושה מה-ParagraphMarker הראשון של ההורה.
• צבע חזית: הטקסט מעובד עם צבע החזית של DARK1, שעובר בירושה מה-TextRun הראשון של ההורה.

ירושה של סגנון לפסקה ברשימה

הפסקה הבאה, שכוללת את הטקסט "This paragraph is in a list", מופיעה ברשימת תבליטים ברמה 1, מאחר שהשדה bullet התואם לה מוגדר ברמה הזו ב-ParagraphMarker. כתוצאה מכך, סגנון הטקסט והפסקה יורש את הסגנון של טקסט ופסקה מהקינון ברמה 1 ברמה העליונה. כתוצאה מכך מתקבל הרינדור הבא:

• טקסט: "הפסקה הזו נמצאת ברשימה" הוא הטקסט שעבר עיבוד. הטקסט עצמו אף פעם לא עובר בירושה.
• יישור: הטקסט מוצג עם יישור של 'END', שעובר בירושה מה-ParagraphMarker השני של ההורה.
• צבע חזית: הטקסט מעובד עם צבע החזית של הטקסט LIGHT1, שעובר בירושה מה-TextRun השני של ההורה.

אינטראקציות בין עדכון של סגנונות של טקסט ופסקאות לבין קבלת בירושה

סגנונות טקסט שלא מוגדרים בצורת צאצא יירשו את הערכים שלהם מתבניות ההורה. סגנונות טקסט שמוגדרים ברמת הצאצא 'יחליפו' את ערכי ההורה בהיקף מקומי מסוים.

אפשר להשתמש ב-UpdateTextStyleRequest כדי לבטל את ההגדרה של סגנון טקסט בצורה של צאצא, כך שכבר לא יהיה שינוי מברירת המחדל המקומי וכך הוא יירש את המאפיינים שלו מצורת ההורה. בנוסף, אם מעדכנים את סגנון הטקסט של הצאצא כך שיתאים לערך שעובר בירושה מתבנית ההורה, הסגנון לא מוגדר באופן מפורש כך שהוא ישתמש בערך שעבר בירושה.

הגדרת סגנון של צורה צאצא כך שיתאים בדיוק לסגנון של תבנית ההורה (ובכך שהיא תקבל בירושה את הסגנון) התוצאה זהה לביטול הגדרת הסגנון של צורת הצאצא.

הדבר לא משפיע על המראה החזותי של הטקסט מיד לאחר עדכון, אך ייתכן שחשוב לעדכן מאוחר יותר את הסגנון של פסקה או את הסגנון ב-placeholder של תבנית ההורה. התנהגות הירושה הזו תואמת להתנהגות של עורך Slides, כך שתוכלו להתנסות בתוצאות של שינויי סגנון לפני שתתחילו לעבוד מול ה-API.

דוגמה

כדאי לשקול את ההגדרות בדוגמה הקודמת של ChildPlaceholder ו-ParentPlaceholder.

עכשיו נניח ששולחים את הפקודה UpdateTextStyleRequest:

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

בבקשה הזו נעשה ניסיון להגדיר DARK1 חזית צבע לכל הטקסט של ChildPlaceholder, באמצעות מסכת שדות כדי לציין שרק צבע החזית של הרכיב צריך להשתנות. אלה התוצאות האפשריות של הבקשה:

• פסקה ראשונה: העיצוב החדש של foregroundColor תואם לforegroundColor שעברה בירושה, כך שהסגנון לא ישתנה ועדיין יועבר בירושה.
• פסקה שנייה: השדה foregroundColor החדש לא תואם לצבע foregroundColor שעבר בירושה, ולכן הצבע החזית של הפסקה השנייה מתעדכן ל-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"} }, },
        ...
      }
    }
  ]
}

סגנון טקסט עם תבליט

בדומה לטקסט רגיל, הגליפים של תבליטים כוללים סגנון טקסט שקובע את אופן העיבוד של הגליף. לא ניתן לשנות את סגנונות הטקסט האלה ישירות באמצעות ה-API של Slides. עם זאת, אם משתמשים ב-UpdateTextStyleRequest כדי לעדכן פסקה שלמה שכוללת תבליט, ממשק ה-API של Slides יעדכן בהתאם את סגנון הטקסט של גליף התבליט.

סגנונות הטקסט של התבליטים עם התבליטים משתנים בהתאם להיררכיית הירושה בהשוואה לסגנונות הטקסט הרגילים.

1. תבליט ברמת דירוג מסוימת יורש תחילה את ההגדרה TextStyle מהשדה NestingLevel.bullet_style, שבתוך אובייקט List של התבליט.
2. לאחר מכן, היא יורשת מה-NestingLevel.bullet_style התואם ב-List של ה-placeholder ההורה.
3. לבסוף, הפונקציה מנסה לרשת את אובייקטי ה-placeholder שנותרו ברמת ההורה.

בתבליטים ב-placeholders ב-Layouts ובמאסטרים יש 'TextStyle' ריק בשדה 'ParagraphMarker.bullet', וכל עדכון של סגנון הטקסט בפסקאות האלה ישתקף רק בהודעות List.