آموزش پایه‌ی Pine Script؛ از نخستین اندیکاتور تا هشدار

از دیدن اندیکاتور تا نوشتن آن

اگر اندیکاتوری را روی نمودار می‌بینید و می‌خواهید منطق پشت آن را بفهمید، قدم بعدی ساخت نسخه‌ای است که قواعدش را خودتان تغییر دهید. در این مسیر یاد می‌گیرید یک اندیکاتور ساده را به اجزای قابل‌فهم تقسیم کنید: ورودی، محاسبه، نمایش و شرط هشدار. هدف یادگیری کامل برنامه‌نویسی نیست؛ فقط یک منطق مشخص را به کد قابل‌اجرا تبدیل می‌کنید.

Pine Script زبان برنامه‌نویسی تریدینگ‌ویو برای ساخت اندیکاتورها و راهبردهاست. هر اسکریپت را با `//@version=۶` شروع کنید و نوع آن را با `indicator()` یا `strategy()` مشخص کنید؛ در این مقاله با یک اندیکاتور پایه کار می‌کنیم. برای نمونه، یک میانگین متحرک ساده (SMA) از قیمت‌های پایانی تعداد معینی کندل محاسبه می‌شود؛ در بخش مثال اصلی، محاسبه و تفسیرش را گام‌به‌گام می‌بینید.

در ادامه، ورودی را با `input.int()` قابل‌تغییر می‌کنید و حداقل طول را روی ۱ می‌گذارید؛ سپس محاسبه را با `ta.sma(close, length)` انجام می‌دهید. برای دیدن نتیجه روی نمودار، `plot()` را در بخش اصلی اسکریپت فراخوانی کنید. برای بررسی مقدار کندل قبلی، از پسوند `[]` استفاده کنید؛ مثلاً `close[۱]` به قیمت پایانی کندل پیشین اشاره می‌کند.

1. کد را در ویرایشگر Pine Script تریدینگ‌ویو وارد کنید و با اجرای اسکریپت، نتیجه را روی نمودار ببینید.
2. طول ورودی را تغییر دهید و بررسی کنید خط اندیکاتور چگونه تغییر می‌کند؛ سپس محاسبه را با منطق بخش مربوط بسنجید.
3. برای هشدار، شرط را با `alertcondition()` تعریف کنید و بعد هشدار همان اسکریپت را در تریدینگ‌ویو بسازید.

این مسیر کمک می‌کند از تماشای یک خط روی نمودار به خواندن منطق پشت آن برسید و نسخه‌ای با ورودی قابل‌تنظیم بسازید. برای نمونه‌های بیشتر، ابزار اندیکاتورها و اسکریپت‌های کریپکس را هم ببینید.

Pine Script چیست و چه چیزی می‌سازد؟

