שירות Docs מתקדם

סקריפט לקריאה, לעריכה ולעיצוב של תוכן ב-Google Docs עם תכונות נוספות.

שירות Docs המתקדם מאפשר לכם להשתמש ב-Google Docs API ב-Google Apps Script. בדומה לשירות Docs המובנה ב-Apps Script, ה-API הזה מאפשר לסקריפטים לקרוא, לערוך ולעצב תוכן ב-Google Docs. ברוב המקרים, קל יותר להשתמש בשירות המובנה, אבל השירות המתקדם הזה מספק כמה תכונות נוספות.

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

חומרי עזר

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

כדי לדווח על בעיות ולמצוא תמיכה נוספת, אפשר לעיין במדריך התמיכה של Docs API.

קוד לדוגמה

בדוגמת הקוד הבאה נעשה שימוש בגרסה 1 של ה-API.

יצירת מסמך

בדוגמה הזו נוצר מסמך חדש.

advanced/docs.gs
/**
 * Create a new document.
 * @see https://developers.google.com/docs/api/reference/rest/v1/documents/create
 * @return {string} documentId
 */
function createDocument() {
  // Create document with title
  const document = Docs.Documents.create({ title: "My New Document" });
  console.log(`Created document with ID: ${document.documentId}`);
  return document.documentId;
}

חיפוש והחלפה של טקסט

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

advanced/docs.gs
/**
 * Performs "replace all".
 * @param {string} documentId The document to perform the replace text operations on.
 * @param {Object} findTextToReplacementMap A map from the "find text" to the "replace text".
 * @return {Object} replies
 * @see https://developers.google.com/docs/api/reference/rest/v1/documents/batchUpdate
 */
function findAndReplace(documentId, findTextToReplacementMap) {
  const requests = [];
  for (const findText in findTextToReplacementMap) {
    const replaceText = findTextToReplacementMap[findText];

    // Replace all text across all tabs.
    const replaceAllTextRequest = {
      replaceAllText: {
        containsText: {
          text: findText,
          matchCase: true,
        },
        replaceText: replaceText,
      },
    };

    // Replace all text across specific tabs.
    const _replaceAllTextWithTabsCriteria = {
      replaceAllText: {
        ...replaceAllTextRequest.replaceAllText,
        tabsCriteria: {
          tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3],
        },
      },
    };
    requests.push(replaceAllTextRequest);
  }
  const response = Docs.Documents.batchUpdate(
    { requests: requests },
    documentId,
  );
  const replies = response.replies;
  for (const [index] of replies.entries()) {
    const numReplacements =
      replies[index].replaceAllText.occurrencesChanged || 0;
    console.log(
      "Request %s performed %s replacements.",
      index,
      numReplacements,
    );
  }
  return replies;
}

הוספה ועיצוב של טקסט

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

advanced/docs.gs
/**
 * Insert text at the beginning of the first tab in the document and then style
 * the inserted text.
 * @param {string} documentId The document the text is inserted into.
 * @param {string} text The text to insert into the document.
 * @return {Object} replies
 * @see https://developers.google.com/docs/api/reference/rest/v1/documents/batchUpdate
 */
function insertAndStyleText(documentId, text) {
  const requests = [
    {
      insertText: {
        location: {
          index: 1,
          // A tab can be specified using its ID. When omitted, the request is
          // applied to the first tab.
          // tabId: TAB_ID
        },
        text: text,
      },
    },
    {
      updateTextStyle: {
        range: {
          startIndex: 1,
          endIndex: text.length + 1,
        },
        textStyle: {
          fontSize: {
            magnitude: 12,
            unit: "PT",
          },
          weightedFontFamily: {
            fontFamily: "Calibri",
          },
        },
        fields: "weightedFontFamily, fontSize",
      },
    },
  ];
  const response = Docs.Documents.batchUpdate(
    { requests: requests },
    documentId,
  );
  return response.replies;
}

קריאת הפסקה הראשונה

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

advanced/docs.gs
/**
 * Read the first paragraph of the first tab in a document.
 * @param {string} documentId The ID of the document to read.
 * @return {Object} paragraphText
 * @see https://developers.google.com/docs/api/reference/rest/v1/documents/get
 */
function readFirstParagraph(documentId) {
  // Get the document using document ID
  const document = Docs.Documents.get(documentId, {
    includeTabsContent: true,
  });
  const firstTab = document.tabs[0];
  const bodyElements = firstTab.documentTab.body.content;
  for (let i = 0; i < bodyElements.length; i++) {
    const structuralElement = bodyElements[i];
    // Print the first paragraph text present in document
    if (structuralElement.paragraph) {
      const paragraphElements = structuralElement.paragraph.elements;
      let paragraphText = "";

      for (let j = 0; j < paragraphElements.length; j++) {
        const paragraphElement = paragraphElements[j];
        if (paragraphElement.textRun !== null) {
          paragraphText += paragraphElement.textRun.content;
        }
      }
      console.log(paragraphText);
      return paragraphText;
    }
  }
}

שיטות מומלצות

עדכונים באצווה

כשמשתמשים בשירות המתקדם של Docs, כדאי לשלב כמה בקשות במערך במקום לקרוא ל-batchUpdate בלולאה.

אל — קריאה ל-batchUpdate בלולאה.

var textToReplace = ['foo', 'bar'];
for (var i = 0; i < textToReplace.length; i++) {
  Docs.Documents.batchUpdate({
    requests: [{
      replaceAllText: ...
    }]
  }, docId);
}

פעולה – התקשר אל batchUpdate עם מערך של עדכונים.

var requests = [];
var textToReplace = ['foo', 'bar'];
for (var i = 0; i < textToReplace.length; i++) {
  requests.push({ replaceAllText: ... });
}

Docs.Documents.batchUpdate({
  requests: requests
}, docId);