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

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

يضبط الطلب أيضًا LinkingMode للرسم البياني في Slides على 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". يتطلّب الطلب رقم تعريف الرسم البياني داخل عرض Slides التقديمي (محدّد بواسطة PRESENTATION_CHART_ID).

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

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

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