Typescript: ما الذي لا يعجبك في موقع الويب والوثائق من TypeScript؟

صفحة "أنواع الأدوات المساعدة" غير محدثة

غالبًا ما يتم تفويت أنواع الأدوات المساعدة الجديدة أو عدم إضافتها إلى صفحة "أنواع الأدوات المساعدة" في الكتيب (على سبيل المثال ، Parameters<T> ). غالبًا ما أضطر إلى اللجوء إلى تصفح lib.es5.d.ts بدلاً من الكتيب.

العلامات: docs

ملعب TypeScript الرسمي ليس جيدًا مثل البدائل مفتوحة المصدر

يقوم https://typescript-play.js.org بعمل أفضل من العمل الرسمي: فهو يغطي إصدارات متعددة من TypeScript ، ويسمح بمشاركة نصوص أكبر حجمًا ، كما أنه يدعم جميع أعلام المترجم ويكون الوضع المتشدد قيد التشغيل افتراضيًا.

العلامات: playground

عدم وجود صفحة فهرس لملاحظات الإصدار

أتمنى أن تكون هناك صفحة فهرس لإدراج كافة ملاحظات الإصدار السابقة ضمن عنوان URL هذا : https://www.typescriptlang.org/docs/handbook/release-notes . بهذه الطريقة ، يمكننا تتبع تحديثات الإصدار السابق على TypeScript.

العلامات: docs ، release notes

لا يوجد مسرد لأسماء الأنواع

إذا مررت رمزًا لشخص ما مثل const a: "foo" | "bar" فقد لا تعرف أن تسمي هذا نوع الاتحاد.

هذا شريط منخفض جدًا ، ولكن عندما نبدأ في الحديث عن الأنواع الوجودية / الشرطية / المعينة / إلخ ، فمن الجيد أن تكون قادرًا على الانتقال إلى صفحة تحاول فقط تحديدها ، ولكن لا توثقها بعمق حتى تتمكن من الحصول على نظرة عامة من كل تصنيف لهذه اللغة

العلامات: types ، handbook

لا توجد صفحة لمشاركتها مع الأشخاص غير التقنيين

هذا ما كنت بحاجة إليه في البداية لإقناع الأشخاص خارج نطاق الهندسة (فكر في مديري PM ، والمديرين غير التقنيين) بالقيمة في استخدام TypeScript. في النهاية كتبت هذا بنفسي لكني أفضل أن يكون مسؤولاً

العلامات: guides

الوثائق المكتوبة بالتأكيد موجودة خارج مستندات TypeScript وهي قديمة

يجب أن يمتلك مشروع TypeScript مستندات حول هذا. وثائق "مؤكد تايب" موجودة في:

• https://definitelytyped.org
• https://github.com/DefinitelyTyped/DefinitelyTyped#how -can-i- المساهمة

يمكن أن تحتوي مستندات TS على نظرة عامة حول ماهيتها ، ولماذا يتم استخدامها ويمكننا إهمال الموقع الرسمي

العلامات: definitely-typed

لا يقوم بتدريس TS بشكل تدريجي

(تم تعديله لمزيد من سهولة القراءة) أشعر أن المستندات تكون أكثر فاعلية عندما يكون لديها "شخصية" واضحة مخصصة لها. عندما تم إنشاء هذه المستندات ، لم يكن ES6 شيئًا بعد. عندما تم إنشاء هذه المستندات ، كان بإمكانك تعلم كل TS في فترة ما بعد الظهر.

لقد تغير الزمن.

لقد قمت بعمل رد فعل ، نص مطبوع ، ورقة غش قبل الميلاد ، شعرت أن مستندات TS على وجه التحديد لا تخدم الأشخاص الذين يعرفون بالفعل es6 ولم يرغبوا أيضًا في تعلم TS المتقدم دفعة واحدة. لذلك تستهدف على وجه التحديد مطور JS ذي الخبرة الذي يجرب TS لأول مرة. يوجد الكثير منا. المستندات الحالية إما "ها هنا ما هي الفئات" أو "هنا مجموعة من الأدوية الجنسية المخيفة المظهر في نفس الصفحة مثل مستندات عامل النوع لدينا".

على وجه الخصوص ، فيما يلي قائمة غير شاملة بالشخصيات التي يجب مراعاتها والتي يمكن أن تكون بمثابة مدرس تقدمي:

• الأشخاص الذين يريدون فقط استخدام TS مع JSDoc ، لا توجد خطوة بناء
• الأشخاص الذين يرغبون في استخدام TS دون كتابة أي أدوية عامة قدر الإمكان
• الأشخاص الذين يقومون بترحيل قواعد الرموز من JS / Flow إلى TS
• الأشخاص الجدد في TS ، والذين تبنوا TS ، لكنهم شاهدوا أخطاء غير مألوفة ، مطولة لأول مرة وليس لديهم أي فكرة عن كيفية التعامل معها (هذا هو جمهور " تحري الخلل وإصلاحه ") أو إلغاء الاشتراك فيه
• الأشخاص الذين يرغبون في نشر تطبيقات TS مقابل مكتبات TS
• الأشخاص الذين يرغبون في تعلم استخدام عوامل تشغيل النوع
• الأشخاص الذين يرغبون في التعرف على نوع الأدوات المساعدة التي قد تساعدهم
• الأشخاص الذين يحتاجون إلى كتابة مكتبات غير نمطية (من تأثير الشبكة إلى حد كبير واهتمام TS أن تجعل كتابة d.ts سهلة للغاية وموثقة جيدًا قدر الإمكان)
• و aaaaaaalll الطريق في النهاية ، الأشخاص الذين يريدون تعلم كيفية كتابة منطق النوع العام الخاص بهم
• (ربما) الأشخاص الذين يرغبون في كتابة المكونات الإضافية التي تحتاج إلى اجتياز TS AST

هذه كلها مراحل في رحلة تبني TS ، يجب علينا رسمها والتأكد من عدم وجود جرف في المستندات حيث يسقط الأشخاص لأنهم لا يعرفون ماذا يفعلون وبالتالي يفترضون أنه صعب للغاية.

