Erweiterter Google Docs-Dienst

Mit dem erweiterten Docs-Dienst können Sie die Google Docs API in Apps Script verwenden. Ähnlich wie beim integrierten Docs-Dienst von Apps Script können Scripts mit dieser API Inhalte in Google Docs lesen, bearbeiten und formatieren. In den meisten Fällen ist der integrierte Dienst einfacher zu verwenden, aber dieser erweiterte Dienst bietet einige zusätzliche Funktionen.

Referenz

Weitere Informationen zu diesem Dienst finden Sie in der Referenzdokumentation für die Docs API. Wie alle erweiterten Dienste in Apps Script verwendet der erweiterte Docs-Dienst dieselben Objekte, Methoden und Parameter wie die öffentliche API. Weitere Informationen finden Sie unter Methodensignaturen bestimmen.

Informationen zum Melden von Problemen und zur Suche nach weiterer Unterstützung finden Sie im Supportleitfaden für die Docs API.

Beispielcode

Im folgenden Beispielcode wird Version 1 der API verwendet.

Dokument erstellen

In diesem Beispiel wird ein neues Dokument erstellt.

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);
  }
}

Text suchen und ersetzen

In diesem Beispiel werden Textpaare auf allen Tabs in einem Dokument gefunden und ersetzt. Das kann nützlich sein, wenn Sie Platzhalter in einer Kopie eines Vorlagendokuments durch Werte aus einer Datenbank ersetzen möchten.

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];
    // One option for replacing all text is to specify all tab IDs.
    const request = {
      replaceAllText: {
        containsText: {
          text: findText,
          matchCase: true
        },
        replaceText: replaceText,
        tabsCriteria: {
          tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3],
        }
      }
    };
    // Another option is to omit TabsCriteria if you are replacing across all tabs.
    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);
  }
}

Text einfügen und formatieren

In diesem Beispiel wird neuer Text am Anfang des ersten Tabs im Dokument eingefügt und mit einer bestimmten Schriftart und -größe formatiert. Aus Effizienzgründen sollten Sie nach Möglichkeit mehrere Vorgänge in einem einzigen batchUpdate-Aufruf zusammenfassen.

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'
    }
  }];
  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);
  }
}

Ersten Absatz lesen

In diesem Beispiel wird der Text des ersten Absatzes des ersten Tabs im Dokument protokolliert. Aufgrund der strukturierten Natur von Absätzen in der Docs API müssen Sie dazu den Text mehrerer untergeordneter Elemente kombinieren.

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) {
  try {
    // 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;
      }
    }
  } catch (e) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', e.message);
  }
}

Best Practices

Batch-Updates

Wenn Sie den erweiterten Docs-Dienst verwenden, kombinieren Sie mehrere Anfragen in einem Array, anstatt batchUpdate in einer Schleife aufzurufen.

Nicht: batchUpdate in einer Schleife aufrufen.

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

Do: batchUpdate mit einer Reihe von Updates aufrufen.

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

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