Регионы

Регионы предоставляют согласованные методы для управления, отображения и уничтожения представлений в ваших приложениях и представлениях.

Region включает:

• Общие возможности Marionette
• События класса
• API DOM

См. документацию по выводке представлений для введения в управление регионами по всему приложению.

Регионы поддерживают жизненный цикл представления при отображении или очистке представления.

Индекс документации

• Инициализация региона
• Определение региона приложения
• Определение регионов
  • Строковый селектор
  • Дополнительные параметры
  • Указание regions как функции
  • Использование RegionClass
  • Ссылка на пользовательский интерфейс в regions
• Добавление регионов
• Удаление регионов
• Использование регионов в представлении
• Отображение представления
  • Проверка, отображает ли регион представление
  • Представления, не являющиеся Marionette
    • Частично отрисованные представления
• Отображение шаблона
• Очистка региона
  • Сохранение существующих представлений
  • Отсоединение существующих представлений
• reset Регион
• destroy Регион
• Проверка, заменяется ли представление другим
• Настройка способа присоединения элемента представления
• Настройка способа удаления представления

Инициализация региона

При инициализации Region существуют два свойства, которые, если переданы, будут присоединены непосредственно к экземпляру: el, и replaceElement.

import { Region } from 'backbone.marionette';

const myRegion = new Region({ ... });

Хотя регионы могут быть инициализированы и полезны сами по себе, их основное применение происходит через Application и View классы.

Определение региона приложения

Приложение определяет единственный регион el с помощью атрибута region. К нему можно получить доступ через getRegion() или напрямую отобразить представление с помощью showView(). Ниже приведен короткий пример:

import { Application } from 'backbone.marionette';
import SomeView from './view';

const MyApp = Application.extend({
  region: '#main-content',

  onStart() {
    const mainRegion = this.getRegion();  // Has all the properties of a `Region`
    mainRegion.show(new SomeView());
  }
});

Пример в реальном времени

Для получения дополнительной информации см. документацию по приложению.

Определение регионов

В Marionette вы можете определить регион с помощью строкового селектора или объекта-литерала в своем Application или View. Этот раздел продемонстрирует два типа, применяемые к View, хотя они будут работать и с Application — просто замените regions на region в вашем определении.

Ошибки При неправильной конфигурации региона будет выброшено исключение.

Строковый селектор

Вы можете использовать селектор jQuery для определения регионов.

import { View } from 'backbone.marionette';

const MyView = View.extend({
  regions: {
    mainRegion: '#main'
  }
});

Дополнительные параметры

Вы можете определить регионы с помощью объекта-литерала. Определения с помощью объекта-литерала ожидают свойство el — строку селектора для привязки региона. С этим форматом можно определить, перезаписывает ли отображение региона родительский el или просто перезаписывает содержимое (по умолчанию).

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

import { View } from 'backbone.marionette';

const OverWriteView = View.extend({
  className: '.new-class'
});

const MyView = View.extend({
  regions: {
    main: {
      el: '.overwrite-me',
      replaceElement: true
    }
  }
});
const view = new MyView();
view.render();

console.log(view.$('.overwrite-me').length); // 1
console.log(view.$('.new-class').length); // 0

view.showChildView('main', new OverWriteView());

console.log(view.$('.overwrite-me').length); // 0
console.log(view.$('.new-class').length); // 1

Когда экземпляр MyView отрисовывается, элемент .overwrite-me будет удален из DOM и заменен элементом .new-class — это позволяет нам, например, отрисовывать представления внутри table или select более удобно — эти элементы обычно очень строги в отношении разрешенного содержимого.

import { View } from 'backbone.marionette';

const MyView = View.extend({
  regions: {
    regionDefinition: {
      el: '.bar',
      replaceElement: true
    }
  }
});

Ошибки При определении региона будет выброшено исключение, если свойство el не указано или если el не существует в HTML.

Указание regions как функции

В представлении View атрибут regions также может быть функцией, возвращающей объект:

import { View } from 'backbone.marionette';

const MyView = View.extend({
  regions(){
    return {
      firstRegion: '#first-region'
    };
  }
});

Использование RegionClass

Если вы создали пользовательский класс региона, вы можете использовать его для определения региона.

import { Application, Region, View } from 'backbone.marionette';

const MyRegion = Region.extend({
  onShow(){
    // Scroll to the middle
    this.$el.scrollTop(this.currentView.$el.height() / 2 - this.$el.height() / 2);
  }
});

const MyApp = Application.extend({
  regionClass: MyRegion,
  region: '#first-region'
})

const MyView = View.extend({
  regionClass: MyRegion,
  regions: {
    firstRegion: {
      el: '#first-region',
      regionClass: Region // Don't scroll this to the top
    },
    secondRegion: '#second-region'
  }
});

Пример в реальном времени

Ссылка на пользовательский интерфейс в regions

