عمليات العناصر

تتيح لك Google Slides API إنشاء موارد PageElement وتعديلها، بما في ذلك مربّعات النص والصور والجداول والأشكال الأساسية والخطوط والفيديوهات المضمّنة. تعرض الأمثلة الواردة في هذه الصفحة بعض عمليات عناصر الصفحة الشائعة باستخدام الأسلوب presentations.batchUpdate.

تستخدِم هذه الأمثلة المتغيّرات التالية:

• PRESENTATION_ID: يشير إلى المكان الذي تقدّم فيه معرّف العرض التقديمي. يمكنك retrieving the value for this ID from the presentation URL.
• PAGE_ID: يشير إلى المكان الذي تقدّم فيه معرّف عنصر الصفحة. يمكنك استرجاع القيمة الخاصة بهذا العنوان من عنوان URL أو باستخدام طلب قراءة واجهة برمجة التطبيقات.
• PAGE_ELEMENT_ID: يشير إلى المكان الذي تقدّم فيه رقم تعريف كائن ملفّق الصفحة. يمكنك تحديد هذا المعرّف للعناصر التي تنشئها (مع بعض القيود) أو السماح لواجهة برمجة التطبيقات Slides API بإنشاء معرّف تلقائيًا. يمكن استرداد أرقام تعريف العناصر من خلال طلب قراءة واجهة برمجة التطبيقات.

يتم تقديم هذه الأمثلة كطلبات HTTP لتكون محايدة من حيث اللغة. للتعرّف على كيفية تنفيذ تحديث مجمّع بلغات مختلفة باستخدام مكتبات عملاء Google API، يمكنك الاطّلاع على الأدلة التالية:

• تعديل النص وتنسيقه
• إضافة أشكال ونصوص
• إضافة رسم بياني

إضافة قائمة نقطية إلى مربّع نص

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء InsertTextRequest لإدراج نص في مربّع نص فارغ محدّد من خلال PAGE_ELEMENT_ID. بعد ذلك، يستخدم العيّنة الأسلوب CreateParagraphBulletsRequest لتحويل كل نص مربّع النص إلى قائمة نقطية. يتم الفصل بين العناصر في القائمة باستخدام \n حرفًا، بينما يتم التحكّم في المسافة البادئة باستخدام \t حرفًا.

في ما يلي بروتوكول الطلب لإنشاء عرض تقديمي:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "My List\n\tItem 1\n\t\tItem 2\n\t\t\tItem 3",
        "insertionIndex": 0
      },
      "createParagraphBullets": {
        "objectId": PAGE_ELEMENT_ID,
        "bulletPreset": "BULLET_ARROW_DIAMOND_DISC",
        "textRange": {
          "type": "ALL"
        }
      }
    }
  ]
}

يمكن أن يؤدي هذا الطلب إلى إنشاء قائمة بعدد نقاط تبدو على النحو التالي:

إضافة شكل إلى شريحة

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء CreateShapeRequest لإضافة شكل موجة إلى شريحة محدّدة بواسطة PAGE_ID. يحدِّد هذا الطلب نوع الشكل، ثم يغيِّر حجمه ويحدِّد موضعه في الشريحة. بعد ذلك، يستخدم الإجراء InsertTextRequest لإضافة نص إلى هذا الشكل. يضبط الطلب رقم تعريف السطر على PAGE_ELEMENT_ID.

في ما يلي بروتوكول الطلب لإضافة شكل إلى شريحة:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "createShape": {
        "objectId": PAGE_ELEMENT_ID,
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 0.6807,
            "scaleY": 0.4585,
            "translateX": 6583050,
            "translateY": 1673950,
            "unit": "EMU"
          }
        },
        "shapeType": "WAVE"
      }
    },
    {
      "insertText": {
        "objectId": PAGE_ELEMENT_ID,
        "text": "My Wave Shape",
        "insertionIndex": 0
      }
    }
  ]
}

