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

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

هذه خدمة متقدّمة يجب تفعيلها قبل استخدامها. enable before use اتّبِع دليل البدء السريع للحصول على تعليمات مفصّلة حول كيفية البدء.

مراجع

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

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

رمز نموذجي

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

إنشاء مستند

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

advanced/docs.gs

عرض على GitHub

/**
 * 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

عرض على GitHub

/**
 * 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

عرض على GitHub

/**
 * 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

عرض على GitHub

/**
 * 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;
    }
  }
}

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

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

عند استخدام خدمة "مستندات 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);