أعتقد أن المستندات يمكن أن تفعل الكثير للمساعدة في تبديد الأسطورة القائلة بأن:

• أنت بحاجة إلى أقصى درجات الأمان في جميع الأوقات (ليس فقط في tsconfig ، ولكن أيضًا في الخيارات التي نتخذها في وظائف الكتابة)
• TS مخصص لمبرمجي OO (نعم ، لقد رأيت هذا)
• TS مخصص فقط لمطوري C # / Java الذين يأتون إلى JS ويفتقدون أنواعًا ، وليس له قيمة حقيقية لمطوري JS
• يجب أن تكون قادرًا على اكتشاف كيفية حل أخطاء TS بنفسك
• بشكل عام ، فإن TS لديها منحنى تعليمي مرتفع للبدء

إذا كانت الموارد متاحة ، يمكننا ويجب علينا استهداف مجتمعات مطوّرة كبيرة ومحددة للمساعدة في تبنيها ، على سبيل المثال لـ React ولكن أيضًا لـ Vue وأيضًا Node وما إلى ذلك. يمكنك القيام بذلك من خلال المستندات الرئيسية ، على سبيل المثال ، تميز مستندات Vue

ربما يكون هذا بمثابة عقبة كبيرة أمام اعتماد TS في المرحلة المتأخرة (أي الأشخاص الذين يحتاجون إلى المزيد من المستندات / الأدوات / الضمان / التمسك باليد من أجل بيعها على TS) كما يمكنني أن أتخيل.

العلامات: docs

مواصفات لغة TypeScript المرتبطة قديمة تمامًا

مباشرة على الصفحة الرئيسية التي تربطها بـ "مواصفات لغة TypeScript".

اقرأ المواصفات على GitHub أو قم بتنزيلها كملف docx أو pdf.

ومع ذلك ، فإن هذه المواصفات قديمة تمامًا (عالقة في الإصدار 1.8 ، آخر تحديث حقيقي في يناير 2016) ، ولم تتم صيانتها. سيكون من الأفضل إسقاط أي ذكر للمواصفات.

العلامات: spec specification outdated

عنصر واجهة مستخدم يشبه الملعب لعينات التعليمات البرمجية

قم بتقديم جميع نماذج التعليمات البرمجية في المستندات في عنصر واجهة مستخدم يشبه الملعب ، مع جميع التلميحات المريحة والإبرازات وما إلى ذلك.

من الناحية المثالية ، مع القدرة على الخروج إلى ملعب كامل ، مع التحرير والنظر إلى JS / الكتابة المنبعثة.

سيعتمد هذا بشكل طبيعي على Official TypeScript Playground ليس جيدًا مثل اقتراح

وثائق API الموجودة فقط في ملاحظات الإصدار

بعض الأنواع ، مثل unknown ، موثقة فقط في ملاحظات الإصدار ، مما يجعل من الصعب اكتشافها.

العلامات: docs

ملعب Fourslash

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

• اجعل ملعب TS يقوم بتحميل أي ملف من TS repo عبر شيء مثل: https://www.typescriptlang.org/play/tests/cases/compiler/aliasAssignments.ts
• اجعل ملعب TS يفهم كلمة "fourslash"
• إضافة تعليقات وصفية على تلك الملفات

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

ملعب يشرح بنية TS معينة

ليس من الصعب أن تتعثر في بناء جملة TS معقد يصعب فهمه حقًا. الأدوية الجنيسة العودية ، مجتمعة عبر النقابات والأنواع المفهرسة غير التقليدية ... على سبيل المثال ، أحد الأعشاش الكبيرة لمثل هذه الحشرات المخيفة هي الكتابة.

ماذا لو كان المرء قادرًا على لصق جزء من بناء الجملة الغني بالزاوية ، ومراقبة عرض أو رسم تخطيطي سهل الهضم من قبل الإنسان. كما تعلم ، حيث يمكنك بلا شك أن ترى بوضوح أن A فئة ، و B هو نوع اتحاد ، و C هو معلمة عامة لـ D وما إلى ذلك وهلم جرا.

بدءًا من `` طباعة AST المطوّلة '' الساذجة ، يمكن أن يتوسع هذا مع مرور الوقت ومساهمة المجتمع في التعرف على الأنماط بشكل أعمق وفي المرئيات التفاعلية الأكثر ثراءً والمخططات الشبيهة بـ UML.

لا يوجد بحث عن الوثائق

غالبًا ما أضطر إلى اللجوء إلى googling حول كيفية القيام بشيء ما باستخدام النص المطبوع بدلاً من استخدام المستند الرئيسي كمصدر للحقيقة ، على سبيل المثال باستخدام DocSearch كما هو الحال في مستندات React

العلامات: search ، exploration

تسليط الضوء على المشاريع المجتمعية

قد تكون هذه أشياء مثل اللقاءات أو المحادثات المجتمعية أو الكتب.

ولكن يمكن أيضًا أن تتعلم مشاريع البرامج الكبيرة التي تستخدم TypeScript والتي يمكن لأي شخص التعلم منها.

العلامات: Community

توفير أدلة لتشغيل أعلام المترجم المحددة

على سبيل المثال ، إذا كنت سأشغل noImplicitReturns فما نوع المشكلات التي سأواجهها ، وكيف يمكنني التعامل معها؟ نقوم بشحن هذه الأنواع من التوصيات مع ملاحظات إصدار الإصدار للوقت الذي تم فيه تقديم هذه الأعلام ، وبالتالي فإن البحث عنها أمر صعب.

العلامات: tsconfig

قم بإنشاء صفحة فهرس خطأ المترجم

تقوم لغة الصدأ بهذا الأمر ، إنها مجهود كبير جدًا للبدء (يوجد في TS أكثر من ألف خطأ في الوقت الحاضر) ولكن رسائل الخطأ في tsc موجزة ، وجودهم في الموقع يجعلهم قابلين للفهرسة بواسطة محركات البحث ، وقابلة للتحسين مع كود مثال .

العلامات: compiler

