ویرایش و استایل‌دهی به متن

متن را با استفاده از محدوده‌های متن که توسط نوع TextRange نمایش داده می‌شوند، ویرایش و سبک‌دهی کنید. یک TextRange بخشی از متن را درون یک شکل یا درون یک سلول جدول نشان می‌دهد. فراخوانی getText روی یک شکل یا سلول جدول، محدوده متنی را برمی‌گرداند که کل متن را پوشش می‌دهد.

اگر از روش‌هایی استفاده کنید که نحوه‌ی قرارگیری متن در یک شکل را ویرایش می‌کنند، هرگونه تنظیمات autofit اعمال شده روی شکل غیرفعال می‌شود.

استفاده از محدوده‌های متنی

یک محدوده متنی دارای دو شاخص است که بخش متن تحت پوشش یک محدوده متنی را مشخص می‌کند: شاخص شروع و شاخص پایان . این شاخص‌ها را با استفاده از توابع getStartIndex و getEndIndex تعیین کنید.

اندیس شروع یک محدوده متنی، شامل (inclusive) و اندیس پایان آن، منحصر (exclusive) است. هر دو اندیس بر اساس صفر هستند.

برای خواندن محتویات یک محدوده متنی، از توابع asString یا asRenderedString استفاده کنید.

برای بازیابی یک زیرمحدوده از درون یک محدوده متنی، از تابع getRange استفاده کنید.

اسکریپت زیر یک کادر متنی در اسلاید اول ایجاد می‌کند و محتوای متنی آن را روی «سلام دنیا!» تنظیم می‌کند. سپس یک زیرمحدوده را بازیابی می‌کند که فقط شامل «سلام» می‌شود.

اسلایدها/سبک/سبک.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 متن را از داخل یک محدوده متنی حذف می‌کند.

اسکریپت زیر نحوه‌ی استفاده از این توابع را نشان می‌دهد:

اسلایدها/سبک/سبک.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!" تنظیم می‌کند. سپس کاراکترهای ۶ تا ۱۱ ("world") را حذف می‌کند و به جای آن متن "galaxy" را در اندیس ۶ وارد می‌کند. این مثال عبارت log زیر را تولید می‌کند:

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

جستجو و جایگزینی

از تابع replaceAllText در ارائه یا صفحه برای انجام یک جستجو و جایگزینی سراسری در کل ارائه یا یک صفحه خاص استفاده کنید.

تابع find در TextRange نمونه‌هایی از یک رشته را در محدوده برمی‌گرداند. می‌توان از آن به همراه setText برای انجام جستجو و جایگزینی در یک سلول شکل یا جدول استفاده کرد.

پاراگراف‌ها، آیتم‌های لیست و اجراها

TextRange توابعی را برای برگرداندن مجموعه‌های مفید از موجودیت‌های متنی ارائه می‌دهد. برخی از این توابع عبارتند از:

  • تابع getParagraphs, تمام پاراگراف‌هایی را که با محدوده متن همپوشانی دارند، ارائه می‌دهد. یک پاراگراف، دنباله‌ای از متن است که با کاراکتر خط جدید "\n" خاتمه می‌یابد.
  • getListParagraphs, که آیتم‌های لیست را در محدوده متن فعلی برمی‌گرداند.
  • getRuns, که اجراهای متنی را که با محدوده متن فعلی همپوشانی دارند، ارائه می‌دهد. اجرا متن بخشی از متن است که در آن همه کاراکترها سبک متن یکسانی دارند.

استایل‌دهی متن

سبک متن، نحوه‌ی نمایش کاراکترهای متن در ارائه شما، از جمله فونت، رنگ و لینک‌دهی را تعیین می‌کند.

تابع getTextStyle از یک محدوده متن، یک شیء TextStyle ارائه می‌دهد که برای استایل‌دهی به متن استفاده می‌شود. شیء TextStyle همان متنی را پوشش می‌دهد که والد آن TextRange است.

اسلایدها/سبک/سبک.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 لینک شده و رنگ آن قرمز شده است.

هنگام خواندن استایل‌ها، اگر محدوده چندین مقدار برای استایل داشته باشد، تابع مقدار null را برمی‌گرداند. بنابراین این نمونه، دستورات لاگ زیر را تولید می‌کند:

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

سبک‌های بسیار دیگری نیز وجود دارند که می‌توانند به متن اعمال شوند. جزئیات بیشتر را می‌توانید در مستندات مرجع TextStyle بیابید.

استایل‌دهی پاراگراف

سبک‌های پاراگراف به کل پاراگراف‌ها اعمال می‌شوند و شامل مواردی مانند ترازبندی متن و فاصله‌گذاری خطوط می‌شوند. تابع getParagraphStyle در TextRange یک شیء ParagraphStyle برای سبک‌دهی به تمام پاراگراف‌هایی که با محدوده متن والد همپوشانی دارند، ارائه می‌دهد.

مثال زیر یک کادر متنی در اسلاید اول با چهار پاراگراف ایجاد می‌کند، سپس سه پاراگراف اول را وسط‌چین می‌کند.

اسلایدها/سبک/سبک.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 می‌توان برای استایل‌دهی به تمام پاراگراف‌هایی که با محدوده متن والد همپوشانی دارند، استفاده کرد.

اسلایدها/سبک/سبک.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