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

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

توضّح هذه الصفحة طريقة تمثيل النص في Slides API.

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

يتكون النص الموجود في شكل أو خلية جدول من سلسلة من 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": {} }
}]

محتوى TextElement

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

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

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

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

إدراج نص

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

إدراج النص له بعض الآثار الجانبية التي تعكس سلوك "العروض التقديمية من Google" محرِّر:

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

جارٍ حذف النص

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

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

تحديث نمط النص

يتم تحديد مظهر النص المعروض في الشريحة حسب نمط النص. المواقع:

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

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

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

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

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

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

يمكنك تحديث أنماط الفقرات باستخدام UpdateParagraphStyleRequest. رسالة في مكالمة إلى batchUpdate.

تدعم Slides API CreateParagraphBulletsRequest تعكس وظيفة الإعدادات المسبقة للرمز النقطي في محرر الشرائح إنشاء قوائم نقطية ومرقّمة وبالمثل، فإن DeleteParagraphBulletsRequest لإزالة أي رموز نقطية حالية في الفقرات.

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

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

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

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

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

• خصائص 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": {},
        ...
      }
    }
  ]
}

لينتج عنها النتائج الموضحة في الفقرات التالية.

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

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

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

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

المحتوى النصي الخاص بـ 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": {"foregroundColor": {"opaqueColor": {"themeColor": "DARK1"} }, },
        ...
      }
    }
  ]
}

نمط النص النقطي

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

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

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