ماذا لو كان المرء قادرًا على لصق جزء من بناء الجملة الغني بالزوايا ، ومراقبة عرض أو رسم تخطيطي سهل الهضم من قبل الإنسان

أعتقد أن هذا سيكون رائعًا ، لكن في بعض الحالات أعتقد أن التفسير المنظم للغاية لكيفية انهيار النوع (والذي يبدو ممكنًا إلى حد ما للإنشاء التلقائي) ليس مفيدًا مثل التعرف على بعض التركيبات الشائعة للأنواع والأنماط التي تحقق هدف معين. كمثال ، لنفترض أنني أريد أن يشرح لك أحد ما هذا:

type X<T extends object> = {
    [K in keyof T]: T[K]
}[keyof T]

يمكن أن أخبرك بذلك

X هو اسم مستعار من النوع بمعامل نوع واحد T مقيد بـ object . عند إنشاء مثيل له باستخدام T ، فإنه ينتج نوعًا معينًا ، حيث تكون القيمة هي نوع الوصول المفهرس لكل مكون K من النوع keyof T T[K] . ثم ينتج X نوع وصول مفهرس لهذا النوع المعين بالنوع keyof T .

ولكن سيكون من المفيد جدًا ، ومع ذلك فمن الصعب للغاية إنتاجه من قِبل أي شخص باستثناء شخص لديه معرفة عملية بـ TypeScript ، لإخبارك:

X يحصل على اتحاد أنواع قيم أعضاء T .

أعتقد أن الحصول على مجموعة من "الوصفات" لأنماط كهذه قد يكون مفيدًا.

تعد صفحة الأنواع المتقدمة مجرد نوع من أنواع الإغراق لأي نوع غير واضح (لقد سرقت مجموعة من أفكار TypeScript لأداة تحليل PHP الثابتة ، لذلك أجد نفسي في تلك الصفحة كثيرًا).

هناك مجموعة من الأفكار مترابطة ، ولكن يمكن فعل ذلك إلى حد ما باستخدام الارتباطات التشعبية بين الصفحات.

يشعر قسم Type Guard / Type Predicate بشكل خاص أنه يستحق صفحته الخاصة.

إرشادات لكتابة المكتبات المطبوعة

لقد وجدت أن شحن مكتبة مكتوبة بلغة Typescript ليس بالأمر السهل. الكثير من حالات الحافة التي يجب مراعاتها اعتمادًا على المستهلك المستهدف. لدي آرائي الخاصة حول هذا الموضوع تمامًا للنقاش ، لكن توثيق الإرشادات الرسمية لمؤلفي المكتبات سيكون رائعًا.

العلامات: libraries ، guidance

يمكن أن يكون التنقل عبر الهاتف المحمول صعبًا

لا أستطيع قراءة كتيب موقع الويب من الهاتف المحمول وهو أمر محبط للغاية. سيكون من الرائع أيضًا أن يكون لديك التنقل السابق / التالي في أسفل الصفحة في كل صفحة من الكتيب.

من تغريدة

العلامات: nav

استخدم المزيد من الأمثلة الواقعية

بعض الأمثلة الحالية عامة أو مجردة بشكل مفرط ، باستخدام اصطلاحات التسمية التي تستند إلى الأحرف (A ، B ، C) أو المصطلحات غير القابلة للربط (foo ، bar ، baz ، args ، obj ، إلخ). آمل أن أرى المزيد من الأمثلة الواقعية (الأشكال ، والحيوانات ، والمنتجات ، والمستخدمون) وحالات الاستخدام المشروعة (استدعاءات واجهة برمجة التطبيقات ، والتسجيل ، ومعالجة الأخطاء ، وتنسيق البيانات). سيكون هذا مفيدًا بشكل خاص للمفاهيم التي هي بالفعل تجريدية ، مثل Generics والأنواع المتقدمة.

ملحوظة: بعض مناطق التوثيق تتعامل بالفعل مع هذه المشكلة 👌🏻 لكنها ضرب وفشل.

العلامات: examples

مكتبة المثال وأفضل الممارسات

أظهر كيفية كتابة أنواع مختلفة من الوظائف. يحتوي Like لوداش على جميع أنواع الوظائف الفاخرة مثل الانتقاء والتمديد والتسوية وما إلى ذلك وصف كيفية كتابتها.

مكتبة تزداد تعقيدًا. يمكن أن يكون قد قرأ المزيد من الروابط للالتزامات التي توضح كيفية استخدام شيء معين في TS في الإنتاج.

أيًا كان ما يتم بناؤه في النهاية ، آمل أن يكون من السهل جدًا على أي شخص إضافة أمثلة إليه. أفترض أنه سيكون كتيب TS مثل git repo.

عادةً ما تتمتع أفضل المشاريع مفتوحة المصدر بأفضل الوثائق وتجربة مستخدم جديدة.

لنجعل TS أكثر ترحيباً بالمستخدمين الجدد.

وصف أفضل لخيارات tsconfig

الوصف الحالي في صفحة خيارات المترجم

• يقدم وصفًا غامضًا جدًا لكل خيار وكيف يؤثر على التجميع والتحقق من النوع. قد تكون بعض الأمثلة مفيدة حقًا.
• تنسيق الجدول يترك مساحة صغيرة من الوصف
• لا توجد معلومات حول إصدار TypeScript
• الترتيب الأبجدي غير مفيد ، فبعض الخيارات مرتبطة ارتباطًا وثيقًا ببعضها البعض مثل target ، module و lib أو جميع الخيارات المتشابهة. من الصعب الحصول على فهم جيد لها عندما تنظر إليها بشكل منفصل. لن تفهم خيار lib بدون فهم target أولاً.
• في معظم الأوقات ، يستخدم الأشخاص هذه الخيارات في ملفات tsconfg ، وليس كخيارات tsc لذلك قد يكون التنسيق الحالي مربكًا للقادمين الجدد.
• المزيد من الأوصاف التفصيلية لبعض الخيارات مبعثرة عبر الوثائق ، مثل @types ، typeRoots و types الخيارات موصوفة في صفحة tsconfig.json و baseUrl و paths في حل الوحدة النمطية

