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

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

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

• PRESENTATION_ID: يشير إلى المكان الذي تُقدِّم فيه رقم تعريف العرض التقديمي. يمكنك استرداد قيمة هذا المعرّف من عنوان URL للعرض التقديمي.
• PAGE_ID: يشير إلى مكان توفير رقم تعريف كائن الصفحة. يمكنك استرداد القيمة من عنوان URL أو باستخدام طلب قراءة واجهة برمجة التطبيقات.
• PAGE_ELEMENT_ID: يشير إلى المكان الذي يتم فيه توفير رقم تعريف كائن عنصر الصفحة. يمكنك تحديد هذا المعرّف للعناصر التي تنشئها (مع بعض القيود) أو السماح لواجهة برمجة تطبيقات العروض التقديمية بإنشاء واحد تلقائيًا. يمكن استرداد معرفات العناصر من خلال طلب قراءة واجهة برمجة التطبيقات.

ويتم تقديم هذه الأمثلة على شكل طلبات 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
• نقل النسخة إلى أسفل الصفحة (من موضع الشكل الأصلي).
• لتعيين خط النص على 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 نقطة،
• لتسطير النص

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

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

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 بحيث يمكنك تعديل الرسم البياني المضمّن في حال تم تعديل الرسم البياني في جدول البيانات المصدر.

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

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).

فيما يلي بروتوكول الطلب لتحديث مخطط من جداول البيانات:

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

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