آموزش جامع Quill.js

📚معرفی و نصب

Quill.js یکی از بهترین Rich Text Editorهای جاوااسکریپت است. رابط API بسیار ساده، معماری ماژولار، پشتیبانی بومی از RTL و Delta format اختصاصی آن را از رقبا متمایز می‌کند.

مقایسه با رقبا

نصب

<!-- CSS (باید قبل از JS باشد) -->
<link rel="stylesheet" href="quill.snow.css">
<!-- یا -->
<link rel="stylesheet" href="quill.bubble.css">

<!-- JS -->
<script src="quill.min.js"></script>

ساده‌ترین راه‌اندازی

<!-- HTML -->
<div id="editor"></div>

// JavaScript
const quill = new Quill('#editor', {
  theme: 'snow',
  placeholder: 'متن خود را اینجا بنویسید...'
});

🎨Themes

Quill دو theme اصلی دارد: Snow (toolbar ثابت بالا) و Bubble (tooltip روی متن انتخابی).

// Snow theme
const snowEditor = new Quill('#snow', {
  theme: 'snow',
  placeholder: 'Snow theme...'
});

// Bubble theme — نیاز به quill.bubble.css
const bubbleEditor = new Quill('#bubble', {
  theme: 'bubble',
  placeholder: 'متن را انتخاب کنید...'
});

🔧Toolbar سفارشی

می‌توانید دقیقاً تعیین کنید چه دکمه‌هایی در toolbar باشند:

const quill = new Quill('#editor', {
  theme: 'snow',
  modules: {
    toolbar: [
      ['bold', 'italic', 'underline', 'strike'],    // فرمت‌های متن
      ['blockquote', 'code-block'],
      [{ header: 1 }, { header: 2 }],                  // عناوین H1, H2
      [{ list: 'ordered'}, { list: 'bullet' }],
      [{ script: 'sub'}, { script: 'super' }],          // زیرنویس، بالانویس
      [{ indent: '-1'}, { indent: '+1' }],               // indent
      [{ direction: 'rtl' }],                              // جهت متن
      [{ size: ['small', false, 'large', 'huge'] }],     // اندازه فونت
      [{ header: [1,2,3,4,5,6,false] }],               // همه عناوین
      [{ color: [] }, { background: [] }],                   // رنگ متن و پس‌زمینه
      [{ font: [] }],                                        // فونت
      [{ align: [] }],                                       // تراز
      ['link', 'image', 'video'],                          // لینک، تصویر، ویدیو
      ['clean']                                              // حذف همه فرمت‌ها
    ]
  }
});

Toolbar با HTML دلخواه

<!-- HTML toolbar -->
<div id="my-toolbar">
  <button class="ql-bold"></button>
  <button class="ql-italic"></button>
  <select class="ql-color"></select>
</div>
<div id="editor"></div>

const quill = new Quill('#editor', {
  modules: { toolbar: '#my-toolbar' }, // اشاره به HTML
  theme: 'snow'
});

⚡API و مدیریت محتوا

δDelta Format

Quill محتوا را در فرمت خاصی به نام Delta ذخیره می‌کند — آرایه‌ای از عملیات insert، delete و retain. این فرمت برای ذخیره در دیتابیس و همگام‌سازی real-time ایده‌آل است.

// گرفتن Delta
const delta = quill.getContents();
// خروجی نمونه:
// { ops: [
//   { insert: 'سلام ', attributes: { bold: true } },
//   { insert: 'دنیا\n' }
// ]}

// تنظیم محتوا با Delta
quill.setContents({
  ops: [
    { insert: 'عنوان اصلی', attributes: { header: 1 } },
    { insert: '\n' },
    { insert: 'این یک متن ' },
    { insert: 'پررنگ',  attributes: { bold: true } },
    { insert: ' و ' },
    { insert: 'رنگی', attributes: { color: '#e74c3c', bold: true } },
    { insert: ' است.\n' }
  ]
});

// اعمال تغییر با Delta (updateContents)
quill.updateContents({
  ops: [
    { retain: 5 },               // رد کردن 5 کاراکتر اول
    { delete: 3 },               // حذف 3 کاراکتر
    { insert: 'جدید' }             // درج متن جدید
  ]
});

