خدمة المستندات المتقدّمة

تتيح لك خدمة "مستندات Google" المتقدّمة استخدام Google Docs API في Apps Script. تمامًا مثل خدمة "مستندات Google" المضمّنة في Apps Script، تسمح واجهة برمجة التطبيقات هذه للنصوص البرمجية بقراءة المحتوى وتعديله وتنسيقه في "مستندات Google". في معظم الحالات، تكون الخدمة المضمّنة أسهل في الاستخدام، ولكن هذه الخدمة المتقدّمة تقدّم بعض الميزات الإضافية.

مَراجع

للحصول على معلومات تفصيلية عن هذه الخدمة، يُرجى الاطّلاع على مستندات المرجع لواجهة برمجة التطبيقات Docs API. مثل جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة "مستندات Google" المتقدّمة العناصر والأساليب والمَعلمات نفسها المستخدَمة في واجهة برمجة التطبيقات المتاحة للجميع. لمزيد من المعلومات، اطّلِع على كيفية تحديد توقيعات الطرق.

للإبلاغ عن المشاكل والعثور على دعم آخر، يُرجى الاطّلاع على دليل دعم Docs API.

نموذج التعليمات البرمجية

يستخدم نموذج الرمز البرمجي أدناه الإصدار 1 من واجهة برمجة التطبيقات.

إنشاء مستند

ينشئ هذا المثال مستندًا جديدًا.

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

البحث عن النص واستبداله

يعثر هذا المثال على أزواج من النصوص ويستبدلها في جميع علامات التبويب في مستند. يمكن أن يكون هذا الإجراء مفيداً عند استبدال العناصر النائبة في نسخة من مستند نموذج بقيمة من قاعدة بيانات.

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

إدراج النص وتطبيق أسلوب عليه

يُدرج هذا العيّنة نصًا جديدًا في بداية علامة التبويب الأولى في المستند ويُعدّله باستخدام خط وحجم محدّدَين. يُرجى العلم أنّه يجب تجميع عمليات متعددة في طلب 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'
    }
  }];
  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 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);
  }
}

أفضل الممارسات

التعديلات المجمّعة

عند استخدام خدمة "مستندات Google" المتقدّمة، يمكنك دمج طلبات متعددة في صفيف بدلاً من استدعاء 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);