إضافة فيديو إلى شريحة

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء CreateVideoRequest لتضمين فيديو في شريحة محدّدة بواسطة PAGE_ID. يغيّر هذا الطلب حجم الفيديو ويحدّد موضعه في الشريحة، ويضبط رقم تعريف الفيديو على PAGE_ELEMENT_ID. تم ضبط المعرّف الفريد للفيديو المصدر علىVIDEO_ID. على سبيل المثال، يحمل الفيديو على YouTube المتوفّر على الرابط https://www.youtube.com/watch?v=7U3axjORYZ0 معرّف 7U3axjORYZ0.

في ما يلي بروتوكول الطلب لإضافة فيديو إلى شريحة:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "createVideo": {
        "objectId": PAGE_ELEMENT_ID,
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 12000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 9000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 381,
            "scaleY": 381,
            "translateX": 152400,
            "translateY": 152400,
            "unit": "EMU"
          }
        },
        "source": "YOUTUBE",
        "id": VIDEO_ID
      }
    }
  ]
}

نسخ عنصر وتعديله

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء DuplicateObjectRequest لأخذ شكل حالي (يتم تحديده باستخدام العنصر PAGE_ELEMENT_ID) وإنشاء نسخة منه (يتم تحديدها باستخدام العنصر COPY_ELEMENT_ID).

بعد ذلك، تُجري الطلبات اللاحقة التغييرات التالية على الكائن المكرّر:

• لضبط لون الخلفية على لون التصميم LIGHT2.
• نقل النسخة إلى أسفل الصفحة (من موضع الشكل الأصلي)
• لضبط خط النص على Georgia بحجم 18 نقطة.
• تعديل النص ليصبح "نسخة الشكل الخاص بي"

تستخدِم الطلبات هنا أقنعة الحقول للحفاظ على خصائص الشكل التي لم تتغيّر (مثل نمط المخطط). ويؤدي استخدام أقنعة الحقول إلى تحسين الأداء أيضًا.

لمزيد من المعلومات عن نسخ شريحة، اطّلِع على النموذج نسخ شريحة.

في ما يلي بروتوكول الطلب لنسخ عنصر وتعديله:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "duplicateObject": {
        "objectId": PAGE_ELEMENT_ID,
        "objectIds": {
          PAGE_ELEMENT_ID: COPY_ELEMENT_ID
        }
      }
    },
    {
      "updateShapeProperties": {
        "objectId": COPY_ELEMENT_ID,
        "fields": "shapeBackgroundFill.solidFill.color",
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "LIGHT2"
              }
            }
          }
        }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": COPY_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
          "scaleX": 1,
          "scaleY": 1,
          "translateX": 0,
          "translateY": 1250000,
          "unit": "EMU"
        }
      }
    },
    {
      "updateTextStyle": {
        "objectId": COPY_ELEMENT_ID,
        "fields": "fontFamily,fontSize",
        "textRange": {
          "type": "ALL"
        },
        "style": {
          "fontFamily": "Georgia",
          "fontSize": {
            "magnitude": 18,
            "unit": "PT"
          }
        }
      }
    },
    {
      "deleteText": {
        "objectId": COPY_ELEMENT_ID,
        "textRange": {
          "type": "ALL"
        }
      }
    },
    {
      "insertText": {
        "objectId": COPY_ELEMENT_ID,
        "text": "My Shape Copy",
        "insertionIndex": 0
      }
    }
  ]
}

في ما يلي الشكل الذي قد يبدو عليه الشكل ونسخته بعد إجراء هذه التعديلات:

تعديل مخطّط صورة أو فيديو

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء UpdateImagePropertiesRequest لتعديل مظهر المخطط الخارجي لصورة محدّدة باستخدام العنصر IMAGE_ELEMENT_ID. وتستخدم هذه السمة أيضًا الطريقة UpdateVideoPropertiesRequest لتعديل مظهر المخطط التفصيلي لفيديو مضمّن محدّد باستخدام العنصر VIDEO_ELEMENT_ID.

