Документація для компонентів UI: Посібник для розробників - javascript.org.ua

Фото від Izzy Park на Unsplash

Останнім часом я глибоко занурився в розробку та підтримку багаторазових UI компонентів, оскільки це є важливою частиною для створення масштабованих, зручних у підтримці та узгоджених користувацьких інтерфейсів. Однак, із ростом складності та кількості компонентів, стає все важче тримати все добре документованим і доступним для розробників, які працюють над різними проєктами. Саме тут документація для UI компонентів стає критично важливим інструментом у арсеналі розробника.

Цей посібник розглядає Bit як універсальний інструмент, що займається всім, що потрібно для ваших UI компонентів: від їх створення до випуску пакетів, з документацією, прикладами та іншою корисною інформацією.

Пакети, опубліковані та задокументовані за допомогою Bit, будуть доступні на Bit Platform (і за бажанням також опубліковані на інших реєстрах пакетів).

1. Створення нового UI компонента

Почнемо з встановлення Bit та налаштування робочого простору Bit для розробки та документування наших компонентів:

npx @teambit/bvm install  
bit init my-components --default-scope MY_ACCOUNT.MY_SCOPE  
cd my-components

Замініть MY_ACCOUNT на ваше ім'я користувача на Bit Platform, а MY_SCOPE на конкретний scope, який ви створили на Bit Platform для публікації ваших компонентів.

Тепер, коли все налаштовано, можемо почати створювати перший компонент. Bit не прив’язаний до конкретного фреймворка, але ми використаємо React для демонстрації простого робочого процесу в цьому посібнику.

Використаємо шаблон Bit для React і назвемо наш компонент ‘color-picker’:

bit create react color-picker

Ви знайдете вихідні файли для новоствореного компонента в директорії color-picker:

├── my-account  
 └── color-picker  
 ├── color-picker.composition.tsx # приклади компонента  
 ├── color-picker.docs.mdx # документація компонента  
 ├── color-picker.spec.tsx # тестовий файл  
 ├── color-picker.tsx # файл реалізації  
 └── index.ts # вхідний файл (основний файл у згенерованому пакеті)

Згенерований компонент є простою реалізацією "hello world". Оновимо файл color-picker.tsx та додамо файл color-picker.module.css для реалізації базового компонента вибору кольору.

/**  
 * @filename: color-picker.tsx  
 */  

import React, { useState } from 'react';  
import styles from './color-picker.module.css';  

interface ColorPickerProps {  
 label?: string;  
 initialColor?: string;  
 onChange?: (color: string) => void;  
}  

export const ColorPicker = ({  
 label = 'Select a color:',  
 initialColor = '#ffffff',  
 onChange,  
}: ColorPickerProps) => {  
 // ...  
};

2. Створення прикладів компонента

Щоб протестувати наш компонент у різних станах і варіаціях, а також надати кілька прикладів для документації компонента, ми перейдемо до файлу .composition.tsx і експортуємо використання цього компонента. Наприклад:

/**  
* @filename: color-picker.composition.tsx  
*/  

import { ColorPicker } from './color-picker.js';  

export const BasicColorPicker = () => {  
 return ;  
};  

export const ColorPickerWithCustomLabel = () => {  
 return ;  
};  

export const ColorPickerWithCustomInitialColor = () => {  
 return ;  
};

Один компонент може мати кілька файлів .composition.tsx.

Запустіть сервер розробки Bit, щоб побачити приклади, відображені у вашому браузері:

bit start

Приклади з’являться внизу документації, а також окремо на вкладці ‘Preview’:

Приклади компонента, відображені на сторінці компонента

Зверніть увагу, що Bit вже згенерував API посилання для нашого компонента на основі його типів TS та JSDocs.

3. Створення документації для компонента

До цього часу ми створили кілька прикладів компонента для нашої документації. Щоб збагачити нашу документацію додатковими усними поясненнями та інтерактивними майданчиками, ми перейдемо до файлу .docs.mdx.
Оскільки це розширення файлу вказує, що це MDX файл, ми можемо поєднувати JSX і Markdown для зручності читання та гнучкості.

---  
description: Інтерфейс для вибору кольору.  
---  

import { ColorPicker } from './color-picker';  

Цей компонент надає простий інтерфейс для вибору кольору за допомогою HTML елемента введення кольору. Він також показує попередній перегляд поточного вибраного кольору.  

## Використання  

1. Встановіть компонент:  

```bash  
npm install @my-account/my-scope.color-picker

Імпортуйте компонент:

import { ColorPicker } from '@my-account/my-scope.color-picker';

Використовуйте компонент:

```jsx live

4. Поширення компонента на Bit Platform

Коли ви завершите зміни в компоненті чи його документації, версіонуйте його, створивши нову версію релізу, і експортуйте його на Bit Platform.

bit tag --message "початкова версія з документацією"  
bit export

Тепер компонент доступний на Bit Platform разом з документацією, прикладами, API посиланням та іншою інформацією. Його можна встановити в будь-який проєкт за допомогою менеджерів пакетів, таких як npm, pnpm та yarn, або встановити в проєкти Bit за допомогою bit.

Наприклад, перегляньте спільну версію цього демонстраційного компонента на Bit Platform.

npm i @learnbit-react/doc-examples.color-picker

Щоб дізнатися більше, відвідайте сайт документації Bit та платформу Bit:

[

Bit. Компонована програма.

Створюйте високопродуктивні та послідовні платформи з незалежних бізнес-функцій.

bit.dev

](https://bit.dev/?source=post_page-----f7343d46911c--------------------------------)

[

Bit. Створюйте з AI.

Створюйте, запускайте, повторно використовуйте та випускайте високоякісне компонентне програмне забезпечення.

bit.cloud

](https://bit.cloud/?source=post_page-----f7343d46911c--------------------------------)

Перекладено з: UI Component Documentation: A Developer’s Guide