دمج نص في مستند

من بين التطبيقات المفيدة لواجهة برمجة تطبيقات محرّر مستندات Google هو دمج المعلومات من أو مصادر بيانات أو أكثر في مستند.

تحدد هذه الصفحة كيفية أخذ البيانات من مصدر خارجي وإدراجها في مستند قالب موجود.

النموذج هو نوع خاص من المستندات يحتوي على نفس النص الثابت لجميع المستندات التي يتم إنشاؤها من النموذج، بالإضافة إلى العناصر النائبة المحدّدة. حيث يمكن وضع نص ديناميكي آخر. على سبيل المثال، قد يحتوي قالب العقد على محتوى ثابت، إلى جانب مواضع لاسم المُستلِم وعنوانه تفاصيل أخرى. يمكن لتطبيقك بعد ذلك دمج البيانات الخاصة بالعملاء في النموذج لإنشاء مستندات مكتملة.

وهناك عدة أسباب تجعل هذا المنهج مفيدًا:

  • من السهل على المصممين ضبط تصميم المستند باستخدام محرر مستندات Google. وهذا أسهل بكثير من ضبط المعلمات لتطبيقك لإعداد التخطيط المعروض.

  • فصل المحتوى عن العرض التقديمي هو تصميم معروف مبدأ به العديد من الفوائد.

رسم بياني مفاهيمي لعملية دمج.

وصفة أساسية

في ما يلي مثال على كيفية استخدام واجهة برمجة التطبيقات لتطبيق "مستندات Google" لدمج البيانات في مستند:

  1. إنشاء المستند باستخدام والمحتوى النائب لمساعدتك في التصميم والتنسيق. يتم حفظ أي تنسيق نصي تريد استبداله.

  2. لكل عنصر ستدرجه، استبدل محتوى العنصر النائب . تأكد من استخدام السلاسل التي من غير المرجح أن تحدث بشكل طبيعي. على سبيل المثال: قد تكون العلامة {{account-holder-name}} علامة جيدة.

  3. في الرمز، استخدِم Google Drive API لإنشاء نسخة من المستند.

  4. في الرمز الخاص بك، استخدم الطريقة batchUpdate() في واجهة برمجة تطبيقات "مستندات Google" مع اسم الوثيقة وتضمين ReplaceAllTextRequest

تشير معرّفات المستندات إلى مستند ويمكن اشتقاقها من عنوان URL

https://docs.google.com/document/d/documentId/edit

مثال

ضع في الاعتبار المثال التالي، الذي يستبدل حقلين عبر جميع علامات تبويب القالب بقيم حقيقية لإنشاء مستند نهائي.

لإجراء هذا الدمج، يمكنك استخدام الرمز أدناه.

Java

String customerName = "Alice";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String date = formatter.format(LocalDate.now());

List<Request> requests = new ArrayList<>();
// One option for replacing all text is to specify all tab IDs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{customer-name}}")
                        .setMatchCase(true))
                .setReplaceText(customerName)
                .setTabsCriteria(new TabsCriteria()
                        .addTabIds(TAB_ID_1)
                        .addTabIds(TAB_ID_2)
                        .addTabIds(TAB_ID_3))));
// Another option is to omit TabsCriteria if you are replacing across all tabs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{date}}")
                        .setMatchCase(true))
                .setReplaceText(date)));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(documentId, body.setRequests(requests)).execute();

Node.js

  let customerName = 'Alice';
  let date = yyyymmdd()
  let requests = [
    // One option for replacing all text is to specify all tab IDs.
    {
      replaceAllText: {
        containsText: {
          text: '{{customer-name}}',
          matchCase: true,
        },
        replaceText: customerName,
        tabsCriteria: {
          tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3],
        },
      },
    },
    // Another option is to omit TabsCriteria if you are replacing across all tabs.
    {
      replaceAllText: {
        containsText: {
          text: '{{date}}',
          matchCase: true,
        },
        replaceText: date,
      },
    },
  ];

  google.options({auth: auth});
  google
      .discoverAPI(
          'https://docs.googleapis.com/$discovery/rest?version=v1&key={YOUR_API_KEY}')
      .then(function(docs) {
        docs.documents.batchUpdate(
            {
              documentId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
              resource: {
                requests,
              },
            },
            (err, {data}) => {
              if (err) return console.log('The API returned an error: ' + err);
              console.log(data);
            });
      });

Python

customer_name = 'Alice'
date = datetime.datetime.now().strftime("%y/%m/%d")

requests = [
        # One option for replacing all text is to specify all tab IDs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{customer-name}}',
                'matchCase':  'true'
            },
            'replaceText': customer_name,
            'tabsCriteria': {
                'tabIds': [TAB_ID_1, TAB_ID_2, TAB_ID_3],
            },
        }},
        # Another option is to omit TabsCriteria if you are replacing across all tabs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{date}}',
                'matchCase':  'true'
            },
            'replaceText': str(date),
        }
    }
]

result = service.documents().batchUpdate(
    documentId=document_id, body={'requests': requests}).execute()

إدارة النماذج

بالنسبة إلى مستندات النماذج التي يحددها التطبيق ويمتلكها، يمكنك إنشاء النموذج باستخدام حساب مخصص يمثل التطبيق. حسابات الخدمة اختيارًا جيدًا وتجنُّب التعقيدات مع سياسات Google Workspace التي وتقييد المشاركة.

عند إنشاء مثيلات للمستندات من النماذج، استخدم دائمًا بيانات اعتماد المستخدم النهائي. يمنح ذلك المستخدمين تحكمًا كاملاً في المستند الناتج ويمنع مشكلات التوسيع المتعلقة بكل مستخدم والحدود القصوى في Drive.

لإنشاء نموذج باستخدام حساب خدمة، عليك اتّباع الخطوات التالية باستخدام: بيانات اعتماد التطبيق:

  1. إنشاء مستند باستخدام documents.create في واجهة برمجة تطبيقات "مستندات Google".
  2. تعديل الأذونات للسماح لمستلمي المستند بقراءته باستخدام permissions.create في واجهة برمجة تطبيقات Drive.
  3. عدِّل الأذونات للسماح لمؤلفي النماذج بالكتابة إليها باستخدام permissions.create في واجهة برمجة تطبيقات Drive.
  4. عدِّل النموذج على النحو المطلوب.

لإنشاء نسخة افتراضية من المستند، عليك اتّباع الخطوات التالية باستخدام بيانات اعتماد المستخدم:

  1. إنشاء نسخة من القالب باستخدام files.copy ضمن Drive API.
  2. استبدال القيم باستخدام documents.batchUpdate في واجهة برمجة تطبيقات المستندات.