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

تتيح لك واجهة برمجة التطبيقات 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 × 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 المستخدَمة لتجنُّب تغيير حجم العنصر واتجاهه.

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

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

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"
        }
      }
    }
  ]
}