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

يمكنك تعديل النص وتصميمه باستخدام النطاقات النصية التي يمثلها النوع TextRange. تمثل TextRange مقطعًا من النص داخل شكل أو داخل خلية جدول. يؤدي استدعاء getText() على خلية شكل أو جدول إلى عرض نطاق نصي يغطي النص بأكمله.

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

استخدام نطاقات نصية

يشتمل النطاق النصي على فهرسَين يحدّدان مقطع النص الذي يغطيه نطاق نصي: فهرس البدء وفهرس النهاية. يمكنك تحديد هذه الفهارس باستخدام الدالتَين getStartIndex() وgetEndIndex().

لقراءة محتوى نطاق نصي، استخدِم الدالتَين asString() أو asRenderedString().

لاسترداد نطاق فرعي من داخل نطاق نصي، استخدم الدالة getRange().

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

slides/style/style.gs
try {
  // Get the first slide of active presentation
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  // Insert shape in the slide with dimensions
  const shape = slide.insertShape(SlidesApp.ShapeType.TEXT_BOX, 100, 200, 300, 60);
  const textRange = shape.getText();
  // Set text in TEXT_BOX
  textRange.setText('Hello world!');
  console.log('Start: ' + textRange.getStartIndex() + '; End: ' +
    textRange.getEndIndex() + '; Content: ' + textRange.asString());
  const subRange = textRange.getRange(0, 5);
  console.log('Sub-range Start: ' + subRange.getStartIndex() + '; Sub-range End: ' +
    subRange.getEndIndex() + '; Sub-range Content: ' + subRange.asString());
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with an error %s ', err.message);
}

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

Start: 0; End: 13; Content: Hello world!
Start: 0; End: 5; Content: Hello

إدراج نص وحذفه

يمكنك أيضًا إدراج أشكال النص وخلايا الجدول وحذفها باستخدام نطاقات النص.

  • يتيح لك كل من insertText() وappendText() إدراج نص.
  • يستبدل setText() نص نطاق نصي بالنص المتوفر.
  • تحذف clear() النص من داخل نطاق نصي.

يوضح النص البرمجي التالي استخدام هذه الدوال:

slides/style/style.gs
try {
  // Get the first slide of active presentation
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  // Insert shape in the slide with dimensions
  const shape = slide.insertShape(SlidesApp.ShapeType.TEXT_BOX, 100, 200, 300, 60);
  const textRange = shape.getText();
  textRange.setText('Hello world!');
  textRange.clear(6, 11);
  // Insert text in TEXT_BOX
  textRange.insertText(6, 'galaxy');
  console.log('Start: ' + textRange.getStartIndex() + '; End: ' +
    textRange.getEndIndex() + '; Content: ' + textRange.asString());
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with an error %s ', err.message);
}

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

Start: 0; End: 14; Content: Hello galaxy!

البحث والاستبدال

استخدِم الدالة replaceAllText() في عرض تقديمي أو صفحة لإجراء بحث واستبدال شامل في العرض التقديمي بأكمله أو في صفحة معيّنة.

تعرض الدالة find() في TextRange مثيلات السلسلة ضمن النطاق. يمكن استخدامها مع setText() لإجراء البحث والاستبدال داخل شكل أو خلية جدول.

الفقرات وعناصر القوائم وعمليات التنفيذ

توفر TextRange دوال لعرض مجموعات مفيدة من الكيانات النصية. وتشمل بعض هذه الدوال ما يلي:

  • getParagraphs(), الذي يوفر جميع الفقرات التي تتداخل مع نطاق النص. الفقرة هي تسلسل من النص ينتهي بحرف السطر الجديد "\n".
  • getListParagraphs(), الذي يعرض عناصر القائمة في النطاق النصي الحالي.
  • getRuns(), التي توفِّر عمليات تنفيذ النص التي تتداخل مع نطاق النص الحالي. text run هو جزء من نص يكون فيه جميع الأحرف نفس نمط النص.

نمط النص

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

توفر الدالة getTextStyle() لنطاق النص كائن TextStyle المستخدم لتصميم النص. يغطي الكائن TextStyle النص نفسه الذي يغطيه العنصر الرئيسي TextRange.

