Memilih item dalam presentasi

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

Pemilihan adalah snapshot saat skrip dimulai. Jika pengguna mengklik dan pilihan berubah saat skrip berjalan, perubahan tersebut tidak akan diterapkan.

Pilihan dan jenis pemilihan

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

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

Anda juga dapat mengambil objek yang berisi pilihan. Dengan melanjutkan contoh di atas, Anda dapat mengambil bentuk yang berisi teks yang dipilih menggunakan selection.getPageElementRange().getPageElements()[0]. Demikian pula, halaman yang berisi bentuk pembatas 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:

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

Membaca halaman saat ini

Untuk mengambil Page saat ini yang sedang dilihat pengguna, gunakan metode getSelection() dan getCurrentPage() sebagai berikut:

slide/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 pemilihan untuk membaca pilihan saat ini dengan cara yang sesuai jenisnya.

slide/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 pemilihan teks menggunakan metode Selection.getTextRange(). Ada dua jenis pemilihan teks:

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

Memodifikasi pilihan

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

Perubahan pemilihan akan tercermin di browser pengguna hanya 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 pemilihan teks sebelumnya. Jadi, penggunaan metode ini di halaman saat ini memungkinkan Anda membatalkan pilihan pilihan saat ini di halaman. Contoh:

slide/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 membatalkan pilihan elemen halaman yang dipilih sebelumnya.

Contoh:

slide/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.

slide/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
//

Mengubah pilihan

Pengeditan yang dijalankan skrip Anda dapat mengubah pilihan saat ini, sehingga apa yang dipilih berubah sebagai hasil dari pengeditan tersebut. Contoh:

  1. Misalnya Anda telah memilih dua bentuk A dan B.
  2. Selanjutnya skrip Anda menghapus bentuk A.
  3. Akibatnya, pilihan ditransformasikan terhadap edit sehingga hanya bentuk B yang dipilih.

Contoh berikut menunjukkan cara mengubah pilihan dengan memanipulasi elemen halaman yang dipilih.

slide/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 dimuat dalam bentuk atau dalam sel tabel dapat dipilih menggunakan metode TextRange.select(). Jika teks dimuat dalam sebuah bentuk, maka bentuk itu juga akan dipilih. Jika teks dimuat dalam sel tabel, sel tabel tersebut dan tabel penutupnya akan dipilih.

Tindakan ini juga menetapkan halaman induk sebagai halaman saat ini.

Pilihan rentang dalam bentuk

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

slide/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
//

Pemilihan kursor dalam sebuah bentuk

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

slide/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 dalam sel tabel

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

slide/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 pilihan kursor dalam teks yang dimuat dalam sel tabel.

slide/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 pemilihan dengan pengeditan tekstual

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

slide/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().

Pilih halaman saat ini

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

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

Pilih elemen halaman

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

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