تحديد العناصر داخل عرض تقديمي

الجزء المحدَّد هو أي جزء محدَّد حاليًا في صفحة عرض تقديمي مفتوحة، مثل نطاق نص مميّز أو جدول. يوضّح لك هذا الدليل كيفية الحصول على الاختيار وضبطه في عرض تقديمي نشط باستخدام Apps Script.

لا يمكن للنص البرمجي الوصول إلا إلى اختيار المستخدم الذي يشغّل النص البرمجي.

الاختيار هو لقطة شاشة لما كان عليه النص البرمجي عند بدء تشغيله. إذا نقر المستخدم وتغيّر الاختيار أثناء تشغيل النص البرمجي، لن تظهر هذه التغييرات.

الاختيارات ونوع الاختيار

يمكنك قراءة الاختيار باستخدام فئة Selection. تحتوي الفئة على طُرق مختلفة للحصول على الكائنات المحدّدة استنادًا إلى نوع الكائنات المحدّدة.

يمثّل العنصر النائب SelectionType النوع المحدّد للعناصر المحدّدة. على سبيل المثال، إذا حدد المستخدم بعض النصوص في شكل، سيكون نوع التحديد TEXT. في هذه الحالة، يمكنك استرداد النطاق المحدّد من النص باستخدام الطريقة selection.getTextRange().

يمكنك أيضًا استرداد العنصر الذي يحتوي على التحديد. على سبيل المثال، يمكنك مواصلة المثال أعلاه واسترداد الشكل الذي يحتوي على النص المحدّد باستخدام selection.getPageElementRange().getPageElements()[0]. وبالمثل، الصفحة التي تحتوي على الشكل المحيط هي الصفحة النشطة الحالية. ل retrieving that page, use selection.getCurrentPage().

قراءة النص المحدَّد

لقراءة الاختيار، استخدِم الأسلوب Presentation.getSelection() كما هو موضّح في المثال التالي:

slides/selection/selection.gs

العرض على GitHub

const selection = SlidesApp.getActivePresentation().getSelection();

قراءة الصفحة الحالية

لاسترداد الصفحة الحالية التي يعرضها المستخدم، استخدِم الأسلوبَين getSelection() وgetCurrentPage() على النحو التالي:

slides/selection/selection.gs

العرض على GitHub

const currentPage = SlidesApp.getActivePresentation().getSelection().getCurrentPage();

يُرجى العلم أنّ الصفحة الحالية قد تكون من أيّ من الأنواع التالية:

• العرض التقديمي
• الرئيسي
• التصميم

يمكن أن تحتوي الصفحة الحالية على عنصر واحد أو أكثر تم اختياره، ويحدِّد نوع الاختيار سمة SelectionType.

قراءة الاختيار استنادًا إلى نوع الاختيار

يوضّح المثال التالي كيفية استخدام نوع الاختيار لقراءة الاختيار الحالي بطريقة مناسبة للنوع.

slides/selection/selection.gs

عرض على GitHub

const selection = SlidesApp.getActivePresentation().getSelection();
const selectionType = selection.getSelectionType();
let currentPage;
switch (selectionType) {
  case SlidesApp.SelectionType.NONE:
    console.log('Nothing selected');
    break;
  case SlidesApp.SelectionType.CURRENT_PAGE:
    currentPage = selection.getCurrentPage();
    console.log('Selection is a page with ID: ' + currentPage.getObjectId());
    break;
  case SlidesApp.SelectionType.PAGE_ELEMENT:
    const pageElements = selection.getPageElementRange().getPageElements();
    console.log('There are ' + pageElements.length + ' page elements selected.');
    break;
  case SlidesApp.SelectionType.TEXT:
    const tableCellRange = selection.getTableCellRange();
    if (tableCellRange !== null) {
      const tableCell = tableCellRange.getTableCells()[0];
      console.log('Selected text is in a table at row ' +
        tableCell.getRowIndex() + ', column ' +
        tableCell.getColumnIndex());
    }
    const textRange = selection.getTextRange();
    if (textRange.getStartIndex() === textRange.getEndIndex()) {
      console.log('Text cursor position: ' + textRange.getStartIndex());
    } else {
      console.log('Selection is a text range from: ' + textRange.getStartIndex() + ' to: ' +
        textRange.getEndIndex() + ' is selected');
    }
    break;
  case SlidesApp.SelectionType.TABLE_CELL:
    const tableCells = selection.getTableCellRange().getTableCells();
    const table = tableCells[0].getParentTable();
    console.log('There are ' + tableCells.length + ' table cells selected.');
    break;
  case SlidesApp.SelectionType.PAGE:
    const pages = selection.getPageRange().getPages();
    console.log('There are ' + pages.length + ' pages selected.');
    break;
  default:
    break;
}

