refactor(Statistic): change color attribute type to string and update docs description (#3671)

* refactor(Statistic): change color attribute type to string and update docs description

* test(Statistic): add tests for trend increase and decrease icons

* chore: update snapshot

* feat(Statistic): add color prop tests and update documentation for color styles

* fix(tests): update import path for COLOR_MAP in Statistic tests

* test(Statistic): refactor colorKeys test to check style attribute instead of contentStyle

* chore: update snapshot

* chore: update settings.json

* docs: 更新颜色风格描述，明确支持深浅色模式切换

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 2 people

src/statistic/__tests__/index.test.jsx

@@ -1,5 +1,6 @@
 import { mount } from '@vue/test-utils';
 import Statistic from '@/src/statistic/index.ts';
+import { COLOR_MAP } from '../../_common/js/statistic/utils';
 
 describe('Statistic', () => {
   describe(':props', () => {
@@ -110,5 +111,48 @@ describe('Statistic', () => {
       expect(trendIconElement.exists()).toBe(true);
       expect(trendIconElement.is('svg')).toBe(true);
     });
+
+    it('color:#ff0000', () => {
+      const wrapper = mount(Statistic, {
+        propsData: {
+          title: 'Total Sales',
+          value: 1000,
+          color: '#ff0000',
+        },
+      });
+
+      const contentElement = wrapper.find('.t-statistic-content');
+      expect(contentElement.exists()).toBe(true);
+      expect(contentElement.attributes('style')).toContain('color: rgb(255, 0, 0)');
+    });
+
+    it('color:yellow', () => {
+      const wrapper = mount(Statistic, {
+        propsData: {
+          title: 'Total Sales',
+          value: 1000,
+          color: 'yellow',
+        },
+      });
+
+      const contentElement = wrapper.find('.t-statistic-content');
+      expect(contentElement.exists()).toBe(true);
+      expect(contentElement.attributes('style')).toContain('color: yellow');
+    });
+
+    it('colors: colorKeys', async () => {
+      Object.keys(COLOR_MAP).forEach((color) => {
+        const wrapper = mount(Statistic, {
+          propsData: {
+            value: 1000,
+            color,
+          },
+        });
+
+        const contentElement = wrapper.find('.t-statistic-content');
+        expect(contentElement.exists()).toBe(true);
+        expect(contentElement.attributes('style')).toContain(`color: ${COLOR_MAP[color]}`);
+      });
+    });
   });
 });

src/statistic/props.ts

@@ -14,13 +14,10 @@ export default {
   },
   /** 是否开始动画 */
   animationStart: Boolean,
-  /** 颜色风格，依次为 TDesign 风格的黑色、蓝色、红色、橙色、绿色。也可以为任何 [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) 支持的 RGB 等值 */
+  /** 颜色风格，预设五个 TDesign 颜色风格：黑色（black）、蓝色（blue）、红色（red）、橙色（orange）、绿色（green）支持深浅色模式切换。也可以自定义任何 [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) 支持颜色值，深浅色模式切换需自行适配 */
   color: {
-    type: String as PropType<TdStatisticProps['color']>,
-    validator(val: TdStatisticProps['color']): boolean {
-      if (!val) return true;
-      return ['black', 'blue', 'red', 'orange', 'green'].includes(val);
-    },
+    type: String,
+    default: '',
   },
   /** 小数保留位数 */
   decimalPlaces: {
@@ -40,7 +37,7 @@ export default {
   prefix: {
     type: [String, Function] as PropType<TdStatisticProps['prefix']>,
   },
-  /** 默认展示进位分隔符，可以自定义为其他内容，`separator = ''` 设置为空字符串/null/undefined 时隐藏分隔符 */
+  /** 默认展示千位分隔符，可以自定义为其他内容，`separator = ''` 设置为空字符串/null/undefined 时展示默认分隔符 */
   separator: {
     type: String,
     default: ',',

src/statistic/statistic.en-US.md

@@ -1,22 +1,29 @@
 :: BASE_DOC ::
 
 ## API
+
 ### Statistic Props
 
 name | type | default | description | required
 -- | -- | -- | -- | --
 animation | Object | - | Animation effect control, `duration` refers to the transition time of the animation `unit: millisecond`, `valueFrom` refers to the initial value of the animation. `{ duration, valueFrom }`。Typescript：`animation` `interface animation { duration: number; valueFrom: number;  }`。[see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/statistic/type.ts) | N
 animationStart | Boolean | false | Whether to start animation | N
-color | String | - | Color style, followed by TDesign style black, blue, red, orange, green.Can also be any RGB equivalent supported by [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)。options：black/blue/red/orange/green | N
+color | String | - | The color style can support TDesign's light and dark modes with the following options: black, blue, red, orange, and green. Alternatively, it can be any [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) value, but in this case, TDesign's light and dark modes will not be supported. | N
 decimalPlaces | Number | - |  Decimal places | N
 extra | String / Slot / Function | - |  Additional display content。Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 format | Function | - | Format numeric display value。Typescript：`(value: number) => number` | N
 loading | Boolean | false | Loading | N
 prefix | String / Slot / Function | - | Prefix content, display priority is higher than trend。Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
-separator | String | , | The carry separator is displayed by default, and can be customized to other content. When `separator = ''` is set to an empty string/null/undefined, the separator is hidden | N
+separator | String | , | Thousands separator is displayed by default, and can be customized to other content, and the default separator is displayed when `separator = ''` is set to an empty string/null/undefined | N
 suffix | String / Slot / Function | - |  Suffix content, display priority is higher than trend。Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 title | String / Slot / Function | - | The title of Statistic。Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
-trend | String | - | trend。options：increase/decrease | N
-trendPlacement | String | left | Position of trending placements。options：left/right | N
+trend | String | - | trend。options: increase/decrease | N
+trendPlacement | String | left | Position of trending placements。options: left/right | N
 unit | String / Slot / Function | - | Unit content。Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 value | Number | - | The value of Statistic | N
+
+### StatisticInstanceFunctions 组件实例方法
+
+name | params | return | description
+-- | -- | -- | --
+start | \- | \- | required。start animation

src/statistic/statistic.md

@@ -1,22 +1,29 @@
 :: BASE_DOC ::
 
 ## API
+
 ### Statistic Props
 
-名称 | 类型 | 默认值 | 说明 | 必传
+名称 | 类型 | 默认值 | 描述 | 必传
 -- | -- | -- | -- | --
 animation | Object | - | 动画效果控制，`duration` 指动画的过渡时间`单位：毫秒`，`valueFrom` 指动画的起始数值。`{ duration, valueFrom }`。TS 类型：`animation` `interface animation { duration: number; valueFrom: number;  }`。[详细类型定义](https://github.com/Tencent/tdesign-vue/tree/develop/src/statistic/type.ts) | N
 animationStart | Boolean | false | 是否开始动画 | N
-color | String | - | 颜色风格，依次为 TDesign 风格的黑色、蓝色、红色、橙色、绿色。也可以为任何 [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) 支持的 RGB 等值。可选项：black/blue/red/orange/green | N
+color | String | - | 颜色风格，预设五个 TDesign 颜色风格：黑色（black）、蓝色（blue）、红色（red）、橙色（orange）、绿色（green）支持深浅色模式切换。也可以自定义任何 [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) 支持颜色值，深浅色模式切换需自行适配 | N
 decimalPlaces | Number | - | 小数保留位数 | N
 extra | String / Slot / Function | - | 额外的显示内容。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 format | Function | - | 格式化数值显示值。TS 类型：`(value: number) => number` | N
 loading | Boolean | false | 是否加载中 | N
 prefix | String / Slot / Function | - | 前缀内容，展示优先级高于 trend。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
-separator | String | , | 默认展示进位分隔符，可以自定义为其他内容，`separator = ''` 设置为空字符串/null/undefined 时隐藏分隔符 | N
+separator | String | , | 默认展示千位分隔符，可以自定义为其他内容，`separator = ''` 设置为空字符串/null/undefined 时展示默认分隔符 | N
 suffix | String / Slot / Function | - | 后缀内容，展示优先级高于 trend。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 title | String / Slot / Function | - | 数值显示的标题。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 trend | String | - | 趋势。可选项：increase/decrease | N
 trendPlacement | String | left | 趋势展示位置。可选项：left/right | N
 unit | String / Slot / Function | - | 单位内容。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 value | Number | - | 数值显示的值 | N
+
+### StatisticInstanceFunctions 组件实例方法
+
+名称 | 参数 | 返回值 | 描述
+-- | -- | -- | --
+start | \- | \- | 必需。开始动画

src/statistic/statistic.tsx

@@ -30,7 +30,7 @@ export default defineComponent({
     const tween = ref(null);
 
     const numberValue = computed(() => (isNumber(props.value) ? props.value : 0));
-    const valueStyle = computed(() => ({ color: COLOR_MAP[color.value] || color.value }));
+    const valueStyle = computed(() => ({ color: COLOR_MAP[color.value as keyof typeof COLOR_MAP] || color.value }));
     const innerDecimalPlaces = computed(
       () => decimalPlaces.value ?? numberValue.value.toString().split('.')[1]?.length ?? 0,
     );

src/statistic/type.ts

@@ -17,9 +17,10 @@ export interface TdStatisticProps {
    */
   animationStart?: boolean;
   /**
-   * 颜色风格，依次为 TDesign 风格的黑色、蓝色、红色、橙色、绿色。也可以为任何 [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) 支持的 RGB 等值
+   * 颜色风格，预设五个 TDesign 颜色风格：黑色（black）、蓝色（blue）、红色（red）、橙色（orange）、绿色（green）支持深浅色模式切换。也可以自定义任何 [CSS color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) 支持颜色值，深浅色模式切换需自行适配
+   * @default ''
    */
-  color?: 'black' | 'blue' | 'red' | 'orange' | 'green';
+  color?: string;
   /**
    * 小数保留位数
    */
@@ -42,7 +43,7 @@ export interface TdStatisticProps {
    */
   prefix?: string | TNode;
   /**
-   * 默认展示进位分隔符，可以自定义为其他内容，`separator = ''` 设置为空字符串/null/undefined 时隐藏分隔符
+   * 默认展示千位分隔符，可以自定义为其他内容，`separator = ''` 设置为空字符串/null/undefined 时展示默认分隔符
    * @default ,
    */
   separator?: string;
@@ -73,6 +74,14 @@ export interface TdStatisticProps {
   value?: number;
 }
 
+/** 组件实例方法 */
+export interface StatisticInstanceFunctions {
+  /**
+   * 开始动画
+   */
+  start: () => void;
+}
+
 export interface animation {
   duration: number;
   valueFrom: number;