Библиотека w3b.js

W3b.js — это небольшой скрипт, созданный автором с целью и в процессе изучения JS. Первоначальный вариант библиотеки содержал в себе лишь несколько часто используемых тривиальных функций для работы с DOM, необходимых для нужд автора. Позднее, по мере продвижения создателя в мире JS, библиотека обзавелась более сложными функциями, которые упрощают разработку интерфейсов.

W3b.js пока не может соревноваться с известными библиотеками вроде JQuery с точки зрения производительности или кроссбраузерности. Однако скромный размер в сочетании с необычными функциями делает её вполне пригодной для использования в небольших проектах, где не требуется поддержка слишком старых браузеров. Один файл весом около 7 kb (gzipped) позволяет выполнить довольно внушительный список задач.

Краткий обзор возможностей

Работа с DOM-элементами

Все базовые функции для работы с DOM реализованы по принципу цепочки методов как в JQuery:

  • поиск, добавление, удаление и создание элементов;
  • манипулирование идентификаторами, классами и атрибутами;
  • получение и изменение CSS;
  • отображение и скрытие контента;
  • чтение и редактирование текстового содержимого и HTML;
  • сравнение элемента с CSS-селекторами;
  • проверка полной или частичной видимости элемента во viewport;
  • добавление и удаление обработчиков событий;
  • проверка готовности DOM.

Например, так выполняются две одинаковые задачи на обычном JS и с использованием библиотеки:

// vanilla js
document.addEventListener("DOMContentLoaded", function() {

  let el = document.body;

  el.addEventListener("click", function(e) {
    console.log(e);
  });

  el.style.cssText = "color: green; font-size: 9em;";
  el.classList.add("my-class");

  let node = document.createElement("div");
  node.textContent = "Hello world!";
  node.classList.add("new-element");
  el.appendChild(node);

  while (el.firstChild) {
    el.removeChild(el.firstChild);
  };

});

// w3b.js
_(document.body).on("click",function(e) { console.log(e); }).CSS({"color":"green","font-size":"9em"}).addClass("my-class").node({node:"div",text:"Hello world",class:"new-element"}).parent().clear();
Вывод информации о браузере

Данные о пользовательском браузере включают в себя:

  • название и версию браузера, для определения которого используется не строка User Agent, а JS hacks;
  • поддержку Flash и Cookies;
  • поддержку интерфейсов touchEvent и pointerEvent;
  • ориентацию экрана, если этот параметр доступен;
  • проверку на устаревшую версию браузера (Opera <= 12.x, Safari <= 9.x, Chrome <= 26, IE <= 11);
  • наличие активного блокировщика рекламы — AdBlock, uBlock Origin и т. п.
console.log(_.ua()); // => { browser: "firefox", version: 63, cookies: true, flash: false, adblock: true, old: false, touch: false, pointer: true, orientation: "landscape-primary" }
Обработка дополнительных событий

Метод _.on() может принимать не только стандартные, но и дополнительные события, для которых обеспечена широкая кроссбраузерность — на текующий момент это swipe и visibilitychange:

  • событие swipe поддерживает различные типы указателей, включая мышь, и передаёт информацию о направлении, времени и дистанции жеста;
  • событие, отслеживающее видимость страницы, представляет собой удобную обертку для Page Visibility API.
// swipe event
_("#element").on("swipe", function(e) {
  if(e.detail.dir === "left" && e.details.dist > 100) console.log("Свайп влево на 101+ пикселей");
});

// page visibility
_(document).on("visibilitychange", function() {
  if(document[hidden]) console.log("Пользователь не видит вкладку");
});
Парсинг метатегов

Из <head> может быть получено содержимое таких метатегов как:

  • title, description, keywords, robots;
  • OpenGraph, Facebook, Twitter;
  • дополнительно проверяется URL, наличие защищенного соединения (HTTPS) и способ отображения документа в качестве фрейма.
