كيفية إنشاء دليل نمط المعيشة

إن استخدام دليل أسلوب المعيشة (LSG) لدفع التطوير هو ممارسة اكتسبت الكثير من الشعبية لأن لديها العديد من المزايا ، بما في ذلك كفاءة الكود واتساق واجهة المستخدم. لكن ، كيف يمكنك إنشاء واحد؟ ماذا يجب ان تشمل؟ وأين تبدأ حتى؟ في هذا البرنامج التعليمي ، سوف أتطرق إلى التفاصيل الدقيقة لإنشاء نمط المعيشة باستخدام DocumentCSS .

جمال نمط الحياة أدلة

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

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

إذا نظرت إلى الأمثلة أدناه سترى القواسم المشتركة ل LSG هي:

• قائمة بالعناصر الموثقة
• وثائق موجزة مع مقتطفات الشفرة ومظاهرات واجهة المستخدم التفاعلية

لونلي بلانت ستايل دليل

دليل قوة نمط المبيعات

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

دليل نمط المولدات

هناك العديد من النكهات للاختيار من بينها ، اعتمادًا على لغة الشفرة التي تريد توثيقها أو إعداد مشروعك. فيما يلي بعض الأماكن للبحث عن الخيارات:

• نظرة عامة متعمقة على أدوات دليل أسلوب الحياة ، روبرت Haritonov ، تحطيم مجلة
• نظرة عامة على مولدات مكتبة النماذج ، ديفيد هوند ، جيثب
• دليل نمط مولد تقرير اخبارى ، سوزان روبرتسون ، A List Apart
• أدوات دليل الأسلوب موقع دليل الموارد

في هذا البرنامج التعليمي ، سأوضح لك كيف يمكنك استخدام DocumentCSS لإنشاء LSG الخاص بك. هذه الأداة التي أنشأتها Bitovi هي مفتوحة المصدر ويمكن استخدامها في أي مشروع لتوثيق CSS (تدعم المعالجات التمهيدية مثل Less و SASS كذلك). إذا كنت مهتمًا بتوثيق جافا سكريبت ولغات أخرى ، فيمكنك القيام بذلك بسهولة باستخدام DocumentCSS ، لأن هذه الأداة هي مجموعة فرعية من DocumentJS. لن أغطي هذا الجزء في هذا البرنامج التعليمي ، ولكن من الجيد أن تضع في اعتبارك.

التخطيط الخاص بك دليل الاسلوب

قبل الغوص في إنشاء LSG ، فإن الخطوة الأولى هي تخطيط ما سيكون فيه. مثل أي موقع جيد ، فإن بنية المعلومات المنظمة بشكل جيد (IE) هي المفتاح.

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

خمر متجر النماذج الطبيعية

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

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

وضع كل ذلك معًا ، دعنا نكتب هذه المجموعات باستخدام رسم بياني:

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

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

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

مع وضع ذلك في الاعتبار ، إليك الشكل الذي سيبدو عليه الرسم البياني:

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

الآن ، أغوص في التصاميم ورسم خريطة موقعك ، بما في ذلك العديد من الفئات التي تعتقد أنها ستكون مفيدة للمستقبل. يمكنك الحصول على أفكار من أدلة أسلوب أخرى ( styleguides.io/examples مورد رائع). بمجرد الانتهاء ، تحقق من هذا الإصدار الأكثر شمولية وقارن.

إنشاء صفحات في دليل نمط المعيشة

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

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

_{ياس! صدقه. يمكنك دمج جميع مستنداتك في مكان واحد!}

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

تثبيت تطبيق العينة

تتضمن عملية التثبيت 3 خطوات:

1. تثبيت العقدة

أولا ، تأكد من وجود العقدة المثبتة. ستحتاج على الأقل الإصدار 6.

2. تثبيت التطبيق

ثم ، قم بتنزيل ملف zip هذا: sgdd-tutorial.zip إلى سطح المكتب وفك ضغطه . هذا أمر مهم لأن موقعًا آخر قد يفصل أوامر التثبيت.

ثم افتح الطرفية وأدخل الأمر التالي:

cd ~/Desktop/vintage-shop-sgdd-tutorial && npm install

سيستغرق الأمر بضع ثوانٍ لتثبيت التطبيق وتبعياته.

3. تشغيل التطبيق

بمجرد الانتهاء من التثبيت ، أدخل الأوامر التالية:

1. npm run develop
2. في علامة تبويب جديدة ، أدخل: npm run document

الآن ، دعنا نفصل هذا:

npm run develop

