KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

TBScrollViewEmpty

★ 99 Open GitHub ↗

A lightweight .NET component for displaying empty, loading, offline, and error states in list views.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# TBScrollViewEmpty.DotNet

一个轻量的 .NET / C# 空数据状态组件，功能参考原来的 Objective-C 项目 `TBScrollViewEmpty`。它不负责请求数据，只负责在列表页面里把当前状态清楚地展示出来。

## 功能概览

- 有数据时隐藏空白页，显示正常列表
- 请求成功但没有数据时显示 `Empty`
- 网络不可用时显示 `Offline`
- 请求失败时显示 `Error`
- 加载过程中显示 `Loading`
- 点击重试按钮后通过事件通知业务层
- 支持自定义标题、详情、按钮文字和图片开关
- 支持用自定义 View 完整替换默认空白页
- Core 层不依赖 UI，便于单元测试和后续扩展

## 项目结构

项目分成两层：

```text
TBScrollViewEmpty.Core
    状态、配置和控制器，不依赖 UI

TBScrollViewEmpty.Maui
    .NET MAUI 默认视图和容器
```

网络请求、网络状态检测、列表数据和页面导航由业务项目负责。组件不会修改 `CollectionView` 的内部方法，也不会拦截刷新调用；数据变化后显式调用 `Update` 即可。

## 状态

```csharp
public enum EmptyStateKind
{
    Content,
    Loading,
    Empty,
    Offline,
    Error
}
```

| 状态 | 含义 |
| --- | --- |
| `Content` | 有数据，隐藏空白页 |
| `Loading` | 正在加载 |
| `Empty` | 请求成功但没有数据 |
| `Offline` | 网络不可用 |
| `Error` | 加载失败 |

## 快速使用

```csharp
var options = new EmptyStateOptions
{
    EmptyTitle = "还没有收藏内容",
    EmptyDetail = "收藏的内容会显示在这里",
    RetryButtonText = "重新加载"
};

var host = new EmptyStateHost(collectionView, options);

host.Controller.RetryRequested += async (_, _) =>
{
    host.Controller.SetLoading();

try
    {
        var items = await LoadDataAsync();
        host.Controller.Update(items.Count, NetworkStatus.Online);
    }
    catch (Exception exception)
    {
        host.Controller.SetError(exception.Message);
    }
};

host.Controller.Update(items.Count, NetworkStatus.Online);
```

`EmptyStateHost` 是一个 `Grid`，会把列表和默认空白页叠在一起。有数据时空白页隐藏，没有数据时空白页显示在列表上方。

## 手动切换状态

```csharp
controller.SetLoading();
controller.SetError("服务器暂时不可用");
controller.SetOffline();
controller.SetEmpty();
controller.SetContent();
```

状态相同的连续设置不会重复触发 `StateChanged`。`Update` 会根据 item 数量和网络状态自动选择 `Content`、`Empty` 或 `Offline`。

## 自定义 View

```csharp
host.SetCustomView(new MyEmptyView());
```

自定义 View 会覆盖默认 View。有数据时它会自动隐藏；传入 `null` 可以恢复默认空白页。

## 配置

`EmptyStateOptions` 目前可以配置：

- `EmptyTitle` / `EmptyDetail`
- `OfflineTitle` / `OfflineDetail`
- `ErrorTitle` / `ErrorDetail`
- `LoadingTitle`
- `RetryButtonText`
- `ShowImage`
- `ShowRetryButton`

默认文案是中文。业务项目可以在创建 `EmptyStateHost` 时传入自己的语言和显示配置。

## 事件

```csharp
host.Controller.StateChanged += (_, args) =>
{
    var state = args.Snapshot.Kind;
    // 可以在这里更新统计、无障碍提示或页面上的其他状态。
};

host.Controller.RetryRequested += (_, _) =>
{
    // 在业务项目中重新发起请求。
};
```

`StateChanged` 会携带 `EmptyStateSnapshot`，其中包括状态、item 数量、网络状态和错误信息。`RetryRequested` 只表示用户点击了重试，实际请求仍由业务层执行。

## 构建和测试

本项目不会自动安装 .NET SDK、MAUI workload 或其他 SDK。请在已经准备好 .NET 8 和 .NET MAUI 环境的机器上执行：

```bash
dotnet restore
dotnet build TBScrollViewEmpty.sln
dotnet test tests/TBScrollViewEmpty.Core.Tests/TBScrollViewEmpty.Core.Tests.csproj
```

只测试 Core 时不需要启动 MAUI 平台：

```bash
dotnet test tests/TBScrollViewEmpty.Core.Tests/TBScrollViewEmpty.Core.Tests.csproj
```

## 目录结构

```text
src/TBScrollViewEmpty.Core/            状态和控制器
src/TBScrollViewEmpty.Maui/            MAUI 视图
samples/TBScrollViewEmpty.Sample/      示例页面
tests/TBScrollViewEmpty.Core.Tests/    Core 单元测试
```

## 版本和平台

- Core：`net8.0`
- MAUI：`net8.0-android`、`net8.0-ios`、`net8.0-maccatalyst`、`net8.0-windows10.0.19041.0`
- 测试框架：xUnit
- UI 框架：.NET MAUI
- 许可证：MIT

