From 3f1bed1fdd6fc851f356fb287c2e0e3c2e74336b Mon Sep 17 00:00:00 2001 From: Mostafa Date: Wed, 17 Apr 2024 15:36:17 +0330 Subject: [PATCH] fix: style-guide typo --- .vitepress/config.ts | 12 +++---- src/style-guide/index.md | 35 ++++++++++--------- src/style-guide/rules-essential.md | 4 +-- src/style-guide/rules-recommended.md | 4 +-- src/style-guide/rules-strongly-recommended.md | 18 +++++----- 5 files changed, 38 insertions(+), 35 deletions(-) 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 هم کاملاً قابل قبول است.

بد

@@ -76,7 +76,7 @@ components/
-## نامگذاری کامپوننت های پایه {#base-component-names} +## نامگذاری کامپوننت‌های پایه {#base-component-names} **کامپوننت های پایه (همچنین به عنوان presentational، dumb، یا pure components شناخته می شوند) که از استایل و قراردادهای خاص برنامه برخوردارند، همگی باید با یک پیشوند خاص شروع شوند، مانند `Base`، `App` یا `V`.** @@ -156,11 +156,11 @@ components/ -## نامگذاری کامپوننت های تک نمونه‌ای {#single-instance-component-names} +## نامگذاری کامپوننت‌های تک نمونه‌ای {#single-instance-component-names} **کامپوننت هایی که تنها باید یک نمونه فعال داشته باشند، باید با پیشوند `The` شروع شوند تا نشان دهند که تنها می‌تواند یک نمونه از آن وجود داشته باشد.** -این به این معنا نیست که این کامپوننت تنها در یک صفحه استفاده می‌شود، بلکه تنها یک بار _برای هر صفحه_ استفاده خواهد شد. این کامپوننت‌ها هرگز پراپ‌ها را قبول نمی‌کنند، زیرا بطور خاص برای برنامه‌ی شما ساخته شده‌اند نه اینکه محتوایشان در برنامه‌ی شما هم استفاده شود. اگر نیاز به افزودن پراپ پیدا کنید، این نشانگر خوبی است که در واقع این یک کامپوننت قابل استفاده مجدد است که _در حال حاضر_ فقط یکبار _برای هر صفحه_ استفاده می‌شود. +این به این معنا نیست که این کامپوننت تنها در یک صفحه استفاده می‌شود، بلکه تنها یک بار _برای هر صفحه_ استفاده خواهد شد. این کامپوننت‌ها هرگز پراپ‌ها را قبول نمی‌کنند، زیرا بطور خاص برای برنامه‌ی شما ساخته شده‌اند نه اینکه محتوایشان در برنامه‌ی شما هم استفاده شود. اگر نیاز به افزودن پراپ پیدا کنید، این نشانگر خوبی است که در واقع این یک کامپوننت قابل استفاده مجدد است که _در حال حاضر_ فقط یکبار _برای هر صفحه_ استفاده می‌شود.

بد

@@ -284,7 +284,7 @@ components/ |- TermsCheckbox.vue ``` -همانطور که ممکن است متوجه شوید، خیلی سخت است که ببینید کدام کامپوننت‌ها به طور خاص مربوط به جستجو هستند. حالا بیایید کامپوننت ها را براساس این قاعده تغییر نام دهیم : +همانطور که ممکن است متوجه شوید، خیلی سخت است که ببینید کدام کامپوننت‌ها به طور خاص مربوط به جستجو هستند. حالا بیایید کامپوننت ها را براساس این قاعده تغییر نام دهیم : ``` components/ @@ -298,7 +298,7 @@ components/ از آنجا که ویرایشگرها به طور معمول فایل‌ها را به ترتیب الفبا مرتب می‌کنند، اکنون تمام ارتباطات مهم بین کامپوننت‌ها با یک نگاه آشکار می‌شوند. -ممکن است شما تمایل داشته باشید که این مشکل را به شیوه های مختلف حل کنید، به عنوان مثال تمام کامپوننت‌های جستجو را زیر یک پوشه با نام "search" و سپس تمام کامپوننت‌های تنظیمات را زیر یک پوشه با نام "settings" قرار دهید. اما ما تنها این رویکرد را در اپلیکیشن‌های بسیار بزرگ (مانند 100+ کامپوننت) توصیه می‌کنیم، به این دلیل : +ممکن است شما تمایل داشته باشید که این مشکل را به شیوه های مختلف حل کنید، به عنوان مثال تمام کامپوننت‌های جستجو را زیر یک پوشه با نام "search" و سپس تمام کامپوننت‌های تنظیمات را زیر یک پوشه با نام "settings" قرار دهید. اما ما تنها این رویکرد را در اپلیکیشن‌های بسیار بزرگ (مانند 100+ کامپوننت) توصیه می‌کنیم، به این دلیل : - عموماً زمان بیشتری برای پیمایش درون زیرپوشه‌های تو در تو نیاز است تا اینکه از طریق یک پوشه تکی با نام `components` پیمایش شوند. - تداخل نام (برای مثال، وجود چندین کامپوننت با نام `ButtonDelete.vue`) باعث می‌شود که پیمایش سریع به یک کامپوننت خاص در ویرایشگر کد دشوارتر شود. @@ -377,7 +377,7 @@ components/ **در بیشتر پروژه‌ها، نام کامپوننت ها باید در [Single-File Components](/guide/scaling-up/sfc) و تمپلیت‌های رشته‌ای به صورت PascalCase باشد، اما در تمپلیت‌های داخل DOM به صورت kebab-case باشد.** -PascalCase در مقایسه با kebab-case مزایایی دارد : +PascalCase در مقایسه با kebab-case مزایایی دارد : - ویرایشگرها می‌توانند در تمپلیت‌ها نام کامپوننت ها را به صورت خودکار تکمیل کنند، زیرا PascalCase در جاوااسکریپت هم استفاده می‌شود. - `` (فرم PascalCase) از لحاظ بصری بیشتر از `` (فرم kebab-case) از عناصر خود HTML مجزا است، زیرا به اندازه دو کاراکتر میان آنها تفاوت وجود دارد (دو حرف بزرگ در حالت PascalCase) در حالی که در حالت kebab-case تنها یک تفاوت وجود دارد (خط فاصله).