الشرائح الذكية

يشرح هذا الدليل كيفية استخدام Google Sheets API وسبب استخدامه لإضافة شرائح ذكية وإدارتها في جداول البيانات.

ما هي الشريحة الذكية؟

باستخدام الشرائح الذكية، يمكنك جلب بيانات تفاعلية غنية من تطبيقات Google Workspace الأخرى إلى "جداول بيانات Google" مباشرةً. تتيح الشرائح الذكية للمستخدمين الوصول السريع إلى المعلومات والإجراءات، ما يحوّل رابط الخلية إلى عنصر ديناميكي. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة إدراج شرائح ذكية في "جداول بيانات Google".

إضافة شريحة ذكية

يتم تمثيل الشرائح على أنّها عمليات تشغيل للشرائح، وهي جزء من CellData، لذا يمكنك إدراج شريحة باستخدام طريقة spreadsheets.batchUpdate الحالية من خلال تقديم UpdateCellsRequest أو AppendCellsRequest.

يجب أن يتضمّن الطلب الحقل chipRuns. تصف عملية تشغيل الشريحة خصائص الشريحة وموضعها ضمن نص الخلية.

عند كتابة chipRuns، عليك أيضًا تقديم userEnteredValue يحتوي على أحرف نائبة (@) لكل شريحة تنوي إضافتها. ستتطابق كل عملية تشغيل في مصفوفة chipRuns مع أحد العناصر النائبة. يمكن حذف عمليات التشغيل غير المقطّعة عند الكتابة.

يوضّح المثال التالي كيفية كتابة شريحة ملف وشريحة مستخدِم ونص عادي في خلية واحدة، وهي A1. * {JSON}

        {
          "updateCells": {
            "rows": [
              {
                "values": [
                  {
                    "userEnteredValue": {
                      "stringValue": "@ is the owner of @."
                    },
                    "chipRuns": [
                      {
                        "chip": {
                          "personProperties": {
                            "email": "johndoe@gmail.com",
                            "displayFormat": "DEFAULT"
                          }
                        }
                      },
                      {
                        "startIndex": 18,
                        "chip": {
                          "richLinkProperties": {
                            "uri": "https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit"
                          }
                        }
                      }
                    ]
                  }
                ]
              }
            ],
            "fields": "userEnteredValue,chipRuns",
            "range": {
              "startRowIndex": 0,
              "startColumnIndex": 0
            }
          }
        }

ضبط خصائص الشريحة

يمكن أن يتضمّن عنصر الشريحة أحد أنواع الخصائص التالية:

personProperties

استخدِم هذا النوع لإنشاء شريحة شخص.

  • email: (مطلوب) عنوان البريد الإلكتروني للشخص الذي تريد ربطه.
  • displayFormat: (اختياري) تنسيق العرض المفضّل لاسم الشخص. يمكن أن يكون أحد الخيارات التالية:
    • DEFAULT: التنسيق العادي "الاسم الأول واسم العائلة".
    • LAST_NAME_COMMA_FIRST_NAME: التنسيق "اسم العائلة، الاسم الأول".
    • EMAIL: عنوان البريد الإلكتروني للشخص.

استخدِم هذا النوع لإنشاء شريحة رابط غني. على الرغم من أنّ واجهة برمجة التطبيقات يمكنها قراءة الروابط المؤدية إلى خدمات Google المختلفة (مثل YouTube أو "تقويم Google")، لا يمكن كتابة الروابط المؤدية إلى ملفات Google Drive إلا على شكل شرائح.

  • uri: (مطلوب) المعرّف الموحّد للمورد. عند الكتابة، يجب أن يكون هذا المعرّف رابطًا لملف على Google Drive. يجب ألا يتجاوز المعرّف الموحّد 2000 بايت.

قراءة شريحة ذكية

لقراءة بيانات شريحة ذكية، استخدِم طريقة spreadsheets.get وضِّمن sheets.data.rowData.values(chipRuns) في مَعلمة الحقول.

ستحتوي مصفوفة chipRuns في الردّ على عناصر لجميع الأقسام الفرعية لنص الخلية.

  • عمليات التشغيل المقطّعة: ستحتوي هذه الأقسام على عنصر chip مملوء يتضمّن personProperties أو richLinkProperties.
  • عمليات التشغيل غير المقطّعة: ستحتوي أقسام النص العادي أيضًا على عنصر تشغيل، ولكن سيكون الحقل chip فارغًا.

للحصول على نص العرض الخاص بالشريحة، أضِف formattedValue كحقل.

تعديل شريحة ذكية

لتعديل شريحة ذكية أو استبدالها، عليك الكتابة فوق محتويات الخلية. استخدِم UpdateCellsRequest أو AppendCellsRequest نفسهما اللذين تستخدمهما لإضافة شريحة، مع تقديم userEnteredValue وchipRun جديدَين. سيؤدي ذلك إلى استبدال الشريحة الحالية في الخلية.

استخدام الشرائح الذكية مع ميزات "جداول بيانات Google" الأخرى

الجداول: يمكن استخدام الشرائح الذكية كنوع عمود في الجدول لتتبُّع مالكي المشاريع (شريحة مستخدِم) أو المستندات ذات الصلة (شريحة الملف).

الفلاتر: يمكنك فلترة النطاقات استنادًا إلى القيمة النصية للشرائح الذكية بداخلها.