عمليات التحويل

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

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

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

يتم تقديم هذه الأمثلة كطلبات HTTP لتكون محايدة من حيث اللغة. للتعرّف على كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات عملاء Google API، اطّلِع على مقالة إضافة أشكال وكلمات.

مثال على شكل السهم

في ما يلي أمثلة على عناصر صفحة تشكل سهامًا بالحجم وبيانات التحويل التالية (يمكن العثور عليها باستخدام طلب presentations.pages.get الطريقة). يستخدِم مثال الشكل قياس unit وحدة القياس الإنجليزية (EMU) وpt (نقطة).

{
  "objectId": PAGE_ELEMENT_ID,
  "size": {
    "width": {
      "magnitude": 3000000,
      "unit": "EMU"
    },
    "height": {
      "magnitude": 3000000,
      "unit": "EMU"
    }
  },
  "transform": {
    "scaleX": 0.3,
    "scaleY": 0.12,
    "shearX": 0,
    "shearY": 0,
    "translateX": 2000000,
    "translateY":  550000,
    "unit": "EMU"
  },
  "shape": {
    "shapeType": "RIGHT_ARROW"
  }
}

محاذاة عنصر مع آخر

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء CreateShapeRequest لإنشاء أشكال جديدة في المواضع الصحيحة التي تكون محاذية لمثال شكل السهم على الصفحة. في كلتا الحالتَين، يجب احتساب إحداثيات X وY للركن العلوي الأيمن من الشكل الجديد.

ينشئ الطلب الأول مستطيلاً أبعاده 100 x ‏50 نقطة يتم محاذاته مع حدود السهم اليمنى، ولكن يتم وضعه على مسافة 50 نقطة (50 * 12,700 = 635,000 وحدة EMU) أسفل الحافة العلوية للسهم. يجب أن يكون إحداثي X للمستطيل الجديد هو نفسه إحداثي X للسهم للحفاظ على محاذاة حدوده اليسرى. الإحداثي Y هو نفسه إحداثي Y للسهم بالإضافة إلى 50 نقطة، لأنّه يتم قياس المسافة من أعلى السهم. إحداثيات المستطيل هي لذلك:

x" = 2000000 EMU
y" = 550000 + (50 * 12700) = 1185000 EMU

ينشئ الطلب الثاني دائرة بعرض 40 نقطة لها خط مركزي أفقي مماثل لخط مركز السهم في المثال، ولكن يتم وضعها على مسافة 100 نقطة (1,270,000 وحدة EMU) على يسار الحافة اليمنى للسهم. الإحداثي X للدائرة هو مجموع إحداثي X للسهم وعرض السهم و100 نقطة. يتطلّب فرض محاذاة خطوط مركز الدائرة الجديدة مراعاة ارتفاع كلٍّ من السهم والدائرة. الإحداثي Y للدائرة هو الإحداثي Y للسهم بالإضافة إلى نصف ارتفاع السهم مطروحًا منه نصف ارتفاع الدائرة. في كلتا الحالتَين، يجب أيضًا مراعاة عوامل التكبير/التصغير المرتبطة بالسهم، لأنّها تؤثر في العرض والارتفاع المعروضَين للسهم. بالتالي، فإنّ إحداثيات الدائرة هي:

x = 2000000 + (0.3 * 3000000) + (100 * 12700) = 4170000 EMU
y = 550000 + (0.5 * 0.12 * 3000000) - (0.5 * 40 * 12700) = 476000 EMU

في ما يلي بروتوكول الطلب لمحاذاة عنصر مع آخر:

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

{
  "requests": [
    {
      "createShape": {
        "shapeType": "RECTANGLE",
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 100,
              "unit": "PT"
            },
            "height": {
              "magnitude": 50,
              "unit": "PT"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 2000000,
            "translateY": 1185000,
            "unit": "EMU"
          }
        }
      }
    },
    {
      "createShape": {
        "shapeType": "ELLIPSE",
        "elementProperties": {
          "pageObjectId": PAGE_ID,
          "size": {
            "width": {
              "magnitude": 40,
              "unit": "PT"
            },
            "height": {
              "magnitude": 40,
              "unit": "PT"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX": 4170000,
            "translateY":  476000,
            "unit": "EMU"
          }
        }
      }
    }
  ]
}

نقل عنصر

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

ينقل الطلب الأول في الحزمة السهم إلى الإحداثيات (X,Y) = (2000000, 150000) EMU (باستخدام ترجمة مطلقة applyMode). ينقل الطلب الثاني في الحزمة السهم من هناك، هذه المرة 40,000 EMU إلى اليمين و35,000 EMU للأعلى (باستخدام ترجمة نسبية applyMode). تم إنشاء مصفوفات التحويل1 المستخدَمة لتجنُّب تغيير حجم العنصر واتجاهه.

بعد تنفيذ كلا الطلبَين، يقع أعلى يمين السهم عند الإحداثيَين (X,Y) = (2040000, 115000) في نظام EMU.

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

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

{
  "requests": [
    {
      "updatePageElementTransform": {
        "objectId": PAGE_ELEMENT_ID,
        "applyMode": "ABSOLUTE",
        "transform": {
            "scaleX": 0.3,
            "scaleY": 0.12,
            "translateX": 2000000,
            "translateY":  150000,
            "unit": "EMU"
        }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": PAGE_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
            "scaleX": 1,
            "scaleY": 1,
            "translateX":  40000,
            "translateY": -35000,
            "unit": "EMU"
        }
      }
    }
  ]
}

عرض عنصر

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء UpdatePageElementTransformRequest لعرض عنصر الصفحة مثال شكل السهم أفقيًا على طول مركزه، بدون تغيير موضعه على الصفحة أو تكبيره أو تصغيره.