var meta = _.meta();
  console.log(meta.opengraph); // => { description: "", image: "", site_name: "", title: "", url: "" }
  console.log(meta.isIframe);  // => false
  console.log(meta.isHttps);   // => true
Перетаскивание элементов

Реализация drag — функции перетаскивания элементов в пределах заданного блока, по опредленным осям и с возможностью добавления callback-функций на всех стадиях (ondragstart, ondrag и ondragend):

_.drag(myElement,{
  restrict: myWrapperElement,
  onStart: function(e) {
    console.log(e);
  },
  axisX: false
});
Работа с cookies

Легкое манипулирование cookies — чтение, добавление с указанием срока и удаление соответствующих записей.

_.cookie({ key: "my_cookie_name", val: "cookie_value", min: 7200 }); // установит cookie на 5 дней
_.cookie({ key: "my_cookie_name" }); // проверит, существует ли cookie с таким именем и вернет true/false
_.cookie({ key: "my_cookie_name", del: true }); // удалит cookie
Генерация браузерных уведомлений

Онлайн уведомления в браузере представляют собой простую и удобную в использовании реализацию Notifications API — браузерных сообщений, показываемых на рабочем столе пользователя вне зависимости от видимости текущей вкладки. При первом запуске автоматически спросит пользователя о разрешении отображения уведомлений от сайта:

_.live({
  head:    "Заголовок уведомления",
  text:    "Текст уведомления",
  icon:    "my-icon.png",
  onclick: function() {}
});
Наложение на документ вертикальной сетки

Инструмент для создания вертикальной сетки позволяет наложить на страницу вертикальный ритм в виде линий настраиваемого цвета, расположенных на заданном одинаковом расстоянии друг от друга. Для удобства основная сетка может быть разделена на вдвое меньшее деление:

_.rhythm({
  size:  24,
  color: "rgba(255, 51, 102, .75)",
  mid:   true
});
Отложенная загрузка изображений и фреймов

Встроенная функция lazy-load позволяет подгружать изображения или фреймы в нескольких режимах:

  • когда элементы окажутся хотя бы частично видимыми во viewport пользователя;
  • по событию click;
  • при навдении указателя мыши — mouseover.
_.lazy({
  items: "[data-js-lazy]",
  onview: true // загрузка при попадании во viewport
});
Подключение на страницу скриптов

Асинхронное подключение файлов JS через элементы <script> позволяет легко отследить готовность скриптов (событие load) или проинформировать об ошибке (событие error) загрузки и выполнить заданные функции. Также доступна настройка, позволяющая загружать скрипты только при заданных CSS-правилах @media:

_.script({
  src:    "path/to/my_script.js",
  onload: function(e) {
    console.log("Скрипт my_script.js загрузился на мобильном устройстве")
  },
  media: "(max-width: 480px)"
});
Проверка экрана на соответствие медиа-запросу

Простая и удобная проверка указанного выражения @media. Может понадобиться, например, в случаях, когда опредленный JS-код должен быть исполнен только на мобильных устройствах:

if(_.mq("(max-width: 900px)")) console.log("Ширина окна не превышает 900px");
Манипулирование текстовой кареткой

Кроссбраузерный метод _.caret() позволяет установить каретку в два положения — за элемент или внутрь элемента, а также выделить весь текст или его часть в указанном элементе. Работает как со стандартными <input />, <textarea>, так и с элементами, обладающих атрибутом contenteditable:

_(my_element).caret(); // устанавливает каретку внутрь элемента
_(my_element).caret("after");     // устанавливает каретку после элемента
_(my_element).caret("select");    // выделяет текст в элементе
Открытие окон и вкладок

Методы _.win() и _.tab() позволяют открывать всплывающие окна заданных размеров и новые вкладки:

_.win({
  w:    640,
  h:    480,
  url:  "https://web3r.ru/",
  name: "blog"
});

