@hsu-react/ui 0.0.1 → 0.0.3

package/src/components/Slider/index.module.less

@@ -1,4 +1,5 @@
 .slider {
+  width: 100%;
   height: 32px;
   margin: 0px;
   padding-block: 0px;
@@ -6,14 +7,14 @@
   overflow-x: hidden;
   overflow-y: visible;
 
-  .ant-slider-step,
-  .ant-slider-track,
-  .ant-slider-rail {
+  :global(.ant-slider-step),
+  :global(.ant-slider-track),
+  :global(.ant-slider-rail) {
     top: 0px;
     height: 100% !important;
   }
 
-  .ant-slider-handle {
+  :global(.ant-slider-handle) {
     position: relative;
     top: 50%;
     transform: translate(calc(-50% - 4px), calc(-50% + 1px)) !important;

package/src/components/Spreadsheet/index.md

@@ -8,10 +8,51 @@ title: Spreadsheet 电子表格
 
 # Spreadsheet 电子表格
 
-> `Spreadsheet` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 `x-data-spreadsheet` 封装的电子表格组件，接收 `xlsx` 的 `WorkBook` 数据并自动转换为表格内容渲染。
 
 ## 引入
 
 ```ts
 import { Spreadsheet } from "@hsu-react/ui";
 ```
+
+## 电子表格
+
+```tsx
+import React from "react";
+import { Spreadsheet } from "@hsu-react/ui";
+import { utils } from "xlsx";
+
+// 用 xlsx 工具构建一个 WorkBook（实际项目中通常由 read() 读取文件得到）
+const aoa = [
+  ["姓名", "部门", "工资"],
+  ["张三", "研发部", 12000],
+  ["李四", "市场部", 9500],
+  ["王五", "财务部", 8800],
+];
+const ws = utils.aoa_to_sheet(aoa);
+const workbook = utils.book_new();
+utils.book_append_sheet(workbook, ws, "员工表");
+
+export default () => (
+  <div style={{ height: 320, width: "100%" }}>
+    <Spreadsheet data={workbook} xOptions={{ showBottomTool: true }} />
+  </div>
+);
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| data | 表格数据，xlsx 的 `WorkBook` 对象 | `WorkBook` | - |
+| xOptions | x-data-spreadsheet 配置项（在其 `Options` 基础上扩展，已忽略 `view`） | `XOptions` | `{}` |
+| className | 容器类名 | `string` | - |
+
+### XOptions
+
+继承 x-data-spreadsheet 的 `Options`（`view` 由组件内部接管），并扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| showBottomTool | 是否显示底部工具栏（sheet 切换栏） | `boolean` | `true` |

package/src/components/Spreadsheet/index.module.less

@@ -4,8 +4,8 @@
 
   overflow: hidden;
 
-  .x-spreadsheet-toolbar,
-  .x-spreadsheet-bottombar {
+  :global(.x-spreadsheet-toolbar),
+  :global(.x-spreadsheet-bottombar) {
     width: 100% !important;
   }
 
@@ -13,14 +13,14 @@
     background-size: auto;
   }
 
-  .x-spreadsheet-menu {
+  :global(.x-spreadsheet-menu) {
     > li:first-child {
       display: none;
     }
   }
 
   &.showBottomTool {
-    .x-spreadsheet-menu {
+    :global(.x-spreadsheet-menu) {
       > li:first-child {
         display: list-item;
       }

package/src/components/Switch/index.md

@@ -8,10 +8,42 @@ title: Switch 开关
 
 # Switch 开关
 
-> `Switch` 组件。完整 API 见源码类型定义，下方为基础用法。
+基于 antd `Switch` 封装的开关，可通过 `options` 配合 `trueValue`/`falseValue` 自动生成开启与关闭状态的文案。
 
 ## 引入
 
 ```ts
 import { Switch } from "@hsu-react/ui";
 ```
+
+## 开关
+
+```tsx
+import React from "react";
+import { Switch } from "@hsu-react/ui";
+
+const options = [
+  { label: "启用", value: 1 },
+  { label: "停用", value: 0 },
+];
+
+export default () => (
+  <div style={{ display: "flex", gap: 16, alignItems: "center" }}>
+    <Switch defaultChecked />
+    <Switch options={options} trueValue={1} falseValue={0} defaultChecked />
+    <Switch disabled />
+  </div>
+);
+```
+
+## API
+
+在 [antd SwitchProps](https://ant.design/components/switch-cn) 基础上扩展：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| options | 选项数据，用于匹配选中/未选中文案 | `SelectOption[]` | - |
+| trueValue | 开启状态对应的 value，从 `options` 中取其 `label` 作为 `checkedChildren` | `number \| string` | - |
+| falseValue | 关闭状态对应的 value，从 `options` 中取其 `label` 作为 `unCheckedChildren` | `number \| string` | - |
+
+> 若直接传入 `checkedChildren` / `unCheckedChildren`，则优先使用传入值。

package/src/components/Switch/index.module.less

@@ -0,0 +1,7 @@
+// 让开关在表单/录入场景中与 Input、Select 等控件保持一致的 32px 最小高度。
+// 开关本体（pill）保持原始尺寸，由该容器居中占位，故不会被拉大。
+.SwitchWrapper {
+  display: inline-flex;
+  align-items: center;
+  min-height: 32px;
+}

package/src/components/Switch/index.tsx

@@ -1,6 +1,7 @@
 import { SwitchProps as AntSwitchProps, Switch as AntSwitch } from "antd";
 import React from "react";
 import { SelectOption } from "../Select";
+import styles from "./index.module.less";
 
 export interface SwitchProps extends AntSwitchProps {
   options?: SelectOption[];
@@ -19,17 +20,19 @@ const Switch: React.FC<SwitchProps> = (props) => {
   } = props;
 
   return (
-    <AntSwitch
-      {...rest}
-      checkedChildren={
-        checkedChildren ||
-        options?.find((item) => item.value === trueValue)?.label
-      }
-      unCheckedChildren={
-        unCheckedChildren ||
-        options?.find((item) => item.value === falseValue)?.label
-      }
-    />
+    <span className={styles.SwitchWrapper}>
+      <AntSwitch
+        {...rest}
+        checkedChildren={
+          checkedChildren ||
+          options?.find((item) => item.value === trueValue)?.label
+        }
+        unCheckedChildren={
+          unCheckedChildren ||
+          options?.find((item) => item.value === falseValue)?.label
+        }
+      />
+    </span>
   );
 };
 

package/src/components/TabBar/index.md

@@ -8,10 +8,79 @@ title: TabBar 标签栏
 
 # TabBar 标签栏
 
-> `TabBar` 组件。完整 API 见源码类型定义，下方为基础用法。
+轻量级标签切换栏，支持受控/非受控、`default` 与 `outline` 两种样式，并可结合路由实现页签跳转。
 
 ## 引入
 
 ```ts
 import { TabBar } from "@hsu-react/ui";
 ```
+
+## 默认样式
+
+通过 `tabGroup` 配置页签，`onTabChange` 监听切换。
+
+```tsx
+import React, { useState } from "react";
+import { TabBar } from "@hsu-react/ui";
+
+export default () => {
+  const [tab, setTab] = useState<string | number>("1");
+
+  const tabGroup = [
+    { title: "全部", key: "1" },
+    { title: "进行中", key: "2" },
+    { title: "已完成", key: "3" },
+  ];
+
+  return <TabBar tabGroup={tabGroup} tab={tab} onTabChange={setTab} />;
+};
+```
+
+## 描边样式
+
+`variant="outline"` 渲染为描边胶囊样式。
+
+```tsx
+import React, { useState } from "react";
+import { TabBar } from "@hsu-react/ui";
+
+export default () => {
+  const [tab, setTab] = useState<string | number>("1");
+
+  const tabGroup = [
+    { title: "全部", key: "1" },
+    { title: "进行中", key: "2" },
+    { title: "已完成", key: "3" },
+  ];
+
+  return (
+    <TabBar
+      variant="outline"
+      tabGroup={tabGroup}
+      tab={tab}
+      onTabChange={setTab}
+    />
+  );
+};
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| tabGroup | 页签数据 | `TabGroup[]` | - |
+| tab | 受控选中项的 key | `string \| number` | - |
+| defaultTab | 默认选中项的 key（非受控） | `string \| number` | - |
+| onTabChange | 切换页签时触发 | `(key: string \| number) => void` | - |
+| variant | 样式风格 | `'default' \| 'outline'` | `'default'` |
+| router | 是否在切换时按 key 进行路由跳转 | `boolean` | - |
+| className | 自定义类名 | `string` | - |
+
+`TabGroup` 结构：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| title | 页签标题 | `string` | - |
+| key | 页签唯一标识 | `string \| number` | - |
+| onClick | 点击该页签时的回调 | `() => void` | - |

package/src/components/Table/_components/Pagination/index.module.less

@@ -4,11 +4,11 @@
   justify-content: flex-end;
   column-gap: 8px;
 
-  &.ant-pagination-start {
+  &:global(.ant-pagination-start) {
     justify-content: flex-start;
   }
 
-  &.ant-pagination-center {
+  &:global(.ant-pagination-center) {
     justify-content: center;
   }
 
@@ -25,10 +25,10 @@
       width: 100%;
       height: 100%;
 
-      .ant-pagination-item-container {
+      :global(.ant-pagination-item-container) {
         width: 100%;
 
-        .ant-pagination-item-ellipsis {
+        :global(.ant-pagination-item-ellipsis) {
           width: 100%;
         }
       }
@@ -40,17 +40,17 @@
       justify-content: center;
     }
 
-    &.ant-pagination-options {
-      .ant-pagination-options-size-changer,
-      .ant-pagination-options-quick-jumper {
+    &:global(.ant-pagination-options) {
+      :global(.ant-pagination-options-size-changer),
+      :global(.ant-pagination-options-quick-jumper) {
         height: 100% !important;
       }
 
-      .ant-pagination-options-size-changer {
-        .ant-select-selector {
+      :global(.ant-pagination-options-size-changer) {
+        :global(.ant-select-selector) {
           height: 100% !important;
 
-          .ant-select-selection-item {
+          :global(.ant-select-selection-item) {
             display: flex;
             align-items: center;
 
@@ -58,14 +58,14 @@
           }
         }
 
-        .ant-select-arrow {
+        :global(.ant-select-arrow) {
           margin-top: 0px;
 
           transform: translateY(-50%);
         }
       }
 
-      .ant-pagination-options-quick-jumper {
+      :global(.ant-pagination-options-quick-jumper) {
         display: inline-flex;
         align-items: center;
 
@@ -78,18 +78,18 @@
 
   &.bordered {
     > li {
-      &:not(.ant-pagination-options):not(.ant-pagination-total-text) {
+      &:not(:global(.ant-pagination-options)):not(:global(.ant-pagination-total-text)) {
         border: 1px solid var(--cf-border);
         border-radius: 4px;
       }
 
-      &.ant-pagination-item {
+      &:global(.ant-pagination-item) {
         margin: 0px 4px 0px 0px;
 
-        &:not(.ant-pagination-item-active):not(
-            .ant-pagination-item-disabled
+        &:not(:global(.ant-pagination-item-active)):not(
+            :global(.ant-pagination-item-disabled)
           ):hover,
-        &.ant-pagination-item-active {
+        &:global(.ant-pagination-item-active) {
           background-color: var(--primary-color, #1890ff);
           border-color: var(--primary-color, #1890ff);
 
@@ -98,11 +98,11 @@
           }
         }
 
-        &:not(.ant-pagination-item-active):not(.ant-pagination-item-disabled) {
+        &:not(:global(.ant-pagination-item-active)):not(:global(.ant-pagination-item-disabled)) {
           border-color: var(--cf-border);
         }
 
-        &:not(.ant-pagination-item-active).ant-pagination-item-disabled {
+        &:not(:global(.ant-pagination-item-active)):global(.ant-pagination-item-disabled) {
           cursor: not-allowed;
 
           &:hover {
@@ -117,16 +117,16 @@
         }
       }
 
-      &.ant-pagination-prev {
+      &:global(.ant-pagination-prev) {
         margin-right: 4px;
       }
 
-      &.ant-pagination-options {
+      &:global(.ant-pagination-options) {
         margin-left: 4px;
       }
 
-      &.ant-pagination-jump-next,
-      &.ant-pagination-jump-prev {
+      &:global(.ant-pagination-jump-next),
+      &:global(.ant-pagination-jump-prev) {
         margin-right: 4px;
       }
     }

package/src/components/Table/index.md

@@ -8,10 +8,69 @@ title: Table 表格
 
 # Table 表格
 
-> `Table` 组件。完整 API 见源码类型定义，下方为基础用法。
+在 antd `Table` 之上封装，扩展了自定义列（权限、排序、省略 Tooltip）、内置分页、自动高度、行拖拽、自动滚动等能力。
 
 ## 引入
 
 ```ts
 import { Table } from "@hsu-react/ui";
 ```
+
+## 表格
+
+```tsx
+import React from "react";
+import { Table } from "@hsu-react/ui";
+
+const columns = [
+  { title: "姓名", dataIndex: "name", width: 120 },
+  { title: "年龄", dataIndex: "age", width: 80 },
+  { title: "住址", dataIndex: "address" },
+];
+
+const dataSource = [
+  { key: "1", name: "张三", age: 32, address: "西湖区湖底公园 1 号" },
+  { key: "2", name: "李四", age: 28, address: "滨江区江南大道 100 号" },
+  { key: "3", name: "王五", age: 45, address: "余杭区文一西路 998 号" },
+];
+
+export default () => (
+  <Table columns={columns} dataSource={dataSource} pagination={false} />
+);
+```
+
+## API
+
+在 [antd TableProps](https://ant.design/components/table-cn) 基础上扩展（`scroll`、`pagination`、`columns` 被重写），常用新增/重写属性如下：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| columns | 列配置，使用自定义 `ColumnsType`（支持 `hidden`、`sort`、`hasPermi`、`help`、`mergeRow`、`fixedWidth`、`ellipsisPosition` 等） | `ColumnsType<RecordType>` | `[]` |
+| scroll | 是否开启滚动；`{ y: false }` 可关闭纵向滚动 | `boolean \| { y: boolean }` | `false` |
+| pagination | 分页配置；为 `false` 时不展示分页 | `false \| PaginationProps` | `{}` |
+| autoWidth | 列宽自适应 | `boolean` | - |
+| scrollAutoHeight | 自动计算并撑满可用高度 | `boolean` | `true` |
+| hideScrollbar | 隐藏表头滚动条 | `boolean` | `true` |
+| thPadding | 表头单元格内边距 | `string` | - |
+| tdPadding | 表体单元格内边距 | `string` | - |
+| expandedCellPadding | 展开行单元格内边距 | `string` | `tdPadding` |
+| fillPanel | 撑满父级 Panel 高度 | `boolean` | - |
+| staticDataSource | 使用静态数据源（前端分页） | `boolean` | `false` |
+| serialNumberColumn | 是否展示序号列 | `boolean` | `false` |
+| hideEmpty | 隐藏空数据占位 | `boolean` | `false` |
+| ellipsisTooltipConfig | 文本省略 Tooltip 配置 | `EllipsisTooltipConfig` | - |
+| onDragEnd | 行拖拽结束回调（开启后启用拖拽排序） | `DragProps["onDragEnd"]` | - |
+| autoScrolling | 是否开启内容自动滚动 | `boolean` | - |
+| autoScrollMode | 自动滚动模式 | `'smooth' \| 'row'` | - |
+| autoScrollingSpeed | smooth 模式滚动速度（px/s） | `number` | `25` |
+| autoScrollLoop | 滚动到末尾后是否循环 | `boolean` | `true` |
+| autoScrollLoopMode | 循环模式 | `'reset' \| 'seamless'` | `'reset'` |
+| onScrollEnd | 滚动到底部回调 | `() => void` | - |
+| onAutoScrollEndAdd | 自动滚动到底部时追加数据 | `() => Promise<boolean>` | - |
+| order | 当前排序 | `{ k: string; t: 'asc' \| 'desc' }` | - |
+| onOrderChange | 排序变化回调 | `(order?) => void` | - |
+| sorter | 是否启用排序 | `boolean` | - |
+| showTotal | 自定义分页总数展示；为 `false` 时不展示 | `false \| ((total, range) => ReactNode)` | - |
+| isExpandedCellTable | 是否为展开行内嵌表格样式 | `boolean` | `false` |
+
+> 另导出 `TableDrag`，用于行拖拽排序场景。