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

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

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

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

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

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

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

  • אם הערך של commentsViewMode הוא COMMENTS_VIEW_MODE_INCLUDED, הערך של suggestionsViewMode חייב להיות SUGGESTIONS_INLINE.
  • אם commentsViewMode מוגדר לערך COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS, צריך להגדיר את suggestionsViewMode לערך SUGGESTIONS_INLINE או DEFAULT_FOR_CURRENT_ACCESS.

אם מגדירים את commentsViewMode לערך COMMENTS_VIEW_MODE_INCLUDED, צריך להגדיר גם את includeTabsContent לערך true. אם משתמשים במסכת שדות שמפנה לשדה tabs (או לכל שדה משנה), ה-API מתייחס לבקשה באופן מרומז כאילו הגדרתם את includeTabsContent ל-true.

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

אחת הסיבות לכך ש-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, שמורכבת מ-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] }

בדוגמה הקודמת, הפסקה מורכבת משלושה רצפים של טקסט, שמתחילים בשורות 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 השרשור).

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

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

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

בדוגמה הבאה מוצג פתרון לשרשור תגובות, שלא דורש תוכן:

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

בדוגמה הבאה של JSON אפשר לראות איך להקצות מחדש שרשור תגובות:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "content": "Replying to the comment thread.",
          "assigneeEmail": "user@example.com"
        }
      }
    }
  ]
}

עריכת פוסט

כדי לערוך את תוכן הטקסט של פוסט שכתבתם, משתמשים בלחצן 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.