slides/style/style.gs
try {
  // Get the first slide of active presentation
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  // Insert shape in the slide with dimensions
  const shape = slide.insertShape(SlidesApp.ShapeType.TEXT_BOX, 100, 200, 300, 60);
  const textRange = shape.getText();
  // Set text in TEXT_BOX
  textRange.setText('Hello ');
  // Append text in TEXT_BOX
  const insertedText = textRange.appendText('world!');
  // Style the text with url,bold
  insertedText.getTextStyle()
      .setBold(true)
      .setLinkUrl('www.example.com')
      .setForegroundColor('#ff0000');
  const helloRange = textRange.getRange(0, 5);
  console.log('Text: ' + helloRange.asString() + '; Bold: ' + helloRange.getTextStyle().isBold());
  console.log('Text: ' + insertedText.asString() + '; Bold: ' +
    insertedText.getTextStyle().isBold());
  console.log('Text: ' + textRange.asString() + '; Bold: ' + textRange.getTextStyle().isBold());
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with an error %s ', err.message);
}

يقوم المثال أعلاه أولاً بإنشاء مربع نص في الشريحة الأولى وتعيين محتواه على "Hello ". ثم يلحق النص "world!". يكون النص الذي تم إلحاقه مؤخرًا بخط غامق ومرتبطًا بـ www.example.com، ويتم ضبط لونه على اللون الأحمر.

عند قراءة الأنماط، تعرض الدالة قيمة فارغة إذا كان النطاق يحتوي على قيم متعددة للنمط. إذًا، يُنتج النموذج أعلاه بيانات السجل التالية:

Text: Hello; Bold: false
Text: world!; Bold: true
Text: Hello world!; Bold: null

هناك العديد من الأنماط الأخرى التي يمكن تطبيقها على النص. يمكن العثور على مزيد من التفاصيل في المستندات المرجعية الخاصة بـ TextStyle.

نمط الفقرة

تنطبق أنماط الفقرات على فقرات كاملة، وتشمل أشياء مثل محاذاة النص والمسافات بين الأسطر. توفّر دالة getParagraphStyle() في TextRange كائن ParagraphStyle لنمط جميع الفقرات التي تتداخل مع نطاق النص الرئيسي.

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

slides/style/style.gs
try {
  // Get the first slide of active presentation
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  // Insert shape in the slide with dimensions
  const shape = slide.insertShape(SlidesApp.ShapeType.TEXT_BOX, 50, 50, 300, 300);
  const textRange = shape.getText();
  // Set the text in the shape/TEXT_BOX
  textRange.setText('Paragraph 1\nParagraph2\nParagraph 3\nParagraph 4');
  const paragraphs = textRange.getParagraphs();
  // Style the paragraph alignment center.
  for (let i = 0; i <= 3; i++) {
    const paragraphStyle = paragraphs[i].getRange().getParagraphStyle();
    paragraphStyle.setParagraphAlignment(SlidesApp.ParagraphAlignment.CENTER);
  }
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with an error %s ', err.message);
}

تصميم القائمة

على غرار ParagraphStyle، يمكن استخدام ListStyle لتنسيق جميع الفقرات التي تتداخل مع نطاق النص الرئيسي.

slides/style/style.gs
try {
  // Get the first slide of active presentation
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  // Insert shape in the slide with dimensions
  const shape = slide.insertShape(SlidesApp.ShapeType.TEXT_BOX, 50, 50, 300, 300);
  // Add and style the list
  const textRange = shape.getText();
  textRange.appendText('Item 1\n')
      .appendText('\tItem 2\n')
      .appendText('\t\tItem 3\n')
      .appendText('Item 4');
  // Preset patterns of glyphs for lists in text.
  textRange.getListStyle().applyListPreset(SlidesApp.ListPreset.DIGIT_ALPHA_ROMAN);
  const paragraphs = textRange.getParagraphs();
  for (let i = 0; i < paragraphs.length; i++) {
    const listStyle = paragraphs[i].getRange().getListStyle();
    console.log('Paragraph ' + (i + 1) + '\'s nesting level: ' + listStyle.getNestingLevel());
  }
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with an error %s ', err.message);
}

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

Paragraph 1's nesting level: 0
Paragraph 2's nesting level: 1
Paragraph 3's nesting level: 2
Paragraph 4's nesting level: 0