Update article.md

Author: HannaParsa

2-ui/99-ui-misc/02-selection-range/article.md

@@ -1,22 +1,23 @@
 کتابخانه ها:
   - d3
   - domtree
+    
 ---
 
 # Selection and Range
 
 
-جاوااسکریپت می‌تواند به یک انتخاب موجود دسترسی داشته باشد، گره‌های DOM را به‌طور کلی یا جزئی انتخاب یا لغو انتخاب کند، محتوای انتخاب‌شده را از سند حذف کند، آن را در یک برچسب قرار دهد و غیره.
+در این فصل به انتخاب در سند و همچنین انتخاب در فیلدهای فرم، مانند `<input>` خواهیم پرداخت.
 
-می‌توانید دستور العمل‌هایی برای کارهای رایج در انتهای فصل، در بخش "Summary" بیابید. شاید این نیازهای فعلی شما را پوشش دهد، اما اگر متن کامل را بخوانید، خیلی بیشتر به دست خواهید آورد.
+جاوا اسکریپت می تواند به یک انتخاب موجود دسترسی داشته باشد، گره های DOM را به طور کلی یا جزئی انتخاب یا لغو انتخاب کند، محتوای انتخاب شده را از سند حذف کند، آن را در یک برچسب قرار دهد و غیره.
 
-درک اشیاء زیربنایی  `Range` و`Selection` آسان است، و پس از آن برای اینکه آنها را به آنچه می‌خواهید انجام دهند، به هیچ دستور العملی نیاز نخواهید داشت.
+می‌توانید دستور العمل‌هایی برای کارهای رایج در انتهای فصل، در بخش "Summary" بیابید. شاید این نیازهای فعلی شما را پوشش دهد، اما اگر متن کامل را بخوانید، خیلی بیشتر به دست خواهید آورد.
 
