สร้างสคริปต์

Blockly ประกอบด้วยไฟล์ TypeScript กว่า 100 ไฟล์ โดยต้องคอมไพล์ โดยคอมไพเลอร์ TypeScript tsc เป็น JavaScript ก่อนจึงจะใช้ได้ ซึ่งจะสร้าง.jsจำนวนมากเท่ากัน ซึ่งเหมาะ สำหรับการทดสอบในเครื่อง แต่การโหลดไฟล์จำนวนมากเช่นนี้ผ่านอินเทอร์เน็ต จะทำให้ผู้ใช้ปลายทางได้รับประสบการณ์การใช้งานที่ช้า เราใช้ Closure Compiler เพื่อบีบอัด (ย่อ) และรวมไฟล์ต่างๆ เป็นไฟล์ 6 ไฟล์ ("Bundle" หรือ "Chunk") ที่มีขนาดรวมน้อยกว่าครึ่งหนึ่งของไฟล์ที่ไม่ได้บีบอัด เพื่อให้ Blockly โหลดได้เร็วขึ้น

ในกระบวนการนี้ โค้ดที่ใช้ฟีเจอร์ ECMAScript ล่าสุด ซึ่งอาจไม่ เข้ากันได้กับเบราว์เซอร์บางตัว จะได้รับการเปลี่ยนรูปแบบเป็น ES6 ซึ่งโดยทั่วไปจะเข้ากันได้กับเบราว์เซอร์ที่ใช้กันอย่างแพร่หลายส่วนใหญ่ ดังนั้น คุณจึงควรแสดงเฉพาะโค้ดที่ย่อขนาดแล้วต่อผู้ใช้ปลายทาง

ที่เก็บ google/blockly มี เฉพาะซอร์สโค้ด ก่อนหน้านี้ยังรวมถึงผลิตภัณฑ์บิลด์ด้วย แต่ตั้งแต่ปี 2019 เราได้เผยแพร่ชุดข้อมูลที่ย่อขนาดแล้วเป็นแพ็กเกจ blockly NPM และตั้งแต่ปี 2022 เรายังแนบเป็นไฟล์ .tgz ไปกับแต่ละรุ่นใน GitHub ด้วย ดังนั้นจึงไม่จำเป็น ต้องสร้าง Blockly เว้นแต่คุณจะแฮ็ก Blockly เอง โดยเฉพาะใน ไฟล์ในไดเรกทอรี core, blocks, generators หรือ msg

กระบวนการสร้าง ทดสอบ และเผยแพร่ Blockly เป็นแบบอัตโนมัติโดยใช้สคริปต์ npm เพื่อเรียกใช้งาน Gulp หน้านี้จะบันทึกสคริปต์หลักและ สิ่งที่แต่ละสคริปต์ทำ

โหมดบีบอัดและโหมดไม่บีบอัด

การโหลด Blockly โดยตรงจากไฟล์ .js แต่ละไฟล์ที่คอมไพเลอร์ TypeScript สร้างขึ้นเรียกว่า "โหมดไม่บีบอัด" เนื่องจากหลีกเลี่ยงขั้นตอนการบิลด์ที่ช้าหลายขั้นตอน จึงช่วยให้วงจรการแก้ไข-คอมไพล์-เรียกใช้เป็นไปอย่างรวดเร็ว นอกจากนี้ยังช่วยในการแก้ไขข้อบกพร่องเนื่องจากโค้ด JavaScript ที่ดำเนินการนั้นเกือบจะ อ่านได้ง่ายเหมือนกับแหล่งที่มาของ TypeScript ต้นฉบับ จึงไม่จำเป็นต้องใช้ Sourcemap

การโหลด Blockly จากชุดรวมที่ย่อขนาดเรียกว่า "โหมดที่บีบอัด" วิธีนี้เป็นวิธีที่ดีที่สุดในการทดสอบการเปลี่ยนแปลงใน Blockly เมื่อใช้เป็นทรัพยากร Dependency ของแพ็กเกจอื่น เนื่องจากจะทดสอบ (เวอร์ชันที่ยังไม่ได้เผยแพร่) blockly แพ็กเกจ npm

