Tài liệu API

Cài đặt

Cài từ npm. Tên gói viết liền một từ; tên thư viện là Forge Dialog.

npm install forgedialog

Import API và một tệp CSS:

import { alert, confirm, prompt, open } from 'forgedialog';
import 'forgedialog/style.css';

Hoặc nạp thẳng bản dựng cho trình duyệt. Nó tạo biến toàn cục ForgeDialog — đây là định danh JavaScript nên viết liền một từ.

<link rel="stylesheet" href="https://unpkg.com/forgedialog/dist/index.css" />
<script src="https://unpkg.com/forgedialog/dist/index.global.js"></script>
<script>
  ForgeDialog.alert('Hello!');
</script>

Yêu cầu Chrome/Edge 88+, Firefox 78+, Safari 15.4+, hoặc Node.js 20+ cho công cụ đóng gói và import phía máy chủ.

Điểm vào

Mọi điểm vào đều tree-shake được và có hạn mức gzip riêng, kiểm tra tự động trong CI. Hãy import cái hẹp nhất đủ dùng.

Import theo năng lực

Các điểm vào chuyên biệt (/alert, /confirm, /prompt) đi kèm bộ áp giao diện nhẹ, chỉ gồm độ mờ nền, lớp phủ, viền, và các bóng dựng sẵn. Thêm năng lực bằng cách import chúng để lấy tác dụng phụ:

import 'forgedialog/appearance';   // per-component colour, radius, hover
import 'forgedialog/interactions'; // dragging
import 'forgedialog/animations';   // animation presets
import { alert } from 'forgedialog/alert';

forgedialog và forgedialog/core đã có sẵn bộ áp giao diện đầy đủ, nên chỉ cần import thêm khi bạn dùng điểm vào chuyên biệt.

Tệp CSS

forgedialog/style.css là tệp gộp tất cả. Muốn gửi ít CSS hơn thì chỉ ghép các lớp mà trang thật sự dùng — core.css thì luôn bắt buộc.

import 'forgedialog/style/core.css';      // required
import 'forgedialog/style/forms.css';     // form fields and file dropzones
import 'forgedialog/style/workflows.css'; // wizard stepper
import 'forgedialog/style/toast.css';
import 'forgedialog/style/lightbox.css';
import 'forgedialog/style/command.css';
import 'forgedialog/style/draggable.css';

Mọi quy tắc đều nằm trong cascade layer forgedialog, nên CSS không đặt trong layer của bạn sẽ thắng mà không cần !important.

alert, confirm, prompt

Bản thay thế trả về promise cho các hàm dựng sẵn của trình duyệt.

await alert('Saved successfully.', { title: 'Success' });

const ok = await confirm('Delete this item?', { title: 'Please confirm' });

const name = await prompt('What is your name?', {
  defaultValue: 'Ada Lovelace',
  inputType: 'text',
  inputLabel: 'Full name',
  placeholder: 'Type a name',
  validate: (value) => (value.trim() ? true : 'Name is required'),
});

alert và confirm tự động nhận role="alertdialog". prompt nhận thêm các tuỳ chọn ở trên, bên cạnh mọi trường của DialogOptions.

open()

API tầng thấp. Nó trả về DialogInstance ngay lập tức chứ không phải promise, nên hộp thoại có thể được cập nhật, di chuyển, hoặc đóng từ bất cứ đâu.

import { open } from 'forgedialog';

const dialog = open({
  title: 'Custom dialog',
  content: (container) => container.append(renderForm()),
  buttons: [
    { text: 'Cancel', onClick: (i) => i.close(null) },
    { text: 'Save', role: 'primary', autoFocus: true, onClick: (i) => i.close(read()) },
  ],
});

const result = await dialog.whenClosed();          // the result, or undefined
const { result: r, reason } = await dialog.whenSettled(); // result plus why it closed

Nội dung và HTML không tin cậy

content nhận một chuỗi (hiển thị dưới dạng văn bản), một phần tử, hoặc một hàm dựng. Còn HTML thì phải quyết định rõ ràng:

// Untrusted markup: pass a sanitizer.
open({ html: userContent, sanitizeHtml: (h) => DOMPurify.sanitize(h) });

// Markup you already trust.
open({ unsafeHtml: '<p>Generated by us</p>' });

Lý do đóng

Mỗi lần đóng đều kèm một lý do: 'button', 'escape', 'backdrop', 'api', 'abort', hoặc 'destroy'. Đọc nó bằng whenSettled().

DialogOptions

Được nhận bởi open() và mọi hàm tiện ích dựng trên nó.

ButtonConfig

DialogInstance

Giao diện

Các tuỳ chỉnh giao diện chỉ áp cho một hộp thoại và đổi được lúc chạy bằng update(). Giá trị độ mờ bị kẹp trong khoảng 0..1; số trần cho độ dày, bo góc, và độ nhoè được hiểu là pixel.

