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

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

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

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

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

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

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

يمكنك أيضًا استرداد العنصر الذي يحتوي على النص المحدّد. بمتابعة المثال أعلاه، يمكنك استرداد الشكل الذي يحتوي على النص المحدّد باستخدام selection.getPageElementRange().getPageElements()[0]. وبالمثل، الصفحة التي تحتوي على الشكل المحيط هي الصفحة النشطة الحالية. لاسترداد هذه الصفحة، استخدِم 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(). هناك نوعان من تحديد النص:

• اختيار النطاق: إذا كان الشكل يحتوي على النص "Hello" وتم اختيار "He"، سيكون النطاق الذي تم إرجاعه هو startIndex=0 وendIndex=2.
• تحديد المؤشر: إذا كان الشكل يحتوي على النص "Hello"، وكان المؤشر بعد "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. لنفترض أنّ لديك شكلَين "أ" و"ب" محدَّدَين.
2. بعد ذلك، يزيل النص البرمجي الشكل A.
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();