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

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

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

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

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

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

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

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

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

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

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

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