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

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

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

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

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

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

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