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

تتيح لك 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. على سبيل المثال، معرّف الفيديو 7U3axjORYZ0 هو للفيديو على YouTube الذي يمكن الوصول إليه من خلال الرابط https://www.youtube.com/watch?v=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.
• يضبط الخط على Corsiva المائل الغامق بحجم 18 نقطة.
• يضع خطًا تحت النص.

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

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

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