Настройки конфигурации тулбара

Тулбар - это панель инструментов для редактирования и форматирования ячеек.

Чтобы иметь возможность обращаться к тулбару, необходимо задать ему id в конфигурации:

const bar = {
    view: "toolbar",
    css: "webix_ssheet_toolbar webix_layout_toolbar",
    id: "bar",
    elements: [{...}]
}

Таким образом вы сможете обращаться к тулбару по его id:

spreadsheet.$$("bar");

Режимы отображения тулбара

Есть 2 режима отображения тулбара: "сокращенный" (по умолчанию) и "полный".

Режим по умолчанию

В режиме по умолчанию тулбар содержит четыре блока элементов управления: Undo/Redo, Font, Align, Number.

Настройки для тулбара по умолчанию задаются в объекте конфигурации buttons. Он содержит названия блоков кнопок (ключи) и массивы кнопок, входящих в эти блоки (значения этих ключей).

const buttons = {
    "undo-redo": ["undo","redo"],
    "font": ["font-family","font-size","font-weight","font-style",
      "underline","strike","color","background","borders"],
    "align": ["text-align","vertical-align","wrap","span",
      "increase-indent","decrease-indent"],
    "format": ["format"]
}

Названия блоков кнопок соответствуют свойствам, обозначенным в файлах локализации, которые указывают язык лейблов.

Полный режим

Чтобы показать все кнопки на тулбаре, задайте свойству toolbar значение "full":

webix.ui({
    view:"spreadsheet",
    data: base_data,
    toolbar: "full"
});

Related sample:  Toolbar with all buttons

Код со всеми элементами тулбара приведен в отдельной статье.

Структура тулбара

Тулбар состоит из следующих блоков:

Блок "Работа с файлом" (File)

webix.ui({
  view: "spreadsheet",
  data: base_data,
  toolbar: [
    {
      rows: [
        {
          margin: 2,
          cols: [
            {
              name: "sheet",
              view: "ssheet-button-icon-top",
              label: "Sheets",
              options: [
                { id: "new-sheet" },
                { id: "copy-sheet" },
                { id: "remove-sheet" },
                { id: "hide-sheet"}
              ],
            },
            {
              rows: [
                { $button: "excel-import" }, 
                { $button: "excel-export" }
            ]},
            {
              rows: [
                { $button: "print" }, 
                { $button: "print-borders" }
            ]},
        ]}
     ]}
   ]
});

Блок содержит селектор "sheet" (Sheet) для работы с листами со следующими опциями:

  • "new-sheet" - создает новый лист
  • "copy-sheet" - копирует содержимое текущего листа в новый лист
  • "remove-sheet" - удаляет лист
  • "hide-sheet" - прячет лист

и четыре кнопки:

  • Кнопка "excel-import" (Import from Excel) импортирует данные из Excel
  • Кнопка "excel-export" (Export to Excel) экспортирует данные в Excel
  • Кнопка "print" (Print) выводит лист на печать
  • Кнопка "print-borders" (Hide/show print borders) переключает видимость границ печати

Блок "Отменить/Восстановить" (Undo/Redo)

  view: "spreadsheet",
  toolbar: [
    {
      rows: [
        { $button: "undo", view: "ssheet-button", label: "Undo", width: 80 },
        { $button: "redo", view: "ssheet-button", label: "Redo", width: 80 },
      ],
    },
  ]

Блок содержит две кнопки:

  • Кнопка "undo" (Undo) отменяет последние изменения и возвращает Spreadsheet в предыдущее состояние
  • Кнопка "redo" (Redo) восстанавливает отмененное изменение

Блок "Шрифт" (Font)

  view: "spreadsheet",
  toolbar: [
    {
      rows: [
        {
          margin: 2,
          cols: [
            {
              margin: 2,
              cols: [
                {
                  $button: "font-family",
                  width: (webix.skin.$active.inputHeight + 2) * 4 + 6,
                },
                { $button: "font-size" },
              ],
            },
            { $button: "borders" },
          ],
        },
        {
          margin: 2,
          cols: [
            {
              margin: 2,
              cols: [
                { $button: "font-weight" },
                { $button: "font-style" },
                { $button: "underline" },
                { $button: "strike" }
              ],
            },
            { $button: "background" },
            { $button: "color" },
          ],
        },
      ],
    },
  ]

