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

يوضّح هذا الدليل كيفية استخدام 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" الأخرى

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

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