قراءة نصوص محدّدة

يمكنك قراءة النص المحدّد باستخدام الأسلوب Selection.getTextRange(). هناك نوعان من اختيار النص:

• اختيار النطاق: إذا كان الشكل يحتوي على النص "مرحبًا"، وتم تحديد "هو"، يكون للنطاق المعروض startIndex=0 وendIndex=2.
• اختيار المؤشر: إذا كان الشكل يحتوي على النص "مرحبًا"، وكان المؤشر بعد "ح" ("ح|مرحبًا")، يكون النطاق المعروض فارغًا مع startIndex=1 وendIndex=1.

تعديل الاختيار

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

لا تظهر تغييرات الاختيار في متصفّح المستخدم إلا بعد اكتمال تنفيذ النص البرمجي أو عند استدعاء Presentation.saveAndClose().

اختيار الصفحة الحالية

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

slides/selection/selection.gs

عرض على GitHub

// Select the first slide as the current page selection and remove any previous selection.
  const selection = SlidesApp.getActivePresentation().getSelection();
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  slide.selectAsCurrentPage();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.CURRENT_PAGE
// selection.getCurrentPage() = slide
//

اختيار عنصر صفحة

لاختيار عنصر صفحة في صفحة، استخدِم الطريقة PageElement.select(). يؤدي ذلك أيضًا إلى إلغاء اختيار أي عناصر صفحة تم اختيارها في السابق.

إنّ الطريقتَين select() وselect(true) متكافئتان.

على سبيل المثال:

slides/selection/selection.gs

عرض على GitHub

  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const pageElement = slide.getPageElements()[0];
  // Only select this page element and remove any previous selection.
  pageElement.select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = pageElement
//

اختيار عناصر صفحة متعددة

لإلحاق عناصر صفحة إضافية بالاختيار، استخدِم الأسلوب PageElement.select(false). يجب أن تكون جميع عناصر الصفحة في الصفحة الحالية.

slides/selection/selection.gs

العرض على GitHub

  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  // First select the slide page, as the current page selection.
  slide.selectAsCurrentPage();
  // Then select all the page elements in the selected slide page.
  const pageElements = slide.getPageElements();
  for (let i = 0; i < pageElements.length; i++) {
    pageElements[i].select(false);
  }
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements() = pageElements
//

تحويل المحتوى المحدّد

يمكن أن تؤدي التعديلات التي يُجريها النص البرمجي إلى تحويل الاختيار الحالي، بحيث يتغيّر ما تم اختياره نتيجةً للتعديل. على سبيل المثال:

1. لنفترض أنّ لديك شكلَين أ و ب محدّدَين.
2. بعد ذلك، يزيل النص البرمجي الشكل "أ".
3. نتيجةً لذلك، يتم تحويل التحديد إلى التعديل بحيث يتم اختيار الشكل "ب" فقط.

يوضّح المثال التالي كيفية تحويل الاختيار من خلال التلاعب بعناصر الصفحة المحدّدة.

slides/selection/selection.gs

عرض على GitHub

  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const shape1 = slide.getPageElements()[0].asShape();
  const shape2 = slide.getPageElements()[1].asShape();
  // Select both the shapes.
  shape1.select();
  shape2.select(false);
  // State of selection
  //
  // selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
  // selection.getCurrentPage() = slide
  // selection.getPageElementRange().getPageElements() = [shape1, shape2]
  //
  // Remove one shape.
  shape2.remove();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.PAGE_ELEMENT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements() = [shape1]
//

تحديد نص

يمكن اختيار النص الوارد في شكل أو في خلية جدول باستخدام الأسلوب TextRange.select(). إذا كان النص مضمّنًا في شكل، سيتم اختيار هذا الشكل أيضًا. إذا كان النص مضمّنًا في خلية جدول، يتم اختيار خلية الجدول هذه والجدول المُحيط بها.

يؤدي ذلك أيضًا إلى ضبط الصفحة الرئيسية على أنّها الصفحة الحالية.

اختيار نطاق في شكل

يوضّح المثال التالي كيفية اختيار نطاق ضمن نص مضمّن في شكل.

