بنية النص وتصميمه

في واجهة برمجة تطبيقات العروض التقديمية، يمكن تضمين النص في أشكال أو في خلايا الجدول. قبل أن تتمكن من معالجة النص وتحديد نمطه، يجب أن تفهم هيكله وكيف يعمل التصميم.

تصف هذه الصفحة كيفية تمثيل النص في واجهة برمجة تطبيقات العروض التقديمية.

تسلسلات العناصر النصية

يتكون النص المضمَّن في شكل أو خلية جدول من سلسلة من بُنى TextElement. يمثل هذا التسلسل بنية النص بالترتيب الذي يظهر به من البداية إلى النهاية.

على سبيل المثال، ضع في اعتبارك محتويات هذه الشريحة - جميعها مضمنة في مربع نص واحد:

لقطة شاشة لشريحة بسيطة

تحتوي الشريحة أعلاه على مربّع نص واحد يحتوي حقله text على تسلسل من العناصر النصية كما هو موضَّح في الرسم البياني التالي:

رسم تخطيطي يوضح تسلسل عناصر النص

بعبارة أخرى، يتم تمثيل تسلسل النصوص هذا في واجهة برمجة تطبيقات العروض التقديمية على النحو التالي:

"textElements": [ {
    "endIndex": 224,
    "paragraphMarker": { "style": {} }
  }, {
    "endIndex": 130,
    "textRun": { "content": "Li lingues differe in li grammatica e li vocabules. Omnicos directe al desirabilite de un nov ", "style": {} }
  }, {
    "endIndex": 143,
    "startIndex": 130,
    "textRun": { "content": "lingua franca", "style": { "italic": True } }
  }, {
    "endIndex": 224,
    "startIndex": 143,
    "textRun": { "content": ": solmen va esser necessi far:\n", "style": {} }
  }, {
    "endIndex": 243,
    "startIndex": 224,
    "paragraphMarker": {
      "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
      "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
  }, {
    "endIndex": 243,
    "startIndex": 224,
    "textRun": { "content": "uniform grammatica\n", "style": {} }
  }, {
    "endIndex": 257,
    "startIndex": 243,
    "paragraphMarker": {
        "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "direction": "LEFT_TO_RIGHT", "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
        "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
}, {
    "endIndex": 257,
    "startIndex": 243,
    "textRun": { "content": "Pronunciation\n", "style": {} }
}, {
    "endIndex": 277,
    "startIndex": 257,
    "paragraphMarker": {
        "style": { "indentStart": { "magnitude": 36, "unit": "PT" }, "indentFirstLine": { "magnitude": 18, "unit": "PT" }, "spacingMode": "COLLAPSE_LISTS" },
        "bullet": { "listId": "foo123", "glyph": "\u25cf" }
    }
}, {
    "endIndex": 277,
    "startIndex": 257,
    "textRun": { "content": "plu sommun paroles.\n", "style": {} }
}, {
    "endIndex": 500,
    "startIndex": 277,
    "paragraphMarker": { "style": {} }
}, {
    "endIndex": 500,
    "startIndex": 277,
    "textRun": { "content": "Ka swu thefognay, tay waddeant varpa u inzo.\n", "style": {} }
}]

محتوى العناصر النصية

يحتوي كل عنصر نصي على فهرس بدء وفهرس نهاية مستندين إلى صفر، ويصفان موقع العنصر داخل النص الكامل لعنصر الصفحة، بالإضافة إلى أحد أنواع الكائنات النصية التالية:

نوع النص الوصف
ParagraphMarker يمثل هذا العنصر النصي بداية فقرة جديدة. يمثل فهرس البداية والنهاية للعنصر النصي النطاق الكامل للفقرة، بما في ذلك حرف السطر الجديد الذي ينهي الفقرة. لا تتداخل الفقرة أبدًا مع فقرة أخرى. تنتهي الفقرات دائمًا بحرف سطر جديد، لذلك يكون هناك دائمًا سطر جديد في نهاية محتوى النص لخلية جدول أو شكل.

يمكن أن تنتمي الفقرات إلى قوائم نقطية أو مرقّمة. وفي هذه الحالة، سيتضمّن محتوى الحقل ParagraphMarker.bullet رقم تعريف قائمة. يشير رقم التعريف هذا إلى عنصر قائمة موجود داخل TextContent بجانب تسلسل TextElement. وستشير الفقرات داخل نفس القائمة المنطقية إلى نفس معرّف القائمة.
TextRun يمثل هذا العنصر النصي سلسلة نصية متجاورة تحمل جميعها نفس نمط النص. لا تتجاوز عمليات تنفيذ النص حدود الفقرات: حتى إذا كان النص الذي ينتهي فقرة واحدة له نفس نمط النص الذي يبدأ في الفقرة التالية، يتم تقسيم المحتوى بعد حرف السطر الجديد لإنشاء عمليات تشغيل نصية منفصلة.

إذا احتجت إلى معالجة السلسلة النصية الكاملة داخل عنصر صفحة، كرِّر جميع العناصر النصية مع إنشاء تسلسل للسلاسل المتوفّرة في كل عمليات التشغيل النصية.
AutoText يشير النص التلقائي إلى أماكن في النص تتغير ديناميكيًا حسب السياق. في العروض التقديمية، يتم استخدام هذا لتمثيل رقم الشريحة الحالية داخل النص.

تعديل محتويات النص

عندما تريد تعديل النص باستخدام واجهة برمجة تطبيقات العروض التقديمية، لا تحتاج إلى إنشاء جميع العناصر النصية المناسبة بشكل صريح. بدلاً من ذلك، يمكنك العمل على النص كما تفعل في محرر الشرائح: عن طريق إدراج نص وحذف النطاقات وتحديث الأنماط على النطاقات. تؤدّي هذه العمليات ضمنيًا إلى إنشاء عنصرَي ParagraphMarker وTextRun حسب الحاجة لتعكس التغييرات التي أجريتها.

جارٍ إدراج نص

يمكنك إدراج نص في فهرس باستخدام الطلب InsertTextRequest في استدعاء batchUpdate. يحدّد حقل insertionIndex الخاص بهذه الطريقة مكان إدراج النص، ويمكنك حساب هذا الفهرس باستخدام حقلَي فهرس البداية والنهاية داخل العناصر النصية.

تنطوي ميزة إدراج النص على بعض الآثار الجانبية التي تعكس سلوك أداة تعديل "العروض التقديمية من Google":

  • يؤدي إدراج حرف سطر جديد إلى إنشاء فقرة جديدة ضمنيًا، ما يؤدي إلى إنشاء عنصر نصي ParagraphMarker يبدأ بفهرس السطر الجديد وينتهي عند السطر الجديد التالي. يتم نسخ نمط الفقرة - بما في ذلك تفاصيل القائمة النقطية والقائمة - من الفقرة الحالية إلى الفقرة الجديدة.
  • ويتم تحديد نمط الأحرف المدرجة تلقائيًا، مع إبقاء نمط النص نفسه الموجود في فهرس الإدراج بشكل عام. ونتيجة لذلك، يتم إدراج النص بشكل عام في TextRun الحالي في هذا الفهرس. يمكنك تعديل هذا النمط لاحقًا باستخدام طلب UpdateTextStyle.

جارٍ حذف النص

يمكنك حذف نطاق زمني محدّد من النص باستخدام الرسالة DeleteTextRequest في استدعاء batchUpdate. ينطوي حذف النص على بعض التفاصيل الدقيقة:

  • يؤدي الحذف الذي يتخطى حدود الفقرة إلى دمج الفقرتين، ما يؤدي إلى حذف العنصر النصي ParagraphMarker الذي يفصل.
  • ستستخدم الفقرة المدمجة الجديدة نمط فقرة مدمجًا، مع مطابقة السلوك في محرر العروض التقديمية.
  • يؤدي الحذف الذي يشمل نطاقه تشغيلًا نصيًا إلى إزالة كل المحتوى من إطار نصي، كما يحذف أيضًا الجزء النصي نفسه.
  • في حال حذف مجموعة يضم نطاقها عنصر AutoText، يتم حذف العنصر AutoText.

جارٍ تعديل نمط النص

يتم تحديد المظهر المعروض للنص في الشريحة من خلال خصائص نمط النص:

  • يتم تحديد أنماط الفقرة، مثل المسافة البادئة والمحاذاة والرموز الرسومية النقطية، من خلال الخصائص في علامات الفقرات.
  • يتم تحديد أنماط الأحرف، مثل الغامق والمائل والتسطير، من خلال خصائص على عمليات التشغيل الفردية للنصوص.

جارٍ تعديل نمط الأحرف

يمكنك تعديل أنماط الأحرف باستخدام الرسالة UpdateTextStyleRequest في استدعاء batchUpdate.

مثل العمليات النصية الأخرى، يتم تطبيق نمط الأحرف على نطاق من النص وينشئ ضمنيًا كائنات TextRun جديدة حسب الحاجة.

يؤدي تعيين بعض أنماط الأحرف ضمنيًا إلى تحديث الأنماط الأخرى ذات الصلة لمطابقة السلوك في محرر العروض التقديمية. على سبيل المثال، تؤدي إضافة رابط إلى تغيير لون مقدمة النص وخصائص التسطير تلقائيًا. راجع الوثائق المرجعية TextStyle للحصول على مزيد من التفاصيل.

تحديث نمط الفقرة

يمكنك تعديل أنماط الفقرات باستخدام الرسالة UpdateParagraphStyleRequest في استدعاء batchUpdate.

تتيح واجهة برمجة تطبيقات "العروض التقديمية من Google" إمكانية CreateParagraphBulletsRequest الذي يعكس وظيفة الإعدادات المسبقة للتعداد النقطي في محرّر "العروض التقديمية من Google" لإنشاء قوائم نقطية ومرقّمة. وبالمثل، يزيل DeleteParagraphBulletsRequest أي رموز نقطية حالية على الفقرات.

الأنماط المكتسَبة

يمكن أن تكتسب بعض الأشكال، المعروفة باسم placeholders، أنماط النص من الأشكال الرئيسية الأخرى: راجِع placeholders لمعرفة المزيد حول اكتساب الأشكال بشكل عام.

يركز هذا القسم على كيفية عمل اكتساب الأنماط لإنشاء أنماط النص النهائية المعروضة في شريحة.

تمثيل الأنماط في العناصر النائبة

يصف القسم الذي يتناول placeholders طريقة عمل الوراثة بين الأشكال الرئيسية والفرعية. تتم معالجة اكتساب أنماط النص من خلال ميزات إضافية ضمن نموذج الوراثة:

  • تحدد خصائص عناصر النص ParagraphMaker تنسيق الفقرة.
  • وتحدد خصائص عناصر النص TextRun تنسيق الأحرف.
  • يحتوي محتوى العناصر النائبة الرئيسية على ثمانية أزواج ParagraphMarker/TextRun (لدعم ثمانية مستويات من تداخل القائمة).
  • يكتسب العنصر النائب الفرعي خصائصه النصية التلقائية من العناصر النصية هذه في المحتوى النصي للعنصر الرئيسي.

يوضح الرسم التخطيطي التالي طريقة واحدة لتصور هذه العلاقات:

رسم بياني لشكل فرعي يكتسب خصائص النص

يحدد أول ParagraphMarker/TextRun في الشكل الأصلي معظم نمط النص الموروثة؛ ويؤثر النمط في الأزواج السبعة المتبقية فقط على الفقرات التي توجد في مستويات الرموز النقطية المتداخلة بشكل تدريجي:

زوج عنصر نصي رئيسي التنسيق الفرعي الذي يتحكم فيه
أوّل ParagraphMarker
أول TextRun		 النمط النصي لفقرات القائمة من المستوى 0 (الخارجي) وجميع الفقرات التي ليست ضمن القائمة.
الثانية ParagraphMarker
ثانية TextRun		 النمط النصي للمستويات المتبقية من القائمة (المدمجة) من 1 إلى 7
ثالث ParagraphMarker
ثالث TextRun
الشوط الرابع، ParagraphMarker
الرابع TextRun
خامس ParagraphMarker
TextRun خامس
السادس ParagraphMarker
السادس TextRun
السابع ParagraphMarker
السابع TextRun
ثامن ParagraphMarker
ثامن TextRun

للوصول إلى هذَين الزوجَين من العناصر النصية، استخدِم فهرسهما الواضح في الحقل textElements كما هو موضّح في المقتطف أدناه، والذي يعرض إعداد النمط التلقائي (القابل للاكتساب) للمستوى 0 والفقرات التي لا تتضمّن قائمة:

"text": {
  "textElements": [  {
     "startIndex": 0,
     "endIndex": 1,
     "paragraphMarker": {
       "style": {  "alignment": "START",  ...  },
       "bullet": {  "nestingLevel": 0,  ...  }
     }
   },{
     "startIndex": 0,
     "endIndex": 1,
     "textRun": {
       "content": "\n",
       "style": {  "foregroundColor": {  "opaqueColor": {  "themeColor": "DARK1"  }  },  }
     }
   },{
     ...
   } ]
 }

تجدر الإشارة إلى أنّ الحقل content في شكل TextRun للشكل الأصلي يتكوّن دائمًا من حرف سطر جديد.

يمكن تجاهل الأنماط المكتسَبة.

يمكن لشكل فرعي تحديد خصائص النمط على عنصري ParagraphMarker وTextRun في المحتوى. ستتجاهل هذه الخصائص المحددة محليًا أي خصائص مكتسبة ضمن نطاقها المحلي. العناصر التي لا تحدد أي نمط ستستخدم النمط المقابل الموروث من الأصل.

وتؤدي إزالة خاصية نمط صريحة من شكل فرعي، حتى لا يتم تعيينها، إلى اكتسابها من الشكل الرئيسي.

مثال

بناءً على الاكتساب الموضح في الرسم التخطيطي أعلاه، افترض أن الشكل ParentPlaceholder يحتوي على المحتوى النصي التالي:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {"alignment": "START", ...},
        "bullet": {"nestingLevel": 0, ...}
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, }
        ...
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {"alignment": "END", ...},
        "bullet": {"nestingLevel": 1, ...}
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "LIGHT1"} }, ...}
      }
    },
   ...
  ]
}

