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

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

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

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

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

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

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

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

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