open({
  title: 'Styled',
  appearance: {
    opacity: 0.96,
    surfaceColor: '#12141a',
    overlayOpacity: 0.55,
    backdropBlur: 12,
    titleColor: '#ffd166',
    titleBackground: '#1b1740',
    contentColor: '#c8ccd4',
    borderColor: '#7c5cff',
    borderWidth: 2,
    radius: 20,
    shadow: { angle: 135, distance: 24, blur: 60, opacity: 0.45 },
  },
});

Bộ áp đầy đủ đi kèm forgedialog và forgedialog/core. Với điểm vào chuyên biệt, hãy thêm import 'forgedialog/appearance' — không có nó thì các trường nâng cao bị bỏ qua chứ không báo lỗi.

Đổ bóng

shadow nhận ba dạng.

Bo góc

radius nhận một giá trị dùng chung cho mọi góc, bất kỳ chuỗi border-radius nào của CSS, hoặc một object khai theo từng góc. Góc không có trong object đó vẫn giữ bo góc của chủ đề chứ không tụt về 0.

appearance: { radius: 20 }
appearance: { radius: '20px 20px 4px 4px' }
appearance: { radius: { topLeft: 24, topRight: 24, bottomRight: 4, bottomLeft: 4 } }

Drawer giữ góc vuông và bottom sheet chỉ bo hai góc trên, trừ khi radius nói khác.

Hover

hover chỉ đổi kiểu hộp thoại khi con trỏ đang ở trên nó, và chỉ với hộp thoại có yêu cầu — mọi hộp thoại khác đứng yên hoàn toàn. Nó dùng lại các trường màu, bo góc, và đổ bóng, cộng thêm ba trường riêng.

Biến đổi khi hover tôn trọng prefers-reduced-motion và bị tạm ngưng trong lúc kéo hộp thoại, nên không thể đẩy nó ra ngoài vùng giới hạn.

Kéo thả

draggable: true là đủ để kéo hộp thoại bằng thanh tiêu đề. Dạng object thêm ràng buộc, hỗ trợ bàn phím, và ghi nhớ vị trí. Kéo thả cần năng lực interactions, thứ mà forgedialog đã bật sẵn cho bạn.

Bottom sheet giữ cử chỉ vuốt để đóng của riêng nó và bỏ qua kéo thả thông thường.

Drawer, sheet, lightbox, trạng thái tải

import { drawer, bottomSheet, lightbox, loading } from 'forgedialog';

drawer({ title: 'Settings', side: 'right', content: renderSettings });

bottomSheet({ title: 'Share', content: renderShare });

lightbox('/photo.jpg', { alt: 'A photo', caption: 'Taken in 2026' });

const task = loading('Uploading…');
task.update('Almost there…');
await task.close();

Đây chỉ là open() kèm một giá trị presentation dựng sẵn, nên mọi trường của DialogOptions vẫn dùng được.

Biểu mẫu

form() dựng một hộp thoại có kiểm tra từ danh sách trường và trả về các giá trị, hoặc null nếu bị huỷ. Tên trường được suy ra vào kiểu kết quả, nên values.email đã có kiểu mà không cần ép.

import { form } from 'forgedialog';

const values = await form(
  [
    { name: 'email', type: 'email', label: 'Email', required: true },
    { name: 'plan', type: 'select', label: 'Plan', options: [
      { value: 'free', label: 'Free' },
      { value: 'pro', label: 'Pro' },
    ] },
    { name: 'notes', type: 'textarea', label: 'Notes', rows: 4 },
  ],
  { title: 'Sign up', submitText: 'Create account' },
);

Các kiểu trường: text, password, email, number, date, textarea, select, checkbox, radio, file. Mỗi trường nhận label, defaultValue, placeholder, helpText, required, và một hàm validate; kiểu số có thêm min, max, step, còn kiểu tệp có thêm accept, multiple, maxFiles, và maxSizeBytes.

formWizard(steps, options?) trải đúng các trường đó ra nhiều bước, kèm nextText, backText, finishText, và callback onStepChange.

Wizard

wizard() là dạng tổng quát: mỗi bước tự vẽ nội dung tuỳ ý, có thể kiểm tra dữ liệu, và có thể chọn bước kế tiếp dựa trên dữ liệu đã thu thập.

import { wizard } from 'forgedialog';

const flow = wizard({
  initialData: { email: '', plan: 'free' },
  persistKey: 'signup',      // resumes where the user left off
  confirmUnsaved: true,      // asks before discarding progress
  steps: [
    { id: 'account', title: 'Account', render: renderAccount, validate: validateAccount },
    { id: 'plan', title: 'Plan', render: renderPlan,
      next: (data) => (data.plan === 'pro' ? 'billing' : 'review') },
    { id: 'billing', title: 'Billing', render: renderBilling },
    { id: 'review', title: 'Review', render: renderReview },
  ],
});

