# فصل ۰۳ — از JavaScript صدا بزن

<div dir="rtl">

# فصل ۰۳ — از JavaScript صدا بزن

## در این فصل چه یاد می‌گیری

دو فصلِ اول را روی کاغذ فهمیدی؛ این فصل برای اولین بار **زنده‌اش** می‌کنی. یک صفحهٔ وبِ کوچک می‌سازی — «دستیارِ من» — که یک کادرِ کلید دارد، یک کادرِ سؤال، و یک دکمه. دکمه را که بزنی، برنامه‌ات با `fetch` مدل را از درِ `API` صدا می‌زند، متنِ جواب را از پاسخِ خام بیرون می‌کشد، و روی همان صفحه نشانش می‌دهد. و مهم‌تر از همه: کلید را از کادرِ ورودی می‌خوانی، **نه از کد** — دقیقاً همان الگوی `BYOK`ِ فصل ۱.

![یک برشِ آموزشی از یک کارتِ ابزارِ تک‌صفحه‌ای که بالایش یک شکافِ کلید دارد، پایینش یک کادرِ متن، و یک بازوی مکانیکی که سؤال را به یک موتورِ مدل می‌رساند و متنِ جواب را برمی‌گرداند؛ کلید داخلِ شکافِ خودِ کارت می‌ماند](/lesson-assets/t5-s03-from-js/prompt/01-image-page-calls-model.png)

آخر این فصل می‌توانی:

- یک صفحهٔ وب بسازی که با `fetch` مدل را از کد صدا می‌زند
- کلید را طبقِ `BYOK` از یک کادرِ ورودی بخوانی، نه از داخلِ کد
- بدنهٔ درخواست را با `method`، `headers` و `body` و `JSON.stringify` برای `POST` بسازی — یک قدمِ کوچکِ تازه روی `fetch`ِ تاروپود
- متنِ جواب را از مسیرِ `candidates[0].content.parts[0].text` روی صفحه نشان بدهی

## قبل از شروع

- **از فصل ۱ و ۲ همین ترم:** `API`، `API key`، الگوی `BYOK`، و مسیرِ `candidates[0].content.parts[0].text`.
- **از تاروپود (ترم ۷، فصل ۸) — پیش‌نیازِ اعلام‌شده:** `fetch`، `async`/`await`. این‌ها را اینجا از نو و عمیق آموزش نمی‌دهیم؛ فقط کوتاه یادآوری می‌کنیم و به‌کارشان می‌بریم. اگر تاروپود را نگذرانده‌ای، بخشِ ۲ برایت یک مرورِ فشرده است.

> 🧪 **آزمایشگاه:** [آزمایشگاه این فصل را باز کن](/lab/embed/hamhoosh/term-5-building/session-03-from-js) — سه فایلِ `index.html`، `script.js` و `styles.css` را همان‌جا بساز و اجرا کن. کلیدِ خودت را در کادرِ بالای صفحه بگذار (نه در کد) و اولین فراخوانیِ واقعی‌ات را بزن.

## ۱. نقشهٔ اپ: کلید، سؤال، جواب

اول صفحه را می‌سازیم، بی‌آنکه هنوز کاری بکند. صفحه پنج چیز دارد: یک کادرِ کلید، یک کادرِ سؤال، یک دکمه، یک خطِ وضعیت (فعلاً خالی می‌ماند؛ در فصل ۶ برای پیام‌های انتظار و خطا ازش استفاده می‌کنیم)، و یک جعبهٔ جواب. به یک نکته دقت کن: کادرِ کلید `type="password"` است، تا وقتی کلیدت را تایپ می‌کنی روی صفحه پیدا نباشد. این هم بخشی از `BYOK` است.

</div>

```html
<!DOCTYPE html>
<html lang="fa" dir="rtl">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>دستیارِ من</title>
    <link rel="stylesheet" href="styles.css">
  </head>
  <body>
    <main>
      <h1>دستیارِ من</h1>
      <p class="hint">کلیدِ Gemini خودت را بگذار، بعد بپرس.</p>
      <input type="password" id="key" placeholder="کلیدِ API خودت — روی کامپیوترِ خودت می‌ماند">
      <textarea id="prompt" placeholder="سؤالت را اینجا بنویس"></textarea>
      <button id="ask">بپرس</button>
      <p id="status" class="status"></p>
      <div id="answer" class="answer"></div>
    </main>
    <script src="script.js"></script>
  </body>
</html>
```

