benxu.AppPlatform.BlazorUI 3.0.2

benxu.AppPlatform.BlazorUI

Blazor UI 元件庫 - 提供可重複使用的 UI 元件。

特色

• AppButton - 多樣式按鈕（Primary, Secondary, Success, Danger）
• AppModal - 模態對話框
• BottomSheet - 底部滑出視窗（行動裝置常見互動模式）
• NotificationPanel - 通知面板（支援從上/從右滑入，可自訂樣式）
• InAppNotification - 應用內通知（Success, Error, Warning, Info）
• LoadingSpinner - 載入動畫（Small, Medium, Large）
• PageLoading - 頁面切換載入元件（全螢幕遮罩、淡入淡出動畫、CSS 客製化）
• LocalizedText - 多語言文字顯示元件
• LanguageSwitcher - 語言切換器

安裝

dotnet add package benxu.AppPlatform.BlazorUI

使用方式

1. 註冊服務

在 MauiProgram.cs 中：

builder.UseAppPlatform(options =>
{
    options.UseBlazorUI();
});

2. 加入全域元件

在 App.razor 或主要 Layout 中加入：

@using benxu.AppPlatform.BlazorUI.Components
@using benxu.AppPlatform.BlazorUI.Services

<InAppNotification />
<NotificationPanel />

3. AppButton 使用範例

@using benxu.AppPlatform.BlazorUI.Components

<AppButton Text="點擊我" OnClick="HandleClick" />

<AppButton Text="主要按鈕" ButtonClass="primary" />
<AppButton Text="次要按鈕" ButtonClass="secondary" />
<AppButton Text="成功按鈕" ButtonClass="success" />
<AppButton Text="危險按鈕" ButtonClass="danger" />

<AppButton Text="載入中..." IsLoading="true" />
<AppButton Text="已停用" Disabled="true" />

@code {
    private async Task HandleClick()
    {
        Console.WriteLine("按鈕被點擊！");
    }
}

4. AppModal 使用範例

@using benxu.AppPlatform.BlazorUI.Components

<AppButton Text="開啟對話框" OnClick="() => isModalOpen = true" />

<AppModal IsOpen="isModalOpen"
          Title="確認對話框"
          OnClose="() => isModalOpen = false">
    <p>這是模態對話框的內容。</p>
    <p>您確定要執行此操作嗎？</p>

    <Footer>
        <AppButton Text="取消"
                   ButtonClass="secondary"
                   OnClick="() => isModalOpen = false" />
        <AppButton Text="確認"
                   ButtonClass="primary"
                   OnClick="HandleConfirm" />
    </Footer>
</AppModal>

@code {
    private bool isModalOpen = false;

    private async Task HandleConfirm()
    {
        Console.WriteLine("已確認！");
        isModalOpen = false;
    }
}

5. InAppNotification 使用範例

@inject INotificationService NotificationService

<AppButton Text="成功通知" OnClick="ShowSuccess" />
<AppButton Text="錯誤通知" OnClick="ShowError" ButtonClass="danger" />
<AppButton Text="警告通知" OnClick="ShowWarning" ButtonClass="warning" />
<AppButton Text="資訊通知" OnClick="ShowInfo" ButtonClass="secondary" />

@code {
    private void ShowSuccess()
    {
        NotificationService.ShowSuccess("操作成功完成！");
    }

    private void ShowError()
    {
        NotificationService.ShowError("發生錯誤，請稍後再試。", 5000);
    }

    private void ShowWarning()
    {
        NotificationService.ShowWarning("請注意此操作可能有風險。");
    }

    private void ShowInfo()
    {
        NotificationService.ShowInfo("這是一則提示訊息。");
    }
}

6. LoadingSpinner 使用範例

@using benxu.AppPlatform.BlazorUI.Components

<LoadingSpinner Size="small" />
<LoadingSpinner Size="medium" Message="載入中..." />
<LoadingSpinner Size="large" Color="#28a745" Message="處理資料中，請稍候..." />

@code {
    private bool isLoading = true;

    protected override async Task OnInitializedAsync()
    {
        await Task.Delay(3000);
        isLoading = false;
    }
}

7. BottomSheet 使用範例

BottomSheet 是一個底部滑出視窗元件，適合用於行動裝置 App 中的表單填寫、確認對話框等場景。

