@pnt-team/pnt-component-frontend 0.0.34 → 0.0.35

package/README.md

@@ -1,34 +1,317 @@
-# pnt-component-frontend
+# @pnt-team/pnt-component-frontend
 
-## 项目说明
+PNT 前端业务组件库，基于 [dumi2](https://d.umijs.org/) + [father4](https://github.com/umijs/father) 构建，收敛 PNT 业务项目中高价值的重复组件与 Hook，实现单一来源维护。
 
-### 1. 项目介绍
+## 安装
 
-本项目是基于 dumi2 构建的一款为 PNT 业务场景打造的业务组件库，旨在解决 PNT 项目开发中组件重复开发、风格不统一、兼容性差等问题，显著提升开发效率，降低维护成本。
+```bash
+npm install @pnt-team/pnt-component-frontend
+# 或
+yarn add @pnt-team/pnt-component-frontend
+```
 
-### 2. 快速体验
+### 依赖要求（peerDependencies）
 
-| 环境 | 地址                                     |
-| ---- | ---------------------------------------- |
-| 测试 | <http://component.pnt-dev.intlgame.com/> |
+| 依赖 | 版本要求 | 说明 |
+|------|---------|------|
+| `react` | `>=16.9.0` | React 核心框架 |
+| `react-dom` | `>=16.9.0` | React DOM 渲染 |
+| `tdesign-react` | `>=1.5.0` | UI 组件库（本组件库基于 TDesign 封装） |
 
-### 3. 技术选型
+> ⚠️ 请确保项目中已安装以上依赖，否则组件可能无法正常运行。
 
-- [dumi2](https://d.umijs.org/docs/intro) 组件文档生成与开发调试工具
-- [React](https://react.dev/) 组件开发核心框架
-- [TypeScript](https://www.typescriptlang.org/) 类型安全保障
-- [Scss/CSS modules](https://lesscss.org/) 样式开发方案
-- [ESLint + Prettier](https://prettier.io/) 代码规范与格式化
+## 快速开始
 
-### 4. 相关地址
+```tsx
+import {
+  // 组件
+  PntCopyData,
+  PntImagePreview,
+  PntSecureBox,
+  // Hooks
+  usePagination,
+  useBtnPermission,
+  useHighSecurity,
+  useOsPlatformList,
+} from '@pnt-team/pnt-component-frontend';
+```
 
-- [Git: 组件库仓库](https://git.tencent.com/pnt-web/playernetwork/frontend/pnt-component-frontend/tree/test)
-- [dumi2 官方文档](https://d.umijs.org/guide)
+## 组件一览
+
+### L1 基础展示组件
+
+#### PntCopyData — 数据复制组件
+
+点击触发元素将数据复制到剪贴板，通过 Popup 气泡提示复制结果。优先使用 `navigator.clipboard`，非安全上下文自动降级为 `document.execCommand('copy')`。
+
+**Props：**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `string \| (() => Promise<string>)` | ✅ | 需要复制的数据，支持字符串或异步函数 |
+| `tips` | `(isCopy: boolean, isFail: boolean) => ReactNode` | ✅ | 提示内容渲染函数 |
+| `contentFn` | `(props: { onClick, onMouseLeave }) => ReactNode` | ✅ | 触发元素渲染函数 |
+| `placement` | `PopupPlacement` | ❌ | Popup 弹出位置，默认由 TDesign 决定 |
+| `className` | `string` | ❌ | 自定义类名 |
+
+**示例：**
+
+```tsx
+// 基础用法
+<PntCopyData
+  data="这是一段需要复制的文本"
+  tips={(isCopy, isFail) => (isFail ? '复制失败' : '复制成功')}
+  contentFn={({ onClick, onMouseLeave }) => (
+    <Button onClick={onClick} onMouseLeave={onMouseLeave}>复制</Button>
+  )}
+/>
+
+// 异步获取数据（如从接口获取密码）
+<PntCopyData
+  data={async () => await fetchSecret()}
+  tips={(isCopy, isFail) => (isFail ? '获取失败' : '已复制到剪贴板')}
+  contentFn={({ onClick, onMouseLeave }) => (
+    <Link onClick={onClick} onMouseLeave={onMouseLeave}>查看密码</Link>
+  )}
+/>
+```
+
+---
+
+#### PntImagePreview — 图片预览组件
+
+用于展示上传的图片，支持预览、删除功能和上传状态显示。
+
+**Props：**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `iconUrl` | `string \| undefined` | ✅ | 图片 URL 地址 |
+| `loading` | `boolean` | ✅ | 上传加载状态 |
+| `defaultImg` | `string` | ❌ | 默认图片（不传则使用内置默认图） |
+| `params` | `{ style?: CSSProperties; [key: string]: any }` | ❌ | 自定义扩展参数 |
+| `onRemove` | `(e: any) => void` | ❌ | 删除回调函数 |
+
+**示例：**
+
+```tsx
+<PntImagePreview
+  iconUrl={imageUrl}
+  loading={uploading}
+  defaultImg="/path/to/default.png"
+  params={{ style: { width: '200px', height: '200px' } }}
+  onRemove={handleRemove}
+/>
+```
+
+---
+
+### L2 业务复合组件
+
+#### PntSecureBox — 高敏信息展示组件
+
+统一处理和展示高敏信息，支持脱敏显示和按需获取真实数据。内部集成 `useHighSecurity` Hook，通过接口解锁敏感数据。
+
+**Props：**
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `dataKey` | `string` | ✅ | 高敏信息的唯一标识 key |
+| `dataValue` | `string` | ✅ | 初始显示值（通常为脱敏后的数据） |
+| `env` | `string \| number` | ✅ | 环境标识（如 dev / test / production） |
+| `gameId` | `string \| number` | ✅ | 游戏 ID |
+| `renderDom` | `(content: string) => React.ReactNode` | ✅ | 自定义渲染函数 |
+| `viewText` | `string` | ❌ | 查看按钮文案，默认 `'View'` |
+| `pageId` | `string` | ❌ | 页面 ID（用于操作日志和权限验证） |
+
+**示例：**
+
+```tsx
+<PntSecureBox
+  dataKey="userPhone"
+  dataValue="138****8888"
+  env="production"
+  gameId={12345}
+  renderDom={(content) => <span>{content}</span>}
+  viewText="查看"
+/>
+```
+
+---
+
+### L3 业务 Hooks
+
+#### usePagination — 分页 Hook
+
+维护分页状态，页码/每页条数变化时通过回调通知外部发起请求。`totalCount` 为 0 时返回 `undefined`，可直接条件渲染 `<Pagination>`。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `onPaginationRequest` | `(params: { pageNumber, pageSize }) => void` | 分页变化时的回调，外部在此发起列表请求 |
+
+**返回值：**
+
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| `paginationData` | `{ currentPage, totalCount, totalPage, pageSize }` | 当前分页数据 |
+| `setPaginationData` | `(data: PaginationData) => void` | 回写分页数据（通常由外部请求完成后调用） |
+| `paginationProps` | `PaginationProps \| undefined` | 可直接展开到 `<Pagination {...paginationProps} />` |
+
+**示例：**
+
+```tsx
+const Demo = () => {
+  const [list, setList] = useState([]);
+  const { paginationData, setPaginationData, paginationProps } = usePagination(
+    async ({ pageNumber, pageSize }) => {
+      const res = await fetchList({ page: pageNumber, size: pageSize });
+      setList(res.data.list);
+      setPaginationData((prev) => ({
+        ...prev,
+        currentPage: pageNumber,
+        pageSize,
+        totalCount: res.data.total,
+        totalPage: Math.ceil(res.data.total / pageSize),
+      }));
+    },
+  );
+
+  return (
+    <>
+      <Table data={list} />
+      {paginationProps && <Pagination {...paginationProps} />}
+    </>
+  );
+};
+```
 
-## 上手开发&发布流程
+---
 
-详见：[CONTRIBUTING](./CONTRIBUTING.md)
+#### useBtnPermission — 按钮权限 Hook
 
-## 开发约定
+获取按钮权限处理方式，支持演示游戏判定和无权限兜底配置。零业务侵入：权限列表与演示游戏信息均通过入参注入。
 
-详见：[CONVENTIONS](./CONVENTIONS.md)
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `permissions` | `BtnPermissionMap` | 按钮权限映射 `{ [type]: { [key]: 1 \| -1 \| -2 } }` |
+| `demoGame` | `{ id: number \| string; name: string }` | 演示游戏信息 |
+| `serviceInfo` | `{ serviceType?, serviceName? }` | 当前服务信息 |
+
+**返回值：**
+
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| `btnPermission` | `BtnPermissionMap` | 权限映射原文 |
+| `isDemoGame` | `boolean` | 是否为演示游戏 |
+| `getBtnPermission` | `(type, key, defaultValue?) => 1 \| -1 \| -2` | 获取按钮权限（1 有权限 / -1 隐藏 / -2 禁用） |
+
+**示例：**
+
+```tsx
+const Demo = ({ btnPermission, userInfo }) => {
+  const { isDemoGame, getBtnPermission } = useBtnPermission({
+    permissions: btnPermission,
+    demoGame: userInfo?.demoGame,
+    serviceInfo: { serviceType: userInfo?.serviceType, serviceName: userInfo?.serviceName },
+  });
+
+  const createPerm = getBtnPermission('global', 'create');
+  if (createPerm === -1) return null; // 隐藏
+  return <Button disabled={createPerm === -2}>新建{isDemoGame ? '（演示）' : ''}</Button>;
+};
+```
+
+---
+
+#### useHighSecurity — 高敏数据解锁 Hook
+
+管理高敏数据的解锁状态，通过接口请求获取真实数据。配合 `PntSecureBox` 组件使用。
+
+**返回值：**
+
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| `securityData` | `object` | 已解锁的高敏数据映射 `{ [key]: value }` |
+| `setSecurityData` | `(data: object) => void` | 手动设置已解锁数据 |
+| `requestSecurityData` | `({ gameId, param, env }) => void` | 请求解锁指定高敏数据 |
+
+---
+
+#### useOsPlatformList — OS/平台列表 Hook
+
+拉取 OS 与平台枚举数据并做模块级缓存，整个会话只请求一次，并发调用共享同一请求。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `fetcher` | `() => Promise<{ code, msg, data }>` | 自定义请求函数（不传则使用内置默认 fetcher） |
+
+**返回值：**
+
+| 返回值 | 类型 | 说明 |
+|--------|------|------|
+| `osPlatformList` | `{ os_list: OsItem[]; platform_list: PlatformItem[] } \| undefined` | OS/平台数据 |
+
+**示例：**
+
+```tsx
+// 使用默认 fetcher
+const { osPlatformList } = useOsPlatformList();
+
+// 注入自定义 fetcher
+const { osPlatformList } = useOsPlatformList(() => http.get('/my/os/platform'));
+
+// 渲染下拉选项
+<Select
+  options={osPlatformList?.platform_list.map((p) => ({
+    label: p.platform_name_zh,
+    value: p.id,
+  }))}
+/>
+```
+
+> 💡 如需强制刷新缓存，可调用 `clearOsPlatformListCache()` 清除全部缓存，或传入指定 fetcher 清除对应缓存。
+
+---
+
+## 本地开发
+
+```bash
+# 克隆仓库 & 安装依赖
+git clone <repo-url>
+cd pnt-component-frontend
+yarn install
+
+# 启动文档开发服务器
+yarn start
+
+# 构建组件库（lib/ 目录）
+yarn build
+
+# 运行测试
+yarn test
+```
+
+> 📝 本地开发涉及接口调试时，需手动更新 `src/configs/token.ts` 中的 token 值。
+
+## 技术栈
+
+| 工具 | 用途 |
+|------|------|
+| [father4](https://github.com/umijs/father) | 组件库构建（ESM / CJS / UMD） |
+| [dumi2](https://d.umijs.org/) | 文档生成与开发调试 |
+| [TDesign React](https://tdesign.tencent.com/react) | UI 组件库（peerDependency） |
+| TypeScript | 类型安全 |
+| Sass | 样式方案 |
+| Jest | 单元测试 |
+
+## 相关资源
+
+- [Git 仓库](https://git.tencent.com/pnt-web/playernetwork/frontend/pnt-component-frontend/tree/test)
+- [dumi2 官方文档](https://d.umijs.org/guide)
+- [father 官方文档](https://github.com/umijs/father/blob/master/docs/config.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnt-team/pnt-component-frontend",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "description": "A react library developed with dumi",
   "license": "MIT",
   "main": "lib/cjs/index.js",