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

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

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

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

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

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

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

{
  "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 نقطة. يتطلب فرض محاذاة خط الوسط للدائرة الجديدة مراعاة ارتفاع كل من السهم والدائرة. والإحداثي ص للدائرة هو الإحداثي ص للسهم زائد نصف ارتفاع السهم مطروحًا منه نصف ارتفاع الدائرة. في كلتا الحالتين، يجب أيضًا أن تأخذ عوامل التحجيم المرتبطة بالسهم في الاعتبار، لأنها تؤثر على العرض والارتفاع المعروضين للسهم. وبالتالي تكون إحداثيات الدائرة كما يلي:

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 إلى اليمين و35,000 وحدة تحويل مترية إلى الأعلى، حيث يتم تحويل الاتجاه النسبي applyMode {يتم تحويله إلى العنصر applyMode باتجاه أعلى).

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