تُجري الطلبات التغييرات التالية على العنصر:

• لضبط لون مخطّط الصورة على لون تصميم ACCENT5 مع جزئي شفافية
• ضبط لون مخطّط الفيديو على لون تصميم ACCENT1 بدون شفافية
• ضبط سمك المخططات على 3 نقاط لكلا الخطّين
• لضبط نمط مخطّط الصورة على SOLID.
• لضبط نمط مخطّط الفيديو على DASH_DOT.

لا يمكن لأي من الطريقتَين UpdateImagePropertiesRequest و UpdateVideoPropertiesRequest تغيير سوى مظهر الصور ومخططات الفيديو. وجميع المواقع الأخرى للقراءة فقط. تستخدِم الطلبات الواردة هنا أقنعة الحقول لتحديد أنّه يجب تغيير المخطّط فقط لحماية الرمز من التغييرات المستقبلية لواجهة برمجة التطبيقات. يؤدي استخدام أقنعة الحقول إلى تحسين الأداء أيضًا.

في ما يلي بروتوكول الطلب لتعديل مخطّط صورة أو فيديو:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "updateImageProperties": {
        "objectId": IMAGE_ELEMENT_ID,
        "fields": "outline",
        "imageProperties": {
          "outline": {
            "dashStyle": "SOLID",
            "outlineFill": {
              "solidFill": {
                "alpha": 0.8,
                "color": {
                  "themeColor": "ACCENT5"
                }
              }
            },
            "weight": {
              "magnitude": 3,
              "unit": "PT"
            }
          }
        }
      }
    },
    {
      "updateVideoProperties": {
        "objectId": VIDEO_ELEMENT_ID,
        "fields": "outline",
        "videoProperties": {
          "outline": {
            "dashStyle": "DASH_DOT",
            "outlineFill": {
              "solidFill": {
                "alpha": 0.8,
                "color": {
                  "themeColor": "ACCENT1"
                }
              }
            },
            "weight": {
              "magnitude": 3,
              "unit": "PT"
            }
          }
        }
      }
    }
  ]
}

في ما يلي الشكل الذي قد تظهر به الصورة والفيديو المضمّن بعد إجراء هذه التعديلات:

تعديل مخطّط شكل

يوضّح رمز النموذج التالي presentations.batchUpdate كيفية استخدام الإجراء UpdateShapePropertiesRequest لاتخاذ شكل حالي (يُحدَّد باستخدام العنصر PAGE_ELEMENT_ID) وتعديل مظهر مخطّطه.

تُجري الطلبات التغييرات التالية على العنصر:

• ضبط لون المخطط على لون تصميم ACCENT5 مع شفافية جزئية
• لضبط سمك المخطط على 3 نقاط.
• لضبط نمط المخطط على LONG_DASH.

تستخدِم الطلبات الواردة هنا أقنعة الحقول للحفاظ على خصائص الشكل التي لم تتغيّر (مثل لون تعبئة الشكل). ويؤدي استخدام أقنعة الحقول إلى تحسين الأداء أيضًا.

في ما يلي بروتوكول الطلب لتعديل المخطط التفصيلي لشكل معيّن:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": PAGE_ELEMENT_ID,
        "fields": "outline",
        "shapeProperties": {
          "outline": {
            "dashStyle": "LONG_DASH",
            "outlineFill": {
              "solidFill": {
                "alpha": 0.6,
                "color": {
                  "themeColor": "ACCENT5"
                }
              }
            },
            "weight": {
              "magnitude": 3,
              "unit": "PT"
            }
          }
        }
      }
    }
  ]
}

في ما يلي الشكل الذي قد يبدو عليه الشكل بعد إجراء هذه التعديلات:

