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

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

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

כשמשתמשים בשיטה ‫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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

בתשובה שלמעלה, בפסקה שכוללת את השורה 'Text following the suggestion' מוצג ההבדל בשימוש ב-SuggestionsViewMode. אם הערך מוגדר כ-SUGGESTIONS_INLINE, ההתחלה של startIndex ב-ParagraphElement היא ב-51 והסיום של endIndex הוא ב-81. ללא הצעות, הטווח של 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, שכוללת 2 חלקים:

  • הסמל 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 הן חלק מההצעה.