From 1c63ca30c1fff1c4cd0c9ddfbd161c9482b25d3a Mon Sep 17 00:00:00 2001 From: Fengbao Li Date: Mon, 3 Aug 2026 20:24:26 +0800 Subject: [PATCH 1/2] refactor(iconfont): extract long API doc from stories string into .md via ?raw - Move the large bilingual (EN/CN) API description out of Iconfont.stories.tsx into Iconfont.apidoc.md, imported with Vite ?raw. - Add .storybook/vite-env.d.ts referencing vite/client so *?raw is typed. - Preserves the existing autodocs render pipeline and EN/CN language toggle (parameters.docs.description.component content is unchanged at runtime). --- .../stories/components/Iconfont.apidoc.md | 35 ++++++++++++++++++ .../stories/components/Iconfont.stories.tsx | 37 +------------------ .storybook/vite-env.d.ts | 1 + 3 files changed, 38 insertions(+), 35 deletions(-) create mode 100644 .storybook/stories/components/Iconfont.apidoc.md create mode 100644 .storybook/vite-env.d.ts diff --git a/.storybook/stories/components/Iconfont.apidoc.md b/.storybook/stories/components/Iconfont.apidoc.md new file mode 100644 index 0000000..832a5a6 --- /dev/null +++ b/.storybook/stories/components/Iconfont.apidoc.md @@ -0,0 +1,35 @@ +- **EN:** `createIconfont` is a factory that turns an iconfont script URL into a ready-to-use icon component. It wraps Ant Design's `createFromIconfontCN` and adds an `iconPrefix` option plus a `size` alias for `style.fontSize`. + +**Factory API** + +| Parameter | Type | Default | Description | +| --- | --- | --- | --- | +| `scriptUrl` | `string` | - | iconfont script URL generated from iconfont.cn | +| `options.iconPrefix` | `string` | `''` | Prefix automatically prepended to `type` unless it already starts with the prefix | + +**Component props** + +| Prop | Type | Default | Description | +| --- | --- | --- | --- | +| `type` | `T` | - | Icon name. Find it in iconfont and click `Copy Code` | +| `size` | `CSSProperties['fontSize']` | - | Alias of `style.fontSize` | +| `spin` | `boolean` | `false` | Whether the icon spins continuously | +| `rotate` | `number` | `0` | Fixed clockwise rotation angle | + +- **CN:** `createIconfont` 是一个工厂函数：传入 iconfont 脚本地址，返回一个可直接使用的图标组件。它封装了 Ant Design 的 `createFromIconfontCN`，额外提供 `iconPrefix` 选项与 `size`（`style.fontSize` 的别名）属性。 + +**工厂 API** + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| `scriptUrl` | `string` | - | 在 iconfont.cn 上生成的脚本地址 | +| `options.iconPrefix` | `string` | `''` | 自动拼接到 `type` 的前缀，若 `type` 已包含该前缀则不再拼接 | + +**组件 props** + +| 属性 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| `type` | `T` | - | 图标名称。在 iconfont 中找到某个图标，点击`复制代码` | +| `size` | `CSSProperties['fontSize']` | - | `style.fontSize` 的别名 | +| `spin` | `boolean` | `false` | 图标是否持续旋转 | +| `rotate` | `number` | `0` | 图标顺时针旋转一个固定角度 | diff --git a/.storybook/stories/components/Iconfont.stories.tsx b/.storybook/stories/components/Iconfont.stories.tsx index 5e66c94..c46bd1c 100644 --- a/.storybook/stories/components/Iconfont.stories.tsx +++ b/.storybook/stories/components/Iconfont.stories.tsx @@ -3,6 +3,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite'; import { Space, Typography } from 'antd'; import { createIconfont } from '../../../src/components/Iconfont'; import { useStoryT } from '../../locales'; +import apidoc from './Iconfont.apidoc.md?raw'; // Ant Design official iconfont demo URL, also used by the repo tests. const SCRIPT_URL = '//at.alicdn.com/t/font_8d5l8fzk5b87iudi.js'; @@ -29,41 +30,7 @@ const meta: Meta = { parameters: { docs: { description: { - component: `- **EN:** \`createIconfont\` is a factory that turns an iconfont script URL into a ready-to-use icon component. It wraps Ant Design's \`createFromIconfontCN\` and adds an \`iconPrefix\` option plus a \`size\` alias for \`style.fontSize\`. - -**Factory API** - -| Parameter | Type | Default | Description | -| --- | --- | --- | --- | -| \`scriptUrl\` | \`string\` | - | iconfont script URL generated from iconfont.cn | -| \`options.iconPrefix\` | \`string\` | \`''\` | Prefix (no trailing '-') prepended to \`type\` as \`-\` unless \`type\` already starts with the prefix | - -**Component props** - -| Prop | Type | Default | Description | -| --- | --- | --- | --- | -| \`type\` | \`T\` | - | Icon name. Find it in iconfont and click \`Copy Code\` | -| \`size\` | \`CSSProperties['fontSize']\` | - | Alias of \`style.fontSize\` | -| \`spin\` | \`boolean\` | \`false\` | Whether the icon spins continuously | -| \`rotate\` | \`number\` | \`0\` | Fixed clockwise rotation angle | - -- **CN:** \`createIconfont\` 是一个工厂函数：传入 iconfont 脚本地址，返回一个可直接使用的图标组件。它封装了 Ant Design 的 \`createFromIconfontCN\`，额外提供 \`iconPrefix\` 选项与 \`size\`（\`style.fontSize\` 的别名）属性。 - -**工厂 API** - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| \`scriptUrl\` | \`string\` | - | 在 iconfont.cn 上生成的脚本地址 | -| \`options.iconPrefix\` | \`string\` | \`''\` | 自动拼接到 \`type\` 的前缀，若 \`type\` 已包含该前缀则不再拼接 | - -**组件 props** - -| 属性 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| \`type\` | \`T\` | - | 图标名称。在 iconfont 中找到某个图标，点击\`复制代码\` | -| \`size\` | \`CSSProperties['fontSize']\` | - | \`style.fontSize\` 的别名 | -| \`spin\` | \`boolean\` | \`false\` | 图标是否持续旋转 | -| \`rotate\` | \`number\` | \`0\` | 图标顺时针旋转一个固定角度 |`, + component: apidoc, }, }, }, diff --git a/.storybook/vite-env.d.ts b/.storybook/vite-env.d.ts new file mode 100644 index 0000000..11f02fe --- /dev/null +++ b/.storybook/vite-env.d.ts @@ -0,0 +1 @@ +/// From 201bcdad2a66ab4068ea9615d9a0b85f9046e33c Mon Sep 17 00:00:00 2001 From: Fengbao Li Date: Mon, 3 Aug 2026 22:46:15 +0800 Subject: [PATCH 2/2] feat(iconfont): add API and introduction markdown files --- .../stories/components/Iconfont.apidoc.md | 35 ----------- .../stories/components/Iconfont/api-doc.md | 39 ++++++++++++ .../index.stories.tsx} | 62 ++++++++++++------- .../stories/components/Iconfont/introduce.md | 7 +++ tsconfig.json | 2 +- 5 files changed, 86 insertions(+), 59 deletions(-) delete mode 100644 .storybook/stories/components/Iconfont.apidoc.md create mode 100644 .storybook/stories/components/Iconfont/api-doc.md rename .storybook/stories/components/{Iconfont.stories.tsx => Iconfont/index.stories.tsx} (71%) create mode 100644 .storybook/stories/components/Iconfont/introduce.md diff --git a/.storybook/stories/components/Iconfont.apidoc.md b/.storybook/stories/components/Iconfont.apidoc.md deleted file mode 100644 index 832a5a6..0000000 --- a/.storybook/stories/components/Iconfont.apidoc.md +++ /dev/null @@ -1,35 +0,0 @@ -- **EN:** `createIconfont` is a factory that turns an iconfont script URL into a ready-to-use icon component. It wraps Ant Design's `createFromIconfontCN` and adds an `iconPrefix` option plus a `size` alias for `style.fontSize`. - -**Factory API** - -| Parameter | Type | Default | Description | -| --- | --- | --- | --- | -| `scriptUrl` | `string` | - | iconfont script URL generated from iconfont.cn | -| `options.iconPrefix` | `string` | `''` | Prefix automatically prepended to `type` unless it already starts with the prefix | - -**Component props** - -| Prop | Type | Default | Description | -| --- | --- | --- | --- | -| `type` | `T` | - | Icon name. Find it in iconfont and click `Copy Code` | -| `size` | `CSSProperties['fontSize']` | - | Alias of `style.fontSize` | -| `spin` | `boolean` | `false` | Whether the icon spins continuously | -| `rotate` | `number` | `0` | Fixed clockwise rotation angle | - -- **CN:** `createIconfont` 是一个工厂函数：传入 iconfont 脚本地址，返回一个可直接使用的图标组件。它封装了 Ant Design 的 `createFromIconfontCN`，额外提供 `iconPrefix` 选项与 `size`（`style.fontSize` 的别名）属性。 - -**工厂 API** - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `scriptUrl` | `string` | - | 在 iconfont.cn 上生成的脚本地址 | -| `options.iconPrefix` | `string` | `''` | 自动拼接到 `type` 的前缀，若 `type` 已包含该前缀则不再拼接 | - -**组件 props** - -| 属性 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `type` | `T` | - | 图标名称。在 iconfont 中找到某个图标，点击`复制代码` | -| `size` | `CSSProperties['fontSize']` | - | `style.fontSize` 的别名 | -| `spin` | `boolean` | `false` | 图标是否持续旋转 | -| `rotate` | `number` | `0` | 图标顺时针旋转一个固定角度 | diff --git a/.storybook/stories/components/Iconfont/api-doc.md b/.storybook/stories/components/Iconfont/api-doc.md new file mode 100644 index 0000000..150ecef --- /dev/null +++ b/.storybook/stories/components/Iconfont/api-doc.md @@ -0,0 +1,39 @@ +- **EN:** + +## API + +**Factory API** + +| Parameter | Type | Default | Description | +| -------------------- | -------- | ------- | --------------------------------------------------------------------------------- | +| `scriptUrl` | `string` | - | iconfont script URL generated from iconfont.cn | +| `options.iconPrefix` | `string` | `''` | Prefix automatically prepended to `type` unless it already starts with the prefix | + +**Component props** + +| Prop | Type | Default | Description | +| -------- | --------------------------- | ------- | ---------------------------------------------------- | +| `type` | `T` | - | Icon name. Find it in iconfont and click `Copy Code` | +| `size` | `CSSProperties['fontSize']` | - | Alias of `style.fontSize` | +| `spin` | `boolean` | `false` | Whether the icon spins continuously | +| `rotate` | `number` | `0` | Fixed clockwise rotation angle | + +- **CN:** + +## API + +**工厂 API** + +| 参数 | 类型 | 默认值 | 说明 | +| -------------------- | -------- | ------ | ---------------------------------------------------------- | +| `scriptUrl` | `string` | - | 在 iconfont.cn 上生成的脚本地址 | +| `options.iconPrefix` | `string` | `''` | 自动拼接到 `type` 的前缀，若 `type` 已包含该前缀则不再拼接 | + +**组件 props** + +| 属性 | 类型 | 默认值 | 说明 | +| -------- | --------------------------- | ------- | ---------------------------------------------------- | +| `type` | `T` | - | 图标名称。在 iconfont 中找到某个图标，点击`复制代码` | +| `size` | `CSSProperties['fontSize']` | - | `style.fontSize` 的别名 | +| `spin` | `boolean` | `false` | 图标是否持续旋转 | +| `rotate` | `number` | `0` | 图标顺时针旋转一个固定角度 | diff --git a/.storybook/stories/components/Iconfont.stories.tsx b/.storybook/stories/components/Iconfont/index.stories.tsx similarity index 71% rename from .storybook/stories/components/Iconfont.stories.tsx rename to .storybook/stories/components/Iconfont/index.stories.tsx index c46bd1c..7ab0d0a 100644 --- a/.storybook/stories/components/Iconfont.stories.tsx +++ b/.storybook/stories/components/Iconfont/index.stories.tsx @@ -1,9 +1,10 @@ import { useMemo } from 'react'; import type { Meta, StoryObj } from '@storybook/react-vite'; import { Space, Typography } from 'antd'; -import { createIconfont } from '../../../src/components/Iconfont'; -import { useStoryT } from '../../locales'; -import apidoc from './Iconfont.apidoc.md?raw'; +import { createIconfont } from '../../../../src/components/Iconfont'; +import { useStoryT } from '../../../locales'; +import apiDoc from './api-doc.md?raw'; +import introduce from './introduce.md?raw'; // Ant Design official iconfont demo URL, also used by the repo tests. const SCRIPT_URL = '//at.alicdn.com/t/font_8d5l8fzk5b87iudi.js'; @@ -11,18 +12,20 @@ const SCRIPT_URL = '//at.alicdn.com/t/font_8d5l8fzk5b87iudi.js'; const ICON_TYPES = ['icon-tuichu', 'icon-facebook', 'icon-twitter'] as const; interface IconfontStoryArgs { + /** URL of the iconfont script | iconfont 脚本的 URL */ + scriptUrl: string; /** Icon name from the iconfont project | iconfont 项目中的图标名称 */ type: string; /** Icon size in px | 图标尺寸（像素） */ - size: number; + size?: number; /** Icon color | 图标颜色 */ - color: string; + color?: string; /** Whether the icon spins continuously | 图标是否持续旋转 */ - spin: boolean; + spin?: boolean; /** Fixed clockwise rotation angle | 顺时针固定旋转角度 */ - rotate: number; + rotate?: number; /** Demo-only: prefix auto-prepended to `type` | 示例专用：自动拼接到 `type` 的前缀 */ - iconPrefix: string; + iconPrefix?: string; } const meta: Meta = { @@ -30,11 +33,12 @@ const meta: Meta = { parameters: { docs: { description: { - component: apidoc, + component: introduce + apiDoc, }, }, }, args: { + scriptUrl: SCRIPT_URL, type: 'icon-tuichu', size: 32, color: '#1677ff', @@ -43,6 +47,11 @@ const meta: Meta = { iconPrefix: '', }, argTypes: { + scriptUrl: { + control: 'text', + description: `- **EN:** URL of the iconfont script. +- **CN:** iconfont 脚本的 URL。`, + }, type: { control: 'select', options: [...ICON_TYPES], @@ -95,21 +104,28 @@ export const Playground: Story = { }, render: function Render(args: IconfontStoryArgs) { const t = useStoryT(); - const IconFont = useMemo(() => createIconfont(SCRIPT_URL, { iconPrefix: args.iconPrefix }), [args.iconPrefix]); - const renderedType = args.type.startsWith(args.iconPrefix) ? args.type : `${args.iconPrefix}-${args.type}`; + const IconFont = useMemo( + () => createIconfont(args.scriptUrl, { iconPrefix: args.iconPrefix }), + [args.scriptUrl, args.iconPrefix], + ); + const renderedType = args.type?.startsWith(args?.iconPrefix ?? '') ? args.type : `${args.iconPrefix}-${args.type}`; return ( - - - - {t('storybook.stories.Iconfont.renderedType')}: {renderedType} - + + {args.type && ( + + )} + {args.type && ( + + {t('storybook.stories.Iconfont.renderedType')}: {renderedType} + + )} ); }, @@ -129,7 +145,7 @@ export const IconGallery: Story = { return ( {ICON_TYPES.map((type) => ( - + {type} diff --git a/.storybook/stories/components/Iconfont/introduce.md b/.storybook/stories/components/Iconfont/introduce.md new file mode 100644 index 0000000..434dbe3 --- /dev/null +++ b/.storybook/stories/components/Iconfont/introduce.md @@ -0,0 +1,7 @@ +- **EN:** + +`createIconfont` is a factory that turns an iconfont script URL into a ready-to-use icon component. It wraps Ant Design's `createFromIconfontCN` and adds an `iconPrefix` option plus a `size` alias for `style.fontSize`. + +- **CN:** + +`createIconfont` 是一个工厂函数：传入 iconfont 脚本地址，返回一个可直接使用的图标组件。它封装了 Ant Design 的 `createFromIconfontCN`，额外提供 `iconPrefix` 选项与 `size`（`style.fontSize` 的别名）属性。 diff --git a/tsconfig.json b/tsconfig.json index 321ed29..e7f3495 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -20,6 +20,6 @@ "experimentalDecorators": true, "strict": true }, - "include": ["./src", "scripts", ".storybook"], + "include": ["./src", "scripts", ".storybook/**/*"], "exclude": ["src/components/tmp"] }