@epxing/icons 5.3.0-beta.3 → 5.3.0-beta.4

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.
Files changed (2) hide show
  1. package/API.md +111 -111
  2. package/package.json +1 -1
package/API.md CHANGED
@@ -1,111 +1,111 @@
1
- # @epxing/icons API
2
-
3
- Vite 构建插件和浏览器图标补齐工具。根入口用于 Node 构建，/runtime 用于浏览器。
4
-
5
- 本页对应包版本 `5.3.0-beta.3`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
6
-
7
- ## 安装与使用
8
-
9
-
10
- ```sh
11
- pnpm add @epxing/icons@5.3.0-beta.2
12
- ```
13
-
14
-
15
- ```js
16
- // vite.config.mjs（Node）
17
- import epxIcons from '@epxing/icons'
18
- export default { plugins: [epxIcons()] }
19
-
20
- // 产品入口（浏览器）
21
- // import { configureIcons, collectIconNames, ensureIcons, createEndpointLoader } from '@epxing/icons/runtime'
22
- // configureIcons({ loader: createEndpointLoader({ url: '/api/icons' }), timeout: 3000 })
23
- // await ensureIcons(collectIconNames(pageConfig))
24
- ```
25
-
26
- ## 接入约定
27
-
28
- 浏览器从 @epxing/icons/runtime 导入，避免把 Node 构建依赖带进产品。图标宿主样式由 @epxing/theme/src/icons/base.scss 提供；loader 补入图案前需先加载底座样式。ready/missing 表示本次检查结果；静态分片的编号规则与 shardOf 保持一致。
29
-
30
- ## 根入口完整导出
31
-
32
- | 导出名 | 形态 | 用途 | 参数 / 配置 / 事件 |
33
- | --- | --- | --- | --- |
34
- | `emitShards` | 函数 | 构建图标静态分片；在 Node 构建阶段调用，输出位置和分片数由选项决定。 | [详细参考](../../docs/revision/icons/api/vite-plugin.md) |
35
- | `default` | 默认导出 | epxIcons(options?)：Vite 图标构建插件工厂。 | [详细参考](../../docs/revision/icons/api/vite-plugin.md) |
36
-
37
- ## 函数、类与工具对象
38
-
39
- 签名中的 any 表示现有声明未进一步限定结构；源代码方法签名保留默认参数。异步结果与泛型以声明为准。
40
-
41
- ### emitShards
42
-
43
- 构建图标静态分片；在 Node 构建阶段调用，输出位置和分片数由选项决定。
44
-
45
- ```ts
46
- emitShards(options?: IconOptions): unknown
47
- ```
48
-
49
- [详细参考](../../docs/revision/icons/api/vite-plugin.md)，包括参数、返回值与运行约束。
50
-
51
- ## 稳定子路径
52
-
53
- 下表按实际 package.json 的公开入口列出。default 使用默认导入，其他名称使用具名导入；类型接口用 import type。
54
-
55
- | 导入路径 | 完整导出名 | 用途 / 详细说明 |
56
- | --- | --- | --- |
57
- | `@epxing/icons/runtime` | `configureIcons`、`collectIconNames`、`ensureIcons`、`ensureIcon`、`createEndpointLoader`、`createShardLoader`、`shardOf`、`__reset`、`IconRuntimeOptions`（类型）、`IconResult`（类型） | 浏览器图标运行时：配置 loader、收集名称、补齐图案、创建加载器和计算分片编号。 [详细参考](../../docs/revision/icons/api/runtime.md) |
58
-
59
- ### 浏览器 runtime 函数
60
-
61
- | 函数 | 调用签名 | 用途 |
62
- | --- | --- | --- |
63
- | `configureIcons` | `configureIcons(options?: IconRuntimeOptions): void` | 配置浏览器图标 loader、builtin、match 和 timeout；timeout 以毫秒计，默认 0 不设上限。 |
64
- | `collectIconNames` | `collectIconNames(config: unknown, out?: Set<string>): string[]` | 递归收集配置中的图标名并去重，返回字符串数组；可传入 Set 累积结果。 |
65
- | `ensureIcons` | `ensureIcons(names: Iterable<string>): Promise<IconResult>` | 批量补齐图标并合并并发请求，返回 Promise&lt;{ ready, missing }&gt;。 |
66
- | `ensureIcon` | `ensureIcon(name: string): Promise<IconResult>` | 确保单个图标可用，返回 Promise&lt;{ ready, missing }&gt;。 |
67
- | `createEndpointLoader` | `createEndpointLoader(options?: Record<string, unknown>): (names: string[]) => Promise<unknown>` | 创建从图标 HTTP 接口批量取图案的 loader，传给 configureIcons。 |
68
- | `createShardLoader` | `createShardLoader(options?: Record<string, unknown>): (names: string[]) => Promise<unknown>` | 创建从静态分片加载图标的 loader，传给 configureIcons。 |
69
- | `shardOf` | `shardOf(name: string, shards?: number): number` | 按图标名计算静态分片编号；构建端与运行时须使用相同分片数。 |
70
- | `__reset` | `__reset(): void` | 仅供测试：清空图标运行时缓存、loader 和已注入样式；产品业务代码不调用。 |
71
-
72
- ## 导出的 TypeScript 类型
73
-
74
- 以下名称仅存在于类型系统，用 import type 导入，不作为运行时对象使用。
75
-
76
- ### IconOptions
77
-
78
- ```ts
79
- interface IconOptions {
80
- [key: string]: unknown
81
- }
82
- ```
83
-
84
- ### IconRuntimeOptions
85
-
86
- ```ts
87
- interface IconRuntimeOptions {
88
- loader?: (names: string[]) => Promise<unknown>
89
- timeout?: number
90
- [key: string]: unknown
91
- }
92
- ```
93
-
94
- ### IconResult
95
-
96
- ```ts
97
- interface IconResult { ready: string[]; missing: string[] }
98
- ```
99
-
100
- ## 源码兼容与其他入口
101
-
102
- /src 路径保留给已有产品和源码级扩展，可能包含平台内部实现；新产品优先采用上方根导出与稳定子路径。通配符表示按实际文件名匹配，不代表所有源码都属于根入口。
103
-
104
- | 公开路径模式 | 实际目标 |
105
- | --- | --- |
106
- | `@epxing/icons/src/*` | `./src/*` |
107
- | `@epxing/icons/package.json` | `./package.json` |
108
-
109
- ## 文档维护
110
-
111
- 本页由 build/gen-package-api-docs.mjs 生成。修改公开入口并更新构建产物和类型声明后，在框架根运行 `pnpm docs:api`；`pnpm docs:api:check` 检查清单、类型、包内文档与站点镜像是否同步，同时验证页面编译和文档链接。用途和示例维护在 build/package-api-notes.mjs，组件和源码方法的详细参考位于 docs/revision。
1
+ # @epxing/icons API
2
+
3
+ Vite 构建插件和浏览器图标补齐工具。根入口用于 Node 构建，/runtime 用于浏览器。
4
+
5
+ 本页对应包版本 `5.3.0-beta.4`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
6
+
7
+ ## 安装与使用
8
+
9
+
10
+ ```sh
11
+ pnpm add @epxing/icons@5.3.0-beta.2
12
+ ```
13
+
14
+
15
+ ```js
16
+ // vite.config.mjs（Node）
17
+ import epxIcons from '@epxing/icons'
18
+ export default { plugins: [epxIcons()] }
19
+
20
+ // 产品入口（浏览器）
21
+ // import { configureIcons, collectIconNames, ensureIcons, createEndpointLoader } from '@epxing/icons/runtime'
22
+ // configureIcons({ loader: createEndpointLoader({ url: '/api/icons' }), timeout: 3000 })
23
+ // await ensureIcons(collectIconNames(pageConfig))
24
+ ```
25
+
26
+ ## 接入约定
27
+
28
+ 浏览器从 @epxing/icons/runtime 导入，避免把 Node 构建依赖带进产品。图标宿主样式由 @epxing/theme/src/icons/base.scss 提供；loader 补入图案前需先加载底座样式。ready/missing 表示本次检查结果；静态分片的编号规则与 shardOf 保持一致。
29
+
30
+ ## 根入口完整导出
31
+
32
+ | 导出名 | 形态 | 用途 | 参数 / 配置 / 事件 |
33
+ | --- | --- | --- | --- |
34
+ | `emitShards` | 函数 | 构建图标静态分片；在 Node 构建阶段调用，输出位置和分片数由选项决定。 | [详细参考](../../docs/revision/icons/api/vite-plugin.md) |
35
+ | `default` | 默认导出 | epxIcons(options?)：Vite 图标构建插件工厂。 | [详细参考](../../docs/revision/icons/api/vite-plugin.md) |
36
+
37
+ ## 函数、类与工具对象
38
+
39
+ 签名中的 any 表示现有声明未进一步限定结构；源代码方法签名保留默认参数。异步结果与泛型以声明为准。
40
+
41
+ ### emitShards
42
+
43
+ 构建图标静态分片；在 Node 构建阶段调用，输出位置和分片数由选项决定。
44
+
45
+ ```ts
46
+ emitShards(options?: IconOptions): unknown
47
+ ```
48
+
49
+ [详细参考](../../docs/revision/icons/api/vite-plugin.md)，包括参数、返回值与运行约束。
50
+
51
+ ## 稳定子路径
52
+
53
+ 下表按实际 package.json 的公开入口列出。default 使用默认导入，其他名称使用具名导入；类型接口用 import type。
54
+
55
+ | 导入路径 | 完整导出名 | 用途 / 详细说明 |
56
+ | --- | --- | --- |
57
+ | `@epxing/icons/runtime` | `configureIcons`、`collectIconNames`、`ensureIcons`、`ensureIcon`、`createEndpointLoader`、`createShardLoader`、`shardOf`、`__reset`、`IconRuntimeOptions`（类型）、`IconResult`（类型） | 浏览器图标运行时：配置 loader、收集名称、补齐图案、创建加载器和计算分片编号。 [详细参考](../../docs/revision/icons/api/runtime.md) |
58
+
59
+ ### 浏览器 runtime 函数
60
+
61
+ | 函数 | 调用签名 | 用途 |
62
+ | --- | --- | --- |
63
+ | `configureIcons` | `configureIcons(options?: IconRuntimeOptions): void` | 配置浏览器图标 loader、builtin、match 和 timeout；timeout 以毫秒计，默认 0 不设上限。 |
64
+ | `collectIconNames` | `collectIconNames(config: unknown, out?: Set<string>): string[]` | 递归收集配置中的图标名并去重，返回字符串数组；可传入 Set 累积结果。 |
65
+ | `ensureIcons` | `ensureIcons(names: Iterable<string>): Promise<IconResult>` | 批量补齐图标并合并并发请求，返回 Promise&lt;{ ready, missing }&gt;。 |
66
+ | `ensureIcon` | `ensureIcon(name: string): Promise<IconResult>` | 确保单个图标可用，返回 Promise&lt;{ ready, missing }&gt;。 |
67
+ | `createEndpointLoader` | `createEndpointLoader(options?: Record<string, unknown>): (names: string[]) => Promise<unknown>` | 创建从图标 HTTP 接口批量取图案的 loader，传给 configureIcons。 |
68
+ | `createShardLoader` | `createShardLoader(options?: Record<string, unknown>): (names: string[]) => Promise<unknown>` | 创建从静态分片加载图标的 loader，传给 configureIcons。 |
69
+ | `shardOf` | `shardOf(name: string, shards?: number): number` | 按图标名计算静态分片编号；构建端与运行时须使用相同分片数。 |
70
+ | `__reset` | `__reset(): void` | 仅供测试：清空图标运行时缓存、loader 和已注入样式；产品业务代码不调用。 |
71
+
72
+ ## 导出的 TypeScript 类型
73
+
74
+ 以下名称仅存在于类型系统，用 import type 导入，不作为运行时对象使用。
75
+
76
+ ### IconOptions
77
+
78
+ ```ts
79
+ interface IconOptions {
80
+ [key: string]: unknown
81
+ }
82
+ ```
83
+
84
+ ### IconRuntimeOptions
85
+
86
+ ```ts
87
+ interface IconRuntimeOptions {
88
+ loader?: (names: string[]) => Promise<unknown>
89
+ timeout?: number
90
+ [key: string]: unknown
91
+ }
92
+ ```
93
+
94
+ ### IconResult
95
+
96
+ ```ts
97
+ interface IconResult { ready: string[]; missing: string[] }
98
+ ```
99
+
100
+ ## 源码兼容与其他入口
101
+
102
+ /src 路径保留给已有产品和源码级扩展，可能包含平台内部实现；新产品优先采用上方根导出与稳定子路径。通配符表示按实际文件名匹配，不代表所有源码都属于根入口。
103
+
104
+ | 公开路径模式 | 实际目标 |
105
+ | --- | --- |
106
+ | `@epxing/icons/src/*` | `./src/*` |
107
+ | `@epxing/icons/package.json` | `./package.json` |
108
+
109
+ ## 文档维护
110
+
111
+ 本页由 build/gen-package-api-docs.mjs 生成。修改公开入口并更新构建产物和类型声明后，在框架根运行 `pnpm docs:api`；`pnpm docs:api:check` 检查清单、类型、包内文档与站点镜像是否同步，同时验证页面编译和文档链接。用途和示例维护在 build/package-api-notes.mjs，组件和源码方法的详细参考位于 docs/revision。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@epxing/icons",
3
- "version": "5.3.0-beta.3",
3
+ "version": "5.3.0-beta.4",
4
4
  "description": "图标构建工具 + 运行时（源码分发：在消费方的构建里跑，无需预构建）。构建期按需生成 Remix 图标与项目彩色图标的 CSS 规则；运行时按需补齐数据库里配的、构建期看不见的图标。渲染底座在 @epxing/theme 的 icons/base.scss。",
5
5
  "type": "module",
6
6
  "main": "./src/vite-plugin.mjs",