إنه متصل بتوفير أدلة لتشغيل اقتراح

تعديل:
ناهيك عن الخيارات الجديدة مثل تلك المتعلقة ببناء المشاريع المركبة ، والتي لا توجد معلومات عنها في المستندات وأنت مجبر على تجميع الصورة بأكملها معًا بناءً على ملاحظات الإصدار ومشكلات GitHub.

العلامات: tsconfig

اجمع الوثائق والمدونة والموارد الرسمية الأخرى في مكان واحد

إذا تمكنا من جمع جميع الموارد الرسمية حول TypeScript في مكان واحد (على سبيل المثال www.typescriptlang.org ) ، فسيكون ذلك رائعًا! 😊

على سبيل المثال ، منشور المدونة حول إعلان الإصدار 3.5 في مكان آخر ( devblogs.microsoft.com ):
https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/

ملاحظة الإصدار v3.4 موجودة في مكان آخر:
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html

أشعر أن هذا ليس مفيدًا جدًا ومربكًا لمطوري TypeScript. 😕

العلامات: blog ، resources

قم بإنشاء tsconfig.json عن طريق ملء نموذج واجهة المستخدم بتفضيلاتك وإعداد المشروع

سيكون من الجيد ، إذا كانت الوثائق ستحتوي على نموذج / معالج يساعد في إنشاء tsconfig.json الذي يناسب البيئة المستهدفة (المتصفح ، nodeJS) ، وتفضيلات المستخدم (صارمة أو متساهلة حسب رغبة المستخدم) وهيكل دليل المشروع. تحتوي خيارات مترجم TS حاليًا على العديد من الخيارات المهملة وبعض أعلام المترجم ، والتي تبدو من النظرة الأولى أنها قد تفعل الشيء نفسه تقريبًا (ما هي الاختلافات بين بعض الخيارات ، على سبيل المثال المتعلقة بالمسارات / dirs / الجذور). يجب أن يلتزم tsconfig الذي تم إنشاؤه بأفضل الممارسات من فريق Microsoft TypeScript الأساسي. قد تشمل الأسئلة الإرشادية الأخرى ما يلي:

• ما هي تجربة فريق تطوير المشروع مع TypeScript (قد يقترح خيارات المترجم ذات الصلة "JS to TS" للمبتدئين مع اقتراح جميع الخيارات الصارمة لـ "TS gurus")
• هل المشروع عبارة عن مكتبة أو تطبيق (في حالة وجود مكتبة بها القليل من التبعيات ، قد يكون من الأسهل استخدام بعض الميزات الصارمة ، مثل strictNullChecks ، لذلك قد يُقترح اعتمادًا على تجربة المستخدم)
• هو التطبيق الذي يستخدم JSX / TSX (رد فعل)
• هل تستخدم الإطار / المكتبة التي تستخدم الديكور
  
  
  
  • يجب إصدار البيانات الوصفية للمصممين ، بحيث يمكن استخدامها بواسطة إطار العمل / المكتبة في وقت التشغيل (اذكر الأطر والمكتبات ، مثل Angular و Aurelia كمثال)
  
  

العلامات: tsconfig ، examples ، guides ، wizard ، exploration

orta أعتقد أنه سيكون من الرائع إنشاء نسخة محمولة من الملعب ، أو على الأقل تكييف النسخة الحالية. اعتبارًا من الآن ، يبدو الملعب سيئًا على الهاتف المحمول (لقطة الشاشة مصنوعة على iPhone 7).

أتمنى أن يكون هناك قسم في منطقة "الكتيب" بالموقع تحدث على وجه التحديد عن حرفية الكائن والطرق المختلفة التي يمكنك من خلالها كتابتها.

على سبيل المثال ، أحتاج باستمرار إلى Google شيئًا مثل "كائن مكتوب على الآلة الكاتبة مع أي خصائص" أو "كائن مكتوب على الآلة الكاتبة حرفيًا مع خاصية واحدة مطلوبة وأي خصائص أخرى".

ويجب علي دائمًا البحث عن النوع { [key: string]: any } ، والذي لم تتم مناقشته في أي مكان.

يتم التحدث عن بعض هذه الأشياء على "واجهات" ولكن هذا ليس واضحًا على الفور.

زيادة أنواع البائعين

في بعض الأحيان عند العمل مع أنواع DefinitelyTyped أو تعريفات وحدة البائع الأخرى ، أجد أنني بحاجة إلى تعديل التعريفات إما إلى:

1) الكتابة فوق / تعديل التعريف الحالي
2) إضافة طرق / خصائص جديدة

لم أتمكن من العثور على وثائق حول الطريقة الصحيحة لإنجاز المهمة في سيناريوهات مختلفة. أنا أيضًا لم أقم بتدوين ملاحظات جيدة عندما احتجت إلى القيام بذلك بنفسي 🐙. https://www.typescriptlang.org/docs/handbook/dec ئذٍ-merging.html يعالج مشكلة كود الطرف الأول ولكني لم أجعل هذه النصيحة تعمل مع أنواع / عمليات تصدير وحدات الطرف الثالث.

من الواضح أنه من الرائع فتح العلاقات العامة على الفور لإصلاح / تحديث الأنواع الموجودة في الريبو المقابل ، ولكن قد يستغرق ذلك بعض الوقت حتى يتم دمجها مرة أخرى في الفرع الرئيسي مما قد يؤدي إلى تعطيل سير العمل وإجبار إضافة تحويلات مؤقتة any و a متابعة TODO.

العلامات: vendor

وثائق مترجم API

يحتوي موقع wiki على بعض المعلومات حول استخدام Compiler API (https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) ولكنه يعرض فقط أمثلة عن كيفية استخدامه لتحقيق أهداف معينة. سيكون من الرائع أن يكون لديك المزيد من معلومات نمط JSDoc لسرد الكائنات والأساليب المحددة الموجودة والتعرف على ما يفعلونه. في الوقت الحالي ، أحاول تعلم واجهة برمجة التطبيقات وأحتاج إلى إلقاء نظرة على مصدر الطباعة لمعرفة ما يحدث.

