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

يوضّح هذا الدليل كيفية استخدام 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: (سمة مطلوبة) عنوان URL للمورد. يجب أن يكون هذا الرابط لملف على Google Drive في حال الكتابة. يجب ألا تتجاوز عناوين URL 2,000 بايت.

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

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

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

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

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

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

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

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

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

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