@next-bricks/presentational-bricks 1.339.1 → 1.339.2

package/docs/brick-value-mapping.md

@@ -0,0 +1,240 @@
+---
+tagName: presentational-bricks.brick-value-mapping
+displayName: WrappedPresentationalBricksBrickValueMapping
+description: 适用于将基本类型的数值转换成有意义的文本进行展示
+category: data-transform
+source: "@next-bricks/presentational-bricks"
+---
+
+# presentational-bricks.brick-value-mapping
+
+> 适用于将基本类型的数值转换成有意义的文本进行展示
+
+## Props
+
+| 属性              | 类型                                                 | 必填 | 默认值  | 说明                                                              |
+| ----------------- | ---------------------------------------------------- | ---- | ------- | ----------------------------------------------------------------- |
+| value             | `string \| number`                                   | -    | -       | 原始值                                                            |
+| fields            | `{     value: string;   }`                           | -    | -       | [已废弃]字段映射, 跟 dataSource 一起使用来获得运行时 value        |
+| mapping           | `Record<     string \| number,     MappingValue   >` | 是   | -       | 映射规则                                                          |
+| showTagCircle     | `boolean`                                            | -    | -       | 显示文字旁边的小圈圈，按照平台规范通常表示状态的标签可设置为 true |
+| dataSource        | `Record<string, any>`                                | -    | -       | 替代 `data` 属性，click 事件时传出的数据                          |
+| triggerClickEvent | `boolean`                                            | -    | `false` | 是否触发点击事件                                                  |
+| isTextEllipsis    | `boolean`                                            | -    | `false` | 文案超出时是否隐藏溢出文本并在鼠标悬停时显示 Tooltip              |
+| link              | `LinkProps`                                          | -    | -       | 配置跳转链接，在 `triggerClickEvent` 为 false 生效                |
+| data              | `any`                                                | -    | -       | [已废弃]可用于接收 useBrick 传递过来的数据                        |
+
+## Events
+
+| 事件                      | detail                                   | 说明                                                  |
+| ------------------------- | ---------------------------------------- | ----------------------------------------------------- |
+| brick-value-mapping.click | `{ data: any; value: string \| number }` | 点击事件，需设置 `triggerClickEvent` 为 true 才会触发 |
+
+## Memo
+
+### 注意
+
+> 如果需要区间的条件规则映射，比如大于、小于等，请使用[条件展示](developers/brick-book/brick/presentational-bricks.brick-conditional-display)
+
+### MappingValue
+
+```typescript
+interface MappingValue {
+  text?: string;
+  color?: Color;
+  icon?: MenuIcon;
+  iconSize?: number;
+}
+```
+
+### LinkProps
+
+```typescript
+interface LinkProps {
+  to?: string;
+  href?: string;
+  innerRef?: string;
+  replace?: boolean;
+  target?: string;
+}
+```
+
+### 映射规则说明
+
+映射支持正则匹配，匹配规则如下：
+
+1. 首先以 `value` 为 key 来获取映射，若成功匹配则使用该规则来展示；若不成功，则走下一步
+2. 将 `映射规则` 中的 key 作为正则，来匹配 `value`, 使用成功匹配的第一个规则
+
+例如
+
+```typescript
+// 以下将展示 `hi`
+const mapping = { hello: { text: "hi" }, ".*": { text: "anything else" } };
+const value = "hello";
+
+// 以下将展示 `anything else`
+const mapping = {
+  www: { text: "world wide web" },
+  ".*": { text: "anything else" },
+};
+const value = "hello";
+```
+
+## Examples
+
+### 基本用法 - 映射为多彩标签（带圆点）
+
+使用 `showTagCircle` 显示状态圆点，通过 `mapping` 将不同值映射为对应的颜色标签。
+
+```yaml
+brick: presentational-bricks.brick-value-mapping
+properties:
+  showTagCircle: true
+  value: success
+  mapping:
+    failed:
+      color: red
+      text: 失败
+    success:
+      color: green
+      text: 正常
+    warning:
+      color: orange
+      text: 异常
+```
+
+### 触发点击事件（填充色标签）
+
+设置 `triggerClickEvent` 为 true 并监听 `brick-value-mapping.click` 事件，同时通过 `dataSource` 传递附加数据。
+
+```yaml
+brick: presentational-bricks.brick-value-mapping
+properties:
+  triggerClickEvent: true
+  showTagCircle: false
+  value: warning
+  dataSource:
+    id: 1001
+    name: 示例数据
+  mapping:
+    warning:
+      color: red-inverse
+      text: 紧急
+    safe:
+      color: green-inverse
+      text: 正常
+events:
+  brick-value-mapping.click:
+    - action: console.log
+      args:
+        - "<% EVENT.detail %>"
+```
+
+### 映射为 icon 加文字
+
+映射结果可以包含图标和文字，通过 `icon` 和 `text` 字段配置。
+
+```yaml
+brick: presentational-bricks.brick-value-mapping
+properties:
+  value: 1
+  mapping:
+    1:
+      text: mapping-text
+      color: green
+      icon:
+        lib: fa
+        icon: link
+```
+
+### 仅映射为 icon（自定义图标大小）
+
+不设置 `text` 时仅展示图标，通过 `iconSize` 自定义图标大小。
+
+```yaml
+brick: presentational-bricks.brick-value-mapping
+properties:
+  value: 2
+  mapping:
+    2:
+      iconSize: 36
+      color: red
+      icon:
+        lib: fa
+        icon: bell
+```
+
+### 正则匹配
+
+当精确匹配不到时，会将 mapping 的 key 作为正则进行匹配，使用第一个匹配成功的规则。
+
+```yaml
+brick: presentational-bricks.brick-value-mapping
+properties:
+  value: hello
+  mapping:
+    ".*":
+      color: orange
+      text: remapping
+      icon:
+        lib: fa
+        icon: star
+    2:
+      iconSize: 36
+      color: red
+      icon:
+        lib: fa
+        icon: bell
+```
+
+### 配置跳转链接
+
+通过 `link` 配置跳转链接，点击标签时会跳转到指定地址。注意 `link` 在 `triggerClickEvent` 为 false 时才生效。
+
+```yaml
+brick: presentational-bricks.brick-value-mapping
+properties:
+  style:
+    display: inline-block
+  value: hello
+  link:
+    to: /developers/brick-book
+  mapping:
+    ".*":
+      color: orange
+      text: remapping
+      icon:
+        lib: fa
+        icon: star
+```
+
+### 文案超出隐藏
+
+设置 `isTextEllipsis` 为 true 时，文案超出容器会隐藏并在鼠标悬停时显示 Tooltip。
+
+```yaml
+brick: presentational-bricks.brick-value-mapping
+properties:
+  style:
+    width: 80px
+  isTextEllipsis: true
+  value: longText
+  mapping:
+    longText:
+      color: blue
+      text: 这是一段非常非常长的文案用于演示超出隐藏效果
+```
+
+### 无匹配时显示原始值
+
+当 value 无法匹配到任何映射规则时，直接显示原始值。
+
+```yaml
+brick: presentational-bricks.brick-value-mapping
+properties:
+  value: 1
+  mapping:
+    0:
+      text: error
+```