(يرجى تجاهل ما إذا لم يتم تنفيذ ذلك لمجرد أن واجهة برمجة التطبيقات ليست مستقرة بعد كما هو مذكور في الويكي)

العلامات: compiler

البرامج التعليمية التي تركز على TS مقارنة باللغات الحالية

يأتي الكثير من الأشخاص إلى TypeScript كلغة ثانية (أو أكثر). تتمثل إحدى طرق تبسيط تعلم TypeScript في مقارنته بلغة موجودة تعرفها بالفعل. يمكننا الحصول على أفضل لغات البرمجة حسب الشعبية مثل JS و Java و C # و PHP و C (+ CPP) و Ruby - ثم قمنا بتوجيه البرامج التعليمية التي تفترض أن لديك معرفة بكيفية عمل هذه اللغة.

في الوقت الحالي ، نفترض فقط أنك تعرف JS.

العلامات: tutorials

تأكد من أنه يمكن الوصول إليه بشكل افتراضي

تأكد من أن الفواصل الزمنية مثل accessibilityinsights.io تمر

العلامات: infra

عناوين URL قصيرة يمكن مشاركتها للملعب

سيكون من الرائع أن ينتج زر "مشاركة" في ملعب TypeScript عناوين URL قصيرة ، بدلاً من تفريغ شفرة المصدر بالكامل في عنوان URL.

بدلاً من ذلك ، اسمح لعنوان URL بأن يحتوي على معرف github gist الذي يملأ الملعب. على سبيل المثال: https://www.typescriptlang.org/play?gist=eb25a1f350e50d6ed3561a777fbfe424

العلامات: playground

أمثلة بإعدادات مختلفة (لحالات / سيناريو استخدام مختلف)

لقد وجدت أنه من الصعب التعرف على كيفية تكوين قاعدة شفرة TS الخاصة بي وما هي الأمثلة التي يمكنني اتباعها لمختلف قواعد الرموز ، لذا سيكون من الرائع أن تظهر قائمة أمثلة مثل https://github.com/microsoft/TypeScriptSamples/ على موقع الويب لتوضيح كيف يمكن للمرء تكوين tsconfig.json وكيف يجب عليه هيكلة ملفات TS للعمل على النحو المنشود.

العلامات: docs ، examples

لا يوجد سبب واضح لوجود المستندات في كتيب ويكي مقابل

الصفحة الموجودة على this في الويكي هي_أروع_ وأتمنى لو كنت قد وجدتها عاجلاً. يجب أن نحدد نوع الأشياء التي يجب أن تعيش في الويكي (خاصة أنه لا يمكن تعديلها بسهولة من قبل أي شخص آخر (يجب على الأشخاص الخارجيين إرسال علاقات عامة)) ونقل الأشياء الأخرى إلى الموقع.

اجعل التنقل بين الموضوعات والعناوين أفضل

موضوعات ضخمة مثل الكتيب § الأنواع المتقدمة لها تنقل ضعيف بين العناوين المنفصلة ، ولا يوجد زر لأعلى أيضًا. سيكون من الجيد حقًا إضافة قائمة تنقل عائمة. من الصعب حاليًا القفز من عنوان إلى آخر أو معرفة المطلوب بسرعة.

فيما يلي مثال جيد للتنقل الوارد في كتاب git للسيناريو التجميعي هذا: https://docs.assemblyscript.org/basics/environment

العلامات: website ، handbook ، navigation

تحرير رمز ملعب الهاتف المحمول

كما أفهمها ، يعد تحرير التعليمات البرمجية المتوافق مع الجوّال مع تمييز بناء الجملة وجميع ميزات IDE الأخرى أمرًا مزعجًا.

ومع ذلك ، وجدت نفسي أرغب في اللعب باستخدام مقتطفات التعليمات البرمجية أثناء استخدام هاتفي ، بعيدًا عن سطح المكتب / الكمبيوتر المحمول ، في كثير من الأحيان.

لا أمانع في وجود حقل <textarea> عادي ، بدلاً من محرر بناء جملة مميز للاستخدام على الأجهزة المحمولة.

قد تكون الأخطاء على صفحة أخرى أو نافذة منبثقة أو بعض عناصر html الأخرى.

العلامات: ملعب ، جوال ، محرر كود

المستند يضيف الامتداد .js لوحدات es6 المتوافقة مع المستعرض

لا يوجد ذكر في أي مكان أنه يمكن استخدام TypeScript بشكل جيد لإنشاء وحدات es6 التي تعمل في المتصفح ببساطة عن طريق إضافة الامتداد .js إلى اسم الاستيراد! المكان الوحيد الذي يبدو أن هذه المعلومات موجود فيه هو في سلسلة الرسائل هذه:
https://github.com/Microsoft/TypeScript/issues/16577#issuecomment -343610106

لست متأكدًا من إصدار TS الذي أضافه ، لكن عمليات الاستيراد مثل "./file.js" تعمل الآن (حتى لو كان الملف هو file.ts بالفعل).

بالنسبة لي كانت هذه ميزة ضخمة ... لكنها غير موجودة رسميًا ؟!

لا تتضمن صفحة "الأنواع المتقدمة" نوع Omit<T, K> .

Omit<T, K> مؤخرًا في TypeScript 3.5 ، لكن صفحة الأنواع المتقدمة لا تزال تحتوي على إخلاء المسؤولية التالي:

ملاحظة: نوع الاستبعاد هو تنفيذ مناسب لنوع الاختلاف المقترح هنا. لقد استخدمنا اسم الاستبعاد لتجنب كسر الشفرة الحالية التي تحدد الفرق ، بالإضافة إلى أننا نشعر أن هذا الاسم ينقل دلالات النوع بشكل أفضل. لم نقم بتضمين الحذفاكتب لأنه مكتوب بشكل تافه كـ Pick>.

قم بتوفير وثائق إعداد المشروع لـ Linters

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

العلامات: linter

لا يوجد شيء يغطي الأخطاء الأكثر شيوعًا أو قيود TypeScript.

