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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

على سبيل المثال، ألقِ نظرة على محتوى هذه الشريحة الذي يتضمّن كل العناصر في مربع ملف شخصي واحد:

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

على وجه التحديد، يتم تمثيل تسلسل النصوص هذا في Slides API على النحو التالي:

"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

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

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

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

إدراج نص

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

تؤدي عملية إدراج النص إلى بعض الآثار الجانبية التي تعكس سلوك محرِّر Slides:

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

حذف النص

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

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

تعديل نمط النص

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• تحدِّد سمات عناصر النص في ParagraphMaker تنسيق الفقرة.
• تحدِّد خصائص عناصر النص 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": {},
        ...
      }
    }
  ]
}

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

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

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

• النص: "This is my first paragraph" هو النص الذي يتم عرضه. ولا يتم أبدًا توارُث النص نفسه.
• المحاذاة: يتم عرض النص باستخدام محاذاة START، ويتم اكتسابها منParagraphMarker الأول ل العنصر الرئيسي.
• لون المقدّمة: يتم عرض النص بلون المقدّمة DARK1، المكتسَب من TextRun الأول للعنصر الرئيسي.

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

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

• النص: "هذه الفقرة مضمّنة في قائمة" هو النص الذي يتم عرضه. ولا يتم أبدًا توارُث النص نفسه.
• المحاذاة: يتم عرض النص باستخدام محاذاة "END"، والتي تم اكتسابها من ParagraphMarker الثاني للعنصر родительский.
• لون المقدّمة: يتم عرض النص بلون LIGHT1 المقدّمة للنص، المكتسَب من TextRun الثاني للعنصر الرئيسي.

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

ستكتسب أنماط النصوص التي لم يتم ضبطها في شكل فرعي قيمًا من الشكل الرئيسي. ستُلغي أنماط النصوص التي تم ضبطها في العنصر الفرعي قيم العنصر الرئيسي في بعض النطاقات المحلية.

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

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

مثال

راجِع التعريفات الواردة في المثال السابق لملفّي ChildPlaceholder وParentPlaceholder.

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

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

يحاول هذا الطلب ضبط 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"} }, },
        ...
      }
    }
  ]
}

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

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

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

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