package/docs/brick-value-mapping.react.md

@@ -0,0 +1,181 @@
+---
+tagName: presentational-bricks.brick-value-mapping
+displayName: WrappedPresentationalBricksBrickValueMapping
+description: 适用于将基本类型的数值转换成有意义的文本进行展示
+category: data-transform
+source: "@next-bricks/presentational-bricks"
+---
+
+# WrappedPresentationalBricksBrickValueMapping
+
+> 适用于将基本类型的数值转换成有意义的文本进行展示
+
+## 导入
+
+```tsx
+import { WrappedPresentationalBricksBrickValueMapping } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性              | 类型                                                 | 必填 | 默认值  | 说明                                                              |
+| ----------------- | ---------------------------------------------------- | ---- | ------- | ----------------------------------------------------------------- |
+| value             | `string \| number`                                   | -    | -       | 原始值                                                            |
+| fields            | `{     value: string;   }`                           | -    | -       | [已废弃]字段映射, 跟 dataSource 一起使用来获得运行时 value        |
+| mapping           | `Record<     string \| number,     MappingValue   >` | 是   | -       | 映射规则                                                          |
+| showTagCircle     | `boolean`                                            | -    | -       | 显示文字旁边的小圈圈，按照平台规范通常表示状态的标签可设置为 true |
+| dataSource        | `Record<string, any>`                                | -    | -       | 替代 `data` 属性，click 事件时传出的数据                          |
+| triggerClickEvent | `boolean`                                            | -    | `false` | 是否触发点击事件                                                  |
+| isTextEllipsis    | `boolean`                                            | -    | `false` | 文案超出时是否隐藏溢出文本并在鼠标悬停时显示 Tooltip              |
+| link              | `LinkProps`                                          | -    | -       | 配置跳转链接，在 `triggerClickEvent` 为 false 生效                |
+| data              | `any`                                                | -    | -       | [已废弃]可用于接收 useBrick 传递过来的数据                        |
+
+## Events
+
+| 事件                       | detail                                   | 说明                                                  |
+| -------------------------- | ---------------------------------------- | ----------------------------------------------------- |
+| onBrick-value-mappingClick | `{ data: any; value: string \| number }` | 点击事件，需设置 `triggerClickEvent` 为 true 才会触发 |
+
+## Examples
+
+### 基本用法 - 映射为多彩标签（带圆点）
+
+使用 `showTagCircle` 显示状态圆点，通过 `mapping` 将不同值映射为对应的颜色标签。
+
+```tsx
+<WrappedPresentationalBricksBrickValueMapping
+  showTagCircle={true}
+  value="success"
+  mapping={{
+    failed: { color: "red", text: "失败" },
+    success: { color: "green", text: "正常" },
+    warning: { color: "orange", text: "异常" },
+  }}
+/>
+```
+
+### 触发点击事件（填充色标签）
+
+设置 `triggerClickEvent` 为 true 并监听点击事件，同时通过 `dataSource` 传递附加数据。
+
+```tsx
+<WrappedPresentationalBricksBrickValueMapping
+  triggerClickEvent={true}
+  showTagCircle={false}
+  value="warning"
+  dataSource={{ id: 1001, name: "示例数据" }}
+  mapping={{
+    warning: { color: "red-inverse", text: "紧急" },
+    safe: { color: "green-inverse", text: "正常" },
+  }}
+  onBrick-value-mappingClick={(e) => {
+    console.log(e.detail);
+  }}
+/>
+```
+
+### 映射为 icon 加文字
+
+映射结果可以包含图标和文字，通过 `icon` 和 `text` 字段配置。
+
+```tsx
+<WrappedPresentationalBricksBrickValueMapping
+  value={1}
+  mapping={{
+    1: {
+      text: "mapping-text",
+      color: "green",
+      icon: { lib: "fa", icon: "link" },
+    },
+  }}
+/>
+```
+
+### 仅映射为 icon（自定义图标大小）
+
+不设置 `text` 时仅展示图标，通过 `iconSize` 自定义图标大小。
+
+```tsx
+<WrappedPresentationalBricksBrickValueMapping
+  value={2}
+  mapping={{
+    2: {
+      iconSize: 36,
+      color: "red",
+      icon: { lib: "fa", icon: "bell" },
+    },
+  }}
+/>
+```
+
+### 正则匹配
+
+当精确匹配不到时，会将 mapping 的 key 作为正则进行匹配，使用第一个匹配成功的规则。
+
+```tsx
+<WrappedPresentationalBricksBrickValueMapping
+  value="hello"
+  mapping={{
+    ".*": {
+      color: "orange",
+      text: "remapping",
+      icon: { lib: "fa", icon: "star" },
+    },
+    2: {
+      iconSize: 36,
+      color: "red",
+      icon: { lib: "fa", icon: "bell" },
+    },
+  }}
+/>
+```
+
+### 配置跳转链接
+
+通过 `link` 配置跳转链接，点击标签时会跳转到指定地址。注意 `link` 在 `triggerClickEvent` 为 false 时才生效。
+
+```tsx
+<WrappedPresentationalBricksBrickValueMapping
+  style={{ display: "inline-block" }}
+  value="hello"
+  link={{ to: "/developers/brick-book" }}
+  mapping={{
+    ".*": {
+      color: "orange",
+      text: "remapping",
+      icon: { lib: "fa", icon: "star" },
+    },
+  }}
+/>
+```
+
+### 文案超出隐藏
+
+设置 `isTextEllipsis` 为 true 时，文案超出容器会隐藏并在鼠标悬停时显示 Tooltip。
+
+```tsx
+<WrappedPresentationalBricksBrickValueMapping
+  style={{ width: 80 }}
+  isTextEllipsis={true}
+  value="longText"
+  mapping={{
+    longText: {
+      color: "blue",
+      text: "这是一段非常非常长的文案用于演示超出隐藏效果",
+    },
+  }}
+/>
+```
+
+### 无匹配时显示原始值
+
+当 value 无法匹配到任何映射规则时，直接显示原始值。
+
+```tsx
+<WrappedPresentationalBricksBrickValueMapping
+  value={1}
+  mapping={{
+    0: { text: "error" },
+  }}
+/>
+```

package/docs/cost-time.md

@@ -0,0 +1,58 @@
+---
+tagName: presentational-bricks.cost-time
+displayName: WrappedPresentationalBricksCostTime
+description: 耗时展示构件，将毫秒级时间自动转换为人类可读的时间文本（如"15秒"、"1天"），支持直接传入耗时或通过起止时间自动计算
+category:
+source: "@next-bricks/presentational-bricks"
+---
+
+# presentational-bricks.cost-time
+
+> 耗时展示构件，将毫秒级时间自动转换为人类可读的时间文本（如"15 秒"、"1 天"），支持直接传入耗时或通过起止时间自动计算
+
+## Props
+
+| 属性       | 类型                                                                     | 必填 | 默认值 | 说明                                                                         |
+| ---------- | ------------------------------------------------------------------------ | ---- | ------ | ---------------------------------------------------------------------------- |
+| cost       | `number`                                                                 | -    | -      | 消耗时间（毫秒级）                                                           |
+| startTime  | `string \| number`                                                       | -    | -      | 起始时间，与 endTime 配合使用，当未传入 cost 时自动计算耗时                  |
+| endTime    | `string \| number`                                                       | -    | -      | 结束时间，与 startTime 配合使用，当未传入 cost 时自动计算耗时                |
+| unitStyle  | `React.CSSProperties`                                                    | -    | -      | 时间单位文本的自定义样式，设置后将使用自定义渲染逻辑而非默认的 costTime 函数 |
+| dataSource | `any`                                                                    | -    | -      | [已废弃]数据源                                                               |
+| fields     | `{     cost?: string;     startTime?: string;     endTime?: string;   }` | -    | -      | [已废弃]字段映射, 跟 dataSource 一起使用来获得运行时对应字段                 |
+
+## Examples
+
+### Basic
+
+直接传入毫秒级耗时，自动转换为可读文本
+
+```yaml
+brick: presentational-bricks.cost-time
+properties:
+  cost: 123456
+```
+
+### 通过起止时间计算耗时
+
+传入起始时间和结束时间，构件自动计算并展示耗时
+
+```yaml
+brick: presentational-bricks.cost-time
+properties:
+  startTime: 1593603641000
+  endTime: 1593603798000
+```
+
+### Styling
+
+自定义时间单位文本的样式
+
+```yaml
+brick: presentational-bricks.cost-time
+properties:
+  cost: 7265000
+  unitStyle:
+    color: "#999"
+    fontSize: "12px"
+```

package/docs/cost-time.react.md

@@ -0,0 +1,60 @@
+---
+tagName: presentational-bricks.cost-time
+displayName: WrappedPresentationalBricksCostTime
+description: 耗时展示构件，将毫秒级时间自动转换为人类可读的时间文本（如"15秒"、"1天"），支持直接传入耗时或通过起止时间自动计算
+category:
+source: "@next-bricks/presentational-bricks"
+---
+
+# WrappedPresentationalBricksCostTime
+
+> 耗时展示构件，将毫秒级时间自动转换为人类可读的时间文本（如"15 秒"、"1 天"），支持直接传入耗时或通过起止时间自动计算
+
+## 导入
+
+```tsx
+import { WrappedPresentationalBricksCostTime } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性       | 类型                                                                     | 必填 | 默认值 | 说明                                                                         |
+| ---------- | ------------------------------------------------------------------------ | ---- | ------ | ---------------------------------------------------------------------------- |
+| cost       | `number`                                                                 | -    | -      | 消耗时间（毫秒级）                                                           |
+| startTime  | `string \| number`                                                       | -    | -      | 起始时间，与 endTime 配合使用，当未传入 cost 时自动计算耗时                  |
+| endTime    | `string \| number`                                                       | -    | -      | 结束时间，与 startTime 配合使用，当未传入 cost 时自动计算耗时                |
+| unitStyle  | `React.CSSProperties`                                                    | -    | -      | 时间单位文本的自定义样式，设置后将使用自定义渲染逻辑而非默认的 costTime 函数 |
+| dataSource | `any`                                                                    | -    | -      | [已废弃]数据源                                                               |
+| fields     | `{     cost?: string;     startTime?: string;     endTime?: string;   }` | -    | -      | [已废弃]字段映射, 跟 dataSource 一起使用来获得运行时对应字段                 |
+
+## Examples
+
+### Basic
+
+直接传入毫秒级耗时，自动转换为可读文本
+
+```tsx
+<WrappedPresentationalBricksCostTime cost={123456} />
+```
+
+### 通过起止时间计算耗时
+
+传入起始时间和结束时间，构件自动计算并展示耗时
+
+```tsx
+<WrappedPresentationalBricksCostTime
+  startTime={1593603641000}
+  endTime={1593603798000}
+/>
+```
+
+### Styling
+
+自定义时间单位文本的样式
+
+```tsx
+<WrappedPresentationalBricksCostTime
+  cost={7265000}
+  unitStyle={{ color: "#999", fontSize: "12px" }}
+/>
+```