ونفترض أن الشكل ChildPlaceholder يحتوي على المحتوى النصي التالي:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {},
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "This is my first paragraph\n",
        "style": {},
      }
      ...
    },
    {  "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {},
        "bullet": {
          "nestingLevel": 1,
          "listId": "someListId",
          "glyph": "●"
        }
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "This paragraph is in a list\n",
        "style": {},
        ...
      }
    }
  ]
}

ويؤدي هذا إلى النتائج الموضحة في الفقرات التالية.

اكتساب النمط للفقرة العادية

الفقرة الأولى في الشكل الفرعي، والتي تتضمن النص "هذه هي فقرتي الأولى"، هي فقرة عادية (وليس في قائمة). لا تحدد أي عناصر في المحتوى النصي أي خصائص للنمط، لذلك يكتسب جميع أنماط الأحرف والفقرات من الأصل. يؤدّي ذلك إلى العرض التالي:

  • النص: "هذه هي فقرتي الأولى" هي النص المعروض. لا يكتسب النص نفسه أبدًا.
  • المحاذاة: يتم عرض النص بمحاذاة START موروثة من أول ParagraphMarker للآباء.
  • لون المقدمة: يتم عرض النص بلون المقدّمة DARK1، والذي تم اكتسابه من لون العنصر الرئيسي TextRun الأول.