+درک اشیاء زیربنایی `Range` و `Selection` آسان است، و پس از آن برای اینکه آنها را به آنچه می‌خواهید انجام دهند، به هیچ دستور العملی نیاز نخواهید داشت.
 ## Range
 
 فهوم اصلی انتخاب [Range](https://dom.spec.whatwg.org/#ranges) است، که اساساً یک جفت "boundary points"است: شروع محدوده و پایان محدوده.
 
-
 یک `Range` object بدون پارامتر ساخته می شود: 
 
 ```js
@@ -31,7 +32,6 @@ let range = new Range();
 
 نکته جالب این است که آرگومان اول `node` در هر دو روش می تواند یک text node یا یelement node عنصر باشد و معنای آرگومان دوم به آن بستگی دارد.
 
-
 **اگر `node` یک text nodeاست، `offset` باید موقعیتی در متن آن باشد.**
 
 به عنوان مثال، با توجه به عنصر `<p>Hello</p>`، می‌توانیم محدوده حاوی حروف «ll» را به صورت زیر ایجاد کنیم:
@@ -50,8 +50,8 @@ let range = new Range();
 
 
 در اینجا اولین فرزند `<p>` را می گیریم (این text node است) و موقعیت های متن را در داخل آن مشخص می کنیم:
-
 ![](range-hello-1.svg)
+
 ### Selecting element nodes
 
 
@@ -60,7 +60,6 @@ let range = new Range();
 این برای ایجاد محدوده هایی که شامل گره ها به عنوان یک کل هستند، مفید است، نه اینکه در جایی در متن خود متوقف شوند.
 
 به عنوان مثال، ما یک قطعه سند پیچیده تر داریم:
-
 ```html autorun
 <p id="p">Example: <i>italic</i> and <b>bold</b></p>
 ```
@@ -104,17 +103,17 @@ drawHtmlTree(selectPDomtree, 'div.select-p-domtree', 690, 320);
 </script>
 
 
-همانطور که می بینیم، این عبارت دقیقاً از دو فرزند `<p>` با نمایه های  `0`  و `1` تشکیل شده است:
+بیایید یک محدوده برای `"Example: <i>italic</i>"` بسازیم.
 
+همانطور که می بینیم، این عبارت دقیقاً از دو فرزند `<p>` با نمایه های  `0`  و `1` تشکیل شده است:
 ![](range-example-p-0-1.svg)
 
-
 - نقطه شروع  `<p>` به عنوان  `node` والد، و  `0` به عنوان آفست است.
-
-     بنابراین می‌توانیم آن را به‌عنوان `range.setStart(p, 0)` تنظیم کنیم.
+  
+    بنابراین می‌توانیم آن را به‌عنوان `range.setStart(p, 0)` تنظیم کنیم.
 - نقطه پایانی نیز `<p>` را به عنوان  `node` والد، اما  `2` را به عنوان آفست دارد (محدوده تا را مشخص می کند، اما `offset` را شامل نمی شود).
-
-     بنابراین می‌توانیم آن را به‌عنوان `range.setEnd(p, 2)` تنظیم کنیم.
+  
+    بنابراین می‌توانیم آن را به‌عنوان `range.setEnd(p, 2)` تنظیم کنیم.
 
 در اینجا نسخه ی نمایشی است. اگر آن را اجرا کنید، می بینید که متن انتخاب شده است:
 
@@ -177,9 +176,9 @@ From <input id="start" type="number" value=1> – To <input id="end" type="numbe
 ما قبلاً می دانیم که چگونه این کار را انجام دهیم. فقط باید شروع و پایان را به عنوان یک افست نسبی در گره های متنی تنظیم کنیم.
 
 ما باید یک محدوده ایجاد کنیم، که:
-
 - از موقعیت 2 در `<p>` فرزند اول شروع می‌شود (با گرفتن همه حرف‌های اول «مثال<b>ample:</b>» به جز دو حرف اول)
 - در `<b>`فرزند اول به موقعیت 3 ختم می شود (با گرفتن سه حرف اول "<b>bol</b>d"، اما نه بیشتر):
+  
 ```html run
 <p id="p">Example: <i>italic</i> and <b>bold</b></p>
 
@@ -229,6 +228,7 @@ From <input id="start" type="number" value=1> – To <input id="end" type="numbe
 - `setStart(node, offset)` مجموعه شروع در: درست بعد از `node`.
 
 تنظیم پایان محدوده (روش های مشابه)
+
 - `setEnd(node, offset)` پایان را در: موقعیت `offset` در `node` تنظیم کنید
 - `setEndBefore(node)` پایان را در: درست قبل از `node` تنظیم کنید
 - `setEndAfter(node)` پایان را در: درست بعد از `node` تنظیم کنید
@@ -237,7 +237,6 @@ From <input id="start" type="number" value=1> – To <input id="end" type="numbe
 
 در همه این روش‌ها، `node` می‌تواند هم یک متن یا یک گره عنصر باشد: برای گره‌های متنی، `offset` بسیاری از کاراکترها را رد می‌کند، در حالی که برای گره‌های عنصر از بسیاری از گره‌های فرزند.
 
-
 حتی روش های بیشتری برای ایجاد محدوده:
 - `selectNode(node)` محدوده را برای انتخاب کل  `node` تنظیم کنید
 - `selectNodeContents(node)` محدوده را برای انتخاب کل محتویات  `node` تنظیم کنید
@@ -322,7 +321,7 @@ Click buttons to run methods on the selection, "resetExample" to reset it.
 
 ما ممکن است اشیاء `Range` ایجاد کنیم، آنها را به اطراف منتقل کنیم -- آنها به صورت بصری چیزی را به تنهایی انتخاب نمی کنند.
 
-انتخاب سند با شی `Selection` نشان داده می شود که می تواند به عنوان `window.getSelection()` یا `document.getSelection()` به دست آید. یک انتخاب ممکن است شامل محدوده صفر یا بیشتر باشد. حداقل،specification](https://www.w3.org/TR/selection-api/) این را می گوید. اگرچه در عمل، فقط فایرفاکس اجازه می دهد تا با استفاده از `key:Ctrl+click` (`key:Cmd+click` برای Mac)، چندین محدوده را در سند انتخاب کنید.
+انتخاب سند با شی`Selection`نشان داده میشود که میتواند به عنوان`window.getSelection()`یا`document.getSelection()`به دست آید. یک انتخاب ممکن است شامل محدوده صفر یابیشتر باشد. حداقل، specification](https://www.w3.org/TR/selection-api/) این رامیگوید.اگرچه درعمل، فقط فایرفاکس اجازه میدهد تا با استفاده از`key:Ctrl+click` (`key:Cmd+click` برای Mac)، چندین محدوده را در سند انتخاب کنید.
 
 در اینجا یک اسکرین شات از یک انتخاب با 3 محدوده، ساخته شده در فایرفاکس آمده است:
 
@@ -336,8 +335,8 @@ Click buttons to run methods on the selection, "resetExample" to reset it.
 
 ## Selection properties
 
-
 همانطور که گفته شد، یک انتخاب ممکن است در تئوری شامل چندین محدوده باشد. ما می توانیم این اشیاء محدوده را با استفاده از روش بدست آوریم:
+
 - `getRangeAt(i)` -- محدوده i-ام را دریافت کنید که از `0` شروع می شود. در همه مرورگرها به جز فایرفاکس، فقط «0» استفاده می شود.
 
 همچنین، ویژگی هایی وجود دارد که اغلب راحتی بهتری را ارائه می دهند.
@@ -440,13 +439,13 @@ As text: <span id="astext"></span>
 ## Selection methods
 
 ا می توانیم با افزودن/حذف محدوده ها با انتخاب کار کنیم:
+
 - `getRangeAt(i)` -- محدوده i-ام را دریافت کنید که از `0` شروع می شود. در همه مرورگرها به جز فایرفاکس، فقط  `0` استفاده می شود.
 - `addRange(range)` -- `range` را به انتخاب اضافه کنید. همه مرورگرها به جز فایرفاکس تماس را نادیده می گیرند، در صورتی که انتخاب از قبل دارای یک محدوده مرتبط باشد.
 - `removeRange(range)` --  `range` را از انتخاب حذف کنید.
 - `removeAllRanges()` -- حذف همه محدوده ها.
 - `empty()` -- نام مستعار `removeAllRanges`.
 
-
 همچنین روش‌های آسانی برای دستکاری مستقیم محدوده انتخاب، بدون فراخوانی `Range` میانی وجود دارد:
 
 - `collapse(node, offset)` -- محدوده انتخاب شده را با یک محدوده جدید جایگزین کنید که در "گره" داده شده شروع و پایان می یابد، در موقعیت "offset".
@@ -459,8 +458,8 @@ As text: <span id="astext"></span>
 - `deleteFromDocument()` -- محتوای انتخاب شده را از سند حذف کنید.
 - `containsNode(node, allowPartialContainment = false)` -- بررسی می کند که آیا انتخاب شامل "node" است (تا حدی اگر آرگومان دوم "true" باشد)
 
-
 برای اکثر وظایف، این روش‌ها خوب هستند، نیازی به دسترسی به شی `Range` زیرین نیست.
+
 به عنوان مثال، انتخاب کل محتوای پاراگراف `<p>`:
 
 ```html run
@@ -501,15 +500,14 @@ The exception is some selection methods, that replace the existing selection, su
 - `input.selectionEnd` -- موقعیت انتهای انتخاب (قابل نوشتن)،
 - `input.selectionDirection` -- جهت انتخاب، یکی از: "backward"، "backward" یا "none" (به عنوان مثال اگر با دوبار کلیک ماوس انتخاب شده باشد)،
   
-
 (رویداد ها)Events:
 - `input.onselect` -- هنگامی که چیزی انتخاب می شود فعال می شود.
 
 متد ها:
+
 - `input.select()` -- همه چیز را در کنترل متن انتخاب می کند (می تواند `textarea` به جای `input` باشد)
 - `input.setSelectionRange(start, end, [direction])` -- انتخاب را تغییر دهید تا از موقعیت `شروع` تا `"پایان` در جهت معین (اختیاری) باشد.
 - `input.setRangeText(replacement, [start], [end], [selectionMode])` -- یک محدوده از متن را با متن جدید جایگزین کنید.
-
   
   آرگومان های اختیاری`«شروع` و`«پایان`، در صورت ارائه، محدوده شروع و پایان را تنظیم می کنند، در غیر این صورت از انتخاب کاربر استفاده می شود.
 
@@ -542,18 +540,18 @@ From <input id="from" disabled> – To <input id="to" disabled>
 ```
 
 لطفا توجه داشته باشید:
-
-
 - وقتی چیزی انتخاب می‌شود، `onselect` فعال می‌شود، اما وقتی انتخاب حذف می‌شود نه.
 - طبق [spec](https://w3c.github.io/selection-api/#dfn-selectionchange)، رویداد  `document.onselectionchange` نباید برای انتخاب‌های داخل یک کنترل فرم فعال شود، زیرا به مرتبط نیست انتخاب `document` و محدوده برخی از مرورگرها آن را تولید می کنند، اما ما نباید به آن تکیه کنیم.
-### Example: moving cursor
 
+  
+### Example: moving cursor
 
 می‌توانیم `selectionStart` و `selectionEnd` را تغییر دهیم که انتخاب را تنظیم می‌کند.
 
 یک مورد مهم لبه زمانی است که `selectionStart` و `selectionEnd` با هم برابر باشند. سپس دقیقاً موقعیت مکان نما است. یا، برای بازنویسی، وقتی چیزی انتخاب نشده است، انتخاب در موقعیت مکان نما جمع می شود.
 
 بنابراین، با تنظیم `selectionStart` و `selectionEnd` روی یک مقدار، مکان‌نما را حرکت می‌دهیم.
+
 مثلا:
 
 ```html run autorun
@@ -575,10 +573,10 @@ Focus on me, the cursor will be at position 10.
 
 ### Example: modifying selection
 
-
 برای تغییر محتوای انتخابی، می‌توانیم از روش `input.setRangeText()` استفاده کنیم. البته، می‌توانیم `selectionStart/End` را بخوانیم و با آگاهی از انتخاب، زیررشته مربوط به `value` را تغییر دهیم، اما `setRangeText` قدرتمندتر و اغلب راحت‌تر است.
 
 این یک روش تا حدودی پیچیده است. در ساده ترین شکل تک آرگومان خود، جایگزین محدوده انتخابی کاربر می شود و انتخاب را حذف می کند.
+
 به عنوان مثال، در اینجا انتخاب کاربر با `*...*` پیچیده می شود:
 
 ```html run autorun
@@ -639,7 +637,7 @@ button.onclick = () => {
 
 ## Making unselectable
 
-2. برای غیرقابل انتخاب کردن چیزی، سه راه وجود دارد:
+ برای غیرقابل انتخاب کردن چیزی، سه راه وجود دارد:
 
 1. از ویژگی `user-select: none` استفاده کنید.
 
@@ -652,13 +650,12 @@ button.onclick = () => {
     <div>Selectable <div id="elem">Unselectable</div> Selectable</div>
     ```
     
-
    این اجازه نمی‌دهد انتخاب از «elem» شروع شود. اما کاربر ممکن است انتخاب را از جای دیگری شروع کند و `elem` را در آن قرار دهد.
 
-     سپس `elem` به بخشی از `document.getSelection()` تبدیل می‌شود، بنابراین انتخاب در واقع اتفاق می‌افتد، اما محتوای آن معمولاً در کپی-پیست نادیده گرفته می‌شود.
+    سپس `elem` به بخشی از `document.getSelection()` تبدیل می‌شود، بنابراین انتخاب در واقع اتفاق می‌افتد، اما محتوای آن معمولاً در کپی-پیست نادیده گرفته می‌شود.
 
 
-4. 3. از اقدام پیش‌فرض در رویدادهای `onselectstart` یا `mousedown` جلوگیری کنید.
+2. از اقدام پیش‌فرض در رویدادهای `onselectstart` یا `mousedown` جلوگیری کنید.
 
     ```html run
     <div>Selectable <div id="elem">Unselectable</div> Selectable</div>
@@ -671,8 +668,8 @@ button.onclick = () => {
    این کار از شروع انتخاب روی `elem` جلوگیری می‌کند، اما بازدیدکننده ممکن است آن را از عنصر دیگری شروع کند و سپس به `elem` گسترش دهد.
 
      زمانی که کنترل‌کننده رویداد دیگری در همان عملکرد وجود دارد که انتخاب را فعال می‌کند، راحت است (e.g. `mousedown`). بنابراین، برای جلوگیری از تضاد، انتخاب را غیرفعال می‌کنیم و همچنان اجازه می‌دهیم محتوای `elem` کپی شود.
-5. همچنین می‌توانیم انتخاب post-factum را بعد از اینکه با `document.getSelection().empty()` رخ داد پاک کنیم. این به ندرت استفاده می شود، زیرا باعث چشمک زدن ناخواسته با ظاهر شدن انتخاب می شود - ناپدید می شود.
-
+   
+3. همچنین می‌توانیم انتخاب post-factum را بعد از اینکه با `document.getSelection().empty()` رخ داد پاک کنیم. این به ندرت استفاده می شود، زیرا باعث چشمک زدن ناخواسته با ظاهر شدن انتخاب می شود - ناپدید می شود.
 
 ## References
 
@@ -683,7 +680,6 @@ button.onclick = () => {
 
 ## Summary
 
-
  ما دو API مختلف را برای انتخاب پوشش دادیم:
 
 1. برای سند: اشیاء `Selection` و `Range`.
@@ -692,6 +688,7 @@ button.onclick = () => {
 وAPI دوم بسیار ساده است، زیرا با متن کار می کند.
 
 دستور العمل های مورد استفاده احتمالاً عبارتند از:
+
 1. دریافت انتخاب:
     ```js
     let selection = document.getSelection();
@@ -704,7 +701,7 @@ button.onclick = () => {
       cloned.append(selection.getRangeAt(i).cloneContents());
     }
     ```
-3. تنظیمات selection:
+2. تنظیمات selection:
     ```js
     let selection = document.getSelection();
 
@@ -715,4 +712,5 @@ button.onclick = () => {
     selection.removeAllRanges();
     selection.addRange(range);
     ```
+    
  و در نهایت، در مورد مکان نما. موقعیت مکان نما در عناصر قابل ویرایش، مانند `<textarea>` همیشه در ابتدا یا انتهای انتخاب است. می‌توانیم با تنظیم `elem.selectionStart` و  `elem.selectionEnd` از آن برای به دست آوردن موقعیت مکان‌نما یا حرکت مکان‌نما استفاده کنیم.