_.tab({
  url:  "https://web3r.ru/w3b",
  name: "w3b"
});
Генерация случайных чисел

Вывод случайного числа из данного промежутка. Может быть полезен при присвоении элементам каких-либо уникальных значений:

var my_number = _.rand(1, 1000); // случайное число между 1 и 1000
Парсинг параметров URL

Благодаря методу _.param() можно получить значение параметров, которые содержатся в URL:

// https://web3r.ru/?hello=world
_.param("hello"); // => "world"
Проверка видимости элемента во viewport

Для проверки видимости элемента предусмотрен метод _.inViewport(), в который может быть передан параметр, указывающий на проверку элемента целиком, а не только его отдельной части:

if(_("#my_block").inViewport())  console.log("Элемент #my_block частично видим пользователем");
if(_("#my_block").inViewport(1)) console.log("Элемент #my_block полностью на экране пользователя");
Встроенные полифиллы

Для совместимости старых брауеров с EcmaScript 6 в билиотеку встроены полифиллы для Object.assign(), Object.values(), Object.keys(), Element.remove(), String.endsWith(), String.startsWith(), Element.matches(), CustomEvent(). Таким образом, они могут быть без проблем использованы в дальнейшем js-коде.

API — основные функции

Метод Аргументы Описание и пример
_(el).length() Возвращает количество элементов, содержащихся в объекте.

_("div").length(); // посчитает количество блоков <div> в документе
_(el).append() node Добавляет указанный элемент node в конец дочерних элементов el.

var s = document.createElement("span");
_("div").append(s); // добавит дочерний <span> в каждый элемент <div> после всех его потомков
_(el).prepend() node Добавляет указанный элемент node в начало дочерних элементов el.

var s = document.createElement("span");
_("div").prepend(h); // добавит дочерний <span> в каждый элемент <div> перед всеми его потомками
_(el).insert() position, html Вставляет HTML в DOM на указанной позиции.

_("#content").insert("afterend","<div><img src='img.gif' alt='My image' /></div>"); // вставит указанные узлы сразу после #content
_(el).next() Возвращает соседний элемент после указанного.

_("ul").next(); // вернет элемент, следующий за первым <ul>
_(el).prev() Возвращает соседний элемент перед указанным.

_("ul").prev(); // вернет элемент, следующий перед первым <ul>
_(el).first() Возвращает первый элемент, содержащийся в объекте.

_("p").first(); // вернет первый найденный элемент <p>
_(el).last() Возвращает последний элемент, содержащийся в объекте.

_("p").last(); // вернет последний найденный элемент <p>
_(el).get() number Возвращает указанный по номеру элемент, содержащийся в объекте.

_("p").get(9); // вернет девятый найденный элемент <p>
_(el).text() text Вставляет или получает простой текст из указанного элемента.

_("#content").text("Lorem Ipsum"); // установит текст для #content
_("#content").text(); // вернёт текстовое содержимое из #content
_(el).html() html, useFragment Вставляет или получает HTML из указанного элемента.

_("#content").html("<div></div>"); // вставит HTML в #content
_("#content").html("<div></div>",true); // вставит указанный HTML в #content с использованием documentFragment (предпочтительнее для большого количества узлов)
_("#content").html(); // вернет содержимое HTML из #content
_(el).node() settings Создание нового элемента DOM.

_("p").node({"name":"img","src":"image.gif","alt":"Image"}); // вставит изображение в каждый элемент <p>
_().node({"name":"img","src":"image.gif","alt":"Image"}); // создаст и вернёт изображение
_(el).clear() element Очищает у элемента все или только указанные дочерние узлы.

_("#contant").clear(); // удалит из #content все дочерние элементы
_("#content").clear("span"); // удалит из #content только теги <span>
_(el).inViewport() isFull Проверят видимость элемента во viewport и выводит true / false.