Блок содержит кнопки для настройки шрифтов и границ ячеек:

  • Селектор "font-family" (Font family) содержит список доступных шрифтов
  • Селектор "font-size" (Font size) задает размер шрифта
  • Группа кнопок для форматирования текста в ячейке:
    • кнопка "font-weight" делает содержимое ячейки полужирным
    • кнопка "font-style" делает содержимое ячейки курсивным
    • кнопка "underline" делает содержимое ячейки подчеркнутым
    • кнопка "strike" делает содержимое ячейки перечеркнутым
  • Палитра "color" (Font color) задает цвет шрифта
  • Палитра "background" (Background color) задает цвет фона
  • Селектор "borders" (Borders) применяет стиль к границам ячеек

Блок "Выравнивание" (Align)

  view: "spreadsheet",
  toolbar: [
    {
      rows: [
        {
          margin: 2,
          cols: [
              { $button: "text-align" }, 
              { $button: "span" }, 
              {$button: "increase-indent"}
          ],
        },
        {
          margin: 2,
          cols: [
              { $button: "vertical-align" }, 
              { $button: "wrap" }, 
              { $button: "decrease-indent"}
          ],
        },
      ],
    },
  ]

Блок содержит элементы управления для выравнивания содержимого ячейки, переноса текста, сдвига текста влево или вправо и объединения ячеек:

  • Селектор "text-align" (Horizontal align) содержит три режима выравнивания текста внутри ячейки: по левому краю, по правому краю, по центру
  • Селектор "vertical-align" (Vertical align) содержит три режима вертикального выравнивания текста внутри ячейки: по верхнему краю, посередине, по нижнему краю
  • Кнопка "span" (Merge) позволяет объединять (и разъединять) ячейки и их содержимое
  • Кнопка "wrap" (Text wrap) переносит текст в ячейке
  • Кнопка "increase-indent" (Increase indent) сдвигает содержимое ячейки вправо
  • Кнопка "decrease-indent" (Decrease indent) сдвигает содержимое ячейки влево

Блок "Числа" (Number)

  view: "spreadsheet",
  toolbar: [
    {
      rows: [
        { $button: "format" },
        {
          margin: 2,
          cols: [
            { $button: "increase-decimals" },
            { $button: "decrease-decimals" },
          ],
        },
      ],
    },
  ]

Блок содержит следующие элементы управления:

  • Селектор "format" (Number format) задает формат содержимого ячейки. Доступные форматы: Common, Currency, Number, Percent, Date, Text, Custom

  • Пара кнопок для увеличения/уменьшения числа десятичных знаков:

    • "increase-decimals" (Increase decimal places)
    • "decrease-decimals" (Decrease decimal places)

Блок "Редактирование" (Edit)

  view: "spreadsheet",
  toolbar: [
    {
      padding: 3,
      rows: [
        {
          cols: [
            { $button: "sort-range" },
            { $button: "create-filter" },
            { $button: "conditional-format" },
            { $button: "add-link" },
            { $button: "clear" },
            { $button: "find" }
          ],
        },
        {
          cols: [
            { $button: "sort-sheet" },
            { $button: "add-range" },
            { $button: "lock-cell" },
            { $button: "add-dropdown" },
            { $button: "validation"}
          ],
        },
      ],
    },
  ]

