Merge remote-tracking branch 'origin/upstream'

Author: mostafa-nematpour

.vitepress/config.ts

@@ -190,10 +190,6 @@ export const sidebar: ThemeConfig['sidebar'] = {
           text: 'اتصال input در فرم',
           link: '/guide/essentials/forms'
         },
-        {
-          text: 'هوک‌های چرخه حیات',
-          link: '/guide/essentials/lifecycle'
-        },
         { text: 'ناظرها - Watchers', link: '/guide/essentials/watchers' },
         {
           text: 'ارجاع از طریق تمپلیت - Template Refs',
@@ -202,6 +198,10 @@ export const sidebar: ThemeConfig['sidebar'] = {
         {
           text: 'مبانی کامپوننت‌ها',
           link: '/guide/essentials/component-basics'
+        },
+        {
+          text: 'هوک‌های چرخه حیات',
+          link: '/guide/essentials/lifecycle'
         }
       ]
     },

.vitepress/theme/components/VueMasteryBanner.vue

@@ -12,14 +12,12 @@ import SponsorsAside from './components/SponsorsAside.vue'
 import VueSchoolLink from './components/VueSchoolLink.vue'
 // import Banner from './components/Banner.vue'
 // import TextAd from './components/TextAd.vue'
-import VueMasteryBanner from './components/VueMasteryBanner.vue'
 
 export default Object.assign({}, VPTheme, {
   Layout: () => {
     // @ts-ignore
     return h(VPTheme.Layout, null, {
       // banner: () => h(Banner),
-      banner: () => h(VueMasteryBanner),
       'sidebar-top': () => h(PreferenceSwitch),
       'sidebar-bottom': () => h(SecurityUpdateBtn),
       'aside-mid': () => h(SponsorsAside)

.vitepress/theme/index.ts

@@ -6,9 +6,9 @@
 
 ## استفاده پایه {#basic-usage}
 
-گاهی اوقات ممکن است به این وضعیت برخورد کنیم که یک بخش از تمپلیت یک کامپوننت از نظر منطقی به آن تعلق دارد، اما از نظر ظاهری باید در مکان دیگری در DOM نمایش داده شود، خارج از ساختار DOM برنامه.
+گاهی اوقات ممکن است به این وضعیت برخورد کنیم که یک بخش از تمپلیت یک کامپوننت از نظر منطقی به آن تعلق دارد، اما از نظر ظاهری باید در مکان دیگری در DOM نمایش داده شود، حتی خارج از ساختار DOM برنامه.
 
-یکی از مثال‌های رایج این وضعیت زمانی است که یک مدال تمام صفحه ای ایجاد می‌کنیم. بهتر است دکمه مدال و خود مدال در داخل همان کامپوننت قرار داشته باشند، زیرا هر دو به وضعیت باز/بسته بودن مدال مرتبط هستند. اما این به این معناست که مدال به همراه دکمه در سلسله مراتب DOM برنامه نمایش داده می‌شود و در نتیجه ممکن است موقعیت دهی مدال با استفاده از CSS مشکل‌ساز شود.
+یکی از مثال‌های رایج این وضعیت زمانی است که یک مُدال تمام صفحه ای ایجاد می‌کنیم. بهتر است کد دکمه مدال و خود مدال در داخل همان کامپوننت قرار داشته باشند، زیرا هر دو به وضعیت باز/بسته بودن مدال مرتبط هستند. اما این به این معناست که مدال به همراه دکمه در سلسله مراتب DOM برنامه نمایش داده می‌شود و در نتیجه ممکن است موقعیت دهی مدال با استفاده از CSS مشکل‌ساز شود.
 
 ساختار HTML زیر را در نظر بگیرید.
 
@@ -169,11 +169,11 @@ const open = ref(false)
 </Teleport>
 ```
 
-که وضعیت `isMobile` می‌تواند با تشخیص تغییرات در media query به صورت پویا به‌روزرسانی شود.
+سپس می‌توانیم به صورت پویا `isMobile` را به روز کنیم.
 
 ## چندین تلپورت بر روی یک هدف {#multiple-teleports-on-the-same-target}
 
-یک مورد رایج می‌تواند شامل کامپوننت `<Modal>` باشد که امکان فعال شدن همزمان چندین نمونه را فراهم می‌کند. در این نوع سناریو، چندین کامپوننت `<Teleport>` می‌توانند محتوای خود را به همان عنصر هدف منتقل کنند. ترتیب اضافه کردن المان‌ها، به ترتیب انتقال‌دهی خواهد بود، به این معنا که المان‌های بعدی پس از المان‌های انتقالی اولیه در داخل عنصر هدف قرار می‌گیرند.
+یک مورد رایج می‌تواند شامل کامپوننت `<Modal>` باشد که امکان فعال شدن همزمان چندین نمونه را فراهم می‌کند. در این نوع سناریو، چندین کامپوننت `<Teleport>` می‌توانند محتوای خود را به همان عنصر هدف منتقل کنند. ترتیب اضافه کردن المان‌ها، به ترتیب انتقال‌دهی خواهد بود، به این معنا که المان‌های بعدی پس از المان‌های انتقالی اولیه در داخل عنصر هدف قرار می‌گیرند، اما همه در داخل همان عنصر هدف خواهند بود.
 
 با توجه به موارد زیر:
 

src/guide/built-ins/teleport.md

@@ -138,4 +138,4 @@ export default {
 
 این روش پیشنهادی هنگام استفاده از SFCها و یا string templateها می‌باشد. اما همانطور که در [محدودیت‌های تجزیه تمپلیت در DOM](/guide/essentials/component-basics#in-dom-template-parsing-caveats) صبحت شد، تگ‌های PascalCase در in-DOM templates قابل استفاده نیستند.
 
-خوشبختانه Vue از تبدیل تگ‌های kebab-case به کامپوننت‌های ثبت‌شده با PascalCase پشتیبانی می‌کند. این به این معناست که کامپوننت ثبت شده `MyComponents` می‌تواند در تمپلیت هم به شکل `<MyComponent>` و هم به شکل `<my-component>` رفرنس داده شود. این قابلیت به ما اجازه می‌دهد تا همان ثبت کردن کامپوننت در جاوااسکریپت را بدون در نظر گرفتن نحوه نوشتن آن در تمپلیت استفاده کنیم.
+خوشبختانه Vue از تبدیل تگ‌های kebab-case به کامپوننت‌های ثبت‌شده با PascalCase پشتیبانی می‌کند. این به این معناست که کامپوننت ثبت شده `MyComponents` می‌تواند در تمپلیت Vue (یا داخل یک عنصر HTML ارائه شده توسط Vue) هم به شکل `<MyComponent>` و هم به شکل `<my-component>` رفرنس داده شود. این قابلیت به ما اجازه می‌دهد تا همان ثبت کردن کامپوننت در جاوااسکریپت را بدون در نظر گرفتن نحوه نوشتن آن در تمپلیت استفاده کنیم.

src/guide/components/registration.md

@@ -303,7 +303,7 @@ function BaseLayout(slots) {
 می‌توانید از پراپرتی [‎$slots](/api/component-instance.html#slots) در ترکیب با [v-if](/guide/essentials/conditional.html#v-if) برای رسیدن به این هدف استفاده کنید.
 
 در مثال زیر یک کامپوننت کارت را با سه اسلات شرطی تعریف می‌کنیم: `header` و `footer` و یک `default`.
-زمانی که header / footer / default  حضور داشته باشد، می‌خواهیم آنها را با یک المنت جدا بپیچیم تا استایل اضافی اعمال شود:
+زمانی که محتوا برای header / footer / default  حضور داشته باشد، می‌خواهیم آنها را با یک المنت جدا بپیچیم تا استایل اضافی اعمال شود:
 
 ```vue-html
 <template>

src/guide/components/slots.md

@@ -110,8 +110,8 @@ const awesome = ref(true)
 
 ## `v-if` با `v-for` {#v-if-with-v-for}
 
+وقتی که `v-if` و `v-for` هر دو روی یک عنصر استفاده شوند، ابتدا `v-if` ارزیابی می‌شود. برای جزئیات بیشتر، به [رندر لیست](list#v-for-with-v-if) مراجعه کنید.
+
 ::: warning توجه داشته باشید
-استفاده از `v-if` و `v-for` روی یک عنصر به دلیل اولویت ضمنی، **توصیه نمی‌شود**. برای جزئیات به [style guide](/style-guide/rules-essential#avoid-v-if-with-v-for) مراجعه کنید.
+استفاده از `v-if` و `v-for` روی یک عنصر به دلیل اولویت ضمنی، **توصیه نمی‌شود**. برای جزئیات به [رندر لیست](list#v-for-with-v-if) مراجعه کنید.
 :::
-
-زمانی که `v-if` و `v-for` هر دو روی یک عنصر استفاده می‌شوند، ابتدا `v-if` ارزیابی می‌شود. برای جزئیات به [list rendering guide](list#v-for-with-v-if) مراجعه کنید.

src/guide/essentials/conditional.md

@@ -223,10 +223,6 @@ data() {
 
 ## `v-if` با `v-for` {#v-for-with-v-if}
 
-::: warning توجه داشته باشید
-استفاده از `v-if` و `v-for` روی یک عنصر به دلیل اولویت ضمنی، **توصیه نمی‌شود**. برای جزئیات به [style guide](/style-guide/rules-essential#avoid-v-if-with-v-for) مراجعه کنید.
-:::
-
 وقتی هر دو روی یک نود وجود داشته باشند، `v-if` اولویت بالاتری نسبت به `v-for` دارد. این بدان معناست که شرط `v-if` دسترسی به متغیرهای درون اِسکوپ `v-for` نخواهد داشت:
 
 ```vue-html
@@ -249,6 +245,16 @@ data() {
 </template>
 ```
 
+:::warning هشدار
+استفاده از `v-if` و `v-for` روی یک عنصر به دلیل اولویت ضمنی **توصیه نمی‌شود**.  
+
+دو مورد رایج وجود دارد که ممکن است وسوسه شوید این کار را انجام دهید:  
+
+- **فیلتر کردن آیتم‌ها در یک لیست** (مانند `v-for="user in users" v-if="user.isActive"‎`). در این موارد، `users` را با یک پراپرتی computed جدید جایگزین کنید که لیست فیلترشده شما را برمی‌گرداند (مثلاً `activeUsers`).  
+
+- **اجتناب از رندر یک لیست در صورتی که نباید نمایش داده شود** (مانند `v-for="user in users" v-if="shouldShowUsers"‎`). در این موارد، `v-if` را به یک عنصر کانتینر بالاتر منتقل کنید (مانند `ul` یا `ol`).  
+:::
+
 ## حفظ وضعیت با `key` {#maintaining-state-with-key}
 
 وقتی Vue لیستی از المان‌های رندرشده با `v-for` را به‌روزرسانی می‌کند، به طور پیش‌فرض از استراتژی پچ در محل (in-place patch) استفاده می‌کند. اگر ترتیب آیتم‌های داده تغییر کرده باشد، به جای جابجایی المان‌های DOM برای مطابقت با ترتیب آیتم‌ها، Vue هر المان را د رجای قبلی خود اصلاح می‌کند و مطمئن می‌شود که محتوای رندرشده در آن اندیس خاص درست است.
@@ -275,7 +281,7 @@ data() {
 `key` اینجا یک خاصیت ویژه‌ای است که با `v-bind` پیاده سازی شده است. نباید آن را با متغیر کلیدی key هنگام [استفاده از v-for با یک آبجکت](#v-for-with-an-object) اشتباه بگیرید.
 :::
 
-[توصیه می‌شود](/style-guide/rules-essential#use-keyed-v-for) هر جا امکان دارد یک خاصیت `key` با `v-for` ارائه دهید، مگر اینکه محتوای DOM تکرارشونده ساده باشد (هیچ اجزاء یا المان‌های DOM حاوی state نباشد) یا عمداً برای افزایش عملکرد به رفتار پیش فرض تکیه می کنید. (مترجم:‌ همه جا از `key` استفاده کنید چون از آینده خبر ندارید و نمی‌دونید چه بلایی قراره سر کدی که شما نوشتید بیاد 😃)
+توصیه می‌شود هر جا امکان دارد یک خاصیت `key` با `v-for` ارائه دهید، مگر اینکه محتوای DOM تکرارشونده ساده باشد (هیچ کامپوننت یا المان‌های DOM حاوی state نباشد) یا عمداً برای افزایش عملکرد به رفتار پیش فرض تکیه می کنید. (مترجم:‌ همه جا از `key` استفاده کنید چون از آینده خبر ندارید و نمی‌دونید چه بلایی قراره سر کدی که شما نوشتید بیاد 😃)
 
 خاصیت `key` مقادیر اولیه - یعنی رشته‌ها و اعداد - را انتظار دارد. از آبجکت‌ها به عنوان کلید `v-for` استفاده نکنید. برای استفاده جزئی از خاصیت `key` لطفا به [مستندات API key](/api/built-in-special-attributes#key) مراجعه کنید. (مترجم: از `index` درون `v-for` به عنوان `key` استفاده نکنید)
 

src/guide/essentials/list.md

@@ -314,6 +314,8 @@ defineExpose({
 
 هنگامی که والد نمونه‌ای از این کامپوننت را از طریق ارجاع تمپلیت می‌گیرد، نمونه بازیابی شده به شکل `{ a: number, b: number }` خواهد بود (refها همانند نمونه‌های معمولی به صورت خودکار unwrap می‌شوند)
 
+توجه داشته باشید که `defineExpose` باید قبل از هر عملیات `await` فراخوانی شود. در غیر این صورت، ویژگی‌ها و متدهایی که پس از عملیات `await` مشخص می‌شوند، قابل دسترسی نخواهند بود.
+
 همچنین ببینید: [Typing Component Template Refs](/guide/typescript/composition-api#typing-component-template-refs) <sup class="vt-badge ts" />
 
 </div>