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

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

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

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

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

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

  • إنّ فصل المحتوى عن طريقة عرضه هو مبدأ تصميم معروف وله العديد من المزايا.

مخطط تصوّري لعملية الدمج

وصفة أساسية

في ما يلي مثال على كيفية استخدام Docs API لدمج البيانات في مستند:

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

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

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

  4. في الرمز البرمجي، استخدِم طريقة Docs API's batchUpdate() مع اسم المستند وضِّمن ReplaceAllTextRequest.

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

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

مثال

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

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

جافا

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

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

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

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