slides/selection/selection.gs

عرض على GitHub

  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const shape = slide.getPageElements()[0].asShape();
  shape.getText().setText('Hello');
  // Range selection: Select the text range 'He'.
  shape.getText().getRange(0, 2).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 2
//

اختيار المؤشر في شكل

يوضّح المثال التالي كيفية اختيار مؤشر داخل نص مضمّن في شكل.

slides/selection/selection.gs

العرض على GitHub

  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const shape = slide.getPageElements()[0].asShape();
  shape.getText().setText('Hello');
  // Cursor selection: Place the cursor after 'H' like 'H|ello'.
  shape.getText().getRange(1, 1).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 1
// selection.getTextRange().getEndIndex() = 1
//

اختيار نطاق في خلية جدول

يوضّح المثال التالي كيفية اختيار نطاق ضمن نص مضمّن في خلية جدول.

slides/selection/selection.gs

العرض على GitHub

  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const table = slide.getPageElements()[0].asTable();
  const tableCell = table.getCell(0, 1);
  tableCell.getText().setText('Hello');
  // Range selection: Select the text range 'He'.
  tableCell.getText().getRange(0, 2).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = table
// selection.getTableCellRange().getTableCells()[0] = tableCell
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 2
//

اختيار المؤشر في TableCell

يوضّح المثال التالي كيفية اختيار نص باستخدام المؤشر ضمن نص مضمّن في خلية جدول.

slides/selection/selection.gs

عرض على GitHub

  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const table = slide.getPageElements()[0].asTable();
  const tableCell = table.getCell(0, 1);
  tableCell.getText().setText('Hello');
  // Cursor selection: Place the cursor after 'H' like 'H|ello'.
  tableCell.getText().getRange(1, 1).select();
// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = table
// selection.getTableCellRange().getTableCells()[0] = tableCell
// selection.getTextRange().getStartIndex() = 1
// selection.getTextRange().getEndIndex() = 1
//

تحويل الاختيار من خلال التعديلات النصية

يوضِّح المثال التالي كيفية تحويل التحديد من خلال تعديل النص المحدّد.

slides/selection/selection.gs

العرض على GitHub

  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  const shape = slide.getPageElements()[0].asShape();
  const textRange = shape.getText();
  textRange.setText('World');
  // Select all the text 'World'.
  textRange.select();
  // State of selection
  //
  // selection.getSelectionType() = SlidesApp.SelectionType.TEXT
  // selection.getCurrentPage() = slide
  // selection.getPageElementRange().getPageElements()[0] = shape
  // selection.getTextRange().getStartIndex() = 0
  // selection.getTextRange().getEndIndex() = 6
  //
  // Add some text to the shape, and the selection will be transformed.
  textRange.insertText(0, 'Hello ');

// State of selection
//
// selection.getSelectionType() = SlidesApp.SelectionType.TEXT
// selection.getCurrentPage() = slide
// selection.getPageElementRange().getPageElements()[0] = shape
// selection.getTextRange().getStartIndex() = 0
// selection.getTextRange().getEndIndex() = 12
//

إلغاء الاختيار

لا تتوفّر طرق صريحة لإلغاء اختيار النص أو عناصر الصفحة. ومع ذلك، يمكن تحقيق هذه النتيجة باستخدام الطريقتَين Page.selectAsCurrentPage() أو pageElement.select().

اختيار صفحة حالية

يوضّح المثال التالي كيفية إلغاء اختيار أي اختيارات حالية في صفحة من خلال ضبط تلك الصفحة على أنّها الصفحة الحالية.

slides/selection/selection.gs

عرض على GitHub

// Unselect one or more page elements already selected.
//
// In case one or more page elements in the first slide are selected, setting the
// same (or any other) slide page as the current page would do the unselect.
//
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  slide.selectAsCurrentPage();

اختيار عنصر صفحة

يوضّح المثال التالي كيفية إلغاء اختيار أي اختيارات حالية على صفحة من خلال اختيار عنصر صفحة واحد، وبالتالي إزالة جميع العناصر الأخرى من الاختيار.

slides/selection/selection.gs

العرض على GitHub

// Unselect one or more page elements already selected.
//
// In case one or more page elements in the first slide are selected,
// selecting any pageElement in the first slide (or any other pageElement) would
// do the unselect and select that pageElement.
//
  const slide = SlidesApp.getActivePresentation().getSlides()[0];
  slide.getPageElements()[0].select();