<div dir="rtl">

هر عنصر یک `id` دارد تا کد بتواند پیدایش کند: `key`، `prompt`، `ask`، `status`، `answer`.

> ✅ **چک کن:** `index.html` را در مرورگر باز کن. باید کادرِ کلید، کادرِ سؤال و دکمه را ببینی. هنوز هیچ‌کاری نمی‌کند — طبیعی است، چون `script.js` را ننوشته‌ایم.

## ۲. `fetch`، `async`، `await` — قرض از تاروپود

این سه را در تاروپود یاد گرفتی؛ اینجا فقط یادآوری‌شان می‌کنیم چون ابزارِ اصلیِ فراخوانی‌اند. `fetch` یعنی «از داخلِ کد یک درخواست بفرست و جواب را بگیر». چون جوابِ اینترنت فوری نیست، `fetch` بلافاصله یک قول (promise) می‌دهد؛ `await` یعنی «همین‌جا بایست تا این قول به جوابِ واقعی برسد»؛ و هر functionی که تویش `await` داری، جلویش باید `async` بگذاری.

حالا بالای `script.js` را بنویس: نامِ مدل، آدرسِ سرویس، و listenerِ دکمه که کلید و سؤال را می‌خواند. نامِ مدل را در یک ثابت جدا می‌گذاریم چون یک عددِ فرّار است:

</div>

```js
const MODEL = "gemini-flash-latest";
const URL = "https://generativelanguage.googleapis.com/v1beta/models/" + MODEL + ":generateContent";

document.querySelector("#ask").addEventListener("click", async function () {
  const key = document.querySelector("#key").value.trim();
  const prompt = document.querySelector("#prompt").value.trim();
  const answer = document.querySelector("#answer");
  // ادامه در بخشِ بعد…
});
```

<div dir="rtl">

به خطِ `const key = document.querySelector("#key").value.trim();` خوب نگاه کن: کلید از کادرِ ورودی خوانده می‌شود، نه از یک ثابتِ داخلِ کد. **این جانِ `BYOK` است.** `.trim()` هم فاصله‌های اضافیِ اول و آخر را می‌گیرد که موقعِ کپی‌کردنِ کلید معمولاً جا می‌مانند.

> ⚠️ **مواظب باش:** هرگز، حتی برای یک تستِ سریع، کلیدت را این‌طور در کد ننویس: `const key = "AIza...";`. اگر همین فایل را منتشر کنی، کلیدت لو رفته. کلید فقط و فقط از کادرِ ورودی می‌آید.

## ۳. فرستادنِ `prompt` و خواندنِ جواب

حالا قلبِ کار: با `fetch` بدنهٔ درخواست را به `endpoint` می‌فرستیم و کلید را در آدرس همراهش می‌کنیم. بدنه همان ساختارِ سادهٔ فصل ۲ است — فقط `contents`. بعد متن را از مسیرِ آشنایش بیرون می‌کشیم:

</div>

```js
  const res = await fetch(URL + "?key=" + key, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      contents: [{ parts: [{ text: prompt }] }]
    })
  });
  const data = await res.json();
  answer.textContent = data.candidates[0].content.parts[0].text;
```

<div dir="rtl">

خط‌به‌خط: `fetch` با `method: "POST"` می‌فرستد (چون داریم داده می‌فرستیم، نه فقط می‌گیریم)، `headers` می‌گوید بدنه از جنسِ `JSON` است، و `JSON.stringify` شیءِ ما را به همان متنِ `JSON`ِ فصل ۲ تبدیل می‌کند. `res.json()` جوابِ خام را به دادهٔ قابلِ استفاده برمی‌گرداند، و مسیرِ `candidates[0].content.parts[0].text` — همان که فصلِ قبل با انگشت دنبالش کردی — متنِ جواب را می‌دهد.