اكتساب النمط لفقرة قائمة

الفقرة التالية التي تتضمّن النص "هذه الفقرة في قائمة"، هي في قائمة نقطية على المستوى 1 للتداخل، كونها ParagraphMarker المقابلة لها تم ضبط الحقل bullet الخاص بها على هذا المستوى. ونتيجة لذلك، فإنها تكتسب النص ونمط الفقرة من مستوى التداخل 1 في الأصل. ينتج عن ذلك العرض التالي:

  • النص: "هذه الفقرة في قائمة" هو النص المعروض. لا يكتسب النص نفسه أبدًا.
  • المحاذاة: يتم عرض النص مع محاذاة "END"، وهو موروث من ParagraphMarker الثاني للوالدين.
  • لون المقدمة: يتم عرض النص مع لون المقدمة للنص LIGHT1، ويتم اكتسابه من لون الواجهة TextRun الخاص بأحد الوالدَين.

التفاعلات بين تحديث واكتساب أنماط النص والفقرات

إن الأنماط النصية التي لم يتم تعيينها في شكل فرعي ستكتسب القيم من نمطها الرئيسي. سوف "تتجاوز" أنماط النص التي يتم تعيينها في العنصر الفرعي القيم الرئيسية في بعض النطاق المحلي.

يمكنك استخدام UpdateTextStyleRequest لإلغاء ضبط نمط نص الشكل الفرعي، بحيث لا يكون له تجاوز محلي وبالتالي اكتساب أحرفه من الشكل الرئيسي. بالإضافة إلى ذلك، يؤدي تعديل نمط النص التابع للنمط الفرعي لمطابقة القيمة المكتسَبة من العنصر الرئيسي إلى إلغاء ضبط النمط ضمنيًا بحيث يستخدم القيمة المكتسبة.

