@ticatec/uniface-element 0.2.4 → 0.3.0

package/dist/pagination/README_CN.md

@@ -0,0 +1,946 @@
+# Pagination 分页
+
+一个智能的分页组件，为大型数据集提供直观的页面导航，具有智能的页码显示和间隔处理功能。
+
+## 功能特性
+
+- **智能页码显示**: 智能算法显示相关页码并处理间隔
+- **多种样式**: 支持朴素、圆角和圆形视觉样式
+- **尺寸变体**: 普通和大尺寸选项
+- **点击导航**: 通过点击处理器轻松选择页面
+- **响应式逻辑**: 根据当前位置调整页码显示
+- **边界处理**: 自动边界验证和修正
+- **间隔指示**: 为非连续页码范围显示省略号 (...)
+- **当前页高亮**: 活动页面的视觉指示
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Pagination from '@ticatec/uniface-element/Pagination';
+  
+  let currentPage = 1;
+  let totalPages = 10;
+  
+  function handlePageChange(page) {
+    currentPage = page;
+    console.log('页面切换到:', page);
+  }
+</script>
+
+<Pagination 
+  pageNo={currentPage}
+  pageCount={totalPages}
+  onPageChange={handlePageChange}
+/>
+```
+
+## API 参考
+
+### 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `pageNo` | `number` | `1` | 当前活动页码 |
+| `pageCount` | `number` | `0` | 总页数 |
+| `type` | `'plain' \| 'round' \| 'circle'` | `'round'` | 视觉样式变体 |
+| `style` | `string` | `''` | 自定义CSS样式 |
+| `big` | `boolean` | `false` | 启用大尺寸变体 |
+| `onPageChange` | `OnPageChange` | `undefined` | 页面变更事件处理器 |
+
+### 类型
+
+```typescript
+export type OnPageChange = (page: number) => void;
+```
+
+## 页码显示逻辑
+
+分页组件使用智能逻辑显示页码：
+
+- **1-5页**: 显示所有页码
+- **6+页**: 显示首页、相关中间页和末页，中间用间隔表示
+- **当前页定位**: 根据当前页位置调整显示
+- **间隔表示**: 使用省略号 (...) 表示非连续范围
+
+## 示例
+
+### 基本数据表格分页
+
+```svelte
+<script>
+  import Pagination from '@ticatec/uniface-element/Pagination';
+  
+  let currentPage = 1;
+  let totalPages = 20;
+  let itemsPerPage = 10;
+  let totalItems = 200;
+  
+  let data = [];
+  
+  function loadData(page) {
+    // 模拟API调用
+    const startIndex = (page - 1) * itemsPerPage;
+    const endIndex = startIndex + itemsPerPage;
+    
+    data = Array.from({ length: itemsPerPage }, (_, i) => ({
+      id: startIndex + i + 1,
+      name: `项目 ${startIndex + i + 1}`,
+      value: Math.random() * 100
+    }));
+  }
+  
+  function handlePageChange(page) {
+    currentPage = page;
+    loadData(page);
+  }
+  
+  // 加载初始数据
+  loadData(currentPage);
+</script>
+
+<div class="data-table">
+  <table>
+    <thead>
+      <tr>
+        <th>ID</th>
+        <th>名称</th>
+        <th>值</th>
+      </tr>
+    </thead>
+    <tbody>
+      {#each data as item}
+        <tr>
+          <td>{item.id}</td>
+          <td>{item.name}</td>
+          <td>{item.value.toFixed(2)}</td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+  
+  <div class="pagination-wrapper">
+    <Pagination 
+      pageNo={currentPage}
+      pageCount={totalPages}
+      onPageChange={handlePageChange}
+      type="round"
+    />
+  </div>
+</div>
+
+<style>
+  .data-table {
+    width: 100%;
+  }
+  
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    margin-bottom: 20px;
+  }
+  
+  th, td {
+    padding: 12px;
+    text-align: left;
+    border-bottom: 1px solid #ddd;
+  }
+  
+  th {
+    background-color: #f5f5f5;
+    font-weight: 600;
+  }
+  
+  .pagination-wrapper {
+    display: flex;
+    justify-content: center;
+    margin-top: 20px;
+  }
+</style>
+```
+
+### 搜索结果分页
+
+```svelte
+<script>
+  import Pagination from '@ticatec/uniface-element/Pagination';
+  
+  let searchQuery = '';
+  let currentPage = 1;
+  let totalPages = 0;
+  let results = [];
+  let loading = false;
+  
+  async function performSearch(query, page = 1) {
+    if (!query.trim()) return;
+    
+    loading = true;
+    
+    try {
+      // 模拟API搜索
+      await new Promise(resolve => setTimeout(resolve, 500));
+      
+      const mockResults = Array.from({ length: 10 }, (_, i) => ({
+        id: i + 1,
+        title: `"${query}"的搜索结果 ${i + 1}`,
+        description: `这是搜索结果 ${i + 1} 的描述`,
+        url: `https://example.com/result-${i + 1}`
+      }));
+      
+      results = mockResults;
+      totalPages = Math.ceil(100 / 10); // 假设总共100个结果
+      currentPage = page;
+    } finally {
+      loading = false;
+    }
+  }
+  
+  function handlePageChange(page) {
+    performSearch(searchQuery, page);
+  }
+  
+  function handleSearch() {
+    currentPage = 1;
+    performSearch(searchQuery, 1);
+  }
+</script>
+
+<div class="search-container">
+  <div class="search-box">
+    <input 
+      type="text" 
+      bind:value={searchQuery}
+      placeholder="输入搜索查询..."
+      on:keydown={(e) => e.key === 'Enter' && handleSearch()}
+    />
+    <button on:click={handleSearch}>搜索</button>
+  </div>
+  
+  {#if loading}
+    <div class="loading">搜索中...</div>
+  {:else if results.length > 0}
+    <div class="results">
+      {#each results as result}
+        <div class="result-item">
+          <h3>{result.title}</h3>
+          <p>{result.description}</p>
+          <a href={result.url} target="_blank">{result.url}</a>
+        </div>
+      {/each}
+      
+      <Pagination 
+        pageNo={currentPage}
+        pageCount={totalPages}
+        onPageChange={handlePageChange}
+        type="circle"
+        style="margin-top: 30px;"
+      />
+    </div>
+  {/if}
+</div>
+
+<style>
+  .search-container {
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 20px;
+  }
+  
+  .search-box {
+    display: flex;
+    gap: 10px;
+    margin-bottom: 20px;
+  }
+  
+  .search-box input {
+    flex: 1;
+    padding: 10px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+  }
+  
+  .search-box button {
+    padding: 10px 20px;
+    background: #007bff;
+    color: white;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+  }
+  
+  .loading {
+    text-align: center;
+    padding: 40px;
+    color: #666;
+  }
+  
+  .result-item {
+    padding: 20px 0;
+    border-bottom: 1px solid #eee;
+  }
+  
+  .result-item h3 {
+    margin: 0 0 10px 0;
+    color: #007bff;
+  }
+  
+  .result-item p {
+    margin: 0 0 10px 0;
+    color: #666;
+  }
+  
+  .result-item a {
+    color: #28a745;
+    text-decoration: none;
+  }
+</style>
+```
+
+### 博客文章不同样式
+
+```svelte
+<script>
+  import Pagination from '@ticatec/uniface-element/Pagination';
+  
+  let posts = [];
+  let currentPage = 1;
+  let totalPages = 15;
+  let paginationStyle = 'round';
+  
+  function loadPosts(page) {
+    // 模拟加载博客文章
+    posts = Array.from({ length: 5 }, (_, i) => ({
+      id: (page - 1) * 5 + i + 1,
+      title: `博客文章 ${(page - 1) * 5 + i + 1}`,
+      excerpt: '这是一篇关于技术的有趣文章，包含了很多有用的信息...',
+      author: `作者 ${i + 1}`,
+      date: new Date(2024, 0, (page - 1) * 5 + i + 1).toLocaleDateString()
+    }));
+  }
+  
+  function handlePageChange(page) {
+    currentPage = page;
+    loadPosts(page);
+  }
+  
+  // 加载初始文章
+  loadPosts(currentPage);
+</script>
+
+<div class="blog-container">
+  <div class="style-selector">
+    <label>分页样式:</label>
+    <select bind:value={paginationStyle}>
+      <option value="plain">朴素</option>
+      <option value="round">圆角</option>
+      <option value="circle">圆形</option>
+    </select>
+  </div>
+  
+  <div class="posts">
+    {#each posts as post}
+      <article class="post">
+        <h2>{post.title}</h2>
+        <div class="post-meta">
+          由 {post.author} 发布于 {post.date}
+        </div>
+        <p>{post.excerpt}</p>
+        <a href="/posts/{post.id}">阅读更多</a>
+      </article>
+    {/each}
+  </div>
+  
+  <div class="pagination-container">
+    <Pagination 
+      pageNo={currentPage}
+      pageCount={totalPages}
+      onPageChange={handlePageChange}
+      type={paginationStyle}
+    />
+  </div>
+</div>
+
+<style>
+  .blog-container {
+    max-width: 900px;
+    margin: 0 auto;
+    padding: 20px;
+  }
+  
+  .style-selector {
+    margin-bottom: 30px;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+  }
+  
+  .style-selector select {
+    padding: 5px 10px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+  }
+  
+  .post {
+    padding: 30px 0;
+    border-bottom: 1px solid #eee;
+  }
+  
+  .post h2 {
+    margin: 0 0 10px 0;
+    color: #333;
+  }
+  
+  .post-meta {
+    color: #666;
+    font-size: 14px;
+    margin-bottom: 15px;
+  }
+  
+  .post p {
+    margin: 0 0 15px 0;
+    line-height: 1.6;
+  }
+  
+  .post a {
+    color: #007bff;
+    text-decoration: none;
+  }
+  
+  .pagination-container {
+    display: flex;
+    justify-content: center;
+    margin-top: 40px;
+  }
+</style>
+```
+
+### 图片画廊大型分页
+
+```svelte
+<script>
+  import Pagination from '@ticatec/uniface-element/Pagination';
+  
+  let images = [];
+  let currentPage = 1;
+  let totalPages = 25;
+  
+  function loadImages(page) {
+    // 模拟加载画廊图片
+    images = Array.from({ length: 12 }, (_, i) => ({
+      id: (page - 1) * 12 + i + 1,
+      src: `https://picsum.photos/300/200?random=${(page - 1) * 12 + i + 1}`,
+      title: `图片 ${(page - 1) * 12 + i + 1}`,
+      description: `美丽的图片编号 ${(page - 1) * 12 + i + 1}`
+    }));
+  }
+  
+  function handlePageChange(page) {
+    currentPage = page;
+    loadImages(page);
+    // 页面变更后滚动到顶部
+    window.scrollTo({ top: 0, behavior: 'smooth' });
+  }
+  
+  // 加载初始图片
+  loadImages(currentPage);
+</script>
+
+<div class="gallery-container">
+  <h1>照片画廊</h1>
+  <p>第 {currentPage} 页，共 {totalPages} 页</p>
+  
+  <div class="image-grid">
+    {#each images as image}
+      <div class="image-card">
+        <img src={image.src} alt={image.title} loading="lazy" />
+        <div class="image-info">
+          <h3>{image.title}</h3>
+          <p>{image.description}</p>
+        </div>
+      </div>
+    {/each}
+  </div>
+  
+  <div class="pagination-wrapper">
+    <Pagination 
+      pageNo={currentPage}
+      pageCount={totalPages}
+      onPageChange={handlePageChange}
+      type="round"
+      big
+    />
+  </div>
+</div>
+
+<style>
+  .gallery-container {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 20px;
+  }
+  
+  .gallery-container h1 {
+    text-align: center;
+    margin-bottom: 10px;
+  }
+  
+  .gallery-container p {
+    text-align: center;
+    color: #666;
+    margin-bottom: 30px;
+  }
+  
+  .image-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+    gap: 20px;
+    margin-bottom: 40px;
+  }
+  
+  .image-card {
+    border: 1px solid #ddd;
+    border-radius: 8px;
+    overflow: hidden;
+    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+    transition: transform 0.2s;
+  }
+  
+  .image-card:hover {
+    transform: translateY(-2px);
+  }
+  
+  .image-card img {
+    width: 100%;
+    height: 200px;
+    object-fit: cover;
+  }
+  
+  .image-info {
+    padding: 15px;
+  }
+  
+  .image-info h3 {
+    margin: 0 0 5px 0;
+    font-size: 16px;
+  }
+  
+  .image-info p {
+    margin: 0;
+    color: #666;
+    font-size: 14px;
+  }
+  
+  .pagination-wrapper {
+    display: flex;
+    justify-content: center;
+  }
+</style>
+```
+
+### 电商产品列表
+
+```svelte
+<script>
+  import Pagination from '@ticatec/uniface-element/Pagination';
+  
+  let products = [];
+  let currentPage = 1;
+  let totalPages = 12;
+  let sortBy = 'name';
+  
+  function loadProducts(page, sort = 'name') {
+    // 模拟加载产品
+    products = Array.from({ length: 8 }, (_, i) => ({
+      id: (page - 1) * 8 + i + 1,
+      name: `产品 ${(page - 1) * 8 + i + 1}`,
+      price: (Math.random() * 100 + 10).toFixed(2),
+      rating: (Math.random() * 2 + 3).toFixed(1),
+      image: `https://picsum.photos/250/250?random=${(page - 1) * 8 + i + 1}`,
+      description: '高品质产品，具有优秀的功能特性'
+    }));
+    
+    // 排序产品
+    if (sort === 'price') {
+      products.sort((a, b) => parseFloat(a.price) - parseFloat(b.price));
+    } else if (sort === 'rating') {
+      products.sort((a, b) => parseFloat(b.rating) - parseFloat(a.rating));
+    }
+  }
+  
+  function handlePageChange(page) {
+    currentPage = page;
+    loadProducts(page, sortBy);
+  }
+  
+  function handleSortChange() {
+    loadProducts(currentPage, sortBy);
+  }
+  
+  // 加载初始产品
+  loadProducts(currentPage, sortBy);
+</script>
+
+<div class="shop-container">
+  <div class="shop-header">
+    <h1>我们的产品</h1>
+    <div class="sort-controls">
+      <label>排序:</label>
+      <select bind:value={sortBy} on:change={handleSortChange}>
+        <option value="name">名称</option>
+        <option value="price">价格</option>
+        <option value="rating">评分</option>
+      </select>
+    </div>
+  </div>
+  
+  <div class="products-grid">
+    {#each products as product}
+      <div class="product-card">
+        <img src={product.image} alt={product.name} />
+        <div class="product-info">
+          <h3>{product.name}</h3>
+          <p class="description">{product.description}</p>
+          <div class="product-details">
+            <span class="price">¥{product.price}</span>
+            <span class="rating">★ {product.rating}</span>
+          </div>
+          <button class="add-to-cart">加入购物车</button>
+        </div>
+      </div>
+    {/each}
+  </div>
+  
+  <div class="pagination-footer">
+    <Pagination 
+      pageNo={currentPage}
+      pageCount={totalPages}
+      onPageChange={handlePageChange}
+      type="round"
+    />
+    <div class="page-info">
+      显示第 {currentPage} 页，共 {totalPages} 页
+    </div>
+  </div>
+</div>
+
+<style>
+  .shop-container {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 20px;
+  }
+  
+  .shop-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 30px;
+  }
+  
+  .sort-controls {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+  }
+  
+  .sort-controls select {
+    padding: 5px 10px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+  }
+  
+  .products-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+    gap: 24px;
+    margin-bottom: 40px;
+  }
+  
+  .product-card {
+    border: 1px solid #ddd;
+    border-radius: 8px;
+    overflow: hidden;
+    transition: box-shadow 0.2s;
+  }
+  
+  .product-card:hover {
+    box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+  }
+  
+  .product-card img {
+    width: 100%;
+    height: 250px;
+    object-fit: cover;
+  }
+  
+  .product-info {
+    padding: 16px;
+  }
+  
+  .product-info h3 {
+    margin: 0 0 8px 0;
+    font-size: 18px;
+  }
+  
+  .description {
+    color: #666;
+    font-size: 14px;
+    margin: 0 0 12px 0;
+  }
+  
+  .product-details {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 16px;
+  }
+  
+  .price {
+    font-size: 20px;
+    font-weight: bold;
+    color: #007bff;
+  }
+  
+  .rating {
+    color: #ff9500;
+  }
+  
+  .add-to-cart {
+    width: 100%;
+    padding: 10px;
+    background: #007bff;
+    color: white;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    font-size: 16px;
+  }
+  
+  .add-to-cart:hover {
+    background: #0056b3;
+  }
+  
+  .pagination-footer {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 10px;
+  }
+  
+  .page-info {
+    color: #666;
+    font-size: 14px;
+  }
+</style>
+```
+
+### 移动端响应式分页
+
+```svelte
+<script>
+  import Pagination from '@ticatec/uniface-element/Pagination';
+  
+  let currentPage = 1;
+  let totalPages = 20;
+  let isMobile = false;
+  
+  import { onMount } from 'svelte';
+  
+  onMount(() => {
+    const checkMobile = () => {
+      isMobile = window.innerWidth < 768;
+    };
+    
+    checkMobile();
+    window.addEventListener('resize', checkMobile);
+    
+    return () => window.removeEventListener('resize', checkMobile);
+  });
+  
+  function handlePageChange(page) {
+    currentPage = page;
+  }
+</script>
+
+<div class="responsive-container">
+  <div class="content">
+    <h2>响应式分页示例</h2>
+    <p>此分页组件适应移动端和桌面端屏幕。</p>
+    
+    <!-- 示例内容 -->
+    <div class="sample-content">
+      {#each Array(10) as _, i}
+        <div class="content-item">
+          项目 {(currentPage - 1) * 10 + i + 1}
+        </div>
+      {/each}
+    </div>
+  </div>
+  
+  <div class="pagination-section">
+    <Pagination 
+      pageNo={currentPage}
+      pageCount={totalPages}
+      onPageChange={handlePageChange}
+      type="round"
+      style={isMobile ? 'transform: scale(0.9);' : ''}
+    />
+    
+    {#if isMobile}
+      <div class="mobile-info">
+        第 {currentPage} 页，共 {totalPages} 页
+      </div>
+    {/if}
+  </div>
+</div>
+
+<style>
+  .responsive-container {
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 20px;
+  }
+  
+  .content h2 {
+    text-align: center;
+    margin-bottom: 10px;
+  }
+  
+  .content p {
+    text-align: center;
+    color: #666;
+    margin-bottom: 30px;
+  }
+  
+  .sample-content {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+    gap: 16px;
+    margin-bottom: 30px;
+  }
+  
+  .content-item {
+    padding: 20px;
+    background: #f8f9fa;
+    border: 1px solid #dee2e6;
+    border-radius: 8px;
+    text-align: center;
+  }
+  
+  .pagination-section {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 10px;
+  }
+  
+  .mobile-info {
+    font-size: 14px;
+    color: #666;
+  }
+  
+  @media (max-width: 767px) {
+    .sample-content {
+      grid-template-columns: 1fr 1fr;
+      gap: 12px;
+    }
+    
+    .content-item {
+      padding: 16px;
+      font-size: 14px;
+    }
+  }
+</style>
+```
+
+## 最佳实践
+
+1. **页面状态管理**: 始终正确维护当前页面状态
+2. **加载状态**: 在页面转换期间显示加载指示器
+3. **URL同步**: 适当时保持URL与当前页面同步
+4. **无障碍功能**: 确保键盘导航和屏幕阅读器支持
+5. **移动端优化**: 在移动设备上考虑触摸友好的尺寸
+6. **性能**: 为非常大的数据集实现虚拟滚动
+7. **用户反馈**: 提供当前页和总页数的清晰指示
+
+## 样式
+
+Pagination 组件提供多个CSS类用于自定义：
+
+```css
+.uniface-pagination-panel {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.uniface-pagination-panel.big {
+  /* 大尺寸变体 */
+}
+
+.uniface-page-no {
+  cursor: pointer;
+  padding: 8px 12px;
+  border-radius: 4px;
+  transition: background-color 0.2s;
+}
+
+.uniface-page-no:hover {
+  background-color: #f5f5f5;
+}
+
+.uniface-page-no.selected {
+  background-color: #007bff;
+  color: white;
+}
+
+.uniface-page-gap {
+  padding: 8px 4px;
+  color: #666;
+}
+
+/* 样式变体 */
+.uniface-pagination-panel.round .uniface-page-no {
+  border-radius: 8px;
+}
+
+.uniface-pagination-panel.circle .uniface-page-no {
+  border-radius: 50%;
+  width: 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.uniface-pagination-panel.plain .uniface-page-no {
+  border-radius: 0;
+  border-bottom: 2px solid transparent;
+}
+
+.uniface-pagination-panel.plain .uniface-page-no.selected {
+  background-color: transparent;
+  color: #007bff;
+  border-bottom-color: #007bff;
+}
+```
+
+## 无障碍功能
+
+- 键盘导航支持 (Tab, Enter, Space)
+- 为屏幕阅读器提供ARIA标签
+- 焦点管理和视觉指示器
+- 高对比度模式兼容性
+- 语义化HTML结构
+
+## 相关组件
+
+- [PaginationPanel](../pagination-panel/README.md) - 完整的分页面板，带页面大小控制
+- [DataTable](../data-table/README.md) - 内置分页的数据表格
+- [Button](../button/README.md) - 用于自定义分页控件