## 暂不包含

第一版不包含网络请求、图片 URL 下载、分页、下拉刷新、自动网络监听、复杂主题系统、页面导航，以及 WPF、WinUI、Avalonia 等其他 UI 框架的适配。

## 备份说明

原 Objective-C 项目和完整历史保留在 Git 的 `backup1` 分支。新的 C# 项目位于 `master` 分支，两套代码可以分别恢复。

---

## English

TBScrollViewEmpty.DotNet is a small .NET and C# component for displaying empty, loading, offline, and error states around a list view. It is inspired by the original Objective-C `TBScrollViewEmpty` project.

The library does not load data or monitor the network. Those responsibilities remain in the host application.

### Features

- Hides the empty view when the list has content
- Shows `Empty` when a successful request returns no items
- Shows `Offline` when the host reports that the network is unavailable
- Shows `Error` when loading fails
- Shows `Loading` while data is being loaded
- Notifies the host application through a retry event
- Supports custom titles, details, button text, and image visibility
- Allows the default empty view to be replaced with a custom View
- Keeps the Core state logic independent from the UI

### Project Structure

The repository is split into two layers:

```text
TBScrollViewEmpty.Core
    State, options, and controller without UI dependencies

TBScrollViewEmpty.Maui
    Default .NET MAUI view and host container
```

The host application owns data loading, network monitoring, list data, and navigation. The component does not patch `CollectionView` or intercept refresh methods. Call `Update` when the data changes.

### States

| State | Meaning |
| --- | --- |
| `Content` | The list has content; hide the empty view |
| `Loading` | Data is being loaded |
| `Empty` | The request succeeded but returned no items |
| `Offline` | The host reports an offline connection |
| `Error` | Loading failed |

### Quick Start

```csharp
var options = new EmptyStateOptions
{
    EmptyTitle = "No saved items",
    EmptyDetail = "Saved items will appear here",
    RetryButtonText = "Try again"
};

var host = new EmptyStateHost(collectionView, options);

host.Controller.RetryRequested += async (_, _) =>
{
    host.Controller.SetLoading();

host.Controller.Update(items.Count, NetworkStatus.Online);
```

`EmptyStateHost` is a `Grid` that places the list and the empty view in the same container. The empty view is hidden when content exists and shown above the list when it does not.

### Manual State Changes

```csharp
controller.SetLoading();
controller.SetError("The server is temporarily unavailable");
controller.SetOffline();
controller.SetEmpty();
controller.SetContent();
```

Setting the same state twice does not raise `StateChanged` twice. `Update` chooses `Content`, `Empty`, or `Offline` from the item count and the supplied network status.

### Custom View

```csharp
host.SetCustomView(new MyEmptyView());
```

A custom View replaces the default view and is hidden automatically when content is available. Pass `null` to restore the default empty view.

### Options

`EmptyStateOptions` currently provides:

- `EmptyTitle` / `EmptyDetail`
- `OfflineTitle` / `OfflineDetail`
- `ErrorTitle` / `ErrorDetail`
- `LoadingTitle`
- `RetryButtonText`
- `ShowImage`
- `ShowRetryButton`

The default text is Chinese. Pass custom options when creating `EmptyStateHost` if the application needs another language or presentation.

### Events

```csharp
host.Controller.StateChanged += (_, args) =>
{
    var state = args.Snapshot.Kind;
    // Update analytics, accessibility text, or other page state here.
};

host.Controller.RetryRequested += (_, _) =>
{
    // Start loading again in the host application.
};
```

`StateChanged` carries an `EmptyStateSnapshot` containing the state, item count, network status, and optional error message. `RetryRequested` only reports the user action; the host application still owns the actual request.

### Build and Test

This repository does not install the .NET SDK or MAUI workloads. On a machine with .NET 8 and .NET MAUI installed, run:

```bash
dotnet restore
dotnet build TBScrollViewEmpty.sln
dotnet test tests/TBScrollViewEmpty.Core.Tests/TBScrollViewEmpty.Core.Tests.csproj
```

The Core tests do not require a running MAUI platform.

### Layout

```text
src/TBScrollViewEmpty.Core/            State and controller
src/TBScrollViewEmpty.Maui/            MAUI views
samples/TBScrollViewEmpty.Sample/      Sample page
tests/TBScrollViewEmpty.Core.Tests/    Core unit tests
```

### Versions and Platforms

- Core: `net8.0`
- MAUI: `net8.0-android`, `net8.0-ios`, `net8.0-maccatalyst`, and `net8.0-windows10.0.19041.0`
- Test framework: xUnit
- UI framework: .NET MAUI
- License: MIT

### Out of Scope

The first version does not include networking, image URL downloading, pagination, pull-to-refresh, automatic network monitoring, a theme engine, navigation, or adapters for WPF, WinUI, and Avalonia.

### Backup

The original Objective-C project and its full history remain in the Git `backup1` branch. The new C# project is on `master`, so either version can be restored independently.

## License

MIT License. See [LICENSE](LICENSE).

TBScrollViewEmpty

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README