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

package/README.md

@@ -1,34 +1,324 @@
-# 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.36",
   "description": "A react library developed with dumi",
   "license": "MIT",
   "main": "lib/cjs/index.js",
@@ -9,7 +9,13 @@
   "types": "lib/esm/index.d.ts",
   "style": "lib/esm/index.css",
   "files": [
-    "lib"
+    "lib/components",
+    "lib/hooks",
+    "lib/utils",
+    "lib/assets",
+    "lib/index.js",
+    "lib/index.d.ts",
+    "lib/global.d.ts"
   ],
   "scripts": {
     "build": "father build",

package/lib/cjs/api/index.d.ts

@@ -1,17 +0,0 @@
-import { commonEesType } from "../utils/request";
-/**
- * 高敏信息解密
- * @returns
- */
-interface SecurityItem {
-    key: string;
-    value: string;
-}
-/**
- * 对数据进行高安全解密处理
- *
- * @param data 需要解密的数据
- * @returns 解密后的数据
- */
-export declare function highSecurity(data: any): Promise<commonEesType<SecurityItem[]>>;
-export {};

package/lib/cjs/api/index.js

@@ -1,45 +0,0 @@
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/api/index.ts
-var api_exports = {};
-__export(api_exports, {
-  highSecurity: () => highSecurity
-});
-module.exports = __toCommonJS(api_exports);
-var import_request = __toESM(require("../utils/request"));
-function highSecurity(data) {
-  return import_request.default.post(
-    "/api/v3/business/game_info/high-security-decrypt?audience=/laas-pnt",
-    data
-  );
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  highSecurity
-});