N.B.: ในที่เก็บ Blockly มีบางแห่งที่ใช้คำว่า "โหมดที่ยังไม่ได้คอมไพล์" และ "โหมดที่คอมไพล์แล้ว" เป็นคำพ้องความหมายของ "โหมดที่ไม่ได้บีบอัด" และ "โหมดที่บีบอัด" ตามลำดับ การใช้งานนี้สมเหตุสมผลในอดีต เนื่องจาก Closure Compiler ใช้เพื่อบีบอัด (ย่อ) โค้ด แต่ตอนนี้ จำเป็นต้องใช้คอมไพเลอร์ TypeScript เสมอ แม้ในโหมดที่ไม่ได้บีบอัด ดังนั้นคำศัพท์ทางเลือกนี้จึงอาจสร้างความสับสนและไม่แนะนำให้ใช้

คู่มือเริ่มต้นฉบับย่อ

  • หากคุณทำการเปลี่ยนแปลงในเครื่องและต้องการตรวจสอบว่าการเปลี่ยนแปลงดังกล่าวไม่ได้ทำให้บิลด์หรือการทดสอบใดๆ เสียหาย ให้เรียกใช้

    npm test

    เพื่อสร้าง Blockly และเรียกใช้ชุดการทดสอบ

  • หากต้องการทดสอบการเปลี่ยนแปลงในเครื่องในเบราว์เซอร์ ให้เรียกใช้

    npm start

    ซึ่งจะคอมไพล์ Blockly และเปิดเว็บเบราว์เซอร์ที่ชี้ไปยังสนามเด็กเล่น Blockly ที่เรียกใช้ Blockly ในโหมดที่ไม่ได้บีบอัด

    ไฟล์ใดๆ ใน core/, blocks/ และ generators/ ที่มีการแก้ไขจะ คอมไพล์ใหม่โดยอัตโนมัติ ให้โหลดแท็บเบราว์เซอร์ซ้ำเพื่อดูการเปลี่ยนแปลง

  • หากต้องการสร้าง Blockly เวอร์ชันที่แก้ไขในเครื่องและทดสอบในโหมดที่บีบอัด เป็นทรัพยากร Dependency ของแพ็กเกจ npm อื่น ให้เรียกใช้

    npm run package

    เพื่อสร้างแพ็กเกจ Blockly จากนั้น

    cd dist && npm link

    เพื่อบอก npm ว่าจะค้นหาไฟล์ที่คอมไพล์แล้วได้จากที่ใด จากนั้นให้ไปที่cdในไดเรกทอรีของโปรเจ็กต์ ก่อนที่จะเรียกใช้

    npm link blockly

    เพื่อให้แพ็กเกจใช้ Blockly เวอร์ชันที่คอมไพล์ใหม่แทนแพ็กเกจ blockly ที่เผยแพร่

การอ้างอิงสคริปต์โดยละเอียด

ส่วนนี้แสดงหลักการ scripts ในไฟล์ package.json ของ Blockly พร้อมคำอธิบายสิ่งที่หลักการเหล่านั้นทำ

สคริปต์เหล่านี้จะสร้างไฟล์ใน 2 ที่ ดังนี้

  • ไฟล์ในbuild/ไดเรกทอรีย่อยเป็นไฟล์กลางที่ใช้สำหรับการทดสอบในเครื่อง หรือนำเข้าโดยส่วนต่างๆ ของไปป์ไลน์การสร้างในภายหลัง
  • ไฟล์ในdist/ไดเรกทอรีย่อยจะสร้างเนื้อหาของแพ็กเกจ npm ที่เผยแพร่

ทั้ง 2 ไดเรกทอรีนี้ไม่ได้ติดตามในที่เก็บ Git ของ Blockly

