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

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

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

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

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

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

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

وصفة أساسية

في ما يلي مثال يوضِّح كيفية استخدام Docs API لدمج البيانات في مستند:

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

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

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

4. في الرمز الخاص بك، استخدِم طريقة batchUpdate() الخاصة بـ Docs API مع اسم المستند وضمِّن 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 في واجهة برمجة تطبيقات المستندات.
2. عدِّل الأذونات للسماح لمستلمي المستند بقراءته باستخدام permissions.create في Drive API.
3. يمكنك تعديل الأذونات للسماح لمؤلفي النماذج بالكتابة فيه باستخدام permissions.create في Drive API.
4. عدِّل النموذج حسب الحاجة.

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

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