FamilyTree.JS

Введение

FamilyTree.JS – это javascript-библиотека от болгарской компании BALKAN, с помощью которой строятся и отображаются на странице веб-браузера интерактивные генеалогические деревья. Данные дерева набиваются и хранятся в текстовом виде прямо в js-файле в структурированном виде, поддающемся для понимания даже не технарю. Есть предустановленные поля для данных, в том числе для фото, есть возможность создавать свои поля. В бесплатной версии библиотека позволяет создавать дерево с числом узлов до 200 и отображать его с помощью браузера на сайте или локальном компьютере. Платная версия позволяет пользователям сайта редактировать данные дерева прямо на странице дерева, т.е. это уже веб-приложение.

База

Движком библиотеки является файл FamilyTree.js. Если его открыть в текстовом редакторе, то непосвященный ничего не поймет, тем более что код в нем минимизирован, т.е. все ненужные пробелы и переводы строк ликвидировны, а названия переменных состоят из одной буквы. Чтобы начать создание семейного дерева надо создать html-файл и в него прописать вызов FamilyTree.js. Например так:

   <script src="FamilyTree.js"></script>

   <script src="https://balkan.app/js/FamilyTree.js"></script>

   <div id="tree"></div>

   <script>
    let family = new FamilyTree("#tree", {
        nodeBinding: {
            field_0: "name",
            img: "img"
        },
        nodes: [
            { id: 1, pids: [2], name: "Елена Прекрасная", gender: "female" },
            { id: 2, pids: [1], name: "Иван Царевич", gender: "male" },
            { id: 3, mid: 1, fid: 2, name: "Василий Иванович", img: "pics/3-small-foto.jpg", gender: "male" }
        ]
    });
   </script>

Во многомерном массиве nodes в фигурных скобках прописаны объекты, являющиеся персонами в семейном дереве. Свойство id – это оригинальный идентификатор персоны, не может быть двух одинаковых. Свойство pids – это ссылка на id супруга (если их больше 1, то id в квадратных скобках разделять запятой). Свойства mid и fid – это ссылки на id мамы и папы. В свойстве gender указывается, мужчина это или женщина – в дереве у них карточки разных цветов.

nodeBinding – это свойства персоны. В примере выше только два свойства "name" (имя) и "img" (фото для карточки). Можно добавлять поля по своему усмотрению, например, field_1: "life" (время жизни) – по умолчанию это поле будет отражено на карточке (узле) в дереве. Следующие поля field_2... в узле дерева не отобразятся, но отобразятся в расширенной карточке, которая открывается в правой области экрана после того, как пользователь кликнул по карточке в дереве. Можно принудительно отобразить поле field_2 и в маленькой карточке, если прописать ему до строки "let family = new FamilyTree..." свойства примерно так:

FamilyTree.templates.tommy.field_2 = '<text class="field_2" style="font-size: 14px;" fill="#ffffff" x="25" y="70" text-anchor="middle">{val}</text>';

Поиск

Поиск по дереву довольно удобный. Искать можно как по всем возможным полям (по умолчанию), так и по отдельному полю. Если вместо поискового контекста задать знак вопроса, то будут выведены названия полей. Если задать поиск a формате "поле контекст", то будет найден контекст только в названном поле. Если задать "контекст_1 контекст_2", то будут найдены объекты, в поле которых есть встречаемость обоих контекстов, причем, не обязательно подряд.

Лайфхаки

Что мне не хватило из базовых встроенных возможностей библиотеки и какой я нашел выход:

1) Не хватило поля для более-менее объемной информации, в котором текст выводился бы на несколько строк, ориентируясь на ширину родительского блока. Это поле мне нужно для общей информации о персоне в свободном виде. Это поля я хотел видеть в расширенной карточке. Создать-то поле я создал, но оно выводилось в одну строку в html-элементе input. Тогда я решил на лету заменять этот элемент на textarea во время генерации расширенной карточки при клике на узел дерева. Сначала в файле index.htm в свойстве nodeBinding прописал новое поле info:"info", заполнил это поле в элементах массива nodes. Потом в конце скрипта дописал:

   document.addEventListener('click', (event) => { // делегирование через document работает с динамическими элементами
      const gElement = event.target.closest('g');
      if (gElement) { // если клик по карточке (узлу)
         const input = document.querySelector('input[data-binding="info"]'); // находим нужный input с данными поля info
         const textarea = document.createElement('textarea');
         Array.from(input.attributes).forEach(attr => {
            textarea.setAttribute(attr.name, attr.value);
         });
         textarea.value = "\n"+input.value;
         input.parentNode.replaceChild(textarea, input); // меняем input на textarea с сохранением параметров
         textarea.cols = 48; textarea.rows = Math.ceil(textarea.value.length / textarea.cols) + 2; // назначаем кол-во строк
         textarea.style.backgroundColor = "#252526";
         textarea.style.color = "#CCF"; textarea.style.border = "0";
      }
   });