Атрибут UI может быть полезным при установке селекторов региона — просто используйте префикс @ui.:

import { View } from 'backbone.marionette';

const MyView = View.extend({
  ui: {
    region: '#first-region'
  },
  regions: {
    firstRegion: '@ui.region'
  }
});

Пример в реальном времени

Добавление регионов

Чтобы добавить регионы к представлению после его инициализации, просто используйте метод addRegion:

import MyView from './myview';

const myView = new MyView();
myView.addRegion('thirdRegion', '#third-region');

Теперь мы можем получить доступ к thirdRegion как к другим.

Вы также можете добавить несколько регионов с помощью addRegions.

import MyView from './myview';

const myView = new MyView();
myView.addRegions({
  main: {
    el: '.overwrite-me',
    replaceElement: true
  },
  sidebar: '.sidebar'
});

Пример в реальном времени

Удаление регионов

Вы можете удалить все регионы из представления, вызвав removeRegions, или удалить регион по имени, используя removeRegion. При удалении региона он будет уничтожен.

import { View } from 'backbone.marionette';

const MyView = View.extend({
  regions: {
    main: '.main',
    sidebar: '.sidebar',
    header: '.header'
  }
});

const myView = new MyView();

// remove only the main region
const mainRegion = myView.removeRegion('main');

mainRegion.isDestroyed(); // -> true

// remove all regions
myView.removeRegions();

Использование регионов в представлении

Помимо добавления и удаления регионов, есть несколько методов для использования регионов. Все эти методы сначала отрисуют неотрисованное представление, чтобы регионы были должным образом инициализированы.

• getRegion(name) — Запрос региона из представления по имени.
• getRegions() — Возвращает объект-литерал всех регионов в представлении, организованных по имени.
• hasRegion(name) — Проверка наличия региона в представлении.
• emptyRegions() — Очистка всех регионов в представлении.

Отображение представления

После определения региона вы можете вызвать его метод show для отображения представления:

const myView = new MyView();
const childView = new MyChildView();
const mainRegion = myView.getRegion('main');

// render and display the view
mainRegion.show(childView, { fooOption: 'bar' });

Это эквивалентно методу showChildView представления, который можно использовать как:

const myView = new MyView();
const childView = new MyChildView();

// render and display the view
myView.showChildView('main', childView, { fooOption: 'bar' });

Оба формата принимают объект options, который будет передан при срабатывании событий при show.

Для получения дополнительной информации об showChildView и getChildView, см. документацию по представлениям.

Ошибки Будет выброшено исключение, если представление ложно или уничтожено.

Проверка, отображает ли регион представление

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

const myView = new MyView();
const mainRegion = myView.getRegion('main');

mainRegion.hasView() // false
mainRegion.show(new OtherView());
mainRegion.hasView() // true

Если вы отобразите представление в регион с существующим представлением, Marionette удалит существующее представление перед отображением нового.

Представления, не являющиеся Marionette

Регионы Marionette не предназначены только для отображения представлений Marionette — они также могут отображать экземпляры Backbone.View. Для этого убедитесь, что ваше представление определяет метод render() и используйте его как обычное представление Marionette:

import _ from 'underscore';
import Bb from 'backbone';
import { View } from 'backbone.marionette';

const MyChildView = Bb.View.extend({
  render() {
    this.$el.append('<p>Some text</p>');
  },

  onRender() {
    console.log('Regions also fire Lifecycle events on Backbone.View!');
  }
});

const MyParentView = View.extend({
  regions: {
    child: '.child-view'
  },

  template: _.template('<div class="child-view"></div>'),

  onRender() {
    this.showChildView('child', new MyChildView());
  }
});

Как видно выше, вы можете отслеживать события жизненного цикла на Backbone.View, и Marionette будет их генерировать.

Отображение шаблона

Вы можете напрямую отобразить шаблон или строку в регион. Кроме того, вы можете передать объект-литерал, содержащий шаблон и любые другие параметры представления. Под капотом создаётся экземпляр Marionette.View с использованием шаблона.

const myView = new MyView();

myView.showChildView('main', {
  template: _.template('This is the <%- section %> page'),
  templateContext: { section: 'main' }
});

myView.showChildView('header', _.template('Welcome to the site'));

myView.getRegion('other').show('This text is in another region');

Очистка региона

Вы можете удалить представление из региона (эффективно «скрыть» его) с помощью region.empty() для региона:

const myView = new MyView();

myView.showChildView('main', new OtherView());
const mainRegion = myView.getRegion('main');
mainRegion.empty();

Это уничтожит представление, очистит все обработчики событий и удалит его из DOM. При очистке региона срабатывают события empty.

ПРИМЕЧАНИЕ Если регион в данный момент не содержит представление, при очистке он отсоединит любой HTML внутри региона. Если регион содержит представление, любой HTML, не принадлежащий представлению, останется.