ويتم ذلك باستخدام تحوُّل أساسي للانعكاس في إطار مرجعي للعنصر. للتوضيح، يتم عرض التحول والانعكاس في الإطار المرجعي من خلال ثلاث طلبات منفصلة إلى أسلوب UpdatePageElementTransformRequest، ولكن من الأفضل احتساب منتج مصفوفات التحويل هذه مسبقًا ثم تطبيق هذا المنتج كطلب واحد.

بالنسبة إلى عمليات التحويل الترجمة، يتم نقل مركز شكل السهم من نقطة الأصل وإليها. يتم التعبير عن قيم المَعلمات كعمليات حسابية للوضوح.

في ما يلي بروتوكول الطلب لعرض عنصر:

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

{
  "requests": [
    {
      "updatePageElementTransform": {
        "objectId": PAGE_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
            "scaleX":  1,
            "scaleY":  1,
            "translateX": -2000000 - 0.5 * 0.3  * 3000000,
            "translateY":  -550000 - 0.5 * 0.12 * 3000000,
            "unit": "EMU"
        }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": PAGE_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
            "scaleX": -1,
            "scaleY":  1,
            "unit": "EMU"
        }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": PAGE_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
            "scaleX":  1,
            "scaleY":  1,
            "translateX":  2000000 + 0.5 * 0.3  * 3000000,
            "translateY":   550000 + 0.5 * 0.12 * 3000000,
            "unit": "EMU"
        }
      }
    }
  ]
}

تغيير حجم عنصر

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء UpdatePageElementTransformRequest لتكبير عنصر الصفحة مثال شكل السهم ليصبح أوسع بنسبة ‎50% ويكون ارتفاعه ‎80% فقط من ارتفاعه الحالي، مع إبقاء مركز السهم في الموضع نفسه والحفاظ على اتجاهه.

ويتم ذلك باستخدام تحويل أساسي للقياس في إطار مرجعي للعنصر. للتوضيح، يتم عرض التغيير في الإطار المرجعي وتغيير حجمه من خلال ثلاث طلبات منفصلة لطريقة UpdatePageElementTransformRequest، ولكن من الأفضل احتساب منتج مصفوفات التحويل هذه مسبقًا ثم تطبيق هذا المنتج كطلب واحد.

بالنسبة إلى عمليات التحويل الترجمة، يتم نقل مركز شكل السهم من نقطة الأصل وإليها. يتم التعبير عن قيم المَعلمات كعمليات حسابية للوضوح.

في ما يلي بروتوكول الطلب لتغيير حجم عنصر:

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

{
  "requests": [
    {
      "updatePageElementTransform": {
          "objectId": PAGE_ELEMENT_ID,
          "applyMode": "RELATIVE",
          "transform": {
              "scaleX":  1,
              "scaleY":  1,
              "translateX": -2000000 - 0.5 * 0.3  * 3000000,
              "translateY":  -550000 - 0.5 * 0.12 * 3000000,
              "unit": "EMU"
          }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": PAGE_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
            "scaleX": 1.5,
            "scaleY": 0.8,
            "unit": "EMU"
        }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": PAGE_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
            "scaleX":  1,
            "scaleY":  1,
            "translateX":  2000000 + 0.5 * 0.3  * 3000000,
            "translateY":   550000 + 0.5 * 0.12 * 3000000,
            "unit": "EMU"
        }
      }
    }
  ]
}

تدوير عنصر حول مركزه

يوضّح نموذج الرمز البرمجي التالي presentations.batchUpdate كيفية استخدام الإجراء UpdatePageElementTransformRequest لتدوير عنصر الصفحة مثال شكل السهم 35 درجة بعكس عقارب الساعة، مع إبقاء مركز السهم في الموضع نفسه والحفاظ على حجمه.

ويتم ذلك باستخدام تحوُّل أساسي للدوران في إطار مرجعي للعنصر. للتوضيح، يتم عرض التحويل والتناوب في الإطار المرجعي من خلال ثلاث طلبات منفصلة لطريقة UpdatePageElementTransformRequest، ولكن من الأفضل احتساب ناتج ملفّات تحويل هذه مسبقًا ثم تطبيق هذا الناتج كطلب واحد.

بالنسبة إلى عمليات التحويل الترجمة، يتم نقل مركز شكل السهم من نقطة الأصل وإليها. يتم التعبير عن قيم المَعلمات كعمليات حسابية للوضوح.

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

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

{
  "requests": [
    {
      "updatePageElementTransform": {
          "objectId": PAGE_ELEMENT_ID,
          "applyMode": "RELATIVE",
          "transform": {
              "scaleX":  1,
              "scaleY":  1,
              "translateX": -2000000 - 0.5 * 0.3  * 3000000,
              "translateY":  -550000 - 0.5 * 0.12 * 3000000,
              "unit": "EMU"
          }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": PAGE_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
            "scaleX":  cos(35 * (pi/180)),
            "scaleY":  cos(35 * (pi/180)),
            "shearX":  sin(35 * (pi/180)),
            "shearY": -sin(35 * (pi/180)),
            "unit": "EMU"
        }
      }
    },
    {
      "updatePageElementTransform": {
        "objectId": PAGE_ELEMENT_ID,
        "applyMode": "RELATIVE",
        "transform": {
            "scaleX":  1,
            "scaleY":  1,
            "translateX":  2000000 + 0.5 * 0.3  * 3000000,
            "translateY":   550000 + 0.5 * 0.12 * 3000000,
            "unit": "EMU"
        }
      }
    }
  ]
}