-
-
Notifications
You must be signed in to change notification settings - Fork 35.7k
/
Copy pathprerequisites.html
335 lines (317 loc) · 20.3 KB
/
prerequisites.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
<!DOCTYPE html><html lang="en"><head>
<meta charset="utf-8">
<title>Prerequisites</title>
<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@threejs">
<meta name="twitter:title" content="Three.js – Prerequisites">
<meta property="og:image" content="https://threejs.org/files/share.png">
<link rel="shortcut icon" href="../../files/favicon_white.ico" media="(prefers-color-scheme: dark)">
<link rel="shortcut icon" href="../../files/favicon.ico" media="(prefers-color-scheme: light)">
<link rel="stylesheet" href="../resources/lesson.css">
<link rel="stylesheet" href="../resources/lang.css">
<script type="importmap">
{
"imports": {
"three": "../../build/three.module.js"
}
}
</script>
</head>
<body>
<div class="container">
<div class="lesson-title">
<h1>Prerequisites</h1>
</div>
<div class="lesson">
<div class="lesson-main">
<p>These articles are meant to help you learn how to use three.js.
They assume you know how to program in JavaScript. They assume
you know what the DOM is, how to write HTML as well as create DOM elements
in JavaScript. They assume you know how to use
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import">es6 modules</a>
via import and via <code class="notranslate" translate="no"><script type="module"></code> tags. They assume you know how to use import maps.
They assume you know some CSS and that you know what
<a href="https://developer.mozilla.org/en-US/docs/Learn/CSS/Introduction_to_CSS/Selectors">CSS selectors are</a>.
They also assume you know ES5, ES6 and maybe some ES7.
They assume you know that the browser runs JavaScript only via events and callbacks.
They assume you know what a closure is.</p>
<p>Here's some brief refreshers and notes</p>
<h2 id="es6-modules">es6 modules</h2>
<p>es6 modules can be loaded via the <code class="notranslate" translate="no">import</code> keyword in a script
or inline via a <code class="notranslate" translate="no"><script type="module"></code> tag. Here's an example</p>
<pre class="prettyprint showlinemods notranslate lang-html" translate="no">
<script type="importmap">
{
"imports": {
"three": "./path/to/three.module.js",
"three/addons/": "./different/path/to/examples/jsm/"
}
}
</script>
<script type="module">
import * as THREE from 'three';
import {OrbitControls} from 'three/addons/controls/OrbitControls.js';
...
</script>
</pre>
<p>See more details at the bottom of <a href="fundamentals.html">this article</a>.</p>
<h2 id="-document-queryselector-and-document-queryselectorall-"><code class="notranslate" translate="no">document.querySelector</code> and <code class="notranslate" translate="no">document.querySelectorAll</code></h2>
<p>You can use <code class="notranslate" translate="no">document.querySelector</code> to select the first element
that matches a CSS selector. <code class="notranslate" translate="no">document.querySelectorAll</code> returns
all elements that match a CSS selector.</p>
<h2 id="you-don-t-need-onload-">You don't need <code class="notranslate" translate="no">onload</code></h2>
<p>Lots of 20yr old pages use HTML like</p>
<pre class="prettyprint showlinemods notranslate notranslate" translate="no"><body onload="somefunction()">
</pre><p>That style is deprecated. Put your scripts
at the bottom of the page.</p>
<pre class="prettyprint showlinemods notranslate lang-html" translate="no"><html>
<head>
...
</head>
<body>
...
</body>
<script>
// inline javascript
</script>
</html>
</pre>
<p>or <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script">use the <code class="notranslate" translate="no">defer</code> property</a>.</p>
<h2 id="know-how-closures-work">Know how closures work</h2>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">function a(v) {
const foo = v;
return function() {
return foo;
};
}
const f = a(123);
const g = a(456);
console.log(f()); // prints 123
console.log(g()); // prints 456
</pre>
<p>In the code above the function <code class="notranslate" translate="no">a</code> creates a new function every time it's called. That
function <em>closes</em> over the variable <code class="notranslate" translate="no">foo</code>. Here's <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures">more info</a>.</p>
<h2 id="understand-how-this-works">Understand how <code class="notranslate" translate="no">this</code> works</h2>
<p><code class="notranslate" translate="no">this</code> is not magic. It's effectively a variable that is automatically passed to functions just like
an argument is passed to function. The simple explanation is when you call a function directly
like</p>
<pre class="prettyprint showlinemods notranslate notranslate" translate="no">somefunction(a, b, c);
</pre><p><code class="notranslate" translate="no">this</code> will be <code class="notranslate" translate="no">null</code> (when in strict mode or in a module) where as when you call a function via the dot operator <code class="notranslate" translate="no">.</code> like this</p>
<pre class="prettyprint showlinemods notranslate notranslate" translate="no">someobject.somefunction(a, b, c);
</pre><p><code class="notranslate" translate="no">this</code> will be set to <code class="notranslate" translate="no">someobject</code>.</p>
<p>The parts where people get confused is with callbacks.</p>
<pre class="prettyprint showlinemods notranslate notranslate" translate="no"> const callback = someobject.somefunction;
loader.load(callback);
</pre><p>doesn't work as someone inexperienced might expect because when
<code class="notranslate" translate="no">loader.load</code> calls the callback it's not calling it with the dot <code class="notranslate" translate="no">.</code> operator
so by default <code class="notranslate" translate="no">this</code> will be null (unless the loader explicitly sets it to something).
If you want <code class="notranslate" translate="no">this</code> to be <code class="notranslate" translate="no">someobject</code> when the callback happens you need to
tell JavaScript that by binding it to the function.</p>
<pre class="prettyprint showlinemods notranslate notranslate" translate="no"> const callback = someobject.somefunction.bind(someobject);
loader.load(callback);
</pre><p><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this"><em>this</em> article might help explain <code class="notranslate" translate="no">this</code></a>.</p>
<h2 id="es5-es6-es7-stuff">ES5/ES6/ES7 stuff</h2>
<h3 id="-var-is-deprecated-use-const-and-or-let-"><code class="notranslate" translate="no">var</code> is deprecated. Use <code class="notranslate" translate="no">const</code> and/or <code class="notranslate" translate="no">let</code></h3>
<p>There is no reason to use <code class="notranslate" translate="no">var</code> <strong>EVER</strong> and at this point it's considered bad practice
to use it at all. Use <code class="notranslate" translate="no">const</code> if the variable will never be reassigned which is most of
the time. Use <code class="notranslate" translate="no">let</code> in those cases where the value changes. This will help avoid tons of bugs.</p>
<h3 id="use-for-elem-of-collection-never-for-elem-in-collection-">Use <code class="notranslate" translate="no">for(elem of collection)</code> never <code class="notranslate" translate="no">for(elem in collection)</code></h3>
<p><code class="notranslate" translate="no">for of</code> is new, <code class="notranslate" translate="no">for in</code> is old. <code class="notranslate" translate="no">for in</code> had issues that are solved by <code class="notranslate" translate="no">for of</code></p>
<p>As one example you can iterate over all the key/value pairs of an object with</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">for (const [key, value] of Object.entries(someObject)) {
console.log(key, value);
}
</pre>
<h3 id="use-foreach-map-and-filter-where-useful">Use <code class="notranslate" translate="no">forEach</code>, <code class="notranslate" translate="no">map</code>, and <code class="notranslate" translate="no">filter</code> where useful</h3>
<p>Arrays added the functions <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach"><code class="notranslate" translate="no">forEach</code></a>,
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map"><code class="notranslate" translate="no">map</code></a>, and
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter"><code class="notranslate" translate="no">filter</code></a> and
are used fairly extensively in modern JavaScript.</p>
<h3 id="use-destructuring">Use destructuring</h3>
<p>Assume an object <code class="notranslate" translate="no">const dims = {width: 300, height: 150}</code></p>
<p>old code</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const width = dims.width;
const height = dims.height;
</pre>
<p>new code</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const {width, height} = dims;
</pre>
<p>Destructuring works with arrays too. Assume an array <code class="notranslate" translate="no">const position = [5, 6, 7, 1]</code>;</p>
<p>old code</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const y = position[1];
const z = position[2];
</pre>
<p>new code</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const [, y, z] = position;
</pre>
<p>Destructuring also works in function arguments</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const dims = {width: 300, height: 150};
const vector = [3, 4];
function lengthOfVector([x, y]) {
return Math.sqrt(x * x + y * y);
}
const dist = lengthOfVector(vector); // dist = 5
function area({width, height}) {
return width * height;
}
const a = area(dims); // a = 45000
</pre>
<h3 id="use-object-declaration-short-cuts">Use object declaration short cuts</h3>
<p>old code</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no"> const width = 300;
const height = 150;
const obj = {
width: width,
height: height,
area: function() {
return this.width * this.height
},
};
</pre>
<p>new code</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no"> const width = 300;
const height = 150;
const obj = {
width,
height,
area() {
return this.width * this.height;
},
};
</pre>
<h3 id="use-the-rest-parameter-and-the-spread-operator-">Use the rest parameter and the spread operator <code class="notranslate" translate="no">...</code></h3>
<p>The rest parameter can be used to consume any number of parameters. Example</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no"> function log(className, ...args) {
const elem = document.createElement('div');
elem.className = className;
elem.textContent = args.join(' ');
document.body.appendChild(elem);
}
</pre>
<p>The spread operator can be used to expand an iterable into arguments</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const position = [1, 2, 3];
someMesh.position.set(...position);
</pre>
<p>or copy an array</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const copiedPositionArray = [...position];
copiedPositionArray.push(4); // [1,2,3,4]
console.log(position); // [1,2,3] position is unaffected
</pre>
<p>or to merge objects</p>
<pre class="prettyprint showlinemods notranslate notranslate" translate="no">const a = {abc: 123};
const b = {def: 456};
const c = {...a, ...b}; // c is now {abc: 123, def: 456}
</pre><h3 id="use-class-">Use <code class="notranslate" translate="no">class</code></h3>
<p>The syntax for making class like objects pre ES5 was unfamiliar to most
programmers. As of ES5 you can now <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">use the <code class="notranslate" translate="no">class</code>
keyword</a>
which is closer to the style of C++/C#/Java.</p>
<h3 id="understand-getters-and-setters">Understand getters and setters</h3>
<p><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get">Getters</a> and
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set">setters</a> are
common in most modern languages. The <code class="notranslate" translate="no">class</code> syntax
of ES5 makes them much easier than pre ES5.</p>
<h3 id="use-arrow-functions-where-appropriate">Use arrow functions where appropriate</h3>
<p>This is especially useful with callbacks and promises.</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">loader.load((texture) => {
// use texture
});
</pre>
<p>Arrow functions bind <code class="notranslate" translate="no">this</code> to the context in which you create the arrow function.</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const foo = (args) => {/* code */};
</pre>
<p>is a shortcut for</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const foo = (function(args) {/* code */}).bind(this));
</pre>
<p>See link above for more info on <code class="notranslate" translate="no">this</code>.</p>
<h3 id="promises-as-well-as-async-await">Promises as well as async/await</h3>
<p>Promises help with asynchronous code. Async/await help
use promises.</p>
<p>It's too big a topic to go into here but you can <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises">read up
on promises here</a>
and <a href="https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await">async/await here</a>.</p>
<h3 id="use-template-literals">Use Template Literals</h3>
<p>Template literals are strings using backticks instead of quotes.</p>
<pre class="prettyprint showlinemods notranslate notranslate" translate="no">const foo = `this is a template literal`;
</pre><p>Template literals have basically 2 features. One is they can be multi-line</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const foo = `this
is
a
template
literal`;
const bar = "this\nis\na\ntemplate\nliteral";
</pre>
<p><code class="notranslate" translate="no">foo</code> and <code class="notranslate" translate="no">bar</code> above are the same.</p>
<p>The other is that you can pop out of string mode and insert snippets of
JavaScript using <code class="notranslate" translate="no">${javascript-expression}</code>. This is the template part. Example:</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const r = 192;
const g = 255;
const b = 64;
const rgbCSSColor = `rgb(${r},${g},${b})`;
</pre>
<p>or</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const color = [192, 255, 64];
const rgbCSSColor = `rgb(${color.join(',')})`;
</pre>
<p>or</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const aWidth = 10;
const bWidth = 20;
someElement.style.width = `${aWidth + bWidth}px`;
</pre>
<h1 id="learn-javascript-coding-conventions-">Learn JavaScript coding conventions.</h1>
<p>While you're welcome to format your code any way you chose there is at least one
convention you should be aware of. Variables, function names, method names, in
JavaScript are all lowerCasedCamelCase. Constructors, the names of classes are
CapitalizedCamelCase. If you follow this rule your code will match most other
JavaScript. Many <a href="https://eslint.org">linters</a>, programs that check for obvious errors in your code,
will point out errors if you use the wrong case since by following the convention
above they can know when you're using something incorrectly.</p>
<pre class="prettyprint showlinemods notranslate lang-js" translate="no">const v = new vector(); // clearly an error if all classes start with a capital letter
const v = Vector(); // clearly an error if all functions start with a lowercase letter.
</pre>
<h1 id="consider-using-visual-studio-code">Consider using Visual Studio Code</h1>
<p>Of course use whatever editor you want but if you haven't tried it consider
using <a href="https://code.visualstudio.com/">Visual Studio Code</a> for JavaScript and
after installing it <a href="https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint">setup
eslint</a>.
It might take a few minutes to setup but it will help you immensely with finding
bugs in your JavaScript.</p>
<p>Some examples</p>
<p>If you enable <a href="https://eslint.org/docs/rules/no-undef">the <code class="notranslate" translate="no">no-undef</code> rule</a> then
VSCode via ESLint will warn you of many undefined variables. </p>
<div class="threejs_center"><img style="width: 615px;" src="../resources/images/vscode-eslint-not-defined.png"></div>
<p>Above you can see I mis-spelled <code class="notranslate" translate="no">doTheThing</code> as <code class="notranslate" translate="no">doThing</code>. There's a red squiggle
under <code class="notranslate" translate="no">doThing</code> and hovering over it it tells me it's undefined. One error
avoided.</p>
<p>If you're using <code class="notranslate" translate="no"><script></code> tags to include three.js you'll get warnings using <code class="notranslate" translate="no">THREE</code> so add <code class="notranslate" translate="no">/* global THREE */</code> at the top of your
JavaScript files to tell eslint that <code class="notranslate" translate="no">THREE</code> exists. (or better, use <code class="notranslate" translate="no">import</code> 😉)</p>
<div class="threejs_center"><img style="width: 615px;" src="../resources/images/vscode-eslint-not-a-constructor.png"></div>
<p>Above you can see eslint knows the rule that <code class="notranslate" translate="no">UpperCaseNames</code> are constructors
and so you should be using <code class="notranslate" translate="no">new</code>. Another error caught and avoided. This is <a href="https://eslint.org/docs/rules/new-cap">the
<code class="notranslate" translate="no">new-cap</code> rule</a>.</p>
<p>There are <a href="https://eslint.org/docs/rules/">100s of rules you can turn on or off or
customize</a>. For example above I mentioned you
should use <code class="notranslate" translate="no">const</code> and <code class="notranslate" translate="no">let</code> over <code class="notranslate" translate="no">var</code>.</p>
<p>Here I used <code class="notranslate" translate="no">var</code> and it warned me I should use <code class="notranslate" translate="no">let</code> or <code class="notranslate" translate="no">const</code></p>
<div class="threejs_center"><img style="width: 615px;" src="../resources/images/vscode-eslint-var.png"></div>
<p>Here I used <code class="notranslate" translate="no">let</code> but it saw I never change the value so it suggested I use <code class="notranslate" translate="no">const</code>.</p>
<div class="threejs_center"><img style="width: 615px;" src="../resources/images/vscode-eslint-let.png"></div>
<p>Of course if you'd prefer to keep using <code class="notranslate" translate="no">var</code> you can just turn off that rule.
As I said above though I prefer to use <code class="notranslate" translate="no">const</code> and <code class="notranslate" translate="no">let</code> over <code class="notranslate" translate="no">var</code> as they just
work better and prevent bugs.</p>
<p>For those cases where you really need to override a rule <a href="https://eslint.org/docs/user-guide/configuring#disabling-rules-with-inline-comments">you can add comments
to disable
them</a>
for a single line or a section of code.</p>
<h1 id="if-you-really-need-to-support-legacy-browsers-use-a-transpiler">If you really need to support legacy browsers use a transpiler</h1>
<p>Most modern browsers are auto-updated so using all these features will help you
be productive and avoid bugs. That said, if you're on a project that absolutely
must support old browsers there are <a href="https://babeljs.io">tools that will take your ES5/ES6/ES7 code
and transpile the code back to pre ES5 Javascript</a>.</p>
</div>
</div>
</div>
<script src="../resources/prettify.js"></script>
<script src="../resources/lesson.js"></script>
</body></html>