@using benxu.AppPlatform.BlazorUI.Components.BottomSheet

<button @onclick="() => _isOpen = true">開啟 Bottom Sheet</button>

<BottomSheet IsOpen="@_isOpen" 
             Title="新增項目" 
             OnClose="() => _isOpen = false">
    <ChildContent>
        
        <div class="bottom-sheet-field">
            <label class="bottom-sheet-field-label">名稱</label>
            <input type="text" class="bottom-sheet-input" @bind="_name" />
        </div>
    </ChildContent>
    <FooterContent>
        <button class="bottom-sheet-button bottom-sheet-button-secondary" 
                @onclick="() => _isOpen = false">
            取消
        </button>
        <button class="bottom-sheet-button bottom-sheet-button-primary" 
                @onclick="HandleSubmit">
            確認
        </button>
    </FooterContent>
</BottomSheet>

@code {
    private bool _isOpen = false;
    private string _name = "";

    private void HandleSubmit()
    {
        Console.WriteLine($"已新增: {_name}");
        _isOpen = false;
    }
}

8. NotificationPanel 使用範例

NotificationPanel 是一個通知面板元件，支援從上方或右側滑入，並允許消費者 App 自訂樣式。

基本用法（預設從右滑入）：

@using benxu.AppPlatform.BlazorUI.Components

<NotificationPanel />

從上方滑入 + 自訂樣式：

@using benxu.AppPlatform.BlazorUI.Components
@using benxu.AppPlatform.BlazorUI.Services

<NotificationPanel SlideDirection="NotificationSlideDirection.Top"
                   PanelClass="my-notification-panel"
                   HeaderClass="my-notification-header" />

在消費者 App 的 CSS 中自訂樣式：

/* 自訂通知面板樣式 */
.my-notification-panel {
    background-color: #f8f9fa;
    border-radius: 0 0 16px 16px;
}

.my-notification-header {
    background-color: white;
    border-bottom: 1px solid #e9ecef;
}

程式化開啓面板：

@inject INotificationPanelService PanelService

<button @onclick="() => PanelService.Open()">開啟通知</button>

9. PageLoading 使用範例

PageLoading 是一個頁面切換載入元件，提供全螢幕遮罩和淡入淡出動畫效果，支援 CSS 客製化。

方式 1：搭配 Router 的 Navigating 參數（頁面切換自動觸發）：

@using benxu.AppPlatform.BlazorUI.Components

<Router AppAssembly="@typeof(MauiProgram).Assembly" OnNavigateAsync="OnNavigateAsync">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(Layout.MainLayout)" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
    <Navigating>
        <PageLoading ForceShow="true" Message="頁面載入中..." />
    </Navigating>
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext context)
    {
        // 可選：確保最少顯示時間避免閃爍
        await Task.Delay(100);
    }
}

方式 2：搭配 IPageLoadingService（手動控制）：

@inject IPageLoadingService PageLoadingService

@code {
    private async Task LoadDataAsync()
    {
        PageLoadingService.Show("正在載入資料...");

        try
        {
            await SomeAsyncOperation();
        }
        finally
        {
            PageLoadingService.Hide();
        }
    }
}

CSS 客製化：

/* 在消費者 App 的 CSS 中覆寫 */
:root {
    --page-loading-overlay-bg: rgba(95, 51, 225, 0.1);
    --page-loading-spinner-color: #5F33E1;
    --page-loading-message-color: #5F33E1;
    --page-loading-message-font-size: 14px;
}

元件 API

AppButton

AppModal

INotificationService

LoadingSpinner

BottomSheet

可用的 CSS 類別：

NotificationPanel

INotificationPanelService

可用的 CSS 類別：

PageLoading

可用的 CSS 變數：

IPageLoadingService

自訂樣式

所有元件都支援 CSS 變數自訂：

:root {
    --primary-color: #007bff;
    --secondary-color: #6c757d;
    --success-color: #28a745;
    --danger-color: #dc3545;
    --warning-color: #ffc107;
    --info-color: #17a2b8;
}

依賴項目

• Microsoft.AspNetCore.Components.Web (8.0.20)
• benxu.AppPlatform.Core

授權

MIT License - Copyright (c) 2025 benxu