تعديل النص وتنسيقه

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

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

استخدام نطاقات النص

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

فهرس البداية لنطاق النص مشمول، وفهرس النهاية غير مشمول. كلا الفهرسين يبدأان من الصفر.

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

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

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

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);
}

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

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

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

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

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

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

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

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

ضبط نمط النص

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

توفّر الدالة 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