apiReference.md

مرجع API

این مستند، API عمومی ویرایشگر «دبیر» را به تفصیل شرح می‌دهد.

کلاس DabirEditor

این کلاس اصلی ویرایشگر است و نقطه ورود برای تمام تعاملات با آن محسوب می‌شود.

---

new DabirEditor(selector, options)

یک نمونه جدید از ویرایشگر را ایجاد و راه‌اندازی می‌کند.

• selector (string): سلکتور CSS برای المان div که ویرایشگر باید در آن رندر شود. باید یک رشته غیرخالی معتبر باشد.
• options (object, اختیاری): یک آبجکت برای پیکربندی ویرایشگر. تمام ورودی‌ها اعتبارسنجی می‌شوند. برای جزئیات کامل به راهنمای تنظیمات مراجعه کنید.

مثال

import DabirEditor from './src/index.js';

const editor = new DabirEditor('#my-editor', {
    placeholder: 'اینجا بنویسید...'
});

---

getHTML()

محتوای فعلی ویرایشگر را به صورت یک رشته HTML خام برمی‌گرداند.

• بازگشتی: string - محتوای HTML ویرایشگر.

مثال

const currentHtml = editor.getHTML();
console.log(currentHtml);
// <p>این یک <strong>متن</strong> است.</p>

---

getMarkdown()

محتوای فعلی ویرایشگر را به مارک‌داون تبدیل کرده و برمی‌گرداند.

• بازگشتی: string - محتوای مارک‌داون ویرایشگر.

مثال

const markdownContent = editor.getMarkdown();
console.log(markdownContent);
// این یک **متن** است.

---

setContent(content, format)

محتوای ویرایشگر را تنظیم می‌کند. این متد محتوای فعلی را به طور کامل با محتوای جدید جایگزین می‌کند. نکته امنیتی: محتوای ورودی (چه HTML و چه مارک‌داون) برای جلوگیری از حملات XSS به صورت خودکار پاکسازی (Sanitize) می‌شود و تگ‌های خطرناک حذف می‌گردند.

• content (string): محتوای جدید برای تنظیم.
• format (string, اختیاری): فرمت محتوای ورودی. می‌تواند 'html' یا 'markdown' باشد. پیش‌فرض 'markdown' است.

مثال

// تنظیم محتوا با مارک‌داون
editor.setContent('## عنوان جدید\n\nاین یک پاراگراف جدید است.');

// تنظیم محتوا با HTML (تگ‌های <script> حذف خواهند شد)
editor.setContent('<h2>عنوان جدید</h2><p>این یک پاراگراف جدید است.</p>', 'html');

---

saveContent()

محتوای فعلی ویرایشگر را به صورت دستی در حافظه محلی (localStorage) ذخیره می‌کند. این متد تنها در صورتی کار می‌کند که ذخیره‌سازی در تنظیمات فعال باشد و ویرایشگر تخریب نشده باشد.

مثال

// یک تغییر در محتوا ایجاد کنید
editor.setContent('محتوای مهمی که باید ذخیره شود.');
// و آن را به صورت دستی ذخیره کنید
editor.saveContent();

---

on(eventName, listener)

یک تابع شنونده (listener) برای یک رویداد خاص ثبت می‌کند.

• eventName (string): نام رویدادی که می‌خواهید به آن گوش دهید.
• listener (Function): تابعی که در زمان وقوع رویداد فراخوانی می‌شود.

مثال

editor.on('change', (data) => {
    console.log('محتوا تغییر کرد!');
    console.log('HTML:', data.html);
    console.log('Markdown:', data.markdown);
});

---

use(Plugin, options)

یک پلاگین را به ویرایشگر اضافه و نصب می‌کند. عملیات نصب در یک بلوک ایمن انجام می‌شود تا خطای احتمالی پلاگین باعث توقف برنامه نشود.

• Plugin (Plugin): کلاس پلاگینی که باید نصب شود.
• options (object, اختیاری): تنظیمات مخصوص پلاگین.

مثال

import { EmojiPlugin } from './plugins/emojiPlugin.js';

// افزودن پلاگین پس از راه‌اندازی اولیه
editor.use(EmojiPlugin);

---

destroy()

ویرایشگر را تخریب کرده و تمام منابع مصرفی را آزاد می‌کند. این متد برای جلوگیری از نشت حافظه (Memory Leak) در برنامه‌های تک‌صفحه‌ای (SPA) بسیار حیاتی است.

عملیات انجام شده:

1. حذف تمام شنونده‌های رویداد (Event Listeners) از DOM.
2. توقف تایمرهای فعال (مانند ذخیره خودکار).
3. پاکسازی مراجع به DOM و متغیرها.
4. فراخوانی متد destroy پلاگین‌ها.

مثال

// زمانی که کاربر از صفحه خارج می‌شود
editor.destroy();

رویدادها (Events)

شما می‌توانید با استفاده از متد on() به رویدادهای زیر گوش دهید:

نام رویداد	توضیحات	پارامترهای Listener
ready	زمانی که ویرایشگر به طور کامل راه‌اندازی و آماده استفاده است، فراخوانی می‌شود.	-
load	زمانی که محتوای اولیه (از حافظه یا پیش‌فرض) در ویرایشگر بارگذاری می‌شود.	(editor: DabirEditor)
change	زمانی که محتوای ویرایشگر ذخیره می‌شود (معمولاً پس از یک وقفه کوتاه بعد از تایپ).	(data: { html: string, markdown: string })
input	بلافاصله پس از هر ورودی کاربر (تایپ، حذف و غیره) فراخوانی می‌شود.	-
contentSet	زمانی که محتوای ویرایشگر با استفاده از متد setContent() تغییر می‌کند.	-
paste	زمانی که متنی در ویرایشگر چسبانده (paste) می‌شود.	(data: { text: string, html: string })
copy	زمانی که متنی از ویرایشگر به صورت مارک‌داون کپی می‌شود.	(data: { markdown: string })
render:replace	(داخلی) زمانی که یک گره DOM با گره دیگری جایگزین می‌شود.	(data: { oldNode: Node, newNode: Node })