عندما تتعلم TypeScript لأول مرة ، هناك أنماط معينة لا يتم دعمها + ولن يتم دعمها في TypeScript. من أبسط هذه الطرق:

const buildResult = (name?: string) => {
  const result = {};
  if (name) {
    result.name = name; // error, this property doesn't exist on {}
  }
  return result;
};

لقد بدأت في تقديم TypeScript لشركتي ، وظهرت حالات مثل هذه كثيرًا ، لذلك بدأت في توثيقها في دليل أسلوب الأسئلة الشائعة / استكشاف الأخطاء وإصلاحها. إنه ينمو بسرعة (لاحظ أن هذا في حالة تقريبية):

بناء كائن خاصية واحدة في كل مرة
لماذا لا تحصل على أخطاء عندما تريدها: فحص الملكية الزائد
كيفية الوصول إلى الخصائص الاختيارية ، بما في ذلك من النقابات
لماذا لا تفعل Object.keys و Object.entries ما تريده
عمل الفلتر مما يقلل العمل بدون أخطاء
تم فقد نوع التصفية

إذا كانت أي من هذه المعلومات موجودة في المستندات ، فلن أتمكن من العثور عليها. لقد فهمت هذه فقط خلال سنوات من التجربة / الخطأ ، وقراءة أكثر المشكلات ارتباطًا على Github.

العلامات: errors ، troubleshooting ، limitations

قدم وثائق واضحة حول كيفية إضافة تعريفات النوع المخصص