يبدأ خادمًا يمكنك من خلاله رؤية تطبيقك قيد التشغيل على: http://localhost: 8080. سترى في المحطة:

وفي المتصفح:

npm run document

يولد دليل نمط المعيشة في http://localhost: 8080 / دليل الأسلوب. يمكنك إضافة العلم -- -w إلى هذا الأمر لمشاهدة التغييرات في التعليمة البرمجية الخاصة بك ومن ثم إنشاء تحديث في دليل نمط المعيشة ، مثل هذا:

npm run document -- -w

التبديل إلى المتصفح الذي يجب عليك رؤيته:

يستخدم دليل نمط المعيشة ولدت DocumentCSS ، لذلك دعونا نلقي نظرة على كيفية هذا العمل.

كيف يعمل DocumentCSS؟

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

لإنشاء دليل نمط المعيشة ، يقوم DocumentCSS بما يلي:

• يقرأ من خلال الملفات المحددة في تكوينه (لهذا البرنامج التعليمي سوف ينظر في .less و .md الملفات)
• يبحث عن التعليقات التي تستخدم "علامات" خاصة (مثل @page ، @stylesheet أو @styles .
• يولد ملفات html ويربطهم لبناء الموقع.

مع أخذ ذلك في الاعتبار ، لنقف إلى استخدام DocumentCSS لإنشاء صفحة جديدة في LSG.

خلق صفحة

للبدء ، افتح أولاً نموذج التطبيق في محرر الشفرة. سترى بنية الملف التالية:

الحفر لأسفل إلى src ، والعثور عليها base/markdown . ستجد هنا صفحات موجودة بالفعل في دليل الأنماط. قم بإنشاء ملف تخفيض جديد وقم بتسمية "about" (بالامتداد .md ). يجب أن تبدو بنية الملف الآن كما يلي:

داخل هذا الملف الجديد ، أضف العلامة @page تليها سلسلتين:

@page about about

الآن دعونا نفصل هذا:

@page

الوسم @page يعلن الملف كصفحة ويخبر DocumentCSS أنه يجب عرض المعلومات الموجودة في هذا الملف كصفحة في دليل النمط. هذا يعمل على تمييزه عن أوراق الأنماط ، أو javascript ، أو أنواع أخرى من الملفات في وثائقك.

about

هذا هو الاسم الفريد للصفحة ويتم استخدامه كمرجع لعلامات أخرى. لذا احتفظ به قصيرًا وصغيرًا وبسيطًا حيث سيتم استخدامه كعنوان url للصفحة. على سبيل المثال ، سيكون عنوان URL لصفحتنا الجديدة هو: http://localhost: 8080 / دليل الأسلوب / about.html

About

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

لعرض الصفحة التي تم تكوينها حديثًا ، قم بتشغيل documentjs في المحطة مرة أخرى (إلا إذا كنت تشاهدها للتغييرات) ، ثم انتقل إلى http://localhost: 8080 / دليل الأسلوب / about.html لعرض الصفحة الجديدة.

الخطوة التالية هي إضافة صفحتك إلى التنقل. لهذا أضف سطرًا ثانيًا إلى ملفك كما يلي:

@page about About@parent index

الوسم @parent يسمح بتحديد أحد الوالدين للوثيقة الخاصة بك. في هذه الحالة ، نريد عرض صفحة "حول" أسفل قسم المنزل. يمكنك الآن إعادة تشغيل المستندات ومشاهدة الصفحة أسفل رابط "الترحيب":

وإذا نقرت على رابط "الترحيب" ، يمكنك الوصول إلى صفحة البداية:

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

@page about About@parent index## Hello World!This is the first page of my style guide. Here I can add any type of content that shouldn’t live with the code. Like who are the main contributors of the style guide or contact info.For example here's an animated gif inside of an `iframe`:

وهنا الناتج:

توثيق ورقة الأنماط في دليل نمط المعيشة

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

نفسك من المستقبل بعد قراءة المستندات التي كتبتها في الماضي.

توثيق ورقة الأنماط

يتبع توثيق ورقة نمط نمط مماثل لـ توثيق صفحة ولكن في هذه الحالة ، ستدخل الوثائق داخل تعليق ، بجوار الرمز (وهذا هو الجمال!).

للبدء ، افتح ورقة الأنماط: buttons-custom.less .

داخل هذا الملف ، وداخل كتلة التعليقات ، أضف العلامة @stylesheet تليها سلسلتين:

/**@stylesheet buttons.less Buttons*/

لاحظ أن تعليق الوثائق يجب أن يبدأ به /** محلل (في هذه الحالة JSDoc ) على الاعتراف بها.

الآن دعونا نفصل هذا:

@stylesheet

الوسم @stylesheet يعلن الملف كصفحة أنماط ويخبر DocumentCSS أنه يجب عرض المعلومات الموجودة في هذا الملف في دليل النمط. وهذا يساعد على تمييزه عن أنواع أخرى من المستندات ، مثل الصفحات والمكونات والنماذج ، وغيرها ( اقرأ هنا عن القائمة الكاملة لأنواع المستندات ).

buttons.less

هذا هو الاسم الفريد لورقة الأنماط ويستخدم كمرجع لعلامات أخرى. بينما يمكنك استخدام أي نوع من الأسماء ، أوصي باستخدام اسم ملف ورقة الأنماط ، لأن ذلك سيساعد في العثور على الملف عند الرجوع إلى الوثائق. ضع في اعتبارك أن هذا سيؤثر على عنوان المستند. على هذا المثال ، سيكون عنوان url: http://localhost: 8080 / دليل الأسلوب / buttons.less.html

Buttons

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

لعرض الصفحة التي تم تكوينها حديثًا ، قم بتشغيل الأمر التالي ما لم يكن لديك متابعًا للتغييرات):

documentjs

ثم اذهب الى http://localhost: 8080 / دليل الأسلوب / buttons.less.html لعرض الصفحة الجديدة.

الآن ، دعنا نضيف هذا المستند الجديد إلى موقعنا. لهذا سنتبع نفس الاتفاقية التي استخدمناها عندما أنشأنا الصفحة باستخدام @parent العلامة:

/*** @stylesheet buttons.less Buttons* @parent styles.base*/

لاحظ أنه في هذه الحالة أضفنا .base لتحديد هذه الصفحة يجب أن تظهر تحت المجموعة "Baseline" الموضحة في الشريط الجانبي (يمكنك أيضًا إنشاء مجموعات في subnav الخاص بك! سنقوم بحفر ذلك في القليل).

يجب أن تبدو إعادة تشغيل المستندات وتحديث الصفحة كما يلي:

الآن للجزء اللحم! باستخدام صفحتنا في مكان يمكننا القيام ببعض الأشياء:

• يمكننا إضافة وصف شامل للمستند
• يمكننا إضافة جميع أنواع المحتوى باستخدام كلٍّ من علامات التبويب المنسدلة أو HTML العادي
• وأفضل ما في الأمر ، يمكننا إضافة عروض توضيحية لرمزنا؟

لنقم بإضافة وصف سريع وعرض توضيحي لأزرار doc:

/*** @stylesheet buttons.less Buttons* @parent styles.base* @description* Global style definitions for all button elements.* @iframe src/base/bootstrap-custom/buttons/buttons-custom.html*/

أعد تشغيل المستندات ، و:

كما ترون @iframe تتيح العلامة إضافة iframe مع العرض التوضيحي إلى المستند. هذا العرض التوضيحي هو مجرد ملف html بسيط مع علامة نصي يستورد CSS من تطبيقك في وقت التشغيل.

دعونا نفتح العرض buttons-custom.html  :

وانظر كيف تبدو الشفرة:

<script src="/node_modules/steal/steal.js" main="can/view/autorender/"><import "vintage-shop/styles.less";script> <a class="btn btn-default" href="#" role="button">Linka><button class="btn btn-default" type="submit">Buttonbutton><input class="btn btn-default" type="button" value="Input"><input class="btn btn-default" type="submit" value="Submit"><hr /><button type="button" class="btn btn-default">Defaultbutton><button type="button" class="btn btn-primary btn-checkout">Primarybutton><button type="button" class="btn btn-success">Successbutton><button type="button" class="btn btn-info">Infobutton><button type="button" class="btn btn-warning">Warningbutton><button type="button" class="btn btn-danger">Dangerbutton><button type="button" class="btn btn-link">Linkbutton>

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

بالإضافة إلى ذلك ، يمكنك استخدام العلامة @demo لعرض مقتطف الشفرة المستخدم فيه أيضًا. مثله:

/*** @stylesheet buttons.less Buttons* @parent styles.base** @description* Global style definitions for all button elements.* @demo src/base/bootstrap-custom/buttons/buttons-custom.html*/

الذي سوف يخرج مثل هذا:

يذهب ديموس الائتمان إلى Bootstrap Docs كابل بيانات توثيق المغلق دليل نمط المعيشة LSG دليل الاسلوب