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

من بين التطبيقات المفيدة لواجهة برمجة تطبيقات محرر مستندات 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

مثال

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

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

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

        List<Request> requests = new ArrayList<>();
        requests.add(new Request()
                .setReplaceAllText(new ReplaceAllTextRequest()
                        .setContainsText(new SubstringMatchCriteria()
                                .setText("{{customer-name}}")
                                .setMatchCase(true))
                        .setReplaceText(customerName)));
        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();

  let customerName = 'Alice';
  let date = yyyymmdd()
  let requests = [
    {
      replaceAllText: {
        containsText: {
          text: '{{customer-name}}',
          matchCase: true,
        },
        replaceText: customerName,
      },
    },
    {
      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);
            });
      });

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

    requests = [
         {
            'replaceAllText': {
                'containsText': {
                    'text': '{{customer-name}}',
                    'matchCase':  'true'
                },
                'replaceText': customer_name,
            }}, {
            '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 API.
3. عدِّل الأذونات للسماح لمؤلفي النماذج بالكتابة إليها باستخدام permissions.create في Drive API.
4. عدِّل النموذج على النحو المطلوب.

لإنشاء مثيل من المستند، نفِّذ الخطوات التالية باستخدام بيانات اعتماد المستخدم:

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