تنسيق النص في شكل أو مربّع نص

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء UpdateTextStyleRequest لاتخاذ شكل حالي (يحدده الرمز PAGE_ELEMENT_ID) وتعديل مظهر نصه.

تُجري الطلبات التغييرات التالية على العنصر:

• لضبط لون النص على لون المظهر ACCENT5
• ضبط الخط على أن يكون غامقًا ومائلًا بحجم 18 نقطة من نوع Corsiva
• يُرسِل خطًا تحت النص.

تستخدِم الطلبات الواردة هنا أقنعة الحقول للحفاظ على خصائص نمط النص التي لم يتم تغييرها (مثل لون الخلفية، أو الروابط، أو Offsets للخط الأساسي). ويؤدي استخدام أقنعة الحقول إلى تحسين الأداء أيضًا.

في ما يلي بروتوكول الطلب لتنسيق النص في شكل أو مربّع نص:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "updateTextStyle": {
        "objectId": PAGE_ELEMENT_ID,
        "fields": "foregroundColor,bold,italic,fontFamily,fontSize,underline",
        "style": {
          "foregroundColor": {
            "opaqueColor": {
              "themeColor": "ACCENT5"
            }
          },
          "bold": true,
          "italic": true,
          "underline": true,
          "fontFamily": "Corsiva",
          "fontSize": {
            "magnitude": 18,
            "unit": "PT"
          }
        },
        "textRange": {
          "type": "ALL"
        }
      }
    }
  ]
}

في ما يلي الشكل الذي قد يبدو عليه نص الشكل بعد إجراء هذه التعديلات:

استيراد رسم بياني من "جداول بيانات Google"

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء CreateSheetsChartRequest لاستيراد رسم بياني من ورقة بيانات ووضعه على شريحة محدّدة باستخدام العنصر PAGE_ID.

يتطلّب الطلب رقم تعريف جدول البيانات (الذي يُحدَّد باستخدام العنصر SPREADSHEET_ID) ورقم تعريف الرسم البياني في جدول البيانات (الذي يُحدَّد باستخدام العنصر SPREADSHEET_CHART_ID). ويُحدَّد رقم تعريف الرسم البياني في عرض PowerPoint باستخدام العنصر PRESENTATION_CHART_ID.

يضبط الطلب أيضًا قيمة LinkingMode للرسم البياني في "العروض التقديمية من Google" على LINKED حتى تتمكّن من تعديل الرسم البياني المضمّن في حال تعديل الرسم البياني في جدول البيانات المصدر.

في ما يلي بروتوكول الطلب لاستيراد رسم بياني من ملف اتّباع التعليمات:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "createSheetsChart": {
        "objectId": PRESENTATION_CHART_ID,
        "spreadsheetId": SPREADSHEET_ID,
        "chartId": SPREADSHEET_CHART_ID,
        "linkingMode": "LINKED",
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 4000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 4000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 100000,
            "translateY": 100000,
            "unit": "EMU"
          }
      }
    }
  ]
}

إعادة تحميل رسم بياني من "جداول بيانات Google"

يوضّح رمز النموذج التالي presentations.batchUpdate كيفية استخدام الإجراء RefreshSheetsChartRequest لإعادة تحميل رسم بياني مرتبط في عرض تقديمي، واستبداله بأحدث إصدار من هذا الرسم البياني من جدول البيانات المصدر في "جداول بيانات Google". يتطلب الطلب رقم تعريف الرسم البياني ضمن عرض "العروض التقديمية من Google" (الذي يحدّده PRESENTATION_CHART_ID).

في ما يلي بروتوكول الطلب لإعادة تحميل رسم بياني من جداول بيانات Google:

POST https://slides.googleapis.com/v1/presentations/PRESENTATION_ID:batchUpdate

{
  "requests": [
    {
      "refreshSheetsChart": {
        "objectId": PRESENTATION_CHART_ID
      }
    }
  ]
}