const data = await flow.result; // the data, or null if cancelled

Bộ điều khiển còn cung cấp next(), back(), goTo(stepId), getData(), và instance bên dưới.

Toast và thông báo

import { toast, notificationCenter, getNotificationHistory } from 'forgedialog';

toast('Saved', { tone: 'success' });

// A duration of 0 or Infinity keeps it up until dismiss() is called.
const upload = toast('Uploading…', { duration: 0 });
upload.dismiss();

toast('Message sent', { action: { text: 'Undo', onClick: undoSend } });

notificationCenter();          // a dialog listing past toasts
getNotificationHistory();      // the same list as data

Các sắc thái gồm info, success, warning, và danger. clearNotificationHistory() xoá sạch nhật ký.

Bảng lệnh

import { commandPalette } from 'forgedialog';

commandPalette([
  { id: 'new', label: 'New document', shortcut: '⌘N', run: createDocument },
  { id: 'search', label: 'Search', keywords: ['find', 'filter'], run: openSearch },
]);

Gõ để lọc theo nhãn và theo keywords; bảng lệnh trả về id của lệnh đã chạy.

Chủ đề

import { setTheme, getTheme, setThemePreset } from 'forgedialog';

setTheme('dark');    // 'light' | 'dark' | 'system'
getTheme();

setThemePreset('glass'); // 'default' | 'minimal' | 'glass' | 'material'

setTheme() ghi data-fd-theme lên <html>. CSS của bạn có thể đọc chính thuộc tính đó để trang và hộp thoại đổi chủ đề cùng lúc — đây đúng là cách site này làm.

Biến CSS

Mọi thứ thuộc về hình thức đều là một biến trên :root, nên viết được cả một chủ đề mà không đụng tới JavaScript.

Các biến riêng từng hộp thoại mà appearance API ghi ra (--fd-dialog-radius, --fd-dialog-shadow, --fd-dialog-title-background, và những cái còn lại) cũng đặt tay được, nếu bạn thích tạo kiểu bằng CSS hơn bằng JavaScript.

Nhãn và đa ngôn ngữ

import { setLabels, getLabels } from 'forgedialog';

setLabels({
  ok: 'Đồng ý',
  cancel: 'Huỷ',
  close: 'Đóng',
  submit: 'Gửi',
  fieldRequired: 'Bắt buộc',
  promptPlaceholder: 'Nhập nội dung',
  notifications: 'Thông báo',
});

Nhãn đặt theo cách này áp dụng ở mọi nơi; từng hộp thoại vẫn ghi đè được bằng tuỳ chọn labels của riêng nó.

Plugin và hook

Năm hook vòng đời chạy cho mọi hộp thoại: beforeOpen, afterOpen, beforeClose, afterClose, và beforeDestroy.

import { on, off, registerPlugin } from 'forgedialog';

// A single hook.
on('afterOpen', ({ instance, options }) => track('dialog', options.title));

// Or a plugin bundling several.
registerPlugin({
  name: 'analytics',
  install: (api) => api.on('afterClose', ({ reason }) => track('close', reason)),
  hooks: {
    beforeClose: ({ preventClose, result }) => {
      if (result === undefined) preventClose?.();
    },
  },
});

Mỗi hook nhận { instance, options, result, reason, preventClose }. Gọi preventClose() trong beforeClose sẽ giữ hộp thoại mở.

Adapter cho framework

Mỗi adapter là một lớp bọc mỏng quanh open(), gắn vòng đời hộp thoại vào vòng đời component, nên không còn gì sót lại sau khi component bị gỡ.

// React and Vue share the same hook shape.
import { useForgeDialog } from 'forgedialog/react';
const { open } = useForgeDialog();
await open({ title: 'Hi' }).whenClosed();

// Svelte: an action on the triggering element.
import { dialogTrigger } from 'forgedialog/svelte';
// <button use:dialogTrigger={{ title: 'Hi' }}>Open</button>

// Web component.
import { defineForgeDialog } from 'forgedialog/web-component';
defineForgeDialog(); // <forge-dialog open title="Hi" message="…" size="md">

TypeScript, SSR, và CSP

• Có kiểu cho cả ESM lẫn CJS. open<T>() luồn kiểu kết quả của nó qua buttons, whenClosed(), và các hook.
• Import gói này trên máy chủ không đụng tới DOM, nên an toàn với bản dựng SSR; hộp thoại chỉ được tạo khi bạn gọi API trong trình duyệt.
• Bản build không chứa eval và new Function, điều này được kiểm tra trong CI, nên nó chạy được dưới Content Security Policy nghiêm ngặt. Chính site này cũng đang chạy dưới một CSP như vậy.
• Mọi điểm vào đều có hạn mức gzip bắt buộc, kiểm tra ở từng pull request.