Блок содержит набор кнопок для редактирования содержимого ячеек:

  • Селектор "sort-range" (Sort Range) сортирует данные в пределах выбранного диапазона; скрывается при выделении одной строки и содержит следующие опции:
    • опция "sort-asc" - сортировка по возрастанию (от A до Z)
    • опция "sort-desc" - сортировка по убыванию (от Z до A)
    • опция "sort-custom" - открывает диалог многоуровневой сортировки
  • Селектор "sort-sheet" (Sort Sheet) сортирует весь лист по первому выбранному столбцу (столбец A, если ни один не выбран) и содержит следующие опции:
    • опция "sort-sheet-asc" - сортировка листа по возрастанию (от A до Z)
    • опция "sort-sheet-desc" - сортировка листа по убыванию (от Z до A)
  • Кнопка "create-filter" (Create/remove filters) создает фильтр в ячейке
  • Кнопка "add-range" (Named ranges) задает именованный диапазон ячеек для использования в математических формулах
  • Кнопка "conditional-format" (Conditional format) задает определенный стиль для ячейки в зависимости от условия
  • Переключатель "lock-cell" (Lock/unlock cell) блокирует или разрешает редактирование значения ячейки
  • Кнопка "add-link" (Add link) добавляет ссылку в ячейку
  • Кнопка "add-dropdown" (Add dropdown) создает в ячейке выпадающий список с опциями
  • Селектор "clear" (Clear) содержит набор опций для очистки ячейки:
    • "clear-value" - очищает значение ячейки
    • "clear-style" - очищает примененные к ячейке стили
    • "clear-conditional-formats" - очищает условное форматирование ячейки
    • "clear-dropdown-editors" - очищает выпадающие списки
    • "clear-filters" - очищает примененные фильтры
    • "clear-comments" - очищает добавленные к ячейке комментарии
    • "clear-all" - очищает всё перечисленное выше
  • Селектор "validation" (Validation) содержит набор опций для валидации содержимого ячеек:
    • опция "add-cell-validation" - добавляет правила валидации к ячейке
    • опция "remove-cell-validation" - удаляет правила валидации из ячейки
    • опция "highlight-invalid-data" - выделяет ячейки с недопустимыми данными
    • опция "remove-highlight-invalid-data" - снимает выделение с ячеек с недопустимыми данными
  • Кнопка "find" (Find and Replace) - служит для поиска указанного содержимого

Блок "Вставить" (Insert)

  view: "spreadsheet",
  toolbar: [
    {
      padding: 3,
      rows: [
        {
          cols: [
            {
              $button: "image",
              view: "ssheet-button",
              label: "Image",
              width: 110,
            },
            {
              $button: "add-comment",
              view: "ssheet-button",
              label: "Comment",
              width: 110,
            },
          ],
        },
        {
          cols: [
            {
              $button: "graph",
              view: "ssheet-button",
              label: "Graph",
              width: 110,
            },
            {
              $button: "controls",
              view: "ssheet-button",
              label: "Controls",
              width: 110,
            },
          ],
        }
      ],
    },
  ]

Блок содержит набор элементов управления для добавления в ячейки дополнительного содержимого:

  • Кнопка "image" (Image) добавляет изображение в ячейку
  • Кнопка "add-comment" (Comment) добавляет комментарий к ячейке
  • Кнопка "graph" (Graph) вставляет спарклайн в ячейку
  • Кнопка "controls" (Controls) вставляет в ячейку чекбокс или радиокнопку

Блок "Просмотр" (View)

  view: "spreadsheet",
  toolbar: [
    {
      padding: 3,
      rows:[
        { cols:[
          { rows:[
              { $button:"row" },
              { $button:"column" }
          ]},
          { rows:[
              { $button: "hide-gridlines" },
              { $button: "hide-headers" },
          ]},
          { rows:[
              { $button:"freeze-rows" },
              { $button:"freeze-columns" }
          ]},
          { rows:[
              { $button:"show-formulas" },
              {}
          ]}
        ]}
     ]}
  ]

