ran
فارسی

DOM مجازی (vnode)

یک DOM مجازی سبک به سبک Snabbdom. رابط کاربری تو را با شیءهای ساده جاوااسکریپت (همان VNodeها) نشان می‌دهد، درخت کهنه را با درخت نو می‌سنجد و فقط تفاوت‌ها را بر DOM واقعی می‌نشاند.

  • init() سازوکار هم‌سنجی را برپا می‌کند و یک تابع patch برمی‌گرداند. ماژول‌های همراه (class / props / attrs / style / events) خودبه‌خود ثبت می‌شوند.
  • patch(oldVnode, newVnode) اگر oldVnode عنصری واقعی از DOM باشد درخت را سوار می‌کند، وگرنه دو درخت vnode را می‌سنجد و DOM را همان‌جا به‌روز می‌کند.
  • h(sel, dataOrChildren?, children?) همان یاری‌رسان hyperscript است که VNode می‌سازد.

وارد کردن

import { init, h, classModule, propsModule, styleModule, eventListenersModule } from 'ranuts/vnode';

نکته: در این پیاده‌سازی init() هیچ آرگومانی نمی‌گیرد: مجموعهٔ ماژول‌ها ثابت است و در درون ثبت می‌شود، پس لازم نیست تک‌تک صادرات‌های *Module را به init بدهی. آن‌ها برای مراجعه و وارسی صادر شده‌اند.

نمونه

آغاز سریع

import { init, h } from 'ranuts/vnode';

// init() یک تابع `patch` برمی‌گرداند.
// ماژول‌های همراه (class، props، attrs، style، events) خودبه‌خود ثبت می‌شوند.
const patch = init();

const container = document.getElementById('app');

