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

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

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

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

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

• من السهل على المصمّمين تحسين تصميم المستند باستخدام محرِّر "مستندات 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<>();
// 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();

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

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

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

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