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

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 ו-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 נכללות של ההצעה.