_("#header").inViewport(); // проверит, видим ли на экране #header хотя бы частично
_("#header").inViewport(true); // проверит, видим ли на экране #header полностью
_(el).caret() act Устанавливает каретку в указанное положение или выделяет текст в элементе.

_(el).caret("after"); // установит каретку сразу после элемента
_(el).caret(); // установит каретку внутри элемента
_(el).caret("select"); // выделит текст внутри элемента
_(el).parent() Возвращает родительский элемент заданного элемента.

_("#block").parent(); // вернет родительский элемент для #block
_(el).is() selector Проверяет соответствие элемента CSS-селектору и возвращает true / false.

_("h1").is("#title"); // проверит, обладает ли первый найденный <h1> идентификатором #title
_(el).on() event, listener Регистрирует указанный обработчик события на элемент.

_("div").on("click",function() {
  alert("Click");
}); // установит для всех блоков <div> событие onclick
_(el).off() event, listener Удаляет указанный обработчик события с элемента.

_("div").off("hover",function() {
  alert("Click");
}); // удалит для всех блоков <div> событие onhover
_(el).each() function Выполняет указанную функцию для каждого объекта.

_("p").each(function(el, i, array) {
  el.classList.add("number-" + i);
}); // установит класс "number-N" с порядковым номером для всех <p>
_(el).addClass() classnames Добавляет CSS класс(ы) к элементу.

_("div").addClass("one two"); // добавит классы "one", "two" для всех <div> (по аналогии с element.classList.add(""))
_(el).removeClass() classnames Удаляет CSS класс(ы) у элемента.

_("div").removeClass("one two");// удалит классы "one", "two" у всех <div> (по аналогии с element.classList.remove(""))
_(el).toggleClass() classnames Переключает CSS класс(ы) элемента.

_("div").toggleClass("one two"); // переключит классы "one", "two" для всех <div> (по аналогии с element.classList.toggle(""))
_(el).hasClass() classnames Проверяет наличие CSS класса у элемента и возвращает true или false.

_("div").hasClass("one"); // проверит наличие класса "one" у первого <div> (по аналогии с element.classList.contains(""))
_(el).attr() name, value Устаналивает элементу атрибут или возвращает его значение.

_("input").attr("spellcheck","true"); // установит для всех <input> атрибут spellcheck="true"
_("input").attr("maxlength"); // вернёт значение атрибута maxlength у первого <input>
_(el).removeAttr() name Удаляет атрибут у элемента.

_("input").removeAttr("disabled"); // удалит у всех <input> атрибут disabled="true"
_(el).hasAttr() name Проверяет наличие атрибута у элемента и возвращает true или false.

_("div").hasAttr("data-test"); // вернет true, если первый <div> имеет атрибут data-test
_(el).show() Делает элемент визуально видимым.

_("#content").show(); // применит свойства visibilty: visible и opacity: 1 для элемента с идентификатором #content
_(el).hide() Визуально скрывает элемент.

_("span").hide(); // применит свойства visibilty: hidden и opacity: 0 для всех элементов <span>
_(el).CSS() name, rules
rule
rule, property
Устанавливает или выводит значение свойства CSS для элемента.

_("#header").CSS({"color":"#fff","background":"#000"}); // установит для элемента #header соответствующие стили
_("#header").CSS("display"); // вернет значение "display" для #header
_("#header").CSS("display","none"); // установит значение свойства "display" как "none" для #header

Поддержка браузерами

W3b.js работает во всех современных браузерах. Благодаря встроенным полифиллам дополнительно обеспечена поддержка Internet Explorer 10+ и Opera 12.

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

Бибилотека еще не готова для полноценного использования и доступна лишь в альфа-версии для тестирования основных функций. Бета-версия и подробная документация появятся на GitHub в самом скором времени.

Для подключения скрипта добавьте следующий код сразу перед закрывающим тегом </body>:

<script src="https://web3r.ru/js/w3b.min.js?0.0.9"></script>