Memilih item dalam presentasi

Pilihan adalah apa pun yang saat ini dipilih di halaman presentasi yang terbuka, seperti rentang teks yang ditandai atau tabel. Panduan ini memberi tahu Anda cara mendapatkan dan menetapkan pilihan dalam presentasi aktif menggunakan Apps Script.

Pilihan ini adalah snapshot dari kondisi saat skrip dimulai. Jika pengguna mengklik dan pilihan berubah saat skrip berjalan, perubahan tersebut tidak akan tercermin.

Pilihan dan jenis pilihan

Anda dapat membaca pilihan menggunakan class Selection. Class ini memiliki berbagai metode untuk mendapatkan objek yang dipilih berdasarkan jenis objek yang dipilih.

Enum SelectionType mewakili jenis objek tertentu yang dipilih. Misalnya, jika pengguna telah memilih beberapa teks dalam bentuk, jenis pilihannya akan menjadi TEXT. Dalam hal ini, Anda dapat mengambil rentang teks yang dipilih menggunakan metode selection.getTextRange().

Anda juga dapat mengambil objek yang berisi pilihan; melanjutkan contoh di atas, Anda dapat mengambil bentuk yang berisi teks yang dipilih menggunakan selection.getPageElementRange().getPageElements()[0]. Demikian pula, halaman yang berisi bentuk yang melingkupi adalah halaman aktif saat ini; untuk mengambil halaman tersebut, gunakan selection.getCurrentPage().

Membaca pilihan

Untuk membaca pilihan, gunakan metode Presentation.getSelection() seperti yang ditunjukkan dalam contoh berikut:

slides/selection/selection.gs
const selection = SlidesApp.getActivePresentation().getSelection();

Membaca halaman saat ini

Untuk mengambil Halaman saat ini yang dilihat pengguna, gunakan metode getSelection() dan getCurrentPage() seperti berikut:

slides/selection/selection.gs
const currentPage = SlidesApp.getActivePresentation().getSelection().getCurrentPage();

Perhatikan bahwa halaman saat ini dapat berupa salah satu jenis berikut:

Halaman saat ini dapat memiliki satu atau beberapa objek yang dipilih, dan SelectionType menentukan jenis pemilihan.

Membaca pilihan berdasarkan jenis pilihan

Contoh berikut menunjukkan cara menggunakan jenis pilihan untuk membaca pilihan saat ini dengan cara yang sesuai dengan jenis.

slides/selection/selection.gs
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;
}

Membaca pilihan teks

Anda dapat membaca pilihan teks menggunakan metode Selection.getTextRange(). Ada dua jenis pemilihan teks:

  • Pemilihan rentang: Jika bentuk berisi teks "Halo", dan "Dia" dipilih, rentang yang ditampilkan memiliki startIndex=0, dan endIndex=2.
  • Pemilihan kursor: Jika bentuk berisi teks "Hello", dan kursor berada setelah "H" ("H|ello"), rentang yang ditampilkan adalah rentang kosong dengan startIndex=1 dan endIndex=1.

Mengubah pilihan

Skrip dapat mengubah pilihan pengguna. Setiap perubahan pilihan yang dilakukan skrip pada presentasi akan tercermin dalam operasi pemilihan berikutnya selama durasi eksekusi skrip.

Perubahan pilihan hanya ditampilkan di browser pengguna setelah eksekusi skrip selesai, atau saat Presentation.saveAndClose() dipanggil.

Memilih halaman saat ini

Halaman dalam presentasi aktif dapat dipilih sebagai halaman saat ini dengan memanggil metode selectAsCurrentPage(). Metode ini menghapus elemen halaman, halaman, atau pilihan teks sebelumnya. Jadi, dengan menggunakan metode ini di halaman saat ini, Anda dapat membatalkan pilihan apa pun saat ini di halaman. Contoh:

slides/selection/selection.gs
// 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
//

Memilih elemen halaman

Untuk memilih elemen halaman di halaman, gunakan metode PageElement.select(). Tindakan ini juga akan membatalkan pilihan elemen halaman yang sebelumnya dipilih.

Contoh:

slides/selection/selection.gs
  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
//

Memilih beberapa elemen halaman

Untuk menambahkan elemen halaman tambahan ke pilihan, gunakan metode PageElement.select(false). Semua elemen halaman harus berada di halaman saat ini.

slides/selection/selection.gs
  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
//

Mentransformasi pilihan

Pengeditan yang dilakukan skrip Anda dapat mengubah pilihan saat ini, sehingga hal yang dipilih akan berubah sebagai hasil dari pengeditan. Contoh:

  1. Misalkan Anda memiliki dua bentuk A dan B yang dipilih.
  2. Selanjutnya, skrip Anda akan menghapus bentuk A.
  3. Akibatnya, pilihan diubah terhadap pengeditan sehingga hanya bentuk B yang dipilih.

Contoh berikut menunjukkan cara transformasi pemilihan dengan memanipulasi elemen halaman yang dipilih.

slides/selection/selection.gs
  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]
//

Memilih teks

Teks yang terdapat dalam bentuk atau dalam sel tabel dapat dipilih menggunakan metode TextRange.select(). Jika teks berada dalam bentuk, bentuk tersebut juga akan dipilih. Jika teks terdapat dalam sel tabel, sel tabel tersebut dan tabel penyertanya akan dipilih.

Tindakan ini juga menetapkan halaman induk sebagai halaman saat ini.

Pilihan rentang dalam bentuk

Contoh berikut menunjukkan cara membuat pemilihan rentang dalam teks yang dimuat dalam bentuk.

slides/selection/selection.gs
  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
//

Pilihan kursor dalam bentuk

Contoh berikut menunjukkan cara membuat pemilihan kursor dalam teks yang dimuat dalam bentuk.

slides/selection/selection.gs
  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
//

Pemilihan rentang di sel tabel

Contoh berikut menunjukkan cara membuat pilihan rentang dalam teks yang terdapat dalam sel tabel.

slides/selection/selection.gs
  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
//

Pemilihan kursor di TableCell

Contoh berikut menunjukkan cara membuat pemilihan kursor dalam teks yang terdapat dalam sel tabel.

slides/selection/selection.gs
  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
//

Transformasi pilihan dengan pengeditan tekstual

Contoh berikut menunjukkan cara transformasi pilihan dengan mengedit teks yang dipilih.

slides/selection/selection.gs
  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
//

Membatalkan pilihan

Tidak ada metode eksplisit untuk membatalkan pilihan teks atau elemen halaman. Namun, hasil ini dapat dicapai menggunakan metode Page.selectAsCurrentPage() atau pageElement.select().

Memilih halaman saat ini

Contoh berikut menunjukkan cara membatalkan pilihan saat ini di halaman dengan menetapkan halaman tersebut sebagai halaman saat ini.

slides/selection/selection.gs
// 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();

Memilih elemen halaman

Contoh berikut menunjukkan cara membatalkan pilihan saat ini di halaman dengan memilih satu elemen halaman, sehingga menghapus semua item lain dari pilihan.

slides/selection/selection.gs
// 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();