@pnt-team/pnt-component-frontend 0.0.91 → 0.0.92
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +127 -54
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
PNT 前端业务组件库，基于 [dumi2](https://d.umijs.org/) + [father4](https://github.com/umijs/father) 构建，收敛 PNT 业务项目中高价值的重复组件与 Hook，实现单一来源维护。
|
|
4
4
|
|
|
5
|
+
> 当前版本：**0.0.91** · 组件清单：`PntImage` / `PntBusinessSelect` / `PntSecureBox` / `PntGeneralLayout`
|
|
6
|
+
|
|
5
7
|
## 安装
|
|
6
8
|
|
|
7
9
|
```bash
|
|
@@ -12,11 +14,12 @@ yarn add @pnt-team/pnt-component-frontend
|
|
|
12
14
|
|
|
13
15
|
### 依赖要求（peerDependencies）
|
|
14
16
|
|
|
15
|
-
| 依赖
|
|
16
|
-
|
|
|
17
|
-
| `react`
|
|
18
|
-
| `react-dom`
|
|
19
|
-
| `tdesign-react`
|
|
17
|
+
| 依赖 | 版本要求 | 说明 |
|
|
18
|
+
| --------------------- | ---------- | -------------------------------------- |
|
|
19
|
+
| `react` | `>=16.9.0` | React 核心框架 |
|
|
20
|
+
| `react-dom` | `>=16.9.0` | React DOM 渲染 |
|
|
21
|
+
| `tdesign-react` | `>=1.5.0` | UI 组件库（本组件库基于 TDesign 封装） |
|
|
22
|
+
| `tdesign-icons-react` | `>=0.2.0` | TDesign 图标库 |
|
|
20
23
|
|
|
21
24
|
> ⚠️ 请确保项目中已安装以上依赖，否则组件可能无法正常运行。
|
|
22
25
|
|
|
@@ -36,12 +39,15 @@ import http from '你的项目中的 axios 实例';
|
|
|
36
39
|
```tsx
|
|
37
40
|
import {
|
|
38
41
|
// L1 基础展示组件
|
|
39
|
-
|
|
42
|
+
PntImage,
|
|
40
43
|
// L2 业务复合组件
|
|
41
44
|
PntBusinessSelect,
|
|
42
45
|
PntSecureBox,
|
|
43
46
|
// L3 布局组件
|
|
44
47
|
PntGeneralLayout,
|
|
48
|
+
// 配置
|
|
49
|
+
PntProvider,
|
|
50
|
+
usePntConfig,
|
|
45
51
|
} from '@pnt-team/pnt-component-frontend';
|
|
46
52
|
```
|
|
47
53
|
|
|
@@ -49,29 +55,56 @@ import {
|
|
|
49
55
|
|
|
50
56
|
### L1 基础展示组件
|
|
51
57
|
|
|
52
|
-
####
|
|
58
|
+
#### PntImage — 业务图片组件
|
|
53
59
|
|
|
54
|
-
|
|
60
|
+
统一的业务图片组件，单一组件通过 `onRemove` 是否传入自适应「上传预览」与「纯预览」两种模式，避免业务侧维护两套组件（原 UploadImageViewer + BasicImageViewer）。
|
|
55
61
|
|
|
56
62
|
**Props：**
|
|
57
63
|
|
|
58
|
-
| 属性 | 类型
|
|
59
|
-
| ------------ |
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `defaultImg` | `string`
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
64
|
+
| 属性 | 类型 | 必填 | 默认值 | 说明 |
|
|
65
|
+
| ------------ | ------------------------------------ | :--: | -------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
66
|
+
| `src` | `string \| undefined` | ✅ | - | 图片 URL；为空则展示 defaultImg 或内置 uploadImg |
|
|
67
|
+
| `alt` | `string` | ❌ | `''` | alt 文本，纯预览模式建议传入以提升可访问性 |
|
|
68
|
+
| `defaultImg` | `string` | ❌ | 内置 uploadImg | 默认图片（仅上传预览模式生效） |
|
|
69
|
+
| `style` | `React.CSSProperties` | ❌ | - | 自定义样式（一般用于控制宽高） |
|
|
70
|
+
| `loading` | `boolean` | ❌ | `false` | 上传中状态（仅上传预览模式生效） |
|
|
71
|
+
| `onRemove` | `(e: any) => void` | ❌ | - | 删除回调（传入即启用上传预览模式） |
|
|
72
|
+
| `container` | `HTMLElement \| (() => HTMLElement)` | ❌ | - | attach 容器（弹窗场景需要，透传给 tdesign ImageViewer） |
|
|
73
|
+
| `texts` | `PntImageTexts` | ❌ | `{ uploading: '上传中', loading: '加载中', loadFailed: '加载失败' }` | 多语言文案，传入字段覆盖默认中文 |
|
|
74
|
+
|
|
75
|
+
**模式判定规则：**
|
|
76
|
+
|
|
77
|
+
| 模式 | 触发条件 | mask 行为 | loading 占位 | defaultImg | error 占位 |
|
|
78
|
+
| ------------ | --------------- | ------------------------ | ----------------------- | :--------: | ---------- |
|
|
79
|
+
| 上传预览模式 | 传入 `onRemove` | 预览按钮 + 分隔线 + 删除 | "上传中"（LoadingIcon） | ✅ | 不显示 |
|
|
80
|
+
| 纯预览模式 | 不传 `onRemove` | 半透明遮罩 + 点击预览 | "加载中"（ImageIcon） | ❌ | "加载失败" |
|
|
65
81
|
|
|
66
82
|
**示例：**
|
|
67
83
|
|
|
68
84
|
```tsx
|
|
69
|
-
|
|
70
|
-
|
|
85
|
+
// 上传预览模式
|
|
86
|
+
<PntImage
|
|
87
|
+
src={iconUrl}
|
|
71
88
|
loading={uploading}
|
|
72
89
|
defaultImg="/path/to/default.png"
|
|
73
|
-
params={{ style: { width: '200px', height: '200px' } }}
|
|
74
90
|
onRemove={handleRemove}
|
|
91
|
+
style={{ width: 136, height: 136 }}
|
|
92
|
+
/>
|
|
93
|
+
|
|
94
|
+
// 纯预览模式
|
|
95
|
+
<PntImage
|
|
96
|
+
src={url}
|
|
97
|
+
alt="avatar"
|
|
98
|
+
style={{ width: 60, height: 60 }}
|
|
99
|
+
container={dialogContainer}
|
|
100
|
+
/>
|
|
101
|
+
|
|
102
|
+
// 多语言
|
|
103
|
+
<PntImage
|
|
104
|
+
src={url}
|
|
105
|
+
alt="avatar"
|
|
106
|
+
style={{ width: 60, height: 60 }}
|
|
107
|
+
texts={{ loading: 'Loading', loadFailed: 'Failed' }}
|
|
75
108
|
/>
|
|
76
109
|
```
|
|
77
110
|
|
|
@@ -81,23 +114,42 @@ import {
|
|
|
81
114
|
|
|
82
115
|
#### PntBusinessSelect — 业务选择器组件
|
|
83
116
|
|
|
84
|
-
统一业务下拉选择器，内置对接后端通用接口 `/api/business/select/list
|
|
117
|
+
统一业务下拉选择器，内置对接后端通用接口 `/api/business/select/list`，支持远程搜索、滚动分页加载、多选、场景化禁用（合规场景 `creatable` 字段）。
|
|
118
|
+
|
|
119
|
+
替代此前 5 个分散的业务 select 接口（`game/list`、`game/list_option`、`compliance-age/game/list`、`biz-list-with-creatable-state`、`sdk_customize/game_list`）。
|
|
85
120
|
|
|
86
121
|
**Props：**
|
|
87
122
|
|
|
88
|
-
| 属性
|
|
89
|
-
|
|
|
90
|
-
| `value`
|
|
91
|
-
| `onChange`
|
|
92
|
-
| `multiple`
|
|
93
|
-
| `scene`
|
|
94
|
-
| `statuses`
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
123
|
+
| 属性 | 类型 | 必填 | 默认值 | 说明 |
|
|
124
|
+
| ---------------------- | ----------------------------------------------------------- | :--: | ----------- | ----------------------------------------------------------------------------------- |
|
|
125
|
+
| `value` | `string \| string[]` | ❌ | - | 当前选中值；单选为 string，多选为 string[] |
|
|
126
|
+
| `onChange` | `(value, context) => void` | ❌ | - | 值变化回调；context.selectedOptions 返回纯业务数据对象 |
|
|
127
|
+
| `multiple` | `boolean` | ❌ | `false` | 是否多选 |
|
|
128
|
+
| `scene` | `'default' \| 'sdk' \| 'compliance_age' \| 'custom_region'` | ❌ | `'default'` | 下拉场景；后端按场景返回默认字段集 |
|
|
129
|
+
| `statuses` | `number[]` | ❌ | - | 业务状态筛选（3-线上运营, 4-接入中, 5-中途结项, 6-已下线） |
|
|
130
|
+
| `businessTypes` | `number[]` | ❌ | - | 业务类型筛选（1-正式业务, 2-测试业务） |
|
|
131
|
+
| `businessAccessMethod` | `number` | ❌ | - | 业务接入类型筛选（1-纯 SDK, 2-LI PASS, 3-工作室品牌账号） |
|
|
132
|
+
| `labelFormat` | `'name' \| 'name_en' \| 'name_id' \| 'name_en_id'` | ❌ | `'name'` | 标签格式 |
|
|
133
|
+
| `labelField` | `string` | ❌ | - | 自定义 label 字段（消费方接口返回字段非标准 name/name_en 时使用） |
|
|
134
|
+
| `optionLabel` | `(item) => ReactNode` | ❌ | - | 自定义选项 label 渲染；优先级高于 labelFormat/labelField |
|
|
135
|
+
| `placeholder` | `string` | ❌ | - | 占位提示文案 |
|
|
136
|
+
| `disabled` | `boolean` | ❌ | `false` | 是否禁用整个选择器 |
|
|
137
|
+
| `clearable` | `boolean` | ❌ | `true` | 是否可清除 |
|
|
138
|
+
| `filterable` | `boolean` | ❌ | `true` | 是否可远程搜索 |
|
|
139
|
+
| `max` | `number` | ❌ | - | 多选时最大可选数量 |
|
|
140
|
+
| `pageSize` | `number` | ❌ | `20` | 每页条数 |
|
|
141
|
+
| `searchDebounce` | `number` | ❌ | `400` | 搜索防抖延迟（毫秒） |
|
|
142
|
+
| `minCollapsedNum` | `number` | ❌ | - | 多选时最少折叠数量；透传至 TDesign Select |
|
|
143
|
+
| `collapsedItems` | `TdSelectProps['collapsedItems']` | ❌ | - | 折叠项自定义渲染；透传至 TDesign Select |
|
|
144
|
+
| `popupProps` | `Partial<TdSelectProps['popupProps']>` | ❌ | - | 弹层属性透传；与内部 onScrollToBottom 合并；常用 attach、overlayClassName |
|
|
145
|
+
| `fields` | `string[]` | ❌ | - | 字段白名单，传给后端 fields 参数；未传时后端按 scene 返回默认字段 |
|
|
146
|
+
| `pagination` | `boolean` | ❌ | `true` | 是否分页；false 时一次性加载全量数据，不远程搜索 |
|
|
147
|
+
| `onLoaded` | `(options) => void` | ❌ | - | 选项加载完成回调；不分页模式下首屏即全量，可复用此数据避免重复请求 |
|
|
148
|
+
| `optionDisabled` | `(item) => boolean` | ❌ | - | 自定义选项禁用逻辑；与合规场景 creatable 判断叠加（任一为 true 即禁用） |
|
|
149
|
+
| `optionTooltip` | `(item) => string` | ❌ | - | 自定义选项 tooltip 内容；返回非空字符串时该选项悬停显示 tooltip，常用于解释禁用原因 |
|
|
150
|
+
| `tooltipPlacement` | `'top' \| 'bottom' \| 'left' \| 'right'` | ❌ | `'top'` | tooltip 位置 |
|
|
151
|
+
| `className` | `string` | ❌ | - | 自定义类名 |
|
|
152
|
+
| `style` | `React.CSSProperties` | ❌ | - | 自定义样式 |
|
|
101
153
|
|
|
102
154
|
**示例：**
|
|
103
155
|
|
|
@@ -111,6 +163,15 @@ import { PntBusinessSelect } from '@pnt-team/pnt-component-frontend';
|
|
|
111
163
|
value={gameId}
|
|
112
164
|
onChange={(v) => setGameId(v as string)}
|
|
113
165
|
/>;
|
|
166
|
+
|
|
167
|
+
// 多选 + 状态过滤
|
|
168
|
+
<PntBusinessSelect
|
|
169
|
+
multiple
|
|
170
|
+
statuses={[3, 4]}
|
|
171
|
+
labelFormat="name_id"
|
|
172
|
+
value={gameIds}
|
|
173
|
+
onChange={(v) => setGameIds(v as string[])}
|
|
174
|
+
/>;
|
|
114
175
|
```
|
|
115
176
|
|
|
116
177
|
---
|
|
@@ -121,15 +182,15 @@ import { PntBusinessSelect } from '@pnt-team/pnt-component-frontend';
|
|
|
121
182
|
|
|
122
183
|
**Props：**
|
|
123
184
|
|
|
124
|
-
| 属性 | 类型 | 必填 | 说明
|
|
125
|
-
| ----------- | -------------------------------------- |
|
|
126
|
-
| `dataKey` | `string` |
|
|
127
|
-
| `dataValue` | `string` |
|
|
128
|
-
| `env` | `string \| number` |
|
|
129
|
-
| `gameId` | `string \| number` |
|
|
130
|
-
| `renderDom` | `(content: string) => React.ReactNode` |
|
|
131
|
-
| `viewText` | `string` |
|
|
132
|
-
| `pageId` | `string` |
|
|
185
|
+
| 属性 | 类型 | 必填 | 默认值 | 说明 |
|
|
186
|
+
| ----------- | -------------------------------------- | :--: | ------------------- | ------------------------------------------------------------ |
|
|
187
|
+
| `dataKey` | `string` | ✅ | - | 高敏信息的唯一标识 key，用于缓存真实值 |
|
|
188
|
+
| `dataValue` | `string` | ✅ | - | 初始显示值，通常为脱敏后的数据（含 `_high_security_:` 前缀） |
|
|
189
|
+
| `env` | `string \| number` | ✅ | - | 环境标识（如 dev / test / production） |
|
|
190
|
+
| `gameId` | `string \| number` | ✅ | - | 游戏 / 业务 ID |
|
|
191
|
+
| `renderDom` | `(content: string) => React.ReactNode` | ✅ | - | 自定义渲染函数，参数为当前显示内容（真实值或脱敏值） |
|
|
192
|
+
| `viewText` | `string` | ❌ | `'View'` | 查看按钮文案 |
|
|
193
|
+
| `pageId` | `string` | ❌ | `location.pathname` | 页面 ID，用于操作日志和权限验证 |
|
|
133
194
|
|
|
134
195
|
**示例：**
|
|
135
196
|
|
|
@@ -152,22 +213,26 @@ import { PntSecureBox } from '@pnt-team/pnt-component-frontend';
|
|
|
152
213
|
|
|
153
214
|
#### PntGeneralLayout — 通用页面布局组件
|
|
154
215
|
|
|
155
|
-
提供标准的「头部 + 子头部 + 内容区 + 底部」页面布局结构，基于 TDesign Layout
|
|
216
|
+
提供标准的「头部 + 子头部 + 内容区 + 底部」页面布局结构，基于 TDesign Layout（flex column）封装，内容区自动填满剩余高度并独立滚动，适用于后台管理系统的列表页、详情页、表单页等场景。
|
|
156
217
|
|
|
157
218
|
**Props：**
|
|
158
219
|
|
|
159
|
-
| 属性 | 类型 | 必填 | 默认值
|
|
160
|
-
| ------------------- | --------------------- |
|
|
161
|
-
| `className` | `string` |
|
|
162
|
-
| `headerTitle` | `ReactNode` |
|
|
163
|
-
| `showBackButton` | `boolean` |
|
|
164
|
-
| `onBackButtonClick` | `() => void` |
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
220
|
+
| 属性 | 类型 | 必填 | 默认值 | 说明 |
|
|
221
|
+
| ------------------- | --------------------- | :--: | --------- | ---------------------------------------------------------------------------------- |
|
|
222
|
+
| `className` | `string` | ❌ | - | 自定义类名，追加到根元素，常用于页面级样式覆写 |
|
|
223
|
+
| `headerTitle` | `ReactNode` | ❌ | - | 头部标题内容，传入后渲染 Header 区域 |
|
|
224
|
+
| `showBackButton` | `boolean` | ❌ | `false` | 是否显示返回按钮 |
|
|
225
|
+
| `onBackButtonClick` | `() => void` | ❌ | - | 返回按钮点击回调 |
|
|
226
|
+
| `headerBordered` | `boolean` | ❌ | `true` | 是否显示头部底部分割线 |
|
|
227
|
+
| `subHeaderContent` | `ReactNode` | ❌ | - | 子头部内容，位于 Header 下方 |
|
|
228
|
+
| `operation` | `ReactNode` | ❌ | - | 头部右侧操作区，常用于放置按钮组 |
|
|
229
|
+
| `bodyRef` | `Ref<HTMLDivElement>` | ❌ | - | 内容区 ref 引用 |
|
|
230
|
+
| `bodyStyle` | `CSSProperties` | ❌ | - | 内容区自定义样式（内边距、圆角建议优先使用 bodyPadding / cardRadius） |
|
|
231
|
+
| `bodyPadding` | `number \| string` | ❌ | `24` | 内容区内边距；数字按 px 处理，全出血内容可传 `'24px 0'` |
|
|
232
|
+
| `cardRadius` | `number` | ❌ | `4` | 内容区卡片圆角（px），联动 t-card 及其 body |
|
|
233
|
+
| `footerButton` | `'fixed' \| 'auto'` | ❌ | `'fixed'` | fixed：底部按钮统一 36px 高 / 92px 最小宽 / 加粗；auto：不约束按钮尺寸，仅保留间距 |
|
|
234
|
+
| `footer` | `ReactNode` | ❌ | - | 底部内容，传入后渲染 Footer 区域 |
|
|
235
|
+
| `children` | `ReactNode` | ❌ | - | 页面主体内容 |
|
|
171
236
|
|
|
172
237
|
**示例：**
|
|
173
238
|
|
|
@@ -204,6 +269,14 @@ import { PntSecureBox } from '@pnt-team/pnt-component-frontend';
|
|
|
204
269
|
>
|
|
205
270
|
<Detail />
|
|
206
271
|
</PntGeneralLayout>
|
|
272
|
+
|
|
273
|
+
// 适配项目风格（无头部边线 / 全出血内容 / 大圆角卡片 / 底部按钮自适应）
|
|
274
|
+
<PntGeneralLayout
|
|
275
|
+
headerBordered={false}
|
|
276
|
+
bodyPadding="24px 0"
|
|
277
|
+
cardRadius={8}
|
|
278
|
+
footerButton="auto"
|
|
279
|
+
/>
|
|
207
280
|
```
|
|
208
281
|
|
|
209
282
|
---
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pnt-team/pnt-component-frontend",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.0.92",
|
|
4
|
+
"description": "PNT 前端业务组件库 — 提供 PntImage（图片预览/上传）、PntBusinessSelect（业务选择器）、PntSecureBox（高敏信息展示）、PntGeneralLayout（通用布局）等组件",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"exports": {
|
|
7
7
|
".": {
|