การสร้าง API แบบ Imperative สำหรับคอมโพเนนต์

เริ่มต้นด้วยการกำหนดสัญญา: FocusableInput อาจเปิดเผยการโฟกัส การยกเลิกโฟกัส และ getValue ห่อหุ้มด้วย forwardRef เก็บการอ้างอิงภายในที่ชี้ไปยังช่องป้อนข้อมูลจริง แล้วส่งคืนการดำเนินการทั้งสามผ่าน useImperativeHandle

เมธอดแต่ละรายการมอบหมายงานต่อให้ช่องป้อนข้อมูลเบื้องหลัง ทำให้คอมโพเนนต์แม่ได้รับการดำเนินการที่ต้องการอย่างตรงจุด โดยไม่ต้องเข้าถึงองค์ประกอบดิบ

คอมโพเนนต์สื่อได้รับประโยชน์อย่างมากจากเอพีไอเชิงคำสั่ง VideoPlayer สามารถเปิดเผยการเล่น การหยุดชั่วคราว และ seekTo โดยแต่ละรายการมอบหมายงานต่อให้เมธอดขององค์ประกอบวิดีโอเอชทีเอ็มแอลแบบเนทีฟผ่านการอ้างอิงวิดีโอภายใน

seekTo รับเวลาเป็นวินาทีและกำหนดค่า currentTime ทำให้คอมโพเนนต์แม่ควบคุมการเล่นได้อย่างแม่นยำ ซึ่งคงทำได้ไม่สะดวกหากขับเคลื่อนด้วยพร็อพเพียงอย่างเดียว

คารูเซลสามารถเปิดเผยการไปถัดไป การไปก่อนหน้า และ goToSlide เพื่อให้ตัวควบคุมภายนอกหรือเครื่องจัดการแป้นพิมพ์ขับเคลื่อนได้ ภายใน เมธอดเหล่านี้จะอัปเดตสถานะดัชนีที่ใช้งานอยู่ และคอมโพเนนต์จะเรนเดอร์สไลด์ใหม่

แนวทางนี้ผสานตัวกระตุ้นเชิงคำสั่งเข้ากับการเรนเดอร์เชิงประกาศ: คอมโพเนนต์แม่สั่งการเปลี่ยนผ่าน แล้วคารูเซลเรนเดอร์ผลลัพธ์ผ่านลำดับการทำงานของสถานะตามปกติ

แฮนเดิลเชิงคำสั่งคือสัญญาสาธารณะ จึงควรจัดทำเอกสารสำหรับแต่ละเมธอด พารามิเตอร์ และค่าที่ส่งคืน เอกสารที่ชัดเจนจะบอกผู้ใช้งานว่าอะไรได้รับการรองรับ และลดการพึ่งพาส่วนภายในที่ไม่ได้จัดทำเอกสาร

ให้มองแฮนเดิลเหมือนพื้นผิวเอพีไออื่น ๆ: รายการอ้างอิงสั้น ๆ ที่แสดงเมธอด เช่น การเล่น การหยุดชั่วคราว และ seekTo(วินาที) จะช่วยป้องกันการใช้งานผิดและความสับสน

เมื่อผู้ใช้งานพึ่งพาแฮนเดิลแล้ว การลบหรือเปลี่ยนชื่อเมธอดถือเป็นการเปลี่ยนแปลงที่ทำให้ใช้งานร่วมกันไม่ได้ ควรเพิ่มเมธอดใหม่แทนการแก้ลายเซ็นเดิม และประกาศเลิกใช้งานอย่างเหมาะสมก่อนลบสิ่งใดออก

การมองแฮนเดิลเป็นเอพีไอที่มีการจัดเวอร์ชันช่วยป้องกันไม่ให้โค้ดปลายทางเสียหายเมื่อคุณขยายคอมโพเนนต์ไปตามเวลา

คอมโพเนนต์จริงจำนวนมากผสมผสานทั้งสองรูปแบบ VideoPlayer อาจรับพร็อพแหล่งที่มาและพร็อพ autoPlay แบบเชิงประกาศ พร้อมทั้งเปิดเผยการเล่นและ seekTo แบบเชิงคำสั่งสำหรับช่วงเวลาที่พร็อพไม่สามารถสื่อความหมายได้ดี