🏋Events و شمارنده زنده

// text-change — هر بار متن تغییر کند
quill.on('text-change', function(delta, oldDelta, source) {
  if (source === 'user') {
    console.log('کاربر تغییر داد — Delta:', delta);
  }
});

// selection-change — تغییر مکان‌نما یا انتخاب
quill.on('selection-change', function(range, oldRange, source) {
  if (range) {
    console.log(`انتخاب: index=${range.index}, length=${range.length}`);
    if (range.length > 0) {
      // متنی انتخاب شده
      const format = quill.getFormat(range);
      console.log('فرمت انتخاب:', format);
    }
  } else {
    console.log('editor blur شد');
  }
});

// editor-change — هر تغییری
quill.on('editor-change', function(eventName) {
  console.log('رویداد:', eventName);
});

🎨Formats و فرمت‌بندی برنامه‌ای

// getFormat — فرمت فعلی یا انتخاب
quill.getFormat();                    // فرمت موقعیت مکان‌نما
quill.getFormat(0, 5);              // فرمت 5 کاراکتر اول

// format — فرمت‌دهی انتخاب فعلی
quill.format('bold', true);
quill.format('color', '#e74c3c');
quill.format('align', 'center');
quill.format('header', 2);

// formatText — فرمت‌دهی بخش خاص
quill.formatText(0, 5, 'bold', true);
quill.formatText(0, 5, {
  bold: true,
  color: '#88ce02',
  underline: true
});

// removeFormat — حذف فرمت از انتخاب
quill.removeFormat(0, quill.getLength());

🔒Read-only و کنترل حالت

// Read-only mode
quill.enable(false);   // غیرفعال — فقط خواندنی
quill.enable(true);    // فعال مجدد

// بررسی وضعیت
quill.isEnabled();       // true یا false

// History — Undo/Redo
quill.history.undo();
quill.history.redo();
quill.history.clear();  // پاک کردن تاریخچه

// focus و cursor
quill.focus();
quill.blur();
quill.setSelection(0);               // انتقال مکان‌نما به ابتدا
quill.setSelection(quill.getLength()); // انتقال به انتها

// scrollIntoView
quill.scrollIntoView();

⚓ Keyboard Shortcuts

🏳RTL و فارسی

Quill پشتیبانی بومی از RTL دارد. با چند تنظیم ساده می‌توان یک ویرایشگر کاملاً فارسی ساخت.

CSS اجباری برای RTL

/* این CSS را حتماً اضافه کنید */
.ql-editor {
  direction: rtl;
  text-align: right;
  font-family: 'Vazirmatn', 'Segoe UI', Tahoma, sans-serif;
  font-size: 15px;
  line-height: 1.9;
}

/* toolbar را LTR نگه دارید */
.ql-toolbar.ql-snow {
  direction: ltr;
}

دکمه RTL در Toolbar

const quill = new Quill('#editor', {
  theme: 'snow',
  modules: {
    toolbar: [
      [{ direction: 'rtl' }],   // دکمه تغییر جهت
      ['bold', 'italic'],
      [{ align: [] }],
    ]
  }
});

🏆فرم کامل — مثال واقعی

ادغام Quill با یک فرم HTML واقعی با اعتبارسنجی و پیش‌نمایش:

<!-- HTML -->
<form id="myForm">
  <div id="editor"></div>
  <input type="hidden" id="html-val" name="content">
  <button type="submit">ارسال</button>
</form>

// JavaScript
const quill = new Quill('#editor', { theme: 'snow' });

document.getElementById('myForm').addEventListener('submit', function(e) {
  e.preventDefault();
  const text = quill.getText().trim();
  if (!text) { alert('محتوا نمی‌تواند خالی باشد!'); return; }
  document.getElementById('html-val').value = quill.root.innerHTML;
  // ارسال فرم یا AJAX
});

🚀زمین بازی کد (Playground)

یک ویرایشگر متن غنی Quill بساز، تم و Toolbar را تغییر بده و محتوای آن را با API بخوان. نسخهٔ ۱.۳.۷ آفلاین بارگذاری می‌شود.