# التثبيت ([name])

يمكنك تنصيب three.js بإستعمال [link:https://www.npmjs.com/ npm] و وسائل البناء الحديثة، أو قم بالبدأ فقط بإستعمال إصدار ثابت متوفر عبر خدمة CDN. بالنسبة لأغلب المستخدمين تنصيب المكتبة بإستعمال npm هو الخيار الأفضل.

بغض النظر عن إختيارك، كن حريصا على أن تقوم بإستدعاء جميع الملفات التي تنتمي لنفس الإصدار. خلط ملفات من إصدارات مختلفة قد ينتج منه بعض السلوكات الغير متوقعة.

جميع طرق تنصيب three.js بناءا على ES modules (شاهد [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules])، التي تمكنك من إستدعاء أجزاء معينة من المكتبة دون الحاجة لإستدعاء المصدر كله.

## التثبيت بإستعمال npm

لتنصيب وحدة (npm module) [link:https://www.npmjs.com/package/three three]، قم بفتح نافذة الأوامر في المجلد الخاص بمشروعك و شغل الأمر التالي:

`npm install three`

سيتم تحميل الرزمة و تثبيتها. و من ثم تصبح مستعد لإستدعائها كالأتي:

`// Option 1: Import the entire three.js core library. import * as THREE from 'three'; const scene = new THREE.Scene(); // Option 2: Import just the parts you need. import { Scene } from 'three'; const scene = new Scene();`

خلال التنصيب بإستعمال npm، لقد قمت بشكل غير مباشر بإستعمال [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool] لجمع كل الرزم التي يحتاجها مشروعك في ملف JavaScript واحد. بينما يمكن لأي جامع رزم حديث العمل مع three.js، يبقى الخيار الأكثر شيوعا هو [link:https://webpack.js.org/ webpack].

لا يمكن الوصول لكل المزايا مباشرة من خلال رزمة three (بإستعمال bare import). بقية الأجزاء المستعملة كثيرا من المكتبة مثل الضوابط (controls)، المحمل (loaders)، و آثار ما بعد المعالجة (post-processing effects)، يجب إستدعائهم من مجلد [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm]. لمعرفة المزيد، قم بزيارة قسم الأمثلة بالأسفل.

لمعرفة المزيد عن وحدات npm. قم بزيارة [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm].

## التثبيت من CDN أو استضافة ثابتة

يمكن إستعمال مكتبة three.js دون الحاجة إلى نظام بناء، سواءا عبر تحميل الملفات إلى خادم الويب الخاص بك أو باستخدام CDN موجود. بسبب أن المكتبة تعتمد على وحدات ES (modules) يجب على أي شفرة برمجية تشير إليها أن تستخدام type="module" كما هو موضح أسفله:

`<script type="importmap"> { "imports": { "three": "https://unpkg.com/three@<version>/build/three.module.js" } } </script> <script type="module"> import * as THREE from 'three'; const scene = new THREE.Scene(); </script>`

## أمثلة

يركز جوهر three.js على أهم المكونات المكونة لمحرك ثلاثي الأبعاد. العديد من المكونات المفيدة الأخرى - مثل الضوابط ، عناصر التحميل ، وتأثيرات ما بعد المعالجة - هي جزء من المجلد [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm]. .يشار إليها باسم "أمثلة" ، لأنه بينما يمكنك استخدامها ببساطة، من المفترض أيضًا إعادة دمجها وتخصيصها. هذه المكونات تضل متزامنة مع المكتبة الأساسية بينما يتم الاحتفاظ بحزم الجهات الخارجية المماثلة على npm بواسطة أشخاص مختلفين وقد لا تكون محدثة.

لا يلزم تثبيت الأمثلة بشكل منفصل ، ولكن يجب استيرادها بشكل منفصل. إذا تم تثبيت three.js بواسطة npm ، يمكنك إستدعاء مكون OrbitControls كالأتي:

`import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; const controls = new OrbitControls( camera, renderer.domElement );`

إذا تم تثبيت three.js من CDN ، فمن المستحسن إستخدم نفس CDN لتثبيت المكونات الأخرى:

`<script type="importmap"> { "imports": { "three": "https://unpkg.com/three@<version>/build/three.module.js", "three/addons/": "https://unpkg.com/three@<version>/examples/jsm/" } } </script> <script type="module"> import * as THREE from 'three'; import { OrbitControls } from 'three/addons/controls/OrbitControls.js'; const controls = new OrbitControls( camera, renderer.domElement ); </script>`

من المهم أن تستخدم جميع الملفات نفس الإصدار. لا تستورد أمثلة مختلفة من إصدارات مختلفة، أو تستخدم أمثلة من إصدارات مختلفة عن مكتبة three.js نفسها.

## التوافق

### واردات CommonJS

في حين أن معظم حِزم JavaScript الحديثة تدعم الآن وحدات ES افتراضيًا ، فقد لا تدعم بعض أدوات البناء القديمة. في مثل هذه الحالات بإستطاعتك تعديل المجمع لفهم وحدات ES:
[link:http://browserify.org/ Browserify] يحتاج فقط إلى إضافة [link:https://github.com/babel/babelify babelify] على سبيل المثال.

### خرائط الإستيراد

تختلف المسارات المستوردة عند التثبيت من npm ، مقارنة بالتثبيت من استضافة ثابتة أو CDN. نحن ندرك أن هذه مشكلة مريحة لكلا مجموعتي المستخدمين. يفضل المطورون الذين لديهم أدوات إنشاء وحزم محددات الحزم المجردة (على سبيل المثال "three") بدلاً من المسارات النسبية ، وتستخدم الملفات في المجلد examples/ مراجع نسبية إلى three.module.js التي لا تتبع هذا التوقع. أولئك الذين لا يستخدمون أدوات الإنشاء - للنماذج الأولية السريعة أو التعلم أو التفضيل الشخصي - قد يكرهون بالمثل تلك الواردات النسبية ، والتي تتطلب هياكل مجلدات معينة وتكون أقل تسامحًا من مساحة الاسم THREE. * العام.

نأمل في إزالة هذه المسارات النسبية عندما يصبح [link:https://github.com/WICG/import-maps import maps] متاحًا على نطاق واسع ، واستبدالها بمحددات الحزمة المجردة إلى اسم الحزمة npm ، 'three'. يتطابق هذا مع توقعات أداة الإنشاء لحزم npm بشكل وثيق ، ويسمح لمجموعتي المستخدمين بكتابة نفس الرمز تمامًا عند استيراد ملف. بالنسبة للمستخدمين الذين يفضلون تجنب أدوات الإنشاء ، يمكن أن يوجه تعيين JSON البسيط جميع الواردات إلى CDN أو مجلد ملف ثابت. من الناحية التجريبية ، يمكنك محاولة استخدام عمليات استيراد أبسط اليوم مع تعبئة خريطة الاستيراد ، كما هو موضح في [link:https://glitch.com/edit/#!/three-import-map?path=index.html import map example].

### Node.js

لأن three.js مبني للويب ، فهو يعتمد على واجهات برمجة تطبيقات المتصفح و DOM التي لا توجد دائمًا في Node.js. يمكن حل بعض هذه المشاكل باستخدام shims مثل [link:https://github.com/stackgl/headless-gl headless-gl] ، أو باستبدال المكونات مثل [page:TextureLoader] ببدائل مخصصة. قد تكون واجهات برمجة تطبيقات DOM الأخرى متشابكة بشكل عميق مع الكود الذي يستخدمها ، وسيكون من الصعب التغلب عليها. نرحب بطلبات السحب البسيطة والقابلة للصيانة لتحسين دعم Node.js ، ولكن نوصي بفتح مشكلة لمناقشة تحسيناتك أولاً.

تأكد من إضافة `{ "type": "module" }` إلى `package.json` الخاص بك لتمكين وحدات ES6 في مشروع node الخاص بك.