> 💡 **نکته:** در تاروپود `fetch` را برای **گرفتن** (GET) دیدی — فقط یک آدرس می‌دادی و جواب می‌گرفتی. اینجا یک قدمِ کوچکِ تازه به آن اضافه می‌کنیم: با `method`، `headers` و `body` همان `fetch` را برای **فرستادن** (POST) به‌کار می‌بریم، و بدنه را با `JSON.stringify` می‌سازیم. غیر از این یک تکه، بقیهٔ `fetch` همان است که می‌شناسی.

> ✅ **چک کن:** کلیدت را در کادر بگذار، یک سؤالِ ساده بنویس («یک لطیفهٔ کوتاه بگو») و دکمه را بزن. بعد از یک لحظه، جوابِ مدل در جعبهٔ جواب می‌نشیند. اولین فراخوانیِ واقعی‌ات از کد انجام شد.

## ۴. کدِ کاملِ این فصل

حالا همه‌چیز کنارِ هم. این `script.js`ِ کامل است — همان تکه‌هایی که ساختیم، سرِ جای درستشان. عمداً ساده و «مسیرِ خوش» است: فرض می‌کند کلید درست است و اینترنت وصل. محکم‌کردنش در برابرِ کلیدِ غلط و اینترنتِ قطع کارِ فصل ۶ است.

</div>

```js
// script.js
// modelِ رایگان — dar zaman-e khandan az mostanadat-e Gemini check kon:
const MODEL = "gemini-flash-latest";
const URL = "https://generativelanguage.googleapis.com/v1beta/models/" + MODEL + ":generateContent";

document.querySelector("#ask").addEventListener("click", async function () {
  const key = document.querySelector("#key").value.trim();
  const prompt = document.querySelector("#prompt").value.trim();
  const answer = document.querySelector("#answer");

  const res = await fetch(URL + "?key=" + key, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      contents: [{ parts: [{ text: prompt }] }]
    })
  });
  const data = await res.json();
  answer.textContent = data.candidates[0].content.parts[0].text;
});
```

<div dir="rtl">

و این هم `styles.css` که صفحه را تمیز و خوانا می‌کند:

</div>

```css
/* styles.css */
body { font-family: Vazirmatn, Tahoma, sans-serif; background: #0f1413; color: #e9ede9; }
main { max-width: 640px; margin: 2rem auto; padding: 0 1rem; }
h1 { color: #2fc6ce; }
input, textarea { width: 100%; margin: 0.5rem 0; padding: 0.7rem; box-sizing: border-box;
  background: #151b19; color: #e9ede9; border: 1px solid #253029; border-radius: 8px; }
textarea { min-height: 8rem; }
button { background: #2fc6ce; color: #06130b; border: 0; padding: 0.7rem 1.4rem;
  border-radius: 8px; font-size: 1rem; cursor: pointer; }
button:disabled { opacity: 0.6; }
.status { color: #98a49e; }
.answer { white-space: pre-wrap; margin-top: 1rem; padding: 1rem;
  background: #151b19; border-radius: 8px; min-height: 2rem; }
```

<div dir="rtl">

> ✅ **چک کن:** هر سه فایل را کنارِ هم بگذار و صفحه را باز کن. کلیدت را بگذار، بپرس، و جواب را ببین. این نسخه فقط مسیرِ خوش را می‌شناسد: اگر کلید درست و اینترنت وصل باشد، جواب می‌آید.

> 🔧 **اگر جواب نگرفتی:** اگر جعبهٔ جواب خالی ماند، `console`ِ مرورگر را باز کن (کلیدِ F12، سربرگِ Console). چون هنوز هیچ نگهبانی نگذاشته‌ایم، خطاها به‌جای صفحه آنجا ظاهر می‌شوند. دو خطا را باید بشناسی:
>
> - `Cannot read properties of undefined (reading '0')` یعنی سرویس جواب داده، ولی در جوابش `candidates` نیست. با کلیدِ غلط یا خالی همین را می‌بینی، چون پاسخِ خطا فقط خانهٔ `error` دارد (فصل ۲). کلید را دوباره کپی کن و مواظبِ فاصلهٔ اضافی باش.
> - `Failed to fetch` یعنی اصلاً جوابی نیامده. اینترنت یا فیلترِ شبکه را چک کن.
>
> فصل ۶ همین خطاها را به پیامِ روی صفحه تبدیل می‌کند.

