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

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

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

כשמשתמשים בשיטה 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 הן חלק מההצעה.

יצירה וניהול של תגובות

אפשר להוסיף תגובות ותשובות, לערוך תגובות ולמחוק תגובות או תשובות באופן פרוגרמטי באמצעות השיטה documents.batchUpdate.

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

הוספת תגובה

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

בדוגמה הבאה של JSON מוסיפים לטווח שצוין שרשור תגובות שלא הוקצה לאף אחד:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added via the API.",
        "range": {
          "startIndex": 10,
          "endIndex": 25
        }
      }
    }
  ]
}

אפשר להקצות תגובה למשתמש ספציפי על ידי הזנת כתובת האימייל שלו בשדה assigneeEmailAddress:

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review this paragraph.",
        "assigneeEmailAddress": "user@example.com",
        "range": {
          "startIndex": 10,
          "endIndex": 25
        }
      }
    }
  ]
}

הוספת תשובה או ביצוע פעולה

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

תשובה מיוצגת על ידי אובייקט Post. אובייקט Post מכיל את התשובה content ויכול לציין באופן אופציונלי commentAction (לRESOLVE או REOPEN השרשור).

הדוגמה הבאה מציגה תשובה לשרשור תגובות קיים:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

בדוגמה הבאה מסומן ששרשור התגובות הסתיים, ולא נדרש תוכן:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "commentAction": "RESOLVE"
        }
      }
    }
  ]
}

עריכת פוסט

כדי לערוך את תוכן הטקסט של פוסט שכתבתם, משתמשים בUpdateCommentPostRequest. צריך לציין את מזהה השרשור (commentId או suggestionId), את postId הפוסט שרוצים לערוך ואת content הטקסט הפשוט החדש.

שימו לב שאי אפשר לערוך את הפוסט הראשי בשרשור של הצעה (כי הוא נוצר על ידי עריכות במצב הצעה).

{
  "requests": [
    {
      "updateCommentPost": {
        "commentId": "comment_thread_id",
        "postId": "post_id",
        "content": "This is the updated comment text."
      }
    }
  ]
}

מחיקת תגובות ותשובות

  • מחיקת שרשור תגובות: כדי להסיר שרשור תגובות שלם, משתמשים בסמל DeleteCommentRequest. רק מי שכתב את הפוסט הראשי בשרשור התגובות יכול למחוק את השרשור.
  • מחיקת תשובה: כדי למחוק תשובה ספציפית, משתמשים בסמל DeleteCommentReplyRequest. אתם יכולים למחוק רק תשובות שכתבתם. אי אפשר למחוק פוסטים של תשובות שמכילים פעולות או מקבלי משימות.

הדוגמה הבאה מוחקת שרשור תגובות:

{
  "requests": [
    {
      "deleteComment": {
        "commentId": "comment_thread_id"
      }
    }
  ]
}

כתיבת הצעות וניהול שרשורי הצעות

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

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

יצירת הצעות באמצעות מצב ההצעה

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

{
  "requests": [
    {
      "insertText": {
        "text": "suggested insertion text",
        "location": {
          "index": 1
        }
      }
    }
  ],
  "writeControl": {
    "writeMode": "SUGGEST"
  }
}

בקשות לא נתמכות במצב הצעות

כשמשתמשים ב-WriteMode.SUGGEST, אי אפשר להשתמש בסוגי הבקשות הבאים, ואם תנסו לעשות זאת תקבלו שגיאה:

  • AddDocumentTab
  • CreateNamedRange
  • DeleteFooter
  • DeleteHeader
  • DeleteNamedRange
  • DeleteTab
  • UpdateDocumentTabProperties
  • UpdateTableColumnProperties

בנוסף, אי אפשר להציע שינויים בפורמט המסמך או בהגדרות של הכותרות העליונות והתחתונות. ב-UpdateDocumentStyle, אין תמיכה בהצעות לסוגי הסגנונות הבאים:

  • documentFormat
  • useEvenPageHeaderFooter
  • useFirstPageHeaderFooter

אישור, דחייה או מחיקה של שרשורי הצעות

אפשר לנהל את שרשורי ההצעות באמצעות הבקשות הבאות:

  • אישור ההצעה: משתמשים ב-AcceptSuggestionRequest כדי לאשר את ההצעה. כדי לעשות זאת, נדרשת גישת עריכה למסמך.
  • דחיית ההצעה: כדי לדחות את ההצעה, לוחצים על RejectSuggestionRequest. כדי לערוך את ההצעה, צריך הרשאת עריכה למסמך או להיות המחבר של ההצעה.
  • מחיקת ההצעה: כדי למחוק את ההצעה, לוחצים על DeleteSuggestionRequest. כדי לעשות את זה, צריך להיות המחבר של ההצעה.

בדוגמה הבאה מאשרים שרשור של הצעה:

{
  "requests": [
    {
      "acceptSuggestion": {
        "suggestionId": "suggestion_thread_id"
      }
    }
  ]
}

סטטוס העדכון של התגובות וההצעות

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

כדי לוודא שהעדכונים של התגובות או ההצעות הוחלו בהצלחה, בודקים את השדה commentUpdateState ב-BatchUpdateDocumentResponse.

הסטטוסים הבאים מוחזרים ב-CommentUpdateState:

  • ‫NO_UPDATES_REQUESTED: לא נשלחה בקשה לעדכונים של תגובות או הצעות בפעולת החבילה.
  • ‫ALL_SAVED: כל העדכונים המבוקשים בתגובות או בהצעות יושמו בהצלחה.
  • ‫ALL_FAILED_UNKNOWN_REASON: כל העדכונים של התגובות או ההצעות שביקשת נכשלו בשמירה, למרות שאולי בוצעו שינויים במודל של Docs.