Сохранение существующих представлений

Если вы замените текущее представление новым, вызвав show, оно автоматически уничтожит предыдущее представление. Вы можете предотвратить это поведение, отсоединив представление перед отображением другого.

Отсоединение существующих представлений

Если вы хотите отсоединить существующее представление от региона, используйте detachView.

const myView = new MyView();

const myOtherView = new MyView();

const childView = new MyChildView();

// render and display the view
myView.showChildView('main', childView);

// ... somewhere down the line
myOtherView.showChildView('main', myView.getRegion('main').detachView());

Примечание При отсоединении представления вы должны передать его в новый регион, чтобы Marionette мог автоматически обработать его жизненный цикл, или destroy его вручную, чтобы предотвратить утечку памяти.

reset Регион

Регион может быть reset в любое время. Это уничтожает любое существующее отображаемое представление и удаляет кэшированный el. При следующем отображении представления регион запрашивает el из DOM.

const myView = new MyView();
myView.showChildView('main', new OtherView());
const myRegion = myView.getRegion('main');
myRegion.reset();

Это может быть полезно при тестировании ваших представлений.

destroy Регион

Регион может быть уничтожен, что reset регион, удалит его из родительского представления и остановит любые внутренние слушатели региона. Уничтоженный регион не должен повторно использоваться.

import { View } from 'backbone.marionette';

const MyView = View.extend({
  regions: {
    mainRegion: '#main'
  }
});

const myView = new MyView();

const myRegion = myView.getRegion('mainRegion');

myRegion.show(new ChildView());

myRegion.destroy();

myRegion.isDestroyed(); // true
myRegion.hasView(); // false
myView.hasRegion('mainRegion'); // false

Проверка, заменяется ли представление другим

Метод isSwappingView возвращает значение true, если представление заменяется другим. Это полезно внутри событий/методов жизненного цикла региона.

Пример отобразит сообщение, когда регион пуст:

import { Region } from 'backbone.marionette';

const EmptyMsgRegion = Region.extend({
  onEmpty() {
    if (!this.isSwappingView()) {
      this.$el.append('Empty Region');
    }
  }
});

Пример в реальном времени

Настройка способа присоединения и отсоединения элемента представления

Переопределите метод attachHtml региона, чтобы изменить способ присоединения представления к DOM (если не используется replaceElement: true). Этот метод получает один параметр — представление для отображения.

Стандартная реализация attachHtml выглядит примерно так:

import { Region } from 'backbone.marionette';

Region.prototype.attachHtml = function(view){
  this.el.appendChild(view.el);
}

Аналогично attachHtml, переопределите метод detachHtml, чтобы определить, как регион отделяет содержимое от его el. Этот метод не получает параметров.

В большинстве случаев вы захотите использовать API DOM, чтобы определить, как прикрепляется HTML региона, но в некоторых случаях вы можете переопределить отдельный класс Region для ситуаций, таких как анимация, где вы хотите контролировать как прикрепление, так и удаление представления.

Этот пример заставит представление скользить вниз с верхней части экрана, а не просто появляться на месте:

import { Region, View } from 'backbone.marionette';

const ModalRegion = Region.extend({
  attachHtml(view){
    // Some effect to show the view:
    this.$el.empty().append(view.el);
    this.$el.hide().slideDown('fast');
  }
});

const MyView = View.extend({
  regions: {
    mainRegion: '#main-region',
    modalRegion: {
      regionClass: ModalRegion,
      el: '#modal-region'
    }
  }
});

Настройка удаления представления

Переопределите метод removeView региона, чтобы изменить способ и время уничтожения/удаления представления из DOM. Этот метод получает один параметр — представление для удаления.

Стандартная реализация removeView выглядит так:

import { Region } from 'backbone.marionette';

Region.prototype.removeView = function(view){
  this.destroyView(view);
}

Метод destroyView уничтожает представление, учитывая, является ли оно потомком Marionette.View или обычного представления Backbone. Его можно заменить вызовом view.destroy(), если гарантируется, что представление происходит от Marionette.View.

Этот пример анимирует представление с эффектом затемнения при показе и скрытии:

import { Region, View } from 'backbone.marionette';

const AnimatedRegion = Region.extend({
  attachHtml(view) {
    view.$el
      .css({display: 'none'})
      .appendTo(this.$el);
    if (!this.isSwappingView()) view.$el.fadeIn('slow');
  },

  removeView(view) {
    view.$el.fadeOut('slow', () => {
      this.destroyView(view);
      if (this.currentView) this.currentView.$el.fadeIn('slow');
    });
  }
});

const MyView = View.extend({
  regions: {
    animatedRegion: {
      regionClass: AnimatedRegion,
      el: '#animated-region'
    }
  }
});

Пример

Аналогичный подход можно использовать для создания анимированного с помощью CSS региона:

Пример