Pine Script زبان برنامه‌نویسی تریدینگ‌ویو برای ساخت ابزارهای تحلیلی روی نمودار است. اندیکاتور یک محاسبه را انجام می‌دهد و نتیجه را، مثلاً به‌شکل خط یا نشانه، نمایش می‌دهد. راهبرد (strategy) علاوه بر این، ورود و خروج‌های تعریف‌شده را در شبیه‌سازی معامله می‌آزماید و گزارش عملکرد می‌سازد. اگر فقط می‌خواهید یک محاسبه را روی نمودار ببینید، اندیکاتور نقطه‌ی شروع این آموزش است. ([tradingview.com](https://www.tradingview.com/support/solutions/۴۳۰۰۰۵۶۱۸۳۶-what-is-pine-script/?utm_source=openai))

ساختار پایه‌ی اسکریپت سه جزء دارد: نسخه‌ی زبان، نوع اسکریپت، و دستورهای محاسبه یا نمایش نتیجه. هر اسکریپت را با `//@version=۶` شروع کنید؛ این خط باید پیش از دستورهای دیگر بیاید. سپس نوع را با `indicator()` یا `strategy()` مشخص کنید و بعد محاسبه یا خروجی را بنویسید. تصویر زیر همین سه جزء را نشان می‌دهد. ([tradingview.com](https://www.tradingview.com/pine-script-docs/language/script-structure/?utm_source=openai))

برای نمونه، یک اندیکاتور ساده می‌تواند با `//@version=۶` و سپس `indicator("میانگین من")` شروع شود و مقدار موردنظر را با `plot()` روی نمودار رسم کند. در این مقاله اندیکاتور می‌سازیم، نه سامانه‌ای برای اجرای سفارش. دستور تعریف نوع اسکریپت تعیین می‌کند که کد اندیکاتور است یا راهبرد.

ویرایشگر Pine فضای نوشتن و ویرایش کد در تریدینگ‌ویو است. آن را از زبانه‌ی Pine Editor در پایین نمودار باز کنید، اسکریپت را وارد کنید و با گزینه‌ی افزودن به نمودار نتیجه را ببینید. پس از هر تغییر، کد را به‌روزرسانی کنید تا نمودار نسخه‌ی جدید را نشان دهد. ([tradingview.com](https://tradingview.com/pine-script-docs/primer/first-steps/?utm_source=openai))

اسکریپت چطور روی کندل‌ها اجرا می‌شود؟

Pine Script اطلاعات هر کندل را جدا می‌خواند. روی هر کندل، اسکریپت با مقدارهای همان کندل اجرا می‌شود. در کندل‌های تاریخی، این کار از قدیمی‌ترین تا جدیدترین کندل پیش می‌رود. در کندل جاری هم با هر به‌روزرسانی قیمت، اسکریپت دوباره اجرا می‌شود. پس `close` روی هر کندل یعنی قیمت پایانی همان کندل، نه یک مقدار ثابت برای کل نمودار.

چند مقدار پرکاربرد، اطلاعات اصلی هر کندل را نشان می‌دهند: `open` قیمت آغاز، `high` بیشترین قیمت، `low` کمترین قیمت و `close` قیمت پایانی. `volume` هم حجم همان کندل را می‌دهد. برای نمونه، شرطی که `high` را با `open` مقایسه می‌کند، می‌سنجد که بیشترین قیمت کندل از قیمت آغازش بالاتر رفته یا نه. هر دو مقدار از همان کندل خوانده می‌شوند.

در تصویر بالا، مسیر خواندن اطلاعات کندل، محاسبه و نمایش خروجی دیده می‌شود. برای خواندن مقدار یک کندل پیشین، کروشه را به نام مقدار اضافه کنید: `close[۱]` قیمت پایانی کندل قبلی است، و `close` قیمت پایانی کندل جاری. شرط `close > close[۱]` این دو را با هم مقایسه می‌کند. روی نخستین کندل، مقدار پیشین وجود ندارد.

روی کندل باز، `close` با هر تغییر قیمت به‌روزرسانی می‌شود؛ یعنی هنوز مقدار نهایی نیست. بعد از بسته‌شدن کندل، این مقدار تثبیت می‌شود و در کندل‌های تاریخی همیشه همان مقدار بسته‌شدن را نشان می‌دهد. اگر شرط شما فقط باید بعد از بسته‌شدن کندل معتبر باشد، آن را با `barstate.isconfirmed` بسنجید.

اجزای محاسبه و نمایش را بشناسید

در Pine Script هر اسکریپت را با `//@version=۶` شروع کنید و نوع آن را مشخص کنید. برای ساخت اندیکاتور، `indicator("میانگین متحرک من")` را بنویسید. متن داخل پرانتز فقط عنوانی است که اسکریپت را با آن روی نمودار و در فهرست‌ها پیدا می‌کنید، نه نام متغیر یا فرمول.

برای طول قابل‌تغییر، از `input.int()` استفاده کنید. در نمونه‌ی زیر مقدار آغازین ۳ است و حداقل طول ۱. مقدار را می‌توانید از تنظیمات اندیکاتور عوض کنید. طول، تعداد کندل‌هایی را تعیین می‌کند که میانگین در محاسبه به کار می‌گیرد.

`ta.sma(close, length)` میانگین ساده‌ی متحرک را از قیمت‌های پایانی (`close`) و طول تعیین‌شده می‌سازد. نام متغیر `average` نشان می‌دهد این مقدار میانگین است. نام‌ها را بر پایه‌ی کاربرد انتخاب کنید تا کد با افزودن شرط‌ها خوانا و قابل‌اصلاح بماند.

عملگر `>` بررسی می‌کند مقدار سمت چپ بزرگ‌تر از سمت راست باشد. پس `close > average` وقتی درست است که قیمت پایانی از میانگین بالاتر باشد. `if` اجرای یک بخش کد را به درست‌بودن شرط وابسته می‌کند؛ مثلاً می‌توانید درون آن برای این وضعیت برچسب بسازید. نامی مثل `priceAboveAverage` معنای نتیجه‌ی شرط را هم روشن می‌کند.

`plot(average)` مقدار میانگین را روی نمودار نمایش می‌دهد و باید در محدوده‌ی اصلی اسکریپت فراخوانی شود. توجه کنید: رسم خط به‌تنهایی هشدار نمی‌سازد. برای تعریف شرط هشدار از `alertcondition()` استفاده کنید و بعد هشدار اسکریپت را در تریدینگ‌ویو بسازید. جدا نگه‌داشتن نسخه، ورودی، محاسبه و خروجی، بررسی کد را ساده‌تر می‌کند.

یک میانگین متحرک ساده را گام‌به‌گام بسازید

فرض کنید قیمت‌های پایانی سه کندل به‌ترتیب ۱۰، ۱۲ و ۱۱ هستند و طول محاسبه ۳ است. طول ۳ یعنی برای محاسبه‌ی میانگین، قیمت پایانی همین سه کندل را در نظر می‌گیرید. قاعده روشن است: قیمت‌ها را جمع کنید و حاصل را بر طول تقسیم کنید.

در تصویر بالا، فرمول برای این مثال نشان داده شده: (۱۰ + ۱۲ + ۱۱) ÷ ۳ = ۱۱. میانگین ساده‌ی این سه قیمت پایانی ۱۱ است و خروجی اندیکاتور هم ۱۱ خواهد بود. اگر شرط شما این باشد که قیمت پایانی از میانگین بزرگ‌تر باشد، در این مثال شرط درست نیست؛ قیمت پایانی کندل سوم ۱۱ است و با میانگین برابر. این فقط رابطه‌ی دو عدد را نشان می‌دهد و توصیه‌ی معامله نیست.

کد را جزءبه‌جزء بسازید

ابتدای اسکریپت، نسخه‌ی زبان را تعیین می‌کند. `indicator()` نوع اسکریپت را اندیکاتور معرفی می‌کند؛ ورودی طول با `input.int()` ساخته می‌شود و `minval=۱` اجازه نمی‌دهد طول کمتر از یک باشد. خط محاسبه، میانگین ساده‌ی قیمت‌های پایانی را با `ta.sma(close, length)` به دست می‌آورد؛ در پایان، `plot()` این مقدار را روی نمودار نشان می‌دهد.

قالب کامل کد این است:

//@version=۶indicator("میانگین متحرک ساده", overlay=true)length = input.int(۳, "طول", minval=۱)smaValue = ta.sma(close, length)plot(smaValue)

در این کد، `close` قیمت پایانی هر کندل است و `length` تعداد کندل‌هایی است که در محاسبه وارد می‌شوند. عدد ۳ مقدار اولیه‌ی ورودی طول است؛ با تغییر آن، تعداد کندل‌های محاسبه‌شده هم تغییر می‌کند. `plot()` در اسکریپت قرار دارد تا میانگین به‌صورت خط روی نمودار رسم شود.

اسکریپت را اجرا و طول را تغییر دهید

1. ویرایشگر Pine را در تریدینگ‌ویو باز کنید و کد را وارد کنید.
2. اسکریپت را اجرا کنید و آن را به نمودار بیفزایید تا خط میانگین را ببینید.
3. تنظیمات اندیکاتور را باز کنید و مقدار طول را تغییر دهید؛ سپس تغییر خط میانگین را روی نمودار بررسی کنید.

ورودی‌ها، هشدارها و محدودیت‌های اجرا

برای تغییر طول میانگین از تنظیمات، آن را با `input.int()` تعریف کنید و حداقل مقدار را ۱ بگذارید. همان ورودی را به `ta.sma(close, length)` بدهید. با تغییر طول، میانگین دوباره محاسبه می‌شود و خط رسم‌شده نیز به‌روز می‌شود.

برای نمونه، ورودی و میانگین را این‌طور تعریف کنید: `length = input.int(۲۰, title="طول میانگین", minval=۱)` و `average = ta.sma(close, length)`. عدد ۲۰ مقدار آغازین است و در تنظیمات اندیکاتور قابل تغییر است. `length` تعداد کندل‌هایی را نشان می‌دهد که میانگین از آن‌ها محاسبه می‌شود.

تعریف شرط و ساخت هشدار

شرط هشدار را با `alertcondition()` در کد تعریف کنید. برای مثال، برای تشخیص عبور قیمت از میانگین: `alertcondition(ta.crossover(close, average), title="عبور قیمت از میانگین", message="شرط عبور برقرار شد")`. این دستور فقط شرط را به تریدینگ‌ویو می‌دهد و به‌تنهایی هشداری فعال نمی‌کند.

1. اسکریپت را ذخیره کنید و با گزینه‌ی افزودن به نمودار، آن را روی نمودار اجرا کنید.
2. در تریدینگ‌ویو ابزار ایجاد هشدار را باز کنید و اسکریپت خود را در فهرست شرط‌ها انتخاب کنید.
3. شرط تعریف‌شده، مانند عبور قیمت از میانگین، را برگزینید؛ سپس تنظیمات هشدار را بررسی و آن را ایجاد کنید.

مقدار `close` روی کندل باز با تغییر قیمت به‌روزرسانی می‌شود. پس شرطی که به قیمت پایانی وابسته است، ممکن است قبل از بسته‌شدن کندل برقرار شود و بعد از بین برود. برای بررسی شرط فقط بعد از بسته‌شدن کندل، `barstate.isconfirmed` را به شرط اضافه کنید؛ مثلاً: `barstate.isconfirmed and ta.crossover(close, average)`. در تصویر پایین، تفاوت کندل باز و بسته را می‌بینید.

اشتباهات رایج را با یک چک‌لیست پیدا کنید

وقتی اسکریپت خطا می‌دهد، اول ساختارش را بررسی کنید. هر اسکریپت را با `//@version=۶` شروع کنید و بعدش نوعش را با `indicator()` یا `strategy()` مشخص کنید. نبودن خط نسخه یا قرارگرفتنش بعد از کد هم جزو خطاهای ساختاری است؛ در این حالت ویرایشگر ممکن است کد را با قواعد نسخه‌ی دیگری بخواند. پیام ویرایشگر را هم از نظر محل خطا بخوانید؛ گاهی علت در خط پیشین است.

خطای نوشتاری را از خطای منطقی جدا کنید

خطای نحوی (Syntax Error) یعنی ساختار نوشتاری با قواعد زبان جور نیست؛ نمونه‌ی روشنش پرانتز بسته‌نشده است. نام تابع نادرست می‌تواند خطای کامپایل یا شناسه‌ی تعریف‌نشده بسازد، اما همیشه خطای نحوی به معنای دقیق نیست. خطای منطقی (Logic Error) وقتی رخ می‌دهد که اسکریپت اجرا می‌شود اما شرط یا محاسبه نتیجه‌ی موردنظر را نمی‌دهد؛ پس اجراشدن کد به‌تنهایی درستی منطق را ثابت نمی‌کند.

برای ورودی طول، از `input.int()` استفاده کنید و حداقل را ۱ بگذارید؛ این کار از انتخاب طول صفر یا مقدار نامعتبر جلوگیری می‌کند. برای نمونه: `length = input.int(۱, "طول", minval=۱)`. بعد مطمئن شوید همین متغیر در `ta.sma(close, length)` استفاده شده و مقدار ورودی در پنل، طول محاسبه را تغییر می‌دهد.

ارجاع زمانی را جداگانه بازبینی کنید. `close` به قیمت پایانی کندل جاری اشاره دارد و `close[۱]` قیمت پایانی کندل قبلی را می‌دهد. اگر شرط شما این دو را مقایسه می‌کند، ببینید جایشان عوض نشده باشد. مقدار `close` روی کندل باز با تغییر قیمت به‌روز می‌شود؛ برای بررسی شرط بعد از بسته‌شدن کندل، `barstate.isconfirmed` را کنترل کنید.

برای هشدار، مطمئن شوید `alertcondition()` شرط درست را تعریف می‌کند و بعد هشدار مربوط به اسکریپت را در تریدینگ‌ویو بسازید. برای ابزارهای مرتبط هم سری به اندیکاتورها و اسکریپت‌های کریپکس بزنید.

بعد از ساخت اندیکاتور چه چیزی را تمرین کنید؟

پس از ساخت اندیکاتور، کار را در پنج گام جمع‌بندی کنید: نوع اسکریپت را با `indicator()` مشخص کنید، ورودی را با `input.int()` بگیرید، مقدار را محاسبه کنید، با `plot()` نمایش دهید و نتیجه را روی نمودار بیازمایید. این مراحل را پس از `//@version=۶` بنویسید و برای ورودی، حداقل طول را ۱ قرار دهید.

تمرین روی چند کندل

طول میانگین را از تنظیمات تغییر دهید و خروجی هر طول را روی چند کندل پیاپی ببینید. ببینید خط میانگین با تغییر طول چطور نسبت به حرکت قیمت واکنش متفاوتی نشان می‌دهد؛ سپس تنظیمات را عوض کنید و همان کندل‌ها را دوباره بسنجید. این تمرین کمک می‌کند ارتباط میان ورودی، محاسبه و نمایش را خودتان دنبال کنید، بدون تکرار مثال محاسبه‌ی اصلی مقاله.

برای ادامه‌ی اندیکاتورنویسی در محیط دیگر، مقاله‌ی «اندیکاتورنویسی با MQL5» را بخوانید؛ پیش از شروع، آشنایی پایه با برنامه‌نویسی لازم است. برای تفاوت ابزارهایی که اطلاعات بازار را نمایش می‌دهند با ابزارهایی که اجرا را خودکار می‌کنند، مقاله‌ی «اکسپرت چیست و چه فرقی با اندیکاتور دارد؟» را هم بخوانید.