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

בעזרת Google Docs, שותפי העריכה יכולים להציע הצעות שהן עריכות שנדחו בפועל וממתינות לאישור.

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

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

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

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

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

תוכן עם הצעות תוכן ללא הצעות 
{
 "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"
  }
 }
},


{
 "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 after thesuggest' (טקסט לאחר ההצעה) מציגה את ההבדל בשימוש ב-SuggestionsViewMode. כאשר הערך מוגדר כ-SUGGESTIONS_INLINE, startIndex של ParagraphElement מתחיל ב-51 ו-endIndex מפסיקה ב-81. אם אין הצעות, הערכים startIndex ו-endIndex נעים בין 32 ל-62.

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

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

Java

המחרוזת הסופית SUGGEST_Mode = "PREVIEW_WITHOUT_SUGGESTIONS"; מסמך doc = service.documents().get(DOCUMENT_ID).setSuggestionsViewMode(SUGGEST_mode).execute();

Python

SUGGEST_mode="PREVIEW_WITHOUT_SUGGESTIONS" result = service.documents().get(documentId=DOCUMENT_ID, 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 הן חלק מההצעה.