virtual-dom README

The project's README from github.com/Matt-Esch/virtual-dom. As one markdown file: README.md.

virtual-dom

A JavaScript DOM model supporting element creation, diff computation and patch operations for efficient re-rendering

build status NPM version Coverage Status Davis Dependency status experimental Join the chat at https://gitter.im/Matt-Esch/virtual-dom

Sauce Test Status

Motivation

Manual DOM manipulation is messy and keeping track of the previous DOM state is hard. A solution to this problem is to write your code as if you were recreating the entire DOM whenever state changes. Of course, if you actually recreated the entire DOM every time your application state changed, your app would be very slow and your input fields would lose focus.

virtual-dom is a collection of modules designed to provide a declarative way of representing the DOM for your app. So instead of updating the DOM when your application state changes, you simply create a virtual tree or VTree, which looks like the DOM state that you want. virtual-dom will then figure out how to make the DOM look like this efficiently without recreating all of the DOM nodes.

virtual-dom allows you to update a view whenever state changes by creating a full VTree of the view and then patching the DOM efficiently to look exactly as you described it. This results in keeping manual DOM manipulation and previous state tracking out of your application code, promoting clean and maintainable rendering logic for web applications.

Example

var h = require('virtual-dom/h');
var diff = require('virtual-dom/diff');
var patch = require('virtual-dom/patch');
var createElement = require('virtual-dom/create-element');

// 1: Create a function that declares what the DOM should look like
function render(count)  {
    return h('div', {
        style: {
            textAlign: 'center',
            lineHeight: (100 + count) + 'px',
            border: '1px solid red',
            width: (100 + count) + 'px',
            height: (100 + count) + 'px'
        }
    }, [String(count)]);
}

// 2: Initialise the document
var count = 0;      // We need some app data. Here we just store a count.

var tree = render(count);               // We need an initial tree
var rootNode = createElement(tree);     // Create an initial root DOM node ...
document.body.appendChild(rootNode);    // ... and it should be in the document

// 3: Wire up the update logic
setInterval(function () {
      count++;

      var newTree = render(count);
      var patches = diff(tree, newTree);
      rootNode = patch(rootNode, patches);
      tree = newTree;
}, 1000);

View on RequireBin

Documentation

You can find the documentation for the seperate components in their READMEs

For information about the type signatures of these modules feel free to read the javascript signature definition

DOM model

virtual-dom exposes a set of objects designed for representing DOM nodes. A "Document Object Model Model" might seem like a strange term, but it is exactly that. It's a native JavaScript tree structure that represents a native DOM node tree. We call this a VTree

We can create a VTree using the objects directly in a verbose manner, or we can use the more terse virtual-hyperscript.

Example - creating a VTree using the objects directly

var VNode = require('virtual-dom/vnode/vnode');
var VText = require('virtual-dom/vnode/vtext');

function render(data) {
    return new VNode('div', {
        className: "greeting"
    }, [
        new VText("Hello " + String(data.name))
    ]);
}

module.exports = render;

Example - creating a VTree using virtual-hyperscript

var h = require('virtual-dom/h');

function render(data) {
    return h('.greeting', ['Hello ' + data.name]);
}

module.exports = render;

The DOM model is designed to be efficient to create and read from. The reason why we don't just create a real DOM tree is that creating DOM nodes and reading the node properties is an expensive operation which is what we are trying to avoid. Reading some DOM node properties even causes side effects, so recreating the entire DOM structure with real DOM nodes simply isn't suitable for high performance rendering and it is not easy to reason about either.

A VTree is designed to be equivalent to an immutable data structure. While it's not actually immutable, you can reuse the nodes in multiple places and the functions we have exposed that take VTrees as arguments never mutate the trees. We could freeze the objects in the model but don't for efficiency. (The benefits of an immutable-equivalent data structure will be documented in vtree or blog post at some point)

Element creation

createElement(tree:VTree) -> DOMNode

Given that we have created a VTree, we need some way to translate this into a real DOM tree of some sort. This is provided by create-element.js. When rendering for the first time we would pass a complete VTree to create-element function to create the equivalent DOM node.

Diff computation