clean

npm run clean จะล้างข้อมูลบิลด์ก่อนหน้าโดยการลบไดเรกทอรี build/ และ dist/ มีประโยชน์ในการแก้ไขการสร้างที่ล้มเหลวซึ่งเข้าใจยาก โดยเฉพาะอย่างยิ่ง การสร้างที่เกิดจากการเปลี่ยนชื่อไฟล์ต้นฉบับ

messages

npm run messages จะอัปเดตไฟล์ข้อความใน msg/json/ ด้วยการเปลี่ยนแปลงใดๆ ที่ทำกับ msg/messages.js และควรเรียกใช้ทุกครั้ง ที่มีการแก้ไขไฟล์นั้น

langfiles

npm run langfiles สร้างไฟล์ภาษาที่คอมไพล์แล้วใน build/msg/ จากไฟล์ข้อความใน msg/json

tsc

npm run tsc จะเรียกใช้คอมไพเลอร์ TypeScript กับเนื้อหาของไดเรกทอรี core/, blocks/ และ generators/ และเอาต์พุตไฟล์ .js แต่ละไฟล์ ไปยัง build/src/

minify

npm run minify จะเรียกใช้ closure-make-deps และ closure-calculate-chunks เพื่อกำหนดวิธีแบ่งไฟล์ .js ที่คอมไพล์แล้วออกเป็นก้อน (บิลด์ที่ย่อขนาดแล้ว) หลังจากนั้นจะเรียกใช้ closure-compiler เพื่อสร้างก้อนดังนี้

  • เนื้อหาของ build/src/core/ จะกลายเป็น dist/blockly_compressed.js
  • เนื้อหาของ build/src/blocks/ จะกลายเป็น dist/blocs_compressed.js
  • เนื้อหาของ build/src/generators/javascript/ (รวมถึง build/src/generators/javascript.js) จะกลายเป็น dist/javascript_compressed.js
  • และเช่นเดียวกันสำหรับ dart, lua, php และ python

Chuk ที่สร้างขึ้นจะใช้ Wrapper เพื่อให้มั่นใจว่าเข้ากันได้กับUniversal Module Definition จึงไม่จำเป็นต้องประมวลผลเพิ่มเติม ก่อนที่จะรวมไว้ในแพ็กเกจ

build

npm run build จะเรียกใช้งานงาน minify และ langfiles ซึ่งควรทำทุกอย่างที่จำเป็นเพื่อโหลดสนามเด็กเล่น Blockly ในโหมดบีบอัดหรือโหมดไม่บีบอัด

package

npm run package จะเรียกใช้ clean และ build จากนั้นจะดำเนินการต่อไปนี้

  • ใช้ Wrapper UMD กับไฟล์ใน build/msg/ โดยวางเวอร์ชันที่ห่อไว้ใน dist/msg/
  • เพิ่มไฟล์สนับสนุนเพิ่มเติมต่างๆ ลงใน dist/ โดยมี Wrapper UMD ในกรณีที่ เกี่ยวข้อง

publish

npm run publish ใช้โดยทีม Blockly เพื่อเผยแพร่แพ็กเกจ blockly npm โดยจะขึ้นอยู่กับโครงสร้างพื้นฐานภายในของ Google จึงไม่เป็นประโยชน์ ต่อนักพัฒนาแอปภายนอก

lint

npm run lint เรียกใช้ ESLint เพื่อทำการวิเคราะห์แบบคงที่ ของซอร์สโค้ด Blockly เพื่อค้นหาปัญหา

test

npm test (หรือ npm run test) จะเรียกใช้package task แล้วเรียกใช้การทดสอบอัตโนมัติต่างๆ (รวมถึงการเรียกใช้ ESLint) ควรเรียกใช้และผ่านการทดสอบในโค้ดที่ส่งเป็นคำขอพุลต่อที่เก็บ Blockly