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

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

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

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

ويتم تقديم هذه الأمثلة في صورة طلبات 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) أسفل الحافة العلوية للسهم. يجب أن يكون الإحداثي السيني للمستطيل الجديد هو نفس الإحداثي السيني للسهم للحفاظ على محاذاة حده الأيسر. الإحداثي 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 تحويل التنسيق النسبي applyModeللتحويل applyModeللانتقال النسبي.

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