diff(previous:VTree, current:VTree) -> PatchObject

The primary motivation behind virtual-dom is to allow us to write code independent of previous state. So when our application state changes we will generate a new VTree. The diff function creates a set of DOM patches that, based on the difference between the previous VTree and the current VTree, will update the previous DOM tree to match the new VTree.

Patch operations

patch(rootNode:DOMNode, patches:PatchObject) -> DOMNode newRootNode

Once we have computed the set of patches required to apply to the DOM, we need a function that can apply those patches. This is provided by the patch function. Given a DOM root node and a set of DOM patches, the patch function will update the DOM. After applying the patches to the DOM, the DOM should look like the new VTree.

Original motivation

virtual-dom is heavily inspired by the inner workings of React by facebook. This project originated as a gist of ideas, which we have linked to provide some background context.

Tools

virtual-dom (Matt-Esch/virtual-dom)

Searching Database…

11.8K ·GitHub
Virtual-dom
Что это такое?virtual-dom — это JavaScript-библиотека, которая моделирует DOM: вы описываете нужный интерфейс в виде виртуального дерева (VTree), а она эффективно создаёт, сравнивает и обновляет настоящий DOM, чтобы перерисовка была быстрой.
Это фреймворк, который забирает себе всё приложение целиком, или библиотека, которую я вызываю напрямую?Это библиотека, а не фреймворк — набор модулей, которые вы подключаете сами: h.js (virtual-hyperscript) описывает узлы, create-element.js строит настоящий DOM из VTree, diff.js вычисляет изменения (патчи), а patch.js применяет их.
Как добавить её в проект?Установите npm-пакет (npm install virtual-dom) и подключите его через require; также собирается отдельная браузерная сборка (dist/virtual-dom.js). Документация по каждому модулю лежит в его собственном README (vdom, vtree, virtual-hyperscript).
Чтобы она работала, нужно что-то тяжёлое — сборка, нативный код или сервер?Нет — это обычный npm-пакет на чистом JavaScript, а его зависимости — только небольшие утилиты (browser-split, error, ev-store, global, is-object, next-tick, x-is-array, x-is-string); никакого нативного кода, Python или внешних сервисов.
Когда состояние моего приложения меняется, оно само перерисовывает интерфейс?Нет, всем управляете вы: при каждом изменении состояния нужно самому построить новое VTree, затем вызвать diff со старым деревом и применить патчи к DOM. Деревья неизменяемые по смыслу — доступные функции никогда не меняют их, поэтому стройте новое дерево, а не правьте старое.
Как обновление проходит через create-element, diff и patch?Первый рендер: передаёте полное VTree в create-element и получаете настоящий DOM-узел. При обновлениях: строите новое VTree, вызываете diff(previousTree, newTree), чтобы получить патчи, затем patch(rootNode, patches) обновляет DOM так, чтобы он соответствовал новому дереву.
Зачем сравнивать виртуальные деревья вместо того, чтобы менять настоящий DOM напрямую?Создание DOM-узлов и чтение их свойств — дорогие операции, а чтение некоторых свойств даже вызывает побочные эффекты. Деревья на чистом JavaScript создавать и читать дёшево, поэтому библиотека вычисляет разницу между деревьями и трогает DOM только там, где что-то изменилось.
Как она связана с React?Она во многом вдохновлена внутренним устройством React от Facebook, но это независимый набор модулей. Проект начинался как gist с идеями — README даёт на него ссылку как на дополнительный контекст.
Могу ли я перевести свою готовую HTML-разметку для работы с ней?Да — в README упомянуты html2hscript (с онлайн-конвертером на html2hscript.herokuapp.com) и консольная утилита html2hyperscript: они разбирают фрагменты HTML и старую разметку и превращают их в hyperscript для построения VTree.
What are similar projects?marked, inferno, typeahead.js, Sortable, masonry, velocity, snabbdom, lit
Which topics is it in?diff, dom, rendering, javascript-library, browser, developers, html, ui, web-development, performance, npm, frontend
Creator
Matt-Esch
Size
0.8 MB
Stars
11.8K
Updated
CommitApr 22
Age
12y
Commits · 90 Days