Блок содержит следующие элементы управления:

  • Кнопка "row" (Rows) служит для вставки, удаления, скрытия, отображения, группировки и разгруппировки строк
  • Кнопка "column" (Columns) служит для вставки, удаления, скрытия, отображения, группировки и разгруппировки столбцов
  • Переключатель "hide-gridlines" (Hide/show gridlines) управляет сеткой Spreadsheet
  • Переключатель "hide-headers" (Hide/show headers) управляет заголовками строк и столбцов
  • Переключатель "freeze-rows" (Freeze/unfreeze rows) фиксирует и снимает фиксацию строк
  • Переключатель "freeze-columns" (Freeze/unfreeze columns) фиксирует и снимает фиксацию столбцов
  • Переключатель "show-formulas" (Hide/Show formulas) показывает формулы в ячейках вместо значений

Настройка коллекции "toolbar"

Особенность тулбара в том, что он может содержать только одну строку кнопок. Однако тулбар можно настроить так, чтобы он состоял из нескольких строк. Для этого используйте коллекцию "toolbar". Она позволяет задавать ширину и высоту кнопок, отступы (margin и padding), а также разделители между блоками кнопок.

Основные правила при работе с пользовательским тулбаром:

  • элементы тулбара помещаются в объект toolbar
  • тулбар строится по принципу лейаута, т.е. состоит из строк и столбцов, что позволяет создавать несколько уровней кнопок
  • кнопка, расширяющая предустановленную кнопку, должна включать свойство $button с именем кнопки в качестве значения
  • отступы кнопкам задаются с помощью свойств padding и margin
  • названия для блоков кнопок задаются компонентом ssheet-bar-title с помощью template
  • размер кнопок и шаблонов по умолчанию можно изменить, используя свойства width и height
  • разделитель между компонентами можно добавить с помощью ssheet-separator
 toolbar: [
    {
        rows:[
          {
            margin: 2,
            cols: [
                {$button: "undo"},
                {$button: "redo"}
            ]
          },
          {},
          {template: "Undo/Redo", view: "ssheet-bar-title", height: 24}
        ]
    },
    {view: "ssheet-separator"},
    {
        rows:[
           {
             margin: 2,
             cols:[
                {$button: "font-family", width: 167},
                {$button: "font-size", width: 90}
             ]
           },
           ...
        ]
    },
    ...
]

Related sample:  Custom toolbar

Кастомизация кнопок

Тулбар SpreadSheet содержит блоки кнопок, сгруппированные по функциональности. Расположение блоков кнопок в тулбаре задается в коллекции "buttons".

Удалить блок или кнопку

Если вы хотите удалить определенный блок или кнопку из тулбара, необходимо убрать соответствующий параметр или значение из объекта конфигурации.

Определение положения кнопок

Коллекция "buttons" - это объект данных, в котором ключ - это название блока, а значение - это массив с названиями кнопок.

По умолчанию тулбар содержит 4 блока с кнопками:

  • "undo-redo" - Отменить/Восстановить
  • "font" - операции со шрифтом и цветом
  • "align" - операции выравнивания, переноса текста и объединения ячеек
  • "format" - настройки формата чисел
webix.ui({
   view:"spreadsheet",
   buttons: {
       "undo-redo": ["undo","redo"],
       "font": ["font-family","font-size","font-weight","font-style",
            "underline","strike","color","background","borders"],
       "align": ["text-align","vertical-align","wrap","span"],
       "format": ["format"]
   }
});

Вы можете добавить новый блок с названием или без него. Чтобы скрыть название блока, поставьте перед ним символ "$".

Название блока кнопок можно задать в локали Spreadsheet.

Чтобы добавить на тулбар предустановленную кнопку, достаточно указать ее название.

Добавление кнопок с текстом

Чтобы добавить кнопку с текстом, необходимо поместить объект с конфигурацией кнопки (включая ее название) в соответствующий блок свойства buttons:

webix.ui({
   view:"spreadsheet",
   buttons: {
       "undo": ["undo","redo"],
        ...
       "My Block": [
           {   view: "button", name: "a", width: 40, label: "New button" }, 
           ...
       ]
    }
});

Related sample:  Text buttons

Добавление кнопок с иконками

