diff --git a/.vitepress/config.ts b/.vitepress/config.ts index a28b3071..aeb10539 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -546,26 +546,26 @@ export const sidebar: ThemeConfig['sidebar'] = { ], '/style-guide/': [ { - text: 'Style Guide', + text: 'راهنمای استایل', items: [ { - text: 'Overview', + text: 'بررسی اجمالی', link: '/style-guide/' }, { - text: 'A - Essential', + text: 'A - ضروری', link: '/style-guide/rules-essential' }, { - text: 'B - Strongly Recommended', + text: 'B - به شدت توصیه میشود', link: '/style-guide/rules-strongly-recommended' }, { - text: 'C - Recommended', + text: 'C - توصیه میشوند', link: '/style-guide/rules-recommended' }, { - text: 'D - Use with Caution', + text: 'D - با احتیاط از آنها استفاده کنید', link: '/style-guide/rules-use-with-caution' } ] diff --git a/src/style-guide/index.md b/src/style-guide/index.md index 36d3becf..f2d057c4 100644 --- a/src/style-guide/index.md +++ b/src/style-guide/index.md @@ -4,35 +4,38 @@ outline: deep # راهنمای استایل (ظاهر) {#style-guide} -این بخش رسمی آموزش ظاهر مخصوص vue است. اگر از vue در پروژهای استفاده میکنید این بهترین منبع برای دور شدن از ارور ها, bikeshedding و ضد الگوهاست. با اینحال ما فکر نمیکنیم هیچ راهنماییای برای تمامی تیمها و پروژهها ایدهال باشد. تجربه نشان میدهد الگوهای ذهنی را میزان فناوری در اطراف و ارزشهای ذهنی مشخص میکنند. -در بیشتر موارد، ما همچنین از پیشنهادات در مورد جاوا اسکریپت یا به طور کلی HTML اجتناب می کنیم. برای ما حائز اهمیت نیست اگر نقطه ویرگول یا کاماهای انتهایی استفاده میکنید. ما اهمیتی نمیدهیم که در HTML شما برای استرینگها از نقل قولهای تک یا دو نقل قول (double quotation or single quotation) استفاده میکنید. با این حال، برخی استثناها وجود دارد، مثلا ما دریافتیم که داشتن یک الگوی خاص در زمینه Vue مفید است. +این بخش رسمی آموزش استایل کدنویسی و استانداردهای مخصوص یک پروژه vue است. اگر از vue در پروژهای استفاده میکنید این بهترین منبع برای دور شدن از خطاها، بحثهای بیمورد و ضد الگوهاست. با اینحال ما فکر نمیکنیم هیچ راهنمای استایلی برای تمامی تیمها و پروژهها ایدهآل باشد. تجربه نشان میدهد الگوهای ذهنی را میزان فناوری در اطراف و ارزشهای ذهنی مشخص میکنند. + +در بیشتر موارد، ما همچنین از پیشنهادات در مورد جاوااسکریپت یا به طور کلی HTML اجتناب میکنیم. برای ما حائز اهمیت نیست اگر نقطه ویرگول یا کاماهای انتهایی استفاده میکنید. ما اهمیتی نمیدهیم که در HTML شما برای استرینگها از نقل قولهای تک یا دو نقل قول (double quotation or single quotation) استفاده میکنید. با این حال، برخی استثناها وجود دارد، مثلا ما دریافتیم که داشتن یک الگوی خاص در زمینه Vue مفید است. در نهایت، قوانین به چهار دسته تقسیم میشوند: ## دستهبندیهای قوانین {#rule-categories} -### اولویتهای الف: ضروریها (پیشگیری از خطا) {#priority-a-essential-error-prevention} +### اولویتهای A: ضروریها (پیشگیری از خطا) {#priority-a-essential-error-prevention} + +این قوانین به جلوگیری از خطاها کمک میکنند، بنابراین آنها را یاد بگیرید و به هر قیمتی از آنها استفاده کنید. ممکن است استثنائاتی وجود داشته باشد، اما بسیار کمیاب هستند و فقط توسط افرادی که در جاوااسکریپت و Vue دانش تخصصی دارند، ممکن است ایجاد شوند. + +- [دیدن همه قوانین الویت A](./rules-essential) -این قوانین به جلوگیری از خطاها کمک می کنند، بنابراین آنها را یاد بگیرید و به هر قیمتی از آنها استفاده کنید. ممکن است استثنائاتی وجود داشته باشد، اما بسیار کمیاب هستند و فقط توسط افرادی که در جاوا اسکریپت و Vue تبحر دارند، ممکن است ایجاد شوند. -- [دیدن همه قوانین الویت الف](./rules-essential) +### اولویتهای B: به شدت توصیه میشود. {#priority-b-strongly-recommended} -### اولویتهای ب: به شدت توصیه می شود. {#priority-b-strongly-recommended} +این قوانین برای بهبود خوانایی و/یا تجربه توسعه دهنده در اکثر پروژه ها یافت شده است. اگر آنها را نقض کنید، کد شما همچنان اجرا می شود، اما نقضها باید کم باشند و به خوبی توجیه شوند. -این قوانین برای بهبود خوانایی و/یا تجربه توسعه دهنده در اکثر پروژه ها یافت شده است. در صورت وجود ارور کد شما همچنان اجرا می شود، اما نقض ها باید کم باشند و به خوبی توجیه شوند. -- [دیدن همه قوانین الویت ب](./rules-strongly-recommended) +- [دیدن همه قوانین الویت B](./rules-strongly-recommended) -### الویتهای پ: توصیه میشوند. {#priority-c-recommended} +### الویتهای C: توصیه میشوند. {#priority-c-recommended} -در جایی که گزینه های متعدد و به همه به یک اندازه خوب وجود دارد، می توان یک انتخاب دلخواه برای اطمینان از ثبات انجام داد. در این قوانین، هر یک از گزینه های قابل قبول را شرح می دهیم و یک انتخاب پیش فرض را پیشنهاد می کنیم. این بدان معناست که میتوانید با خیال راحت انتخاب متفاوتی در پایگاه کد خود داشته باشید، به شرطی که بدون تغییر باشد و دلیل خوبی داشته باشید. لطفاً دلیل خوبی داشته باشید! با انطباق با استاندارد جامعه، شما: +در جایی که گزینههای متعدد و به همه به یک اندازه خوب وجود دارد، می توان یک انتخاب دلخواه برای اطمینان از ثبات انجام داد. در این قوانین، هر یک از گزینههای قابل قبول را شرح میدهیم و یک انتخاب پیش فرض را پیشنهاد میکنیم. این بدان معناست که میتوانید با خیال راحت انتخاب متفاوتی در پایگاه کد خود داشته باشید، به شرطی که بدون تغییر باشد و دلیل خوبی داشته باشید. لطفاً دلیل خوبی داشته باشید! با انطباق با استاندارد جامعه، شما: -1.مغز خود را آموزش دهید تا به راحتی بیشتر کدهای کامیونیتی را که با آن روبرو می شوید تجزیه کند +1. مغز خود را آموزش دهید تا به راحتی بیشتر کدهای کامیونیتی را که با آن روبرو می شوید تجزیه کند 2. بتوانید اکثر نمونه های کد کامیونیتی را بدون تغییر کپی و پیست کنید -3. اغلب میبینید که کارمندهای جدید از همین الانش هم به سبک کدنویسی مورد علاقه شما عادت کردهاند، حداقل راجع به Vue +3. غالباً میبینید کارمندان جدید استخدام شده، دست کم در مورد Vue، از قبل به سبک کدنویسی مورد علاقه شما عادت کردهاند. -- [دیدن همه قوانین الویت پ](./rules-recommended) +- [دیدن همه قوانین الویت C](./rules-recommended) -### الویتهای ج: با احتیاط از آنها استفاده کنید {#priority-d-use-with-caution} +### الویتهای D: با احتیاط از آنها استفاده کنید {#priority-d-use-with-caution} -برخی از ویژگیهای Vue برای تطبیق موارد ارورهای نادر یا مهاجرتهای نرم از یک پایگاه کدهای قدیمی وجود دارد. با این حال، وقتی بیش از حد از این ویژگیها استفاده می شود، می توانند حفظ کد شما را دشوارتر کنند یا حتی به منبع ارورها تبدیل شوند. این قوانین به ویژگیهای بالقوه پرخطر اشاره میکنند و توضیح میدهند که چه زمانی و چرا باید از آنها اجتناب کرد. +برخی از ویژگیهای Vue برای حالات نادر یا مهاجرتهای نرمتر از یک پایگاه کدهای قدیمی وجود دارد. با این حال، وقتی بیش از حد از این ویژگیها استفاده میشود، میتوانند حفظ کد شما را دشوارتر کنند یا حتی به منبع باگها تبدیل شوند. این قوانین به ویژگیهای بالقوه پرخطر اشاره میکنند و توضیح میدهند که چه زمانی و چرا باید از آنها اجتناب کرد. -- [دیدن همه قوانین الویت ج](./rules-use-with-caution) +- [دیدن همه قوانین الویت D](./rules-use-with-caution) diff --git a/src/style-guide/rules-essential.md b/src/style-guide/rules-essential.md index a8c76d8a..abf03cbb 100644 --- a/src/style-guide/rules-essential.md +++ b/src/style-guide/rules-essential.md @@ -1,6 +1,6 @@ -# قوانین اولویت A: ضروری {#priority-a-rules-essential} +# قوانین اولویت A : ضروری {#priority-a-rules-essential} -این قوانین به جلوگیری از خطاها کمک میکنند، پس حتماً آنها را یاد بگیرید و همیشه از آنها پیروی کنید. ممکن است استثناهایی وجود داشته باشد، اما باید بسیار نادر باشند و توسط کسانی که در vue و جاوااسکریپت حرفه ای هستند، اعمال شوند. +این قوانین به جلوگیری از خطاها کمک میکنند، پس حتماً آنها را یاد بگیرید و همیشه از آنها پیروی کنید. ممکن است استثناهایی وجود داشته باشد، اما باید بسیار نادر باشند و توسط کسانی که در vue و جاوااسکریپت حرفهای هستند، اعمال شوند. ## از نامهای چند کلمهای برای کامپوننتها استفاده کنید {#use-multi-word-component-names} diff --git a/src/style-guide/rules-recommended.md b/src/style-guide/rules-recommended.md index 7835b0cb..a9e3c316 100644 --- a/src/style-guide/rules-recommended.md +++ b/src/style-guide/rules-recommended.md @@ -1,6 +1,6 @@ -# قوانین اولویت C: پیشنهاد شده {#priority-c-rules-recommended} +# قوانین اولویت C : پیشنهاد شده {#priority-c-rules-recommended} -زمانی که که انتخابهای متعدد و به یک اندازه خوب وجود دارد، میتوان برای حفظ ثبات، یک انتخاب دلخواه انجام داد. در این قوانین، ما هر یک از انتخابهای قابل قبول را شرح داده و یک انتخاب پیشفرض را پیشنهاد میدهیم. این به این معنا است که شما آزاد هستید تا انتخاب های متفاوتی در کدهای خودتان داشته باشید، تا زمانی که در آنها ثابت هستید و برایشان دلیل معقولی دارید. لطفا دلیل معقول و منطبق با کامیونیتی خود داشته باشید. با منطبق شدن با استندارد های کامیونیتی شما: +زمانی که که انتخابهای متعدد و به یک اندازه خوب وجود دارد، میتوان برای حفظ ثبات، یک انتخاب دلخواه انجام داد. در این قوانین، ما هر یک از انتخابهای قابل قبول را شرح داده و یک انتخاب پیشفرض را پیشنهاد میدهیم. این به این معنا است که شما آزاد هستید تا انتخابهای متفاوتی در کدهای خودتان داشته باشید، تا زمانی که در آنها ثابت هستید و برایشان دلیل معقولی دارید. لطفا دلیل معقول و منطبق با کامیونیتی خود داشته باشید. با منطبق شدن با استاندارد های کامیونیتی شما: 1. ذهن خود را آموزش میدهید تا بسیاری از کدهای کامیونیتی که با آنها مواجه میشوید را تجزیه و تحلیل کنید. 2. قادر خواهید بود بیشتر کدهای کامیونیتی را بدون تغییر دادن، کپی و پیست کنید. diff --git a/src/style-guide/rules-strongly-recommended.md b/src/style-guide/rules-strongly-recommended.md index 75232c9f..ca4df77b 100644 --- a/src/style-guide/rules-strongly-recommended.md +++ b/src/style-guide/rules-strongly-recommended.md @@ -2,7 +2,7 @@ این قوانین برای بهبود خوانایی و یا تجربه توسعه دهنده در اکثر پروژهها، ایجاد شده اند. اگر این قوانین را نقض کنید، کد شما هنوز اجرا خواهد شد، اما نقضها باید نادر و به خوبی توجیه شده باشند. -## فایل های کامپوننت {#component-files} +## فایلهای کامپوننت {#component-files} **هرگاه یک سیستم ساخت (build system) برای ادغام فایلها موجود باشد، هر کامپوننت باید در یک فایل جداگانه قرار گیرد.** @@ -40,11 +40,11 @@ components/ -## فرمت نامگذاری کامپوننت های تک فایلی {#single-file-component-filename-casing} +## فرمت نامگذاری کامپوننتهای تک فایلی {#single-file-component-filename-casing} **نام فایل کامپوننتهای تک فایلی ([Single-File Components](/guide/scaling-up/sfc)) باید همیشه به صورت PascalCase یا همیشه kebab-case باشند.** -PascalCase بهترین عملکرد را در تکمیل خودکار در ویرایشگرهای کد دارد، زیرا با نحوه ارجاع به کامپوننتها در JS یا JSX و قالبها تا جای ممکن هماهنگ است. با این حال، نام فایل با مخلوط حروف بزرگ و کوچک ممکن است گاهی مشکلاتی را در سیستمهای حساس به حروف بزرگ و کوچک ایجاد کند، به همین دلیل kebab-case هم کاملاً قابل قبول است. +PascalCase بهترین عملکرد را در تکمیل خودکار در ویرایشگرهای کد دارد، زیرا با نحوه ارجاع به کامپوننتها در JS یا JSX و تمپلیتها تا جای ممکن هماهنگ است. با این حال، نام فایل با مخلوط حروف بزرگ و کوچک ممکن است گاهی مشکلاتی را در سیستمهای حساس به حروف بزرگ و کوچک ایجاد کند، به همین دلیل kebab-case هم کاملاً قابل قبول است.