2) Не хватило возможности просмотра больших фотографий по каждому человеку. В расширенной карточке вместо кнопки расшаривания сделал кнопку для просмотра большой фотки. Для этого после строки "let family = new FamilyTree..." прописал:

   editForm: {
      buttons: {
         share: null, // Отключает кнопку "Поделиться"
         pic: { icon: FamilyTree.icon.add(24,24,'#FF9'), text: "Фото" }, // Добавляю новую кнопку
      },
   },

   family.editUI.on('button-click', function (sender, args) {
      if (args.name == 'pic') {
         var data = family.get(args.nodeId);
       // Создаём затемнённый div на всё окно
         const overlay = document.createElement('div');
         overlay.style.position = 'fixed';
         overlay.style.top = overlay.style.left = '0';
         overlay.style.width = overlay.style.height = '100%';
         overlay.style.backgroundColor = 'black';
         overlay.style.opacity = '0.7';
         overlay.style.zIndex = '99';
       // Создаём картинку, которая будет поверх overlay (но не внутри него)
         const img = document.createElement('img');
         img.src = 'imgs/'+data.id+'_big_foto.jpg'; // путь к большой картинке, data.id - id персоны в имени файла
         img.style.position = 'fixed';
         img.style.zIndex = '100';
         img.style.top = img.style.left = '50%';
         img.style.transform = 'translate(-50%, -50%)';
         img.style.maxWidth = img.style.maxHeight = '95%'; // для адаптивности, чтобы не вылезала за экран
         img.style.objectFit = 'contain';
       // Создаём кнопку вверху справа для успокоения пользователя
         const button = document.createElement('button');
         button.textContent = 'X';
         button.style.position = 'fixed';
         button.style.top = button.style.right = '25px';
         button.style.zIndex = '1002';
         button.style.padding = '10px 20px';
         button.style.fontSize = '16px';
         button.style.cursor = 'pointer';
         button.style.backgroundColor = '#f44336';
         button.style.color = 'white';
         button.style.border = 'none';
         button.style.borderRadius = '5px';
         button.style.fontWeight = 'bold';
       // Добавляем всё на страницу
         document.body.appendChild(overlay);
         document.body.appendChild(img);
         document.body.appendChild(button);
       // Функция удаления
         const removeElements = () => {
            overlay.remove();
            img.remove();
            button.remove();
         };
       // Вешаем событие на кнопку, а лучше на экран вне большой картинки
         button.addEventListener('click', removeElements);
         overlay.addEventListener('click', removeElements);
      }
   });

3) Захотелось немного кастомизировать поиск по дереву. Выше строки "let family = new FamilyTree..." я прописал переменные:

   FamilyTree.SEARCH_PLACEHOLDER = "Поиск:"; // название поля поиска
   FamilyTree.SEARCH_CLOSE_RESULT_ON_ESCAPE_OR_CLICKOUTSIDE = 1; // закрытие результатов поиска по любому месту вне результатов
   FamilyTree.SEARCH_RESULT_LIMIT = 16; // максимальное кол-во найденных карточек

4) Потребовалась фокусировка на избранной персоне при старте дерева. Моё дерево разрослось и для удобства навигации по нему в движке предусмотрена кнопка на узле (три кружочка), по которой пользователь может раскрыть скрытую ветку. С одной стороны это удобно, с другой стороны моя желаемая для отображения ветка оказалась первоначально скрыта. Выход в следующей функции, которая пишется в конце скрипта:

   family.onInit(() => family.center(5));

Анатолий Опарин, июнь 2026

Скачать, почитать

📥 Скачать FamilyTree.JS с сайта разработчика.
📗 Внушительная справка по FamilyTree.JS на английском на сайте разработчика.
👫 Скачать пример проекта, в котором реализованы лайфхаки, описанные выше. После распаковки и запуска файла index.htm вы сразу увидите результат в своем браузере.