## ۵. جوابِ روی صفحه هم می‌تواند مطمئن ولی غلط باشد

اپت کار می‌کند — ولی درست‌کارکردنِ اپ ربطی به درست‌بودنِ جواب ندارد. حالا این را از مدل بپرس: «پرجمعیت‌ترین کشورِ جهان کدام است؟». ممکن است چیزی شبیهِ این بگیری (خروجیِ تو ممکن است فرق کند):

</div>

```text
پرجمعیت‌ترین کشورِ جهان چین است.
```

<div dir="rtl">

لحنش قاطع است، ولی جمعیت یک عددِ زنده است که مدام عوض می‌شود، و مدل تا `knowledge cutoff`ِ خودش را می‌داند و بس — بعد از آن خبر ندارد. این دقیقاً همان‌جاست که ترم ۱ هشدار داد: مدل از لحظهٔ حال بی‌خبر است. جواب ممکن است دیروز درست بوده و امروز کهنه باشد.

> ✅ **وارسی:** جوابِ مدل را با یک منبعِ زنده و تاریخ‌دار بسنج — نه با پرسیدنِ دوباره از خودِ مدل. یک آمارِ رسمیِ به‌روزِ جمعیت را باز کن و ببین همین امروز کدام کشور بالاتر است. سه قانونِ ثابتِ این دوره برای همین ساخته شده‌اند: **«اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمی‌شود درست باشد».** یک اپِ سالم که جوابِ کهنه را زیبا نشان می‌دهد، بازهم جوابِ کهنه را نشان می‌دهد؛ وارسی کارِ توست.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| `fetch` | فِچ | فرستادنِ درخواست به یک آدرس، از داخلِ کد (قرض از تاروپود) |
| `async` / `await` | اِی‌سینک / اِوِیت | علامتِ functionِ منتظر / «بایست تا جواب برسد» (قرض از تاروپود) |
| `JSON.stringify` | جِی‌سان‌استرینگیفای | تبدیلِ شیءِ برنامه به متنِ `JSON` برای فرستادن در `body`ِ درخواست |

<div dir="rtl">

## تمرین‌ها

**تمرین اجباری:** اپ را کامل بساز و یک سؤالِ واقعیِ خودت را بپرس تا جواب بگیری. بعد کلید را عمداً خالی بگذار و دکمه را بزن؛ صفحه هیچ پیامی نشان نمی‌دهد، ولی اگر `console`ِ مرورگر (کلیدِ F12) را باز کنی، خطا را همان‌جا می‌بینی. در یک جمله بنویس چه خطایی دیدی — فصل ۶ همین را به یک پیامِ روی صفحه تبدیل می‌کنیم.

**تمرین ستاره‌دار ⭐:** یک سؤالِ حساسِ زمانی بپرس (مثلِ «امروز چندم است؟» یا «آخرین جامِ جهانی را کی برد؟») و جوابش را با یک منبعِ واقعی و به‌روز وارسی کن — یک نمونهٔ دیگر از «مدل از لحظهٔ حال بی‌خبر است». بعد همان سؤال را یک بارِ دیگر بفرست و ببین آیا جوابِ مدل کلمه‌به‌کلمه همان است یا فرق کرد.

## در فصل بعد

اپت زنده شد: از کد صدا می‌زنی، کلید را امن از کادر می‌خوانی، و جواب را نشان می‌دهی. ولی هنوز مدل را «هدایت» نکرده‌ای — هر بار فقط `prompt`ِ خام را می‌فرستی. فصلِ بعد به همین `script.js` دو چیز اضافه می‌کنیم: `system prompt` در کد (تا مدل یک نقشِ ثابت بگیرد) و `temperature` (تا خلاق یا دقیق بودنش را کنترل کنی) — همان پارامترهایی که در ترم ۲ در زمینِ بازیِ چت دیدی، این‌بار داخلِ کدِ خودت.

</div>

---
Source: https://yaadestan.com/courses/hamhoosh/lessons/t5/s03-from-js (یادستان, Yaadestan)
