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

الجزء المحدَّد هو أي جزء محدَّد حاليًا في صفحة عرض تقديمي مفتوحة، مثل نطاق نص مميّز أو جدول. يوضّح لك هذا الدليل كيفية الحصول على الاختيار وضبطه في عرض تقديمي نشط باستخدام 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();

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

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

يمكن أن تحتوي الصفحة الحالية على عنصر واحد أو أكثر محدد، ويحدد عنصر تحديدًا نوع التحديد.

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

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

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.
• تحديد المؤشر: إذا كان الشكل يحتوي على النص "مرحبًا"، وكان المؤشر بعد "H" ("H|ello")، يكون النطاق المعروض فارغًا يشتمل على 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. لنفترض أن لديك شكلين A وB محددين.
2. بعد ذلك، يزيل النص البرمجي الشكل "أ".
3. ونتيجة لذلك، يتم تحويل التحديد مقابل التعديل بحيث يتم تحديد الشكل B فقط.

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

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