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

ב-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

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

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

כשצריך לשנות טקסט באמצעות 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 מגדירים את עיצוב התווים.
• התוכן של תוספי ה-placeholder של ההורה מכיל שמונה זוגות כאלה של ParagraphMarker/TextRun (כדי לתמוך בשמונה רמות של הטמעת רשימות).
• placeholder של צאצא יורש את מאפייני הטקסט שמוגדרים כברירת מחדל מרכיבי הטקסט האלה בתוכן הטקסט של ההורה.

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

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

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

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

הפסקה הבאה, שכוללת את הטקסט 'הפסקה הזו נמצאת ברשימה', נמצאת ברשימה עם תווי נקודה-פסיק ברמה 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"
  }
}

הבקשה הזו מנסה להגדיר את 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"} }, },
        ...
      }
    }
  ]
}

סגנון טקסט של תבליט

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

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

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