Чтобы ваша новая кнопка соответствовала общему виду SpreadSheet, следуйте рекомендациям ниже:

  • задайте ширину кнопки, равную 40px
  • используйте "webix_ssheet_button_icon" как часть имени класса элемента icon
  • в качестве background-image используйте простые иконки с прозрачным фоном и цветом #787878

Пример создания кнопки с иконкой приведен ниже:

webix.ui({
   view:"spreadsheet",
   buttons: {
       "undo": ["undo","redo"],
       ...
       "Insert": [
        {
           view: "button", name: "insert-image", width: 40,
           label: "<span class='webix_ssheet_button_icon icon_image'></span>",
           tooltip: "Insert image", click: insertImage
         }
       ]
   }
});

Related sample:  Icon buttons

Группировка кнопок

Если количество кнопок превышает ширину тулбара, вы можете их сгруппировать. Для этого добавьте на тулбар кнопку с иконкой и прикрепите к ней выпадающее меню. Поместите все нужные кнопки в список выпадающего меню.

Описанная структура представлена в коде ниже:

webix.ui({
   view:"spreadsheet",
   buttons: {
       "undo": ["undo","redo"],
       ...
       "$other": [
          {},
          {
            view: "button",  name: "a", width: 40,
            label: "<span class='webix_ssheet_button_icon icon_other'></span>",
            tooltip: "Other options", popup: $$("mypopup")
          }
       ]
   }
});

Related sample:  Additional buttons

Использование пользовательской темы

Если вы используете для SpreadSheet пользовательскую тему, необходимо задать стили по умолчанию для кнопок тулбара, чтобы их значения отрисовывались корректно. Это означает, что вам нужно использовать копию ваших стилей из CSS-файла при создании темы. Например:

webix.skin[skin_name].spreadsheet = {
    "color": "#666666",
    "background" : "#ffffff",
    "font-family": "'PT Sans', Tahoma",
    "font-size": "15",
    "text-align": "left",
    "vertical-align": "middle",
    "white-space": "nowrap",
    "format": "common"
}

Кастомизация выпадающего меню

Выпадающее меню с иконками

Для создания выпадающего меню с иконками поместите компонент "ssheet-icons" в тело компонента datasuggest:

webix.ui({
   id: "mypopup",
   view: "datasuggest",
   body:{
       view: "ssheet-icons",
       xCount:3,
       yCount:1,
       tooltip: {
           template: "#title#"
       }
   },
   data: [
       {id: "insert_image", css: "bar_chart", title: "Bar"},
       {id: "insert_chart", css: "line_chart",  title: "Line"},
       {id: "insert_column", css: "pie_chart", title: "Pie"}
   ]
});

Компонент "ssheet-icons" основан на DataView, поэтому вы можете задать лейаут для иконок, используя свойства xCount и yCount.

Свойство css в элементах данных определяет правила CSS, где вы можете задать фоновое изображение для кнопки:

.bar_chart{
   content: url("images/bar-chart.svg");
}

Related sample:  Icon buttons in popup

Стилизация иконок в выпадающем меню

Стиль кнопок в выпадающем меню должен совпадать со стилем остальных кнопок тулбара. Чтобы достичь этого, следуйте рекомендациям ниже:

  • используйте "webix_ssheet_button_icon" как часть имени класса элемента icon
  • в качестве background-image используйте простые иконки с прозрачным фоном и цветом #787878

Выпадающее меню с текстовыми кнопками

Чтобы прикрепить выпадающее меню к кнопке на тулбаре, задайте ей свойство popup.

webix.ui({
   view:"spreadsheet",
   buttons: {
       ...
       "$other": [
           { view: "button", popup: $$("mypopup"),...}
       ]
   }
});

Также вы можете вызвать метод show() и передать DOM-элемент кнопки, чтобы показать выпадающее меню как в примере:

$$("mypopup").show($$("mybutton").$view);

Related sample:  Additional buttons

Выпадающее меню со списком

Для создания выпадающего меню со списком используйте компонент "ssheet-suggest". Компонент основан на ContextMenu, что позволяет добавлять в него подменю и разделители:

webix.ui({
   id: "mypopup",
   view: "ssheet-suggest",
   template: "<span class='webix_ssheet_button_icon #icon#'></span> #value#",
   data:[
       { id: "insert_image", icon: "image", value: "Insert image"},
       { id: "insert_chart", icon: "chart",  value: "Insert chart"},
       { $template: "Separator" },
       { id: "insert_column", icon: "column", value: "Insert column"},
       { id: "insert_row", icon: "row",  value: "Insert row"}
   ]
});

Выпадающее меню с формой

Вы также можете создать выпадающее меню с формой и прикрепить его к кнопке Spreadsheet.

Чтобы контролы формы внутри выпадающего меню отображались корректно, выполните следующие условия:

  • используйте только нижние границы
  • установите плейсхолдеры
  • для стилизации с помощью CSS используйте "webix_ssheet_suggest", для списков формы задайте padding:0
  • для цветовой палитры используйте компонент "ssheet-colorpicker"

Чтобы границы всех контролов внутри выпадающего меню отображались корректно, вы можете использовать компонент "ssheet-form-popup" вместо "popup", а для саджестов "ssheet-form-suggest":

webix.ui({
   id: "mypopup",
   view: "ssheet-form-popup",
   body: {
       view: "form",
       borderless: true,
       elements:[
            {view: "text", placeholder: "Name",...},
            {view: "richselect", label: "Type", placeholder: "Select", suggest:{
               view:  "ssheet-form-suggest",
               data:["Area","Bar","Line"]
            }},
            {view: "ssheet-colorpicker", label: "Color"}
      ]
   }
});

Related sample:  Popup with Form

Кастомизация диалоговых окон

Элементы в диалоговом окне SpreadSheet работают по тем же правилам, что и элементы выпадающего меню. Для создания диалогового окна вместо компонента window рекомендуется использовать компонент "ssheet-dialog".

Компонент "ssheet-dialog" применяет стили к заголовку и добавляет три кнопки: иконку Close в верхней части диалогового окна и две кнопки внизу (Cancel и Save).

Чтобы задать заголовок окна, используйте свойство head.

webix.ui({
   id: "mydialog",
   view: "ssheet-dialog",
   head: "Editor",
   body: {
       view: "form",
       elements:[
           ...
       ]
   }
});

Related sample:  Dialog

Настройки иконки Close

Чтобы задать фон для иконки, используйте "webix_ssheet_hide_icon".

.webix_ssheet_hide_icon{
   content: url("images/edit.svg");
}

Диалоговое окно запускает событие onHideClick по клику на иконку:

on:{
   onHideClick: function(){
       // клик произошел 
       this.hide();
   }
}

Кнопки Cancel и Save

Кнопки Cancel и Save добавляются в диалоговое окно автоматически. Если вы хотите убрать их, задайте значение false свойству buttons:

view: "ssheet-dialog",
buttons: false,
…

Названия кнопок заданы в локали SpreadSheet:

webix.i18n.spreadsheet.labels.cancel = "Cancel";
webix.i18n.spreadsheet.labels.save = "Save";

Диалоговое окно запускает события onCancelClick и onSaveClick по клику на соответствующую кнопку.

Добавление таблицы

Кроме контролов, вы можете добавить в диалоговое окно любой компонент, например, таблицу. Чтобы получить соответствующий внешний вид таблицы, рекомендуется использовать "ssheet-dialog-table".

webix.ui({
    id: "mydialog",
    view: "ssheet-dialog",
    head: "Editor",
    body: {
      cols:[
        {
          view: "ssheet-dialog-table", 
          autowidth: true, 
          autoheight:1,
          autoConfig:true,
          data:[
              {id: 1, name: "Range1", range: "A3:C8"},
              {id: 2, name: "Range2", range: "D3:F8"}
          ]
        },
        {
            view: "form",
            elements:[
            ...
        ]}
    ]}
});

Related sample:  DataTable in Dialog

Наверх