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

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

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

• PRESENTATION_ID—تشير إلى المكان الذي تقدّم فيه معرّف العرض التقديمي. يمكنك استرداد قيمة هذا المعرّف من عنوان 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.
• يضع خطًا تحت النص.

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

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

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). يتم تحديد رقم تعريف الرسم البياني في عرض Slides التقديمي بواسطة PRESENTATION_CHART_ID.

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

في ما يلي بروتوكول الطلب لاستيراد رسم بياني من "جداول بيانات Google":

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
      }
    }
  ]
}