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

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

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

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

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

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

כדי להגדיר אם התגובות ייכללו באחזור המסמך, משתמשים בפרמטר האופציונלי commentsViewMode. אם מגדירים את 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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

בתשובה הקודמת, הפסקה שמכילה את השורה '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] }

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