שירות Docs מתקדם

השירות המתקדם של Docs מאפשר להשתמש ב-Google Docs API ב-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() {
  try {
    // Create document with title
    const document = Docs.Documents.create({'title': 'My New Document'});
    console.log('Created document with ID: ' + document.documentId);
    return document.documentId;
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', e.message);
  }
}

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

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

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];
    const request = {
      replaceAllText: {
        containsText: {
          text: findText,
          matchCase: true
        },
        replaceText: replaceText
      }
    };
    requests.push(request);
  }
  try {
    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;
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error : %s', e.message);
  }
}

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

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

advanced/docs.gs
/**
 * Insert text at the beginning of 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
      },
      text: text
    }
  },
  {
    updateTextStyle: {
      range: {
        startIndex: 1,
        endIndex: text.length + 1
      },
      textStyle: {
        fontSize: {
          magnitude: 12,
          unit: 'PT'
        },
        weightedFontFamily: {
          fontFamily: 'Calibri'
        }
      },
      fields: 'weightedFontFamily, fontSize'
    }
  }];
  try {
    const response =Docs.Documents.batchUpdate({'requests': requests}, documentId);
    return response.replies;
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with an error %s', e.message);
  }
}

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

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

advanced/docs.gs
/**
 * Read the first paragraph of the body of 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) {
  try {
    // Get the document using document ID
    const document = Docs.Documents.get(documentId);
    const bodyElements = document.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;
      }
    }
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', e.message);
  }
}

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

עדכונים בכמות גדולה

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

מה לא לעשות — מתקשרים אל batchUpdate בלולאה.

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

Do — Call batchUpdate עם מגוון עדכונים.

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

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