رابط‌های برنامه‌نویسی وب و مرورگر

Web API چیست؟

مرورگرها مجموعه‌ای از رابط‌های آماده ارائه می‌دهند — بدون نصب، در دسترس جهانی:

// همه این‌ها Web API هستند:
window, document, fetch, localStorage,
setTimeout, console, navigator,
WebSocket, Worker, History...

window — پنجره جهانی

// window ریشه همه — حتی بدون نوشتن:
console.log(window === this);  // در سطح بالا true

// ابعاد:
console.log(window.innerWidth);    // عرض viewport
console.log(window.innerHeight);
console.log(window.screen.width);  // رزولوشن واقعی

// متدهای دیالوگ:
// window.alert("پیام");
const sure = window.confirm("مطمئنی؟");   // true/false
const name = window.prompt("اسمت؟");       // رشته یا null

// باز و بسته کردن:
// const w = window.open("https://example.com");
// w.close();

// اسکرول:
window.scrollTo(0, 500);           // فوری
window.scrollTo({ top: 500, behavior: "smooth" });  // نرم
window.scrollBy(0, 100);           // نسبی

// رویدادهای پنجره:
window.addEventListener("resize", () => {
    console.log(window.innerWidth);
});
window.addEventListener("scroll", () => {
    console.log("اسکرول:", window.scrollY);
});

navigator — اطلاعات مرورگر

console.log(navigator.userAgent);    // رشته کامل مرورگر
console.log(navigator.language);    // "fa-IR"
console.log(navigator.languages);   // ["fa-IR", "fa", "en"]
console.log(navigator.onLine);      // آنلاین؟
console.log(navigator.platform);    // "Win32"

// چند核心:
console.log(navigator.hardwareConcurrency); // تعداد هسته CPU
console.log(navigator.maxTouchPoints);       // لمس پشتیبانی؟

// تشخیص موبایل:
const isMobile = /Android|iPhone|iPad/i.test(navigator.userAgent);

// اتصال شبکه:
console.log(navigator.connection?.effectiveType); // "4g"

// اشتراک‌گذاری — Web Share:
if (navigator.share) {
    await navigator.share({
        title: "عنوان",
        text: "متن",
        url: "https://example.com"
    });
}

location — آدرس صفحه

// اجزا:
console.log(location.href);      // کامل
console.log(location.protocol);  // "https:"
console.log(location.host);      // "site.com:8080"
console.log(location.pathname);  // "/products/5"
console.log(location.search);    // "?page=2&sort=price"
console.log(location.hash);      // "#comments"
console.log(location.origin);    // "https://site.com"

// ناوبری:
// location.assign("https://example.com");  // اضافه به تاریخچه
// location.replace("https://example.com"); // جایگزینی — بدون بازگشت
// location.reload();                        // رفرش

// تغییر hash — بدون reload:
location.hash = "#section-2";

History API — تاریخچه

//后退 — back/forward:
history.back();
history.forward();
history.go(-2);  // دو مرحله عقب

// pushState — SPA routing:
history.pushState(
    { page: "products" },           // state
    "",                              // title (نادیده)
    "/products"                      // URL جدید — بدون reload!
);

// جایگزینی:
history.replaceState({ page: "home" }, "", "/");

// گوش دادن به تغییر:
window.addEventListener("popstate", (e) => {
    console.log("تغییر تاریخچه:", e.state);
});

URL و URLSearchParams

// کار با URL:
const url = new URL("https://api.example.com/search?q=js&page=2#results");

console.log(url.hostname);   // api.example.com
console.log(url.pathname);   // /search
console.log(url.hash);       // #results

// پارامترها:
console.log(url.searchParams.get("q"));    // "js"
console.log(url.searchParams.get("page")); // "2"

// تغییر:
url.searchParams.set("page", "3");
url.searchParams.append("filter", "new");
console.log(url.search);  // ?q=js&page=3&filter=new

// ساخت از صفر:
const api = new URL("https://api.example.com/users");
api.searchParams.set("limit", "10");
api.searchParams.set("offset", "20");
console.log(api.toString());

localStorage — ذخیره دائمی

// ذخیره — فقط رشته:
localStorage.setItem("theme", "dark");
localStorage.setItem("user", JSON.stringify({ name: "علی" }));

// خواندن:
const theme = localStorage.getItem("theme");       // "dark"
const user = JSON.parse(localStorage.getItem("user"));

// حذف:
localStorage.removeItem("theme");
// localStorage.clear();  // همه

// طول:
console.log(localStorage.length);

// رویداد تغییر — در تب‌های دیگر:
window.addEventListener("storage", (e) => {
    console.log("تغییر در تب دیگر:", e.key, e.newValue);
});

sessionStorage — ذخیره موقت

// فقط در همین تب:
sessionStorage.setItem("captcha", "1234");

// بعد از reload می‌ماند، بعد از بستن تب می‌رود:
const code = sessionStorage.getItem("captcha");