هناك عدد من المكتبات التي لا تتضمن أنواعًا ، والتي لا تتوفر بها حزمة @types/* . أود أن أكون قادرًا على كتابة ملفات التصريح الخاصة بي لهذه داخل مشروعي ، ولكن لا يبدو أن هناك أي توثيق بالطريقة "الصحيحة" لكتابتها والحصول على نسخة مطبوعة للتعرف عليها. لنفترض أنني أستورد وحدة من npm. هل أحتاج إلى استخدام declare module x ؟ أو declare module "x" ؟ أو استخدام مساحة الاسم؟ أو مجرد تصدير الأنواع؟ هل هناك مكان معين أحتاج لوضع هذه الملفات فيه؟ ما هي خيارات التكوين التي أحتاج إلى ضبطها؟ typeRoots ؟ types ؟ paths ؟ include ؟ أو ماذا؟ - كل ما وجدته حتى الآن هو رسائل خطأ محيرة وخيارات تهيئة مفسرة بشكل سيئ وأسئلة SO قديمة.

العلامات: docs

عدم وجود وثائق دون اتصال

أدوات التطوير الأساسية الحديثة مثل git أو npm لها مجموعة فرعية خاصة بها من الأوامر التي تسمح لنا بالوصول إلى الوثائق / المراجع في وضع عدم الاتصال ، على سبيل المثال:

$ git help ls-remote
$ npm help search 

أعتقد أنه سيكون من الجيد الحصول على هذه الميزة (على الرغم من اختلاف TS قليلاً).
سيسمح لنا باستكشاف المستندات محليًا عبر الأمر help like دون الحاجة إلى الرجوع إلى الموقع / github وما إلى ذلك:

$ tsc help tsc # basic CLI arguments desc
$ tsc help config # opens up html page of the tsconfig.json docs
$ tsc help v3.5 # opens up html page changelog
$ tsc help enum # finds pages containing `enum` type and hints their names/opens them up

العلامات: offline ، search ، cli ، local

الأمثلة بحاجة إلى بعض الألوان المميزة بشكل أفضل!

كيف ينبغي أن يكون:

const whomstve = (name: string) => name + 'is life'

كيف هو حاليا:

const whomstve = (name: string) => name + 'is life'

هناك القليل من اللون الأزرق ، لكن هذا كل شيء.

مرحبًا يا رفاق ، لقد كنت أراقب هذه المشكلة أثناء التفكير في الهيكل العام للموقع والوثائق العامة خلال الشهر الماضي. الآن بعد أن تمت تسوية هذه المشكلة ، أصبح لدي فهم أكثر قليلاً لما أود أن يبدو عليه المستندات.

دعنا نحاول النظر في كل هذه النقاط بناءً على ردود الفعل ، مع القليل من الخلط من أجل سهولة القراءة.

يمكن أن توجد مستندات API في بعض الأحيان في ملاحظات الإصدار فقط

سيكون هذا الأمر خادعًا ، جزئيًا لأنني الآن لست متأكدًا مما يعيش فقط في ملاحظات الإصدار.

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

لا بحث على الموقع

نعم ، أوافق ، هذا بالتأكيد مهم للموقع الجديد.

الموقع مغلق المصدر

مثبت! https://github.com/microsoft/TypeScript-website

سيخرج العمل الجديد من الفرع الرئيسي ، ولكن في الوقت الحالي ، يمكن الوصول إلى الموقع القديم أعلاه والحصول على العلاقات العامة. لقد قمت بنقل المشكلات من TypeScript repo إلى هنا أيضًا ، لذلك من السهل تتبعها جميعًا.

صفحات الأدوات غير محدثة

مثبت! قمت بدمج الكثير من العلاقات العامة جزئيًا ، وحصلت على الكتيب الحالي محدثًا من المجتمع. بالإضافة إلى التأكد من ظهوره في التنقل (بدلاً من البحث على الويب فقط)

أوصاف خيارات تكوين TS المحسّنة

لقد بدأت في استكشاف هذا خلال عطلة نهاية الأسبوع (كيف يمكننا التأكد من أن المترجم وموقع الويب يشتركان في نفس مصدر البيانات الأولي لهذه المستندات ، وما الذي يمكن أن يبنيه موقع الويب بالإضافة إلى ذلك لتوفير مزيد من السياق)

بعض الأمثلة على الاتجاه حتى الآن:

• ملاحظاتي الخاصة من عام 2017
• لقد كنت أتحدث مع Ethan Arrowood @ mathorndev الذي يمكن أن يكون tsconfig-ui هو الأساس لإنشاء مستكشف TSConfig

الملعب ليس بجودة البدائل

مثبت! أنا أعتبر هذا نقطة انطلاق إيجابية في الاتجاه العام الذي أود أن يكون الملعب. لدي بعض الأمثلة على نماذج بالأحجام الطبيعية التي توفر منظورًا طويل المدى حول الشكل الذي يجب أن يبدو عليه الملعب ويشعر به لجعله أفضل ما في السلالة حقًا.

( انقر لاستكشافات فيجما )

عناوين URL قصيرة قابلة للمشاركة في الملعب

ثابت ، انظر أدناه

لا يوجد مسرد لأسماء الأنواع

لقد بدأت في كتابة خاصتي ، حيث تعلمت المترجم - أتوقع أن أرى هذا الموجز في الكتيب الجديد. كما أنه يؤثر على أمثلة الملاعب ، والتي تعمل بمثابة مسرد لأمثلة لبعض الأنواع الأكثر تقدمًا

[playground ex1، playground ex2]

لا يقوم بتدريس TS بشكل تدريجي

هذا يهدف إلى تناوله في الكتيب الجديد ، للاقتباس من بعض # 29288 (قم بالتمرير إلى New handbook )

تعد كتابة مستند عام لجميع المستخدمين أمرًا صعبًا لأن جمهور TypeScript واسع ، وإحدى نقاط القوة (والضعف) في الكتيب الحالي هي أنه يحاول خدمة الجميع في وقت واحد. لدينا عدة مجموعات مختلفة من المطورين الذين لديهم توقعات مختلفة عند تعلم TypeScript ، ونحتاج إلى ضبط مستوى عرض المفاهيم المختلفة. بالنظر إلى ذلك ، فإن هدفنا هو تنظيم الدليل في ثلاثة أجزاء مختلفة:

1. مقدمات مخصصة (الإعداد للكتيب الأساسي)
   
   
   
   1. الكتيب الأساسي (الجميع يقرأ هذا)
   
   
   2. صفحات مرجعية (نوع من الغطس العميق / الملاحق)
   
   

بشكل فعال ، يحتوي على بعض نقاط البداية المختلفة ثم يحاول تعليم اللغة بمجرد أن تتعرف على النظام البيئي المحيط.

هل هذا يعالج كل شيء في التعليق؟ لا ، فقط البداية. خريطة الموقع الحالية لدي واسعة جدًا ، وهذه هي أنواع المشكلات التي أهتم بها

لقد تركت مساحة كبيرة للمناورة في كتب الطبخ والأدلة الحالية لخريطة الموقع ، مع كون كتب الطهي شيئًا يمكننا تشجيع المزيد من دعم المجتمع به.

تقديم أدلة

لقد استغرقت وقتًا لبدء فرز نماذج التعليمات البرمجية الحالية وتحديثها الموجودة حاليًا على موقع TypeScript على الويب. ما زلت أحدد العينات التي من الأفضل تركها إلى جانبنا مقابل إعادة التوجيه إلى الوثائق الرسمية (على سبيل المثال ، إذا كان المشروع يدعم الآن TypeScript ، ولديهم مستنداتهم الخاصة)

كما هو مذكور أعلاه ، أعتقد أن قسم كتب الطهي والأدلة الفعلية في الموقع يجب أن يكون كافياً لتغطية ذلك

مواصفات اللغة قديمة

نعم ، لا أعرف ما إذا كان بإمكاني إزالته تمامًا من الريبو الرئيسي - لكن لن يتم ذكره في الموقع الجديد.

تقديم تجارب أفضل تشبه IDE لعينات التعليمات البرمجية

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

صفحة فهرس خطأ المترجم

لست متأكدًا مما إذا كان هذا سيحدث أم لا ، في جزء منه يحتوي TypeScript على الكثير من رموز الخطأ ويتم تغييرها بانتظام. من الجدير العودة مرة واحدة إلى موقع ويب ومستندات يعملان بشكل كامل ، ولكنه الآن في الخلفية.

اعرض المزيد من الأمثلة الواقعية

يقوم الكتيب الجديد حتى الآن بعمل جيد في هذا 👍🏾 - يمكننا أن نهدف إلى الإبقاء عليه بهذه الطريقة. مع بقية المستندات ، سأحاول تغيير أي شيء أراه على هذا النحو.

دعم الجوال في الموقع ضعيف

إنني أتطلع إلى استخدام نظام تصميم Microsoft (السائل) للموقع الجديد ، مما يعني أن دعم الأجهزة المحمولة (مع إمكانية الوصول) يجب أن يأتي "مجانًا في الغالب"

مع وجود شيء معقد مثل الملعب وهو أمر أكثر تعقيدًا ، أعتقد أن عقلية التصفح / الاستكشاف مناسبة تمامًا للهاتف المحمول بحجم الهاتف. لذلك ، لدي نموذج بالحجم الطبيعي لكوني أقرب قليلاً إلى تجربة للقراءة فقط:

استكشف تحسينات المساعدة في tsc

أنا منفتح على هذا ، لكن CLI المطبوع عليها عبارة عن أمر واحد فقط ، تجميع (وهذا هو السبب في عدم وجود حاجة للمساعدة في الأوامر الفرعية (على الرغم من أن - init kinda يكسر ذلك))

تقديم المشورة بشأن تحسين DTS

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

دمج المستندات / المدونات / التحرر

صعب ، ليس لدي إجابة على ملاحظات المدونة / الإصدار. نحن نستخدم نظام تدوين منتجات Microsoft مع أي شخص آخر ، ولست متأكدًا مما إذا كان من الجيد نقل كل ذلك إلى موقع الويب نفسه. يمكننا تحديد ذلك أقرب إلى الوقت.

على الجانب الأسهل ، أود بالتأكيد إزالة هذا النوع من المعلومات من الويكي وتركه فقط داخل موقع الويب (حيث يمكن فهرسته بواسطة بحث الموقع) - أود ترك TypeScript wiki خصيصًا للمساهمة في نسخة مطبوعة على الآلة الكاتبة، والعمل مع مترجم نسخة مطبوعة على الآلة الكاتبة واجهات برمجة التطبيقات (على سبيل المثال عند import * as ts from “typescript” ، أو بناء المساعد الخادم اللغة)

تغطية الأخطاء الأكثر شيوعًا

ويتصل هذا إلى ما سبق - هناك التعليمات واسعة حقا صفحة لهذا النوع من المشاكل، وأنا فقط اكتشفت للتو في الويكي (3 سنوات إلى استخدامي للTS).

يمكننا أن نأخذ هذا كخط أساس ونبدأ في جذبهم إلى الموقع الرئيسي مع ردودكم أيضًا

إضافة تمييز بناء الجملة

موافق موافق ، شكرا!

بشكل عام ، أعتقد أن لدينا الكثير من هذه الأشياء التي يتم استكشافها أو العمل عليها بنشاط ، وأنا منفتح لمزيد من التعليقات بينما نواصل العمل على المستندات!

عمل رائع شكرا جزيلا orta !

ماذا عن استعارة / تحسين / التعاون مع تجربة VSCode tsconfig في محرر Playground ، بدلاً من إنشاء تجربة منفصلة؟

يجعل Playground أفضل ، والتجربة الحالية في VSCode هي بالفعل نصف لائقة.

لست متأكدًا حقًا مما تعنيه. هل تعجبك ميزات مخطط JSON التي يتم إكمالها تلقائيًا في VS Code؟ كنت أخطط للحصول على ذلك في جزء محرر JSON ، لكن نظرة عامة على كل خيار كواجهة مستخدم رسومية مع تسميات هي طريقة مفيدة لرؤية جميع الخيارات والاختيار والاختيار.

orta عندما يصبح الكتيب الجديد هو الكتيب الرسمي ، هل ستتوقف عناوين URL التي تشير إلى أقسام الكتيب الحالي؟ أم أن الكتيب الجديد سيكون على عنوان URL مختلف؟ أنا فقط أتساءل لأنني وضعت مجموعات من روابط الكتيبات في إجابات SO على مدار السنوات العديدة الماضية (أنا متأكد من أن الآخرين قد فعلوا ذلك أيضًا) وسيكون من المؤسف إذا تم كسرها جميعًا. (هل هناك مشكلة أو موقع أفضل للحديث عن خطط ترحيل الوثائق العامة؟)

ortajcalz كان يتساءل نفس الشيء، لدي أكثر من 2.5K إجابات SO، وإيجاد كل الإجابات مع الروابط وتحديثها كل شيء لا يطاق. من الناحية المثالية ، ستستمر الروابط مع الأجزاء في العمل وإعادة التوجيه إلى مواقع جديدة. أنا على استعداد للمساعدة في رسم الخرائط إذا لزم الأمر.

نعم ، لا أؤمن بكسر URIs - هناك بعض الخيارات لاستكشافها.

أعتقد أنه من المحتمل أنه سيتم استخدام جذر URL جديد للكتيب (على سبيل المثال ، ليس docs/handbook/x.html ولكن ربما /handbook/x.html ) ، وإعادة توجيه الصفحات القديمة إلى أقرب ما يعادلها عبر خريطة بعض الفرز.

أود أن أعرف ما تعنيه كل تسميات جيثب لهذا المستودع. بعضها لا يحتاج إلى شرح ، لكن البعض الآخر ليس كذلك.

على سبيل المثال ، "يلزم اقتراح" غير واضح بالنسبة لي. سيكون من المفيد لجميع التسميات الحصول على أوصاف أطول كما يفعل البعض بالفعل.

لا يمكن الارتباط بالمستندات لخيارات المترجم المحددة _ المحددة

فريقي جديد نسبيًا على TypeScript ، وعلى هذا النحو ، يتغير tsconfig.json بشكل متكرر ، وفي كثير من الأحيان أريد توجيه الأشخاص إلى الوثائق الخاصة بخيارات المترجم المحددة ، على سبيل المثال:

https://www.typescriptlang.org/docs/handbook/compiler-options.html#strict-null-checks
(or)
https://www.typescriptlang.org/docs/handbook/compiler-options.html#strictNullChecks

روابط مثل هذه لا تعمل ، لكني أرغب في ذلك.

حاليًا معرف HTML الوحيد الذي يمكنني رؤيته في تلك الصفحة هو # خيارات التحويل البرمجي ، وهو ليس مفيدًا لأنه في الأساس في الجزء العلوي - ومع ذلك ، فإن وجود معرف لكل خيار من الخيارات سيكون مفيدًا جدًا لجذب الأشخاص إلى الجزء المطلوب من الصفحة.

العلامات: compiler

@ Tyler-Murphy لقد أصلحنا ذلك الآن

ssalka - نعم ، مكالمة جيدة ستكون في مستندات tsconfig الجديدة

-

سأقوم بإغلاق هذه المشكلة ، وسأعيد فتح واحدة جديدة في المستقبل بنفس الفرضية بمجرد أن نتعمق أكثر في الكتيب والموقع الجديد 👍

ملعب الكتابة المطبوعة:
أشعر وكأنني مجنون ولكن لا يمكنني العثور على خيار "مشاركة" بسيط لحفظ ومشاركة مشروعي (على سبيل المثال ، للإضافة إلى مشكلة جيثب).
أرى جميع الروابط ضمن "تصدير" ولكن بدون "مشاركة".

ملعب الكتابة المطبوعة:
أشعر وكأنني مجنون ولكن لا يمكنني العثور على خيار "مشاركة" بسيط لحفظ ومشاركة مشروعي (على سبيل المثال ، للإضافة إلى مشكلة جيثب).
أرى جميع الروابط ضمن "تصدير" ولكن بدون "مشاركة".

مثال: رابط الملعب

الموقع الجديد يبدو لطيفا حقا! ومع ذلك ، فقد لاحظت أن هذا الطلب (روابط الربط لخيارات المترجم) لم يتم إجراؤه في 😕

يبدو أنه سيكون طلبًا سهلاً حقًا للاستيعاب وسيكون مفيدًا جدًا للقادمين الجدد. آمل أن أراه في التحديث المستقبلي!