แนวทางคือใช้พร็อพสำหรับสถานะและการกำหนดค่า และเก็บแฮนเดิลเชิงคำสั่งไว้สำหรับการดำเนินการครั้งเดียวที่ถูกกระตุ้นในช่วงเวลาเฉพาะ

หากต้องการทดสอบเอพีไอเชิงคำสั่ง ให้เรนเดอร์คอมโพเนนต์พร้อมการอ้างอิง ห่อการโต้ตอบไว้ในการอัปเดตที่ควบคุม แล้วเรียกเมธอดที่เปิดเผยผ่าน ref.current จากนั้นตรวจสอบผลลัพธ์ที่สังเกตได้ เช่น วิดีโอหยุดชั่วคราวหรือดัชนีสไลด์เปลี่ยนแปลง

การเรียกกลับของการอ้างอิงสามารถเก็บแฮนเดิลระหว่างการเรนเดอร์ ทำให้การทดสอบมีการอ้างอิงที่เสถียรสำหรับเรียกเมธอด

สตอรีบุ๊กเป็นสถานที่ที่ดีสำหรับสาธิตแฮนเดิลเชิงคำสั่ง เรื่องราวหนึ่งเรื่องสามารถเก็บการอ้างอิงไปยังคอมโพเนนต์และเรนเดอร์ปุ่มที่เรียกเมธอดของคอมโพเนนต์ ทำให้ผู้ตรวจสอบทดลองการเล่น การหยุดชั่วคราว หรือ goToSlide ได้แบบโต้ตอบ

เรื่องราวเหล่านี้ยังทำหน้าที่เป็นเอกสารที่มีชีวิต โดยแสดงให้เห็นอย่างชัดเจนว่าเอพีไอเชิงคำสั่งทำงานอย่างไรเมื่อแยกออกมาใช้งานโดยลำพัง

แฮนเดิลเชิงคำสั่งพบได้บ่อยเมื่อห่อหุ้มไลบรารีที่ไม่ใช่รีแอ็กต์ ไลบรารีแผนภูมิเปิดเผยเมธอดสำหรับวาดใหม่หรืออัปเดต ชุดพัฒนาซอฟต์แวร์แผนที่เปิดเผย panTo และ setZoom ส่วนโปรแกรมแก้ไขข้อความสมบูรณ์เปิดเผย insertText หรือ getContents

การห่อหุ้มไลบรารีเช่นนี้ไว้ในคอมโพเนนต์รีแอ็กต์และเปิดเผยแฮนเดิลที่สะอาด ทำให้ส่วนอื่นของแอปพลิเคชันมีวิธีขับเคลื่อนที่เป็นระเบียบและสอดคล้องกับแนวทางของรีแอ็กต์

เมธอดบนแฮนเดิลมักปิดล้อมสถานะปัจจุบันไว้ จึงควรใช้อาร์เรย์การพึ่งพาของ useImperativeHandle เพื่อรีเฟรชเมธอดเมื่อจำเป็น และใช้ useCallback กับตัวช่วยภายในเพื่อหลีกเลี่ยงการปิดล้อมค่าที่ล้าสมัย

แฮนเดิลที่จัดการอย่างดีจะทำงานกับค่าที่เป็นปัจจุบันเสมอ ดังนั้นเมื่อคอมโพเนนต์แม่เรียก getValue หรือ seekTo พฤติกรรมที่ได้จะสอดคล้องกับการเรนเดอร์ล่าสุด

นำแนวทางการออกแบบไปใช้กับเอพีไอของคอมโพเนนต์เชิงคำสั่ง

คุณได้ออกแบบแฮนเดิลสำหรับ FocusableInput, VideoPlayer และคารูเซล โดยแต่ละรายการเปิดเผยเมธอดการดำเนินการจำนวนเล็กน้อย ควรจัดทำเอกสารและจัดเวอร์ชันให้เมธอดเหล่านั้น เนื่องจากผู้ใช้งานพึ่งพาเมธอดเหล่านี้ในฐานะเอพีไอสาธารณะ

ผสานการดำเนินการเชิงคำสั่งเข้ากับพร็อพเชิงประกาศ ทดสอบผ่าน ref.current ภายในการอัปเดตที่ควบคุม และสาธิตพฤติกรรมในสตอรีบุ๊ก รูปแบบเดียวกันนี้ยังใช้ห่อหุ้มไลบรารีแผนภูมิ แผนที่ และโปรแกรมแก้ไขได้อย่างเป็นระเบียบ