// کاربرد — فرم چندمرحله‌ای:
const step = sessionStorage.getItem("wizardStep") || "1";
sessionStorage.setItem("wizardStep", "2");

Cookies — کوکی‌ها

// خواندن همه — رشته:
console.log(document.cookie);
// "theme=dark; lang=fa"

// نوشتن:
document.cookie = "user=ali; max-age=3600; path=/";
document.cookie = "token=abc; expires=Fri, 31 Dec 2025 23:59:59 GMT; secure; samesite=strict";

// حذف — با گذشته کردن تاریخ:
document.cookie = "user=; max-age=0";

// کاربرد: توکن‌های احراز هویت، ردیابی
// محدودیت: ~4KB، با هر درخواست ارسال می‌شود

Clipboard API

// کپی:
async function copyText(text) {
    try {
        await navigator.clipboard.writeText(text);
        console.log("کپی شد!");
    } catch (e) {
        // fallback برای HTTP:
        const ta = document.createElement("textarea");
        ta.value = text;
        document.execCommand("copy");
    }
}

// خواندن — نیاز به permission:
async function pasteText() {
    const text = await navigator.clipboard.readText();
    console.log(text);
}

Notifications API

// درخواست مجوز:
const permission = await Notification.requestPermission();
// "granted" | "denied" | "default"

// نمایش:
if (permission === "granted") {
    const notif = new Notification("پیام جدید", {
        body: "سلام! چطوری؟",
        icon: "/icon.png",
        tag: "message-1",       // جایگزین قبلی
        data: { chatId: 42 }
    });

    notif.onclick = (e) => {
        window.focus();
        console.log("کلیک روی نوتیف", e.target.data);
    };
}

Geolocation API

// موقعیت — نیاز به permission:
navigator.geolocation.getCurrentPosition(
    (pos) => {
        console.log("عرض:", pos.coords.latitude);   // 35.6892
        console.log("طول:", pos.coords.longitude);  // 51.3890
        console.log("دقت:", pos.coords.accuracy);   // متر
    },
    (err) => console.log("خطا:", err.message),
    { enableHighAccuracy: true, timeout: 5000 }
);

// پیگیری مداوم:
const watchId = navigator.geolocation.watchPosition(
    pos => console.log("حرکت به:", pos.coords)
);
navigator.geolocation.clearWatch(watchId);  // توقف

Fullscreen API

const video = document.querySelector("video");

// تمام صفحه:
async function goFull() {
    try {
        await video.requestFullscreen();
    } catch (e) {
        console.log("خطا:", e.message);
    }
}

// خروج:
if (document.fullscreenElement) {
    await document.exitFullscreen();
}

// رویداد:
document.addEventListener("fullscreenchange", () => {
    console.log("تغییر حالت:", document.fullscreenElement);
});

Page Visibility API

document.addEventListener("visibilitychange", () => {
    if (document.hidden) {
        console.log("تب مخفی — توقف تایمرها/ویدیو");
        pauseVideo();
    } else {
        console.log("تب دیده شد — ادامه");
        resumeVideo();
    }
});

// کاربرد: صرفه‌جویی باتری و CPU

Broadcast Channel — ارتباط تب‌ها

// ایجاد کانال:
const channel = new BroadcastChannel("app-sync");

// ارسال به همه تب‌های دیگر:
channel.postMessage({ type: "logout", userId: 42 });

// دریافت:
channel.onmessage = (e) => {
    console.log("پیام از تب دیگر:", e.data.type);
};

// بستن:
channel.close();

// کاربرد: همگام‌سازی logout/login بین تب‌ها

Web Workers — کارگران وب

اجرای کد سنگین در Thread جداگانه — بدون قفل UI:

// فایل worker.js:
self.onmessage = (e) => {
    const { data } = e.data;
    // محاسبه سنگین:
    const result = heavyComputation(data);
    self.postMessage({ result });
};

// در صفحه اصلی:
const worker = new Worker("worker.js");

worker.onmessage = (e) => {
    console.log("نتیجه:", e.data.result);
};

worker.postMessage({ data: largeArray });
worker.terminate();  // پایان کارگر

Service Worker — کارگر سرویس

پروکسی بین صفحه و شبکه — آفلاین، کش، Push:

// ثبت — در صفحه اصلی:
if ("serviceWorker" in navigator) {
    navigator.serviceWorker.register("/sw.js")
        .then(reg => console.log("ثبت شد"))
        .catch(err => console.log("خطا:", err));
}

// sw.js — کش کردن:
self.addEventListener("install", (e) => {
    e.waitUntil(
        caches.open("app-v1").then(cache =>
            cache.addAll(["/", "/index.html", "/style.css", "/app.js"])
        )
    );
});

// fetch — استراتژی Cache First:
self.addEventListener("fetch", (e) => {
    e.respondWith(
        caches.match(e.request).then(cached =>
            cached || fetch(e.request)
        )
    );
});

جمع‌بندی