# PagingTagHelper v1.0.0: Pagination Enterprise-Ready pour le noyau ASP.NET moderne
2025-11-07T19:12
> REMARQUE: Venir, juste mettre les touches de finition à elle. [Suivez GitHub ! ](https://github.com/scottgal/mostlylucid.pagingtaghelper).
**C'est juste pour vous montrer tout ce que je suis en train de faire avec ce contrôle !**
## Présentation
Après des mois d'évolution et des retours précieux de la communauté (5.7k+ téléchargements!), je suis heureux d'annoncer que la bibliothèque PagingTagHelper a atteint la version 1.0.0. Ce n'est pas seulement une bosse de numéro de version – il représente une maturation complète de la bibliothèque avec des fonctionnalités qui le rendent adapté pour le monde réel, les applications de production.
Si vous avez suivi cette série, vous vous souviendrez que nous avons commencé avec [lance-roquettes nues](https://www.mostlylucid.net/blog/pagingtaghelper), ajouté [en-têtes triables](https://www.mostlylucid.net/blog/pagingtaghelperpt11), et extrait [contrôle de la taille des pages](https://www.mostlylucid.net/blog/pagingtaghelperpt2). La version 1.0.0 prend tout ce que nous avons appris et ajoute des fonctionnalités d'entreprise critiques:
- **Pagination des jetons de continuation** pour les bases de données NoSQL (Cosmos DB, DynamoDB, Azure Table Storage)
- **Localisation multilingue** soutenir 8 langues hors de la boîte
- **Modes JavaScript flexibles** de HTMX à zéro-JavaScript
- **Pure Tailwind Views** Sans dépendances DaisyUI
- **Préservation des paramètres de l'URL intelligente** sur toute la navigation
- **HTMX 2.0.4** mise à jour avec compatibilité en arrière
Plongons dans chacune de ces caractéristiques et voyons comment ils travaillent ensemble pour créer une solution de pagination vraiment flexible.
[](https://www.nuget.org/packages/mostlylucid.pagingtaghelper)
[](https://www.nuget.org/packages/mostlylucid.pagingtaghelper)
[TOC]
## Pagination continue du jeton {#pagination continue du jeton}
Pagination traditionnelle fonctionne magnifiquement avec les bases de données SQL où vous pouvez facilement `SKIP` et `TAKE` Mais que se passe-t-il lorsque vous travaillez avec des bases de données NoSQL comme Cosmos DB, DynamoDB ou Azure Table Storage ? Ces bases de données ne prennent pas en charge la pagination offset – à la place, elles utilisent **jetons de suite**.
### Comprendre la pagination basée sur les jetons {#comprendre la pagination basée sur les jetons}
Voici comment la pagination continue de jeton diffère de la pagination traditionnelle:
```mermaid
graph TD
A[Traditional Paging] --> B[Page 1: OFFSET 0 LIMIT 10]
A --> C[Page 2: OFFSET 10 LIMIT 10]
A --> D[Page 3: OFFSET 20 LIMIT 10]
E[Token-Based Paging] --> F[Page 1: No token]
F --> G[Returns: Data + Token_A]
G --> H[Page 2: Token_A]
H --> I[Returns: Data + Token_B]
I --> J[Page 3: Token_B]
style A stroke:#0ea5e9,stroke-width:3px
style E stroke:#ec4899,stroke-width:3px
```
**Pâques traditionnelles :**
- Vous spécifiez exactement les enregistrements à récupérer (OFFSET/LIMIT)
- Vous pouvez sauter sur n'importe quelle page directement
- La base de données doit analyser tous les enregistrements antérieurs
**Pagination à base de jetons :**
- Base de données retourne un jeton opaque représentant "où continuer"
- Le format de jeton est spécifique à la base de données et opaque pour le client
- La navigation vers l'avant est naturelle, la navigation vers l'arrière nécessite une histoire symbolique
### Poursuite de la mise en œuvre de Pager {#suite-pager-mise en œuvre}
La nouvelle `` tag helper rend la mise en œuvre de pagination basée sur jeton simple. Tout d'abord, créer un modèle qui implémente `IContinuationPagingModel`:
```csharp
public class ProductPagingViewModel : IContinuationPagingModel
{
public string? NextPageToken { get; set; }
public bool HasMoreResults { get; set; }
public int PageSize { get; set; } = 25;
public int CurrentPage { get; set; } = 1;
public Dictionary? PageTokenHistory { get; set; }
public ViewType ViewType { get; set; } = ViewType.TailwindAndDaisy;
// Your actual data
public List Products { get; set; } = new();
}
```
L'interface est minimale mais puissante. Voyons ce que chaque propriété fait :
- `NextPageToken`: Le jeton pour récupérer la page suivante (fournie par votre base de données)
- `HasMoreResults`: Booléen indiquant s'il y a plus de pages
- `PageSize`: Articles par page
- `CurrentPage`: Numéro de page affiché uniquement pour l'interface utilisateur
- `PageTokenHistory`: Dictionary mapping pages numbers to jens for backer navigation
- `ViewType`: Quel cadre CSS utiliser pour le rendu
Implémentons maintenant une action de contrôleur qui simule la pagination Cosmos DB :
```csharp
[Route("Products")]
public async Task Products(
int currentPage = 1,
int pageSize = 25,
string? pageToken = null,
string? tokenHistory = null)
{
// Simulate fetching from Cosmos DB
var cosmosResults = await _cosmosService.GetProductsAsync(
pageSize: pageSize,
continuationToken: pageToken
);
// Deserialize token history for backward navigation
var history = string.IsNullOrEmpty(tokenHistory)
? new Dictionary()
: JsonSerializer.Deserialize>(tokenHistory)
?? new Dictionary();
// Store current token in history
if (!string.IsNullOrEmpty(pageToken))
{
history[currentPage] = pageToken;
}
var viewModel = new ProductPagingViewModel
{
CurrentPage = currentPage,
PageSize = pageSize,
NextPageToken = cosmosResults.ContinuationToken,
HasMoreResults = cosmosResults.HasMoreResults,
PageTokenHistory = history,
Products = cosmosResults.Items
};
if (Request.IsHtmx())
{
return PartialView("_ProductList", viewModel);
}
return View(viewModel);
}
```
Cette implémentation montre comment l'historique des jetons permet une navigation en arrière. Sans elle, la pagination continue des jetons ne prendrait en charge que les boutons "Next". En maintenant un dictionnaire de cartes page à jeton, nous pouvons prendre en charge à la fois la navigation "Précédente" et "Next".
Voici le flux d'accumulation de jetons visualisé:
```mermaid
sequenceDiagram
participant User
participant Controller
participant Database
participant TokenHistory
User->>Controller: Request Page 1 (no token)
Controller->>Database: Query with no token
Database-->>Controller: Data + Token_A
Controller->>TokenHistory: Store Token_A for page 1
Controller-->>User: Display Page 1
User->>Controller: Request Page 2 (Token_A)
Controller->>Database: Query with Token_A
Database-->>Controller: Data + Token_B
Controller->>TokenHistory: Add Token_B for page 2
Controller-->>User: Display Page 2
User->>Controller: Request Page 1 (retrieve from history)
Controller->>TokenHistory: Get Token for Page 1
Controller->>Database: Query with Token_A
Database-->>Controller: Data + Token_A
Controller-->>User: Display Page 1
```
Dans votre vue Razor, l'utilisation du pager de suite est simple:
```razor
@model ProductPagingViewModel
Product
Company
Price
@foreach (var product in Model.Products)
{
@product.Name
@product.CompanyName
$@product.Price.ToString("N2")
}
```
L'aide de tag automatiquement :
- Sérialise l'historique des jetons en paramètres de requête
- Construit des URLs de navigation avec des jetons appropriés
- Désactive "Précédent" quand à la page 1
- Désactive "Next" lorsque `HasMoreResults` est faux
- Préserve tous les autres paramètres de requête (recherche, filtres, etc.)
### Historique des jetons pour la navigation arrière {#token-history}
Le génie de l'approche historique des jetons est qu'elle est entièrement optionnelle. Si vous avez seulement besoin de navigation "Next" (par exemple, défilement infini), vous pouvez ignorer entièrement l'histoire des jetons:
```razor
```
Cela rend juste un bouton "Next" sans indicateurs de page ou gestion de l'historique.
Pour la navigation complète, l'historique des jetons est automatiquement sérialisé comme JSON dans la chaîne de requête. Voici à quoi ressemble une URL avec l'historique des jetons :
```
/Products?currentPage=3&pageSize=25&pageToken=abc123&tokenHistory=%7B%221%22%3A%22xyz789%22%2C%222%22%3A%22abc123%22%7D
```
Les `tokenHistory` paramètre contient le dictionnaire encodé, rendant la navigation en arrière transparente.
### Navigation de page numérotée {#numbered-page-navigation}
L'une des plus importantes améliorations de UX dans le pager de suite est **boutons de page numérotés**. Lorsque vous naviguez vers l'avant, le pager affiche les numéros de page cliquables pour toutes les pages visitées :
```
Initial page 1: [Next →]
After next click: [← Prev] [1] [2 active] [3 disabled] [Next →]
After next click: [← Prev] [1] [2] [3 active] [4 disabled] [Next →]
Click page 2: [← Prev] [1] [2 active] [3] [4 disabled] (no next - not visited yet)
```
Cela fournit une pagination traditionnelle UX tout en maintenant l'architecture de backend basée sur des jetons. L'implémentation stocke des jetons pour chaque page visitée, permettant la navigation directe sur toute page précédemment consultée.
**Limiter la croissance historique :**
Pour empêcher l'utilisation de la mémoire non limitée, définissez `max-history-pages` (par défaut: 20):
```razor
```
Lorsque la limite est atteinte, les jetons de page les plus anciens sont automatiquement parés.
### Critique : Préservation des paramètres de requête {#query-parameter-conservation}
**C'est la caractéristique la plus importante de l'implémentation de la pager de suite.**
Les jetons de continuation ne sont valides qu'avec le même contexte de requête (filtres, tris, recherches) qui les a générés. L'utilisation d'un jeton avec différents paramètres de requête retournera des données incorrectes ou échouera entièrement.
Le pager de suite conserve automatiquement TOUS les paramètres de requête à l'exception de ses propres paramètres :
```html
/Products?category=electronics&brand=acme&minPrice=100
/Products?category=electronics&brand=acme&minPrice=100¤tPage=2&pageToken=xyz123&tokenHistory={...}
```
Vous pouvez désactiver ce comportement si nécessaire :
```razor
```
Mais c'est **fortement découragé** Sauf si vous êtes absolument certain que vos jetons ne dépendent pas du contexte de requête.
**Pourquoi cela importe-t-il?**
Exemple de DB Cosmos :
```csharp
// Page 1 with filter
var query = container.GetItemQueryIterator(
"SELECT * FROM c WHERE c.category = 'electronics'",
continuationToken: null
);
var response = await query.ReadNextAsync();
// Returns: Products + Token_A
// Page 2 with SAME filter - Token_A is valid
var query2 = container.GetItemQueryIterator(
"SELECT * FROM c WHERE c.category = 'electronics'",
continuationToken: Token_A // ✅ Works!
);
// Page 2 with DIFFERENT filter - Token_A is invalid
var query3 = container.GetItemQueryIterator(
"SELECT * FROM c WHERE c.category = 'computers'",
continuationToken: Token_A // ❌ Wrong results or error!
);
```
La préservation automatique des paramètres du pager assure que les jetons sont toujours utilisés avec leur contexte de requête d'origine.
---
## Soutien à la localisation {#soutien à la localisation}
Les applications modernes servent le public mondial, et les contrôles de pagination doivent parler la langue de vos utilisateurs. La version 1.0.0 inclut un support de localisation complet intégré directement dans la bibliothèque.
### Langues intégrées {#langues intégrées}
La bibliothèque est livrée avec des traductions pour 8 langues:
Code (en anglais seulement) Langue (en anglais seulement)
|------|----------|
| `en` Anglais (par défaut)
| `de` Allemand (Deutsch)
| `es` Espagnol (Español)
| `fr` Français (français)
| `it` Italien (Italiano)
| `pt` Portugais (Português)
| `ja` Japonais (日本語)
| `zh-Hans` Chinois simplifié (
Tout le texte est localisé, y compris :
- Les étiquettes des boutons précédents/suivant/premier/dernier
- Texte sommaire de la page ("Afficher X à Y des éléments Z")
- Étiquettes ARIA pour l'accessibilité
- Étiquette de taille de page ("Items par page")
Le système de localisation est alimenté par `.resx` fichiers ressources, ce qui facilite l'ajout de vos propres langues. Tous les fichiers ressources sont dans `mostlylucid.pagingtaghelper/Resources/`.
### Utilisation de la localisation {#localisation-usage}
L'utilisation de la localisation est simple. Il suffit d'ajouter le `language` attribut & #160;:
```razor
```
Cela rend tout le texte en allemand:
```html
Zeige 1 bis 10 von 256 Einträgen
```
Pour un changement de langage dynamique basé sur les préférences de l'utilisateur, définissez la langue dans votre contrôleur :
```csharp
public async Task Products(
int page = 1,
int pageSize = 10,
string language = "en")
{
var pagingModel = await GenerateModel(page, pageSize);
ViewBag.SelectedLanguage = language;
return View(pagingModel);
}
```
Puis, dans votre vue, créez un sélecteur de langue:
```razor
@{
var selectedLanguage = ViewBag.SelectedLanguage as string ?? "en";
var languages = new Dictionary
{
{ "en", "English" },
{ "de", "German" },
{ "es", "Spanish" },
{ "fr", "French" },
{ "it", "Italian" },
{ "pt", "Portuguese" },
{ "ja", "Japanese" },
{ "zh-Hans", "Chinese" }
};
}
```
Vous pouvez également outrepasser les chaînes de texte individuelles tout en bénéficiant de la localisation pour d'autres éléments :
```razor
```
Les `PagingLocalizer` Le service gère automatiquement le formatage spécifique à la culture. Si vous passez un code de langue invalide, il revient gracieusement à l'anglais.
Pour l'intégration HTMX, vous souhaitez préserver la langue à travers les requêtes :
```html
```
Cela garantit que les mises à jour de la vue partielle HTMX maintiennent la langue sélectionnée.
---
## Modes JavaScript {#javascript-modes}
L'une des améliorations les plus significatives de v1.0.0 est l'introduction de modes JavaScript flexibles. Auparavant, vous aviez un choix booléen: `use-htmx="true"` ou `use-htmx="false"`. Maintenant, vous avez cinq modes distincts, chacun optimisé pour différents scénarios.
### Modes disponibles {#modes disponibles}
Voici la ventilation complète des modes JavaScript :
```mermaid
graph TD
A[JavaScript Modes] --> B[HTMX]
A --> C[HTMXWithAlpine]
A --> D[Alpine]
A --> E[PlainJS]
A --> F[NoJS]
B --> B1[Uses HTMX for partial updates]
B --> B2[hx-get, hx-target, hx-swap]
C --> C1[HTMX + Alpine.js directives]
C --> C2[Enhanced interactivity]
D --> D1[Pure Alpine.js]
D --> D2[x-data, @click handlers]
E --> E1[Vanilla JavaScript]
E --> E2[onclick handlers]
F --> F1[Zero JavaScript]
F --> F2[Standard anchor links & forms]
```
Voyons chaque mode en action :
**1. Mode HTMX (par défaut)**
```razor
```
Reveurs :
```html
```
Parfait pour les mises à jour de pages dynamiques sans rechargement complet de la page. C'est le mode recommandé pour les applications ASP.NET Core modernes.
**2. HTMXWithAlpine Mode**
```razor
```
Reveurs :
```html
```
Combine HTMX pour la navigation avec Alpine.js pour une interactivité supplémentaire côté client. Utilisez ceci lorsque vous avez besoin d'éléments d'interface utilisateur réactifs à côté de la pagination (indicateurs de chargement, animations, validation côté client).
**3. Mode alpin**
```razor
```
Reveurs :
```html
```
Pure Alpine.js sans HTMX. Utile lorsque vous utilisez déjà Alpine.js mais ne voulez pas de dépendances HTMX.
**4. Mode PlainJS**
```razor
```
Reveurs :
```html
```
Pas de dépendances framework, il suffit de vanille JavaScript. Ce mode inclut également un helper pour les changements de taille de page:
```razor
@Html.PageSizeOnchangeSnippet()
```
Ceci injecte le JavaScript nécessaire pour gérer les changements de taille de page déroulante sans HTMX.
**5. Mode noJS**
```razor
```
Reveurs :
```html
Next ›
```
Zéro JavaScript requis. Parfait pour :
- Exigences en matière d'accessibilité
- Scénarios d'amélioration progressive
- Environnements où JavaScript est désactivé
- Pages critiques de référencement où vous voulez une navigation conviviale
La beauté de ce système est que **tous les modes préservent vos paramètres de requête existants**. Que vous filtriez par catégorie, recherche ou tri, la pagination maintient automatiquement votre état.
### Migration à partir de use-htmx {#migration-from-use-htmx}
Pour la compatibilité arrière, l'ancien `use-htmx` l'attribut fonctionne toujours :
```razor
```
Cependant, je recommande de migrer vers la nouvelle `js-mode` attribut pour plus de clarté:
```razor
```
---
## Améliorations du type de vue {#viewtype-enhancements}
La version 1.0.0 introduit deux ajouts importants de ViewType qui traitent des scénarios réels communs.
### Pure Tailwind {#pure-tailwind}
Auparavant, si vous vouliez du style TailwindCSS, vous avez `TailwindAndDaisy` vue qui utilise les composants DaisyUI. C'est génial si vous utilisez déjà DaisyUI, mais que faire si vous voulez pur Tailwind sans la dépendance DaisyUI?
Entrez `ViewType.Tailwind`:
```razor
```
Cela rend uniquement en utilisant les classes d'utilitaire Tailwind standard:
```html
Page 1
```
Numéro `btn`, `badge`, ou `join` classes – juste pur Tailwind. Cela vous donne un contrôle complet sur le style sans dépendances de bibliothèque de composants.
**Comparaison :**
VoirTypeSérie CSS Librairie des composantsUtiliser le cas d'utilisation
|----------|---------------|-------------------|----------|
| `TailwindAndDaisy` TailwindCSS de DaisyUIS Projets utilisant déjà DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUIS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyUS de DaisyU.
| `Tailwind` TailwindCSS Aucun projet Pure Tailwind
| `Bootstrap` Constituants de bootstrap de bootstrap de bootstrap de projets de bootstrap de bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap de type bootstrap.
| `Plain` Pas de dépendances du cadre
| `NoJS` CSS embedded Aucun besoin de JavaScript Zéro
### Mode NoJS {#nojs-mode}
Les `NoJS` ViewType combine zéro JavaScript avec le style CSS Plain:
```razor
```
Principales différences par rapport aux autres types de vues :
1. **La navigation utilise des liens d'ancrage**, pas les boutons:
```html
Next ›
```
2. **Le sélecteur de taille de page est un formulaire**:
```html
```
Les `onchange="this.form.submit()"` fournit la commodité lorsque JavaScript est disponible, mais le `