לעבוד עם הצעות

ב-Google Docs, שותפי עריכה יכולים להוסיף הצעות שהן למעשה עריכות שמושהות וממתינות לאישור.

כשמשתמשים בשיטה documents.get כדי לאחזר תוכן של מסמך, יכול להיות שהתוכן יכלול הצעות שלא נפתרו. כדי לשלוט באופן שבו documents.get מייצג הצעות, משתמשים בפרמטר האופציונלי SuggestionsViewMode. אלה תנאי הסינון שזמינים עם הפרמטר הזה:

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

אם לא תספקו את SuggestionsViewMode, Google Docs API ישתמש בהגדרת ברירת מחדל שמתאימה להרשאות של המשתמש הנוכחי.

הצעות ואינדקסים

אחת הסיבות לכך שSuggestionsViewMode חשוב היא שהאינדקסים בתגובה עשויים להשתנות בהתאם לשאלה אם יש הצעות, כפי שמוצג בהמשך.

תוכן עם הצעות תוכן ללא הצעות 
{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 51,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 50,
          "textRun": {
           "content": "Suggested insertion",
           "suggestedInsertionIds": [
            "suggest.vcti8ewm4mww"
           ],
           "textStyle": {}
          }
         },
         {
          "startIndex": 50,
          "endIndex": 51,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 51,
       "endIndex": 81,
       "paragraph": {
        "elements": [
         {
          "startIndex": 51,
          "endIndex": 81,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},


{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 32,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 32,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 32,
       "endIndex": 62,
       "paragraph": {
        "elements": [
         {
          "startIndex": 32,
          "endIndex": 62,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

בתשובה שלמעלה, הפסקה שמכילה את השורה 'טקסט אחרי ההצעה' מראה את ההבדל כשמשתמשים ב-SuggestionsViewMode. אם הערך מוגדר כ-SUGGESTIONS_INLINE, ה-startIndex של ParagraphElement מתחיל ב-51 ומסתיים ב-81.endIndex ללא הצעות, הטווח של startIndex ושל endIndex הוא 32-62.

קבלת תוכן בלי הצעות

בדוגמה הבאה של קטע קוד אפשר לראות איך מקבלים מסמך כתצוגה מקדימה עם כל ההצעות שנדחו (אם יש כאלה) על ידי הגדרת הפרמטר SuggestionsViewMode לערך PREVIEW_WITHOUT_SUGGESTIONS.

Java

final string SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS";
Document doc =
    service
        .documents()
        .get(DOCUMENT_ID)
        .setIncludeTabsContent(true)
        .setSuggestionsViewMode(SUGGEST_MODE)
        .execute();

Python

SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS"
result = (
  service.documents()
  .get(
      documentId=DOCUMENT_ID,
      includeTabsContent=True,
      suggestionsViewMode=SUGGEST_MODE,
  )
  .execute()
)

השמטה של הפרמטר SuggestionsViewMode שקולה להזנת הערך DEFAULT_FOR_CURRENT_ACCESS כערך הפרמטר.

הצעות לסגנון

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

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

אחת מההערות האלה היא SuggestedTextStyle, שמורכבת משני חלקים:

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

  • הפרמטר textStyleSuggestionState מציין איך ההצעה משנה את השדות של textStyle.

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

[01] "paragraph": {
[02]    "elements": [
[03]        {
[04]            "endIndex": 106,
[05]            "startIndex": 82,
[06]            "textRun": {
[07]                "content": "Some text that does not ",
[08]                "textStyle": {}
[09]            }
[10]        },
[11]        {
[12]            "endIndex": 115,
[13]            "startIndex": 106,
[14]            "textRun": {
[15]                "content": "initially",
[16]                "suggestedTextStyleChanges": {
[17]                    "suggest.xymysbs9zldp": {
[18]                        "textStyle": {
[19]                            "backgroundColor": {},
[20]                            "baselineOffset": "NONE",
[21]                            "bold": true,
[22]                            "fontSize": {
[23]                                "magnitude": 11,
[24]                                "unit": "PT"
[25]                            },
[26]                            "foregroundColor": {
[27]                                "color": {
[28]                                    "rgbColor": {}
[29]                                }
[30]                            },
[31]                            "italic": false,
[32]                            "smallCaps": false,
[33]                            "strikethrough": false,
[34]                            "underline": false
[35]                        },
[36]                        "textStyleSuggestionState": {
[37]                            "boldSuggested": true,
[38]                            "weightedFontFamilySuggested": true
[39]                        }
[40]                    }
[41]                },
[42]                "textStyle": {
[43]                    "italic": true
[44]                }
[45]            }
[46]        },
[47]        {
[48]            "endIndex": 143,
[49]            "startIndex": 115,
[50]            "textRun": {
[51]                "content": " contain any boldface text.\n",
[52]                "textStyle": {}
[53]            }
[54]        }
[55]    ],
[56]    "paragraphStyle": {
[57]        "direction": "LEFT_TO_RIGHT",
[58]        "namedStyleType": "NORMAL_TEXT"
[59]    }
[60] }

בדוגמה שלמעלה, הפסקה מורכבת מ-3 רצפים של טקסט, שמתחילים בשורות 6, 14 ו-50. בודקים את רצף הטקסט האמצעי:

  • שורה 16: יש אובייקט suggestedTextStyleChanges.
  • שורה 18: התג textStyle מציין עיצובים שונים.
  • שורה 36: התו textStyleSuggestionState מציין שרק החלק המודגש של המפרט הזה היה ההצעה.
  • שורה 42: העיצוב באותיות מוטות של רצף הטקסט הזה הוא חלק מהמסמך הנוכחי (ולא מושפע מההצעה).

רק תכונות הסגנון שהוגדרו לtrue בtextStyleSuggestionState הן חלק מההצעה.