Новый api отправки сообщений
This commit is contained in:
FrigaT
@@ -1,50 +1,39 @@
|
||||
# API Reference (краткий)
|
||||
# Справочник API
|
||||
|
||||
Документ перечисляет публичные API фреймворка и их назначение.
|
||||
Ниже краткое описание публичных API проекта BotPages.
|
||||
|
||||
## BotPages.Core
|
||||
|
||||
### `BotPagesApp`
|
||||
- `AddAdapter(string messengerType, IMessangerAdapterSetup adapter)` — зарегистрировать адаптер для мессенджера.
|
||||
- `AddDefaultPage<TPage>() where TPage : SingletonPage` — установить "домашнюю" страницу приложения.
|
||||
- `AddMiddleware<TMiddleware>(TMiddleware instance) where TMiddleware : IPageMiddleware` — добавить middleware в конвейер.
|
||||
- `MapCommand<TPage>(string commandTemplate) where TPage : Page` — зарегистрировать команду, ведущую на страницу.
|
||||
- `MapCommand(string template, CommandHandler handler)` — зарегистрировать кастомный обработчик команды.
|
||||
- `MapRoute<TPage>(string template) where TPage : Page` — вручную зарегистрировать маршрут для страницы.
|
||||
- `AutoMapRoute()` — автоматически найти и зарегистрировать все Page-типы в загруженных сборках.
|
||||
- `HandleUpdateAsync(UpdateContext update, CancellationToken ct)` — главный обработчик апдейтов (вызвается адаптером).
|
||||
- `Build(CancellationToken ct)` — запустить все адаптеры и начать обработку апдейтов.
|
||||
- `AddTelegramAdapter(string token)` — регистрирует Telegram адаптер с заданным токеном.
|
||||
- `AddAdapter(string messengerType, IMessengerAdapter adapter)` — регистрирует произвольный адаптер.
|
||||
- `AddMiddleware(IPageMiddleware middleware)` — добавляет middleware в pipeline.
|
||||
- `MapCommand<TPage>(string template)` — привязать команду к странице.
|
||||
- `MapRoute<TPage>(string template)` — зарегистрировать маршрут.
|
||||
- `AutoMapRoute()` — выполнить автопоиск Page?классов и зарегистрировать их маршруты.
|
||||
- `Build(CancellationToken ct)` — подготовить и запустить приложение.
|
||||
|
||||
### Страницы
|
||||
- `Page` — абстрактный базовый класс.
|
||||
- `StatefulPage` — страница с сохранением состояния.
|
||||
- `SingletonPage` — одноэкземплярная страница.
|
||||
### `IMessengerAdapter`
|
||||
- `Task<string?> SendAsync(SendRequest request, CancellationToken ct = default)` — универсальный метод отправки для всех адаптеров.
|
||||
- `IAlbumBuilder CreateAlbumBuilder(PageContext ctx)` — создать билдер альбома (если поддерживается).
|
||||
- `Task OnLeaveAsync(PageContext ctx, CancellationToken ct)` — вызывается при уходе со страницы.
|
||||
|
||||
### Навигация
|
||||
- `NavigationService` — отвечает за определение текущей страницы и переходы.
|
||||
- `GoToAsync<TPage>(PageContext ctx, CancellationToken ct)`
|
||||
- `GoToHomeAsync(PageContext ctx, CancellationToken ct)`
|
||||
### `SendRequest`
|
||||
- `ChatId` — идентификатор чата.
|
||||
- `Text`, `TextFormat` — текст и формат.
|
||||
- `File`, `Caption`, `CaptionFormat` — файл и подпись.
|
||||
- `Inline`, `Reply` — inline и reply клавиатуры.
|
||||
- `MessageId` — id редактируемого сообщения.
|
||||
- `AdapterOptions` — адаптер?специфичные опции (например `TelegramOptions`).
|
||||
|
||||
### Команды
|
||||
- `CommandsRegistry` — реестр команд (внутренний). Поддерживает шаблоны с именованными аргументами и опциональными параметрами.
|
||||
|
||||
### Middleware
|
||||
- `IPageMiddleware` — интерфейс middleware.
|
||||
- `InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)`
|
||||
|
||||
### Абстракции адаптеров
|
||||
- `IMessangerAdapterSetup` — настройка адаптера.
|
||||
- `IMessengerAdapter` — экземпляр адаптера, реализующий `StartAdapterAsync(Func<UpdateContext, Task> onUpdate, List<Command> commands, CancellationToken ct)`.
|
||||
- `IMessengerAdapterFactory` — фабрика/реестр адаптеров (`MultiAdapterFactory` — реализация).
|
||||
|
||||
### Хранилище состояний
|
||||
- `IStateStorage` — абстракция для сохранения состояния страниц между сессиями.
|
||||
### `PageContext` расширения
|
||||
- `SendAsync(SendRequest request, CancellationToken ct = default)` — отправить `SendRequest`.
|
||||
- `SendTextAsync(...)`, `SendFileAsync(...)` — удобные оболочки, создающие `SendRequest`.
|
||||
|
||||
## BotPages.Telegram
|
||||
- Реализация адаптера для Telegram на базе `Telegram.Bot`.
|
||||
- `TelegramUpdateMapper` — маппит апдейты Telegram в `UpdateContext`.
|
||||
- `TelegramAlbumBuilder` — собирает медиа-альбомы из последовательных апдейтов.
|
||||
- `TelegramAdapter` — реализация адаптера, стартует `StartAdapterAsync`.
|
||||
- `TelegramAdapter` — реализация `IMessengerAdapter` для Telegram.
|
||||
- `TelegramOptions` — настройки адаптера (например `NotifyOnSend`).
|
||||
- `MessageBuilderExtensions.WithTelegramOptions` — расширение для установки `TelegramOptions` для конкретного сообщения.
|
||||
|
||||
|
||||
# Генерация документации
|
||||
|
||||
@@ -1,28 +1,37 @@
|
||||
# Быстрый старт — BotPages
|
||||
# Быстрый старт с BotPages
|
||||
|
||||
Эта инструкция поможет запустить и протестировать проект локально.
|
||||
Это руководство поможет быстро запустить demo?приложение с Telegram?адаптером.
|
||||
|
||||
Требования
|
||||
- .NET 8 SDK
|
||||
- Токен Telegram (если используете Telegram-адаптер)
|
||||
- Токен Telegram?бота (для demo)
|
||||
|
||||
Сборка
|
||||
|
||||
```bash
|
||||
dotnet build
|
||||
```
|
||||
|
||||
Запуск демонстрации
|
||||
1. Откройте проект `Demo`.
|
||||
2. Внесите токен Telegram (если используется) в код инициализации адаптера или в переменные окружения проекта Demo.
|
||||
3. Запустите:
|
||||
Запуск demo
|
||||
|
||||
1. Установите переменную окружения `TELEGRAM_TOKEN`:
|
||||
|
||||
```bash
|
||||
setx TELEGRAM_TOKEN "<token>" # Windows
|
||||
export TELEGRAM_TOKEN="<token>" # Linux/macOS
|
||||
```
|
||||
|
||||
2. Запустите demo:
|
||||
|
||||
```bash
|
||||
dotnet run --project Demo
|
||||
```
|
||||
|
||||
Пример конфигурации приложения
|
||||
|
||||
```csharp
|
||||
var app = new BotPagesApp(stateStorage, logger)
|
||||
.AddAdapter("telegram", new TelegramAdapterSetup("<token>"))
|
||||
.AddTelegramAdapter(token)
|
||||
.AddDefaultPage<WelcomePage>()
|
||||
.MapCommand<WelcomePage>("/start")
|
||||
.AddMiddleware(new LoggingMiddleware(logger));
|
||||
@@ -30,18 +39,9 @@ var app = new BotPagesApp(stateStorage, logger)
|
||||
await app.Build(CancellationToken.None);
|
||||
```
|
||||
|
||||
Как написать страницу
|
||||
- Наследуйте `StatefulPage` для страниц с пер-сессионным состоянием.
|
||||
- Наследуйте `SingletonPage` для одноэкземплярных страниц.
|
||||
- Переопределите `OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError` по необходимости.
|
||||
- Для автоматического маппинга маршрутов используйте `AutoMapRoute()`.
|
||||
Основные понятия
|
||||
- `SendRequest` — единый формат запроса на отправку (текст, файлы, кнопки, адаптер?опции). Используйте `PageContext.SendAsync` для отправки.
|
||||
- `Page` / `StatefulPage` / `SingletonPage` — модели страниц и их жизненный цикл.
|
||||
- `IPageMiddleware` — middleware выполняется для каждого входящего обновления.
|
||||
|
||||
Тестирование команд
|
||||
- Команды регистрируются в `BotPagesApp.MapCommand`.
|
||||
- Шаблон команд поддерживает именованные и опциональные аргументы: `/cmd {a} {b?}`.
|
||||
|
||||
Подсказки
|
||||
- Middleware выполняются в том порядке, в котором их добавляют в `BotPagesApp`.
|
||||
- Команды имеют приоритет над обработкой страниц (если текст начинается с `/`).
|
||||
|
||||
Если требуется подробный справочник API — смотрите `docs/API_REFERENCE.md`.
|
||||
Далее: см. `docs/API_REFERENCE.md` для описания публичных API.
|
||||
Reference in New Issue
Block a user