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

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

بعد تنفيذ الطلبين، تستقر الزاوية العلوية اليسرى للسهم عند إحداثيات (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"
        }
      }
    }
  ]
}