لا يؤثر هذا في المظهر المرئي للنص مباشرةً بعد التحديث، ولكن قد يكون مهمًا إذا عدّلت لاحقًا نمط فقرة أو نص في عنصر نائب أصلي. يتطابق سلوك التوريث هذا مع سلوك أداة تعديل الشرائح، لذا يمكنك تجربة نتائج تغييرات النمط قبل التعامل مع واجهة برمجة التطبيقات.

مثال

ضع في الاعتبار التعريفات الواردة في المثال السابق لكل من ChildPlaceholder وParentPlaceholder.

لنفترض الآن أنّك أرسلت UpdateTextStyleRequest هذا:

{ "updateTextStyle": {
    "objectId": "ChildPlaceholder",
    "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
    "textRange": { "type": "ALL" },
    "fields": "foregroundColor"
  }
}

يحاول هذا الطلب ضبط لون المقدمة DARK1 على كل النص الخاص بـ ChildPlacePlace باستخدام قناع حقل لتحديد أنّه يجب تغيير لون المقدمة فقط. يؤدي هذا الطلب إلى النتائج التالية:

  • الفقرة الأولى: يتطابق foregroundColor الجديد مع foregroundColor الموروثة، لذا لم يتغير هذا النمط وما زال يتم اكتسابه.
  • الفقرة الثانية: لا تتطابق السمة foregroundColor الجديدة مع السمة foregroundColor الموروثة، لذا يتم تعديل لون مقدمة الفقرة الثانية إلى DARK1.

