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

تتيح لك 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 للدائرة هو مجموع الإحداثي السيني للسهم وعرض السهم و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"
        }
      }
    }
  ]
}