// ساختن یک درخت vnode
let vnode = h('div#app.container', { style: { color: 'red' } }, [
  h('h1', 'Hello vnode'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Click me'),
]);

// رسم نخست: به‌جای vnode کهنه یک عنصر واقعی DOM بده تا درخت درون آن سوار شود
patch(container, vnode);

// بعدها: درخت به‌روزشده را بساز و vnode پیشین را روی آن patch کن.
// تنها تفاوت‌ها (متن، سبک، شنونده‌ها) بر DOM می‌نشیند.
const newVnode = h('div#app.container', { style: { color: 'green' } }, [
  h('h1', 'Hello again'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Updated'),
]);

patch(vnode, newVnode);
vnode = newVnode; // تازه‌ترین درخت را برای patch بعدی نگه دار

ساختن گره با h

// فقط برچسب
h('div');

// برچسب + data
h('div', { class: { active: true } });

// برچسب + یک فرزند متنی
h('span', 'hello');

// برچسب + آرایه‌ای از فرزندان
h('ul', [h('li', 'one'), h('li', 'two')]);

// برچسب + data + فرزندان
h('a', { attrs: { href: '/home' } }, 'Home');

// گزینشگرهای به سبک CSS، شناسه و کلاس‌ها را تعیین می‌کنند
h('div#main.card.large', 'content'); // <div id="main" class="card large">content</div>

// اگر گزینشگر با "svg" آغاز شود، فضای‌نام SVG خودبه‌خود اعمال می‌شود
h('svg', { attrs: { width: 100, height: 100 } }, [h('circle', { attrs: { cx: 50, cy: 50, r: 40 } })]);

API

init()

سازوکار هم‌سنجی را می‌سازد و یک تابع patch برمی‌گرداند. ماژول‌های همراه در درون ثبت می‌شوند و خودش آرگومانی نمی‌گیرد.

بازگشت

مقدار توضیح نوع
patch درخت‌های vnode را بر DOM واقعی سوار یا با آن هم‌سنجی می‌کند (oldVnode: VNode | Element, vnode: VNode) => VNode

patch(oldVnode, vnode)

همان چیزی است که init() برمی‌گرداند. در نخستین فراخوان، به‌جای oldVnode یک Element واقعی از DOM بده تا درخت درون آن سوار شود. در فراخوان‌های بعدی، VNode پیشین را بده تا همان‌جا سنجیده و به‌روز شود. VNode تازه را برمی‌گرداند که آن را به‌عنوان مقدار «کهنه» برای فراخوان بعدی نگه می‌داری.

پارامترها

پارامتر توضیح نوع
oldVnode vnode پیشین، یا در نخستین سوار شدن یک عنصر DOM VNode | Element
vnode درخت vnode تازه‌ای که باید رسم شود VNode

h(sel, dataOrChildren?, children?)

یاری‌رسان hyperscript که یک VNode می‌سازد. چند شکل دارد:

امضا توضیح
h(sel) عنصری که فقط از یک گزینشگر ساخته می‌شود
h(sel, data) عنصری همراه با VNodeData (که data می‌تواند null باشد)
h(sel, children) عنصری همراه با فرزندان: یک متن یا عدد، یک VNode، یا یک آرایه
h(sel, data, children) عنصری همراه با داده و فرزندان

پارامترها

پارامتر توضیح نوع
sel گزینشگر به سبک CSS: tag، tag#id، tag.class و ترکیب آن‌ها (div#id.a.b). با svg… فضای‌نام SVG خودبه‌خود افزوده می‌شود string
data دادهٔ گره: class / props / attrs / style / شنونده‌ها / key / hook. می‌تواند null باشد VNodeData | null
children یک متن یا عدد (که گرهٔ متنی می‌شود)، یک VNode تنها، یا آرایه‌ای از آن‌ها VNodeChildren

فیلدهای VNodeData

میدان توضیح نوع اعمال‌کننده
props ویژگی‌های DOM که با elm[key] = value گذاشته می‌شوند Record<string, any> propsModule
attrs صفت‌های HTML که با setAttribute گذاشته می‌شوند (true و false صفت را می‌گذارند و برمی‌دارند) Record<string, string | number | boolean> attributesModule
class کلاس‌های شرطی: نگاشتی از نوع name → boolean Record<string, boolean> classModule
style سبک‌های درون‌خطی: نگاشتی از نوع name → value (کلیدهای --var به متغیرهای CSS بدل می‌شوند) Record<string, any> styleModule
on شنونده‌های رویداد: event → handler (یا آرایه‌ای از دستگیره‌ها) Record<string, Function | Function[]> eventListenersModule
key نشانی پایدار که الگوریتم هم‌سنجی برای جفت کردن و جابه‌جا کردن فرزندان به کار می‌برد string | number (هستهٔ هم‌سنجی)
ns نشانی فضای‌نام (در زیردرخت‌های SVG خودبه‌خود گذاشته می‌شود) string (هستهٔ هم‌سنجی)
hook قلاب‌های چرخهٔ عمر برای هر vnode (Hooks) Hooks (فقط در سطح نوع: نکته را ببین)

نکته: hook و نوع Hooks بخشی از سطح عمومی نوع‌ها هستند. اما این پیاده‌سازی پیراسته، DOM را از راه چرخهٔ عمر ماژول‌ها (create / update / destroy) می‌گرداند؛ فراخوان‌های data.hook که به هر vnode بسته‌اند، در حلقهٔ کنونی patch صدا زده نمی‌شوند.

ماژول‌ها

هر ماژول متولی یک تکه از VNodeData است. init() همهٔ آن‌ها را ثبت می‌کند؛ ضمناً تک‌تک هم صادر شده‌اند.

صادرات متولی توضیح
classModule data.class بر پایهٔ نگاشت name → boolean کلاس‌ها را می‌گذارد و برمی‌دارد
propsModule data.props ویژگی‌های DOM را یکراست نسبت می‌دهد (elm[key] = value)
attributesModule data.attrs صفت‌های HTML را با setAttribute می‌گذارد و برمی‌دارد (از جمله xml و xlink)
styleModule data.style سبک‌های درون‌خطی و ویژگی‌های سفارشی CSS را می‌گذارد
eventListenersModule data.on شنونده‌های رویداد را می‌چسباند و برمی‌دارد
modules — شیء ثبت پیش‌فرض که نام هر ماژول را به خودِ ماژول می‌نگارد

صادرات‌های لایهٔ پایین‌تر

صادرات نوع توضیح
vnode (sel, data, children, text, elm) => VNode کارخانهٔ سطح‌پایین VNode که h در درون به کار می‌برد. در کد برنامه h را ترجیح بده.
addNS (data, children, sel) => void فضای‌نام SVG را بازگشتی بر یک زیردرخت اعمال می‌کند. برای گزینشگرهای svg… خودِ h آن را صدا می‌زند.
htmlDomApi DOMAPI مبدل پیش‌فرض DOM مرورگر که patch در درون به کار می‌برد (ساختن، درج، حذف، گره‌های متنی و…).
is { array, isStr, primitive, isVnode } یاری‌رسان‌های کوچک پاسداری از نوع که در سراسر درون vnode به کار می‌روند.
Chain class Chain سازندهٔ دستوری و زنجیره‌پذیر DOM (setAttribute، append، setTextContent و…). به هم‌سنجی vnode ربطی ندارد.
create (tagName, options?) => Chain کارخانه‌ای برای راحتی کار که یک Chain تازه برمی‌گرداند.

نوع‌ها

نوع شکل و معنا
VNode { sel, data, children, elm, text, key, listener? }: یک گرهٔ مجازی
VNodeData { props?, attrs?, class?, style?, on?, key?, ns?, hook? }: فیلدها را در بالا ببین
VNodes VNode[]
VNodeChildElement VNode | string | number
VNodeChildren VNodeChildElement | VNodeChildElement[]
ArrayOrElement<T> T | T[]
Key string | number
Hooks { pre?, init?, create?, insert?, prepatch?, update?, postpatch?, destroy?, remove?, post? }
DOMAPI واسطی که عملیات DOM مورد استفادهٔ patch را وصف می‌کند (htmlDomApi را ببین)
Fragment گسترشی بر DocumentFragment برای کار با قطعه‌ها
Modules Record<string, Record<string, ModuleHook>>: شکل دفتر ثبت ماژول‌ها
ModuleHook یک فراخوان تنها از چرخهٔ عمر یک ماژول

یادداشت‌ها

  1. فقط مرورگر. ranuts/vnode به document و APIهای DOM دست می‌زند؛ آن را در کد مرورگر وارد کن، نه در Node.
  2. آخرین vnode را نگه دار. patch همان VNode تازه را برمی‌گرداند. آن را ذخیره کن و در به‌روزرسانی بعدی به‌عنوان oldVnode بده تا تفاوت‌ها نسبت به درخت کنونی سنجیده شود.
  3. در یک VNode، text و children با هم جمع نمی‌شوند: هر گره یا گرهٔ متنی است یا عنصری با فرزند.
  4. برای فهرست‌ها key بگذار. وقتی فهرستی پویا را می‌کشی، به هم‌نیاها مقدارهای key پایدار بده تا هم‌سنجی بتواند گره‌ها را جفت و جابه‌جا کند به‌جای آنکه از نو بسازد.