المحتوى النصي لـ ChildPlacePlace متوفر الآن كما يلي:

"text": {
  "textElements": [
    { "startIndex": 0,  "endIndex": 1,
      "paragraphMarker": {
        "style": {},
      }
    },
    { "startIndex": 0,  "endIndex": 1,
      "textRun": {
        "content": "This is my first paragraph\n",
        "style": {},
      }
      ...
    },
    { "startIndex": 1,  "endIndex": 2,
      "paragraphMarker": {
        "style": {},
        "bullet": {"nestingLevel": 1, "listId": "someListId", "glyph": "●" }
      }
    },
    { "startIndex": 1,  "endIndex": 2,
      "textRun": {
        "content": "This paragraph is in a list\n",
        "style": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
        ...
      }
    }
  ]
}

نمط نص حرف رسومي نقطي

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

تتبع أنماط النص الرسومي النقطية تسلسلاً هرميًا مختلفًا قليلاً للتوريث عن أنماط النص العادي.

  1. يكتسِب الرمز النقطي عند مستوى دمج معيّن أولًا من مجموعة TextStyle التي يتم ضبطها في الحقل NestingLevel.bullet_style داخل كائن List للرمز النقطي.
  2. بعد ذلك، يكتسبه من NestingLevel.bullet_style المقابل في العنصر النائب الرئيسي List.
  3. وأخيرًا، فإنها تسعى إلى الموروث من كائنات العنصر النائب الرئيسية المتبقية.