@cfp-studio/analyzer-api 0.1.16 → 0.1.18
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/dist/empty-hint.d.mts +91 -0
- package/dist/empty-hint.mjs +1 -0
- package/dist/index.d.mts +11231 -4
- package/dist/index.mjs +1 -1
- package/package.json +9 -5
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
//#region src/empty-hint.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* 「渲染成功但内容为空」的提示(`docs/todo/39` §5)。
|
|
4
|
+
*
|
|
5
|
+
* ## 为什么要单独一类提示
|
|
6
|
+
*
|
|
7
|
+
* 组件可能出现三种「看不到东西」的情况,前两种已经有归属:
|
|
8
|
+
*
|
|
9
|
+
* | 情况 | 现有归属 |
|
|
10
|
+
* | --- | --- |
|
|
11
|
+
* | 编译期失败(`.less` 缺包、模块解析失败) | `preview/index.html` 的 `startupErrorGuard` |
|
|
12
|
+
* | 渲染期抛错 | `renderErrorPanel`(同目录 `error-panel.ts`) |
|
|
13
|
+
* | **渲染成功但什么都没画出来** | **本文** |
|
|
14
|
+
*
|
|
15
|
+
* 典型场景是 `Modal` 没传 `open`:组件没抛错、DOM 也建了,只是尺寸为 0 ——
|
|
16
|
+
* 用户看到一片空白,误以为预览坏了。这时给一句话,比让他去翻 Output 强。
|
|
17
|
+
*
|
|
18
|
+
* ## 为什么判定放在预览页内
|
|
19
|
+
*
|
|
20
|
+
* 「空」这个事实的判定依据就是 `#root` 的 DOM。放在预览页内(`runNewRender` 的成功分支)
|
|
21
|
+
* 可以就地读取;放到宿主侧则要先让 `runtime-bridge` 发一条结构化事件,还要为
|
|
22
|
+
* embedded / browser 两种渲染面各写一遍通路。
|
|
23
|
+
*
|
|
24
|
+
* ## 与错误面板的关系
|
|
25
|
+
*
|
|
26
|
+
* 复用同一套覆盖层约定:挂在 `document.body`、带 `data-preview-error-panel` 标记
|
|
27
|
+
* (`runtime-bridge.walk()` 据此跳过它,否则它会作为普通 DOM 出现在 Runtime Tree 里)、
|
|
28
|
+
* 幂等清理。但**配色是中性色**:这不是错误,是提示。
|
|
29
|
+
*/
|
|
30
|
+
/** 提示层的 id。与错误面板(`cfp-error-panel`)区分,两者可同时存在但通常不会。 */
|
|
31
|
+
declare const EMPTY_HINT_ID = "cfp-empty-hint";
|
|
32
|
+
/**
|
|
33
|
+
* 与错误面板共用同一个标记属性。
|
|
34
|
+
*
|
|
35
|
+
* 复用而不是新开一个:`runtime-bridge` 只需跳过一类「预览工具自己画的节点」,
|
|
36
|
+
* 分两个属性只会让所有跳过逻辑都写两遍。
|
|
37
|
+
*/
|
|
38
|
+
declare const EMPTY_HINT_ATTRIBUTE = "data-preview-error-panel";
|
|
39
|
+
/** 单次渲染后等多久才判定「空」(见 `scheduleEmptyHintCheck` 的说明)。 */
|
|
40
|
+
declare const EMPTY_HINT_DELAY_MS = 400;
|
|
41
|
+
/** 组件级「空」的判定所需的最小信息(便于单测,不依赖真实 DOM 类型)。 */
|
|
42
|
+
interface RectLike {
|
|
43
|
+
width: number;
|
|
44
|
+
height: number;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* 子节点面积之和(用 `getBoundingClientRect` 的宽高)。
|
|
48
|
+
*
|
|
49
|
+
* 只关心“有没有面积”,不关心位置 —— 所以不用 `offsetWidth`(它受 `transform` 影响的方式
|
|
50
|
+
* 与 `getBoundingClientRect` 不同,而后者才是用户实际看到的)。
|
|
51
|
+
*/
|
|
52
|
+
declare function totalAreaOf(rects: readonly RectLike[]): number;
|
|
53
|
+
/**
|
|
54
|
+
* 判断一次渲染是否是「空的」。
|
|
55
|
+
*
|
|
56
|
+
* 两条判据(满足任一条即为空):
|
|
57
|
+
*
|
|
58
|
+
* 1. 没有子节点 —— 组件返回了 `null` / 空 fragment;
|
|
59
|
+
* 2. 所有子节点面积之和为 0 —— 渲染了 `<div>` 但没尺寸(`Modal` 关闭态、`display: none`)。
|
|
60
|
+
*
|
|
61
|
+
* 第 2 条是必须的:`Modal` 的例子正是「渲染了东西但没有尺寸」,只看子节点数会漏掉。
|
|
62
|
+
*/
|
|
63
|
+
declare function isEmptyRender(childCount: number, measure: () => readonly RectLike[]): boolean;
|
|
64
|
+
/**
|
|
65
|
+
* 对真实 `#root` 应用 {@link isEmptyRender}。
|
|
66
|
+
*
|
|
67
|
+
* `transform: scale` 会让 `getBoundingClientRect` 跟着缩,但比例不影响「是否为 0」,
|
|
68
|
+
* 所以不需要额外的坐标换算。
|
|
69
|
+
*/
|
|
70
|
+
declare function isRootEmpty(root: Element | null | undefined): boolean;
|
|
71
|
+
interface RenderEmptyHintOptions {
|
|
72
|
+
/** 被预览的可预览项名称,用于标题。 */
|
|
73
|
+
previewableName?: string;
|
|
74
|
+
/** 用户关闭后回调(由调用方决定是否在本次渲染内不再提示)。 */
|
|
75
|
+
onDismiss?: () => void;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* 画出「内容为空」提示(中性色,挂在 `document.body` 的独立覆盖层上)。
|
|
79
|
+
*
|
|
80
|
+
* 与 `renderErrorPanel` 一样用**内联样式**:面板渲染在用户页面之上,会继承用户的
|
|
81
|
+
* 全局 CSS(reset / `* { box-sizing }` 等),内联样式才不会被覆盖。
|
|
82
|
+
*
|
|
83
|
+
* 返回清理函数(幂等)。
|
|
84
|
+
*/
|
|
85
|
+
declare function renderEmptyHint(options?: RenderEmptyHintOptions): () => void;
|
|
86
|
+
/** 移除提示(幂等)。 */
|
|
87
|
+
declare function clearEmptyHint(): void;
|
|
88
|
+
/** 当前是否正显示空内容提示。 */
|
|
89
|
+
declare function isEmptyHintVisible(): boolean;
|
|
90
|
+
//#endregion
|
|
91
|
+
export { EMPTY_HINT_ATTRIBUTE, EMPTY_HINT_DELAY_MS, EMPTY_HINT_ID, RectLike, RenderEmptyHintOptions, clearEmptyHint, isEmptyHintVisible, isEmptyRender, isRootEmpty, renderEmptyHint, totalAreaOf };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
const e=`cfp-empty-hint`,t=`data-preview-error-panel`,n=400;function r(e){return e.reduce((e,t)=>e+Math.max(0,t.width)*Math.max(0,t.height),0)}function i(e,t){return e===0?!0:r(t())===0}function a(e){return e?i(e.children.length,()=>[...e.children].map(e=>{let t=e.getBoundingClientRect();return{width:t.width,height:t.height}})):!1}function o(n={}){s();let r=document.createElement(`div`);r.id=e,r.setAttribute(t,``),r.style.cssText=[`position: fixed`,`left: 50%`,`top: 24px`,`transform: translateX(-50%)`,`z-index: 2147483646`,`box-sizing: border-box`,`max-width: min(560px, calc(100vw - 48px))`,`padding: 10px 14px`,`font-family: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif`,`font-size: 12px`,`line-height: 1.6`,`color: #6b7280`,`background: #f8fafc`,`border: 1px solid #cbd5e1`,`border-radius: 8px`,`box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12)`,`pointer-events: auto`,`text-align: left`].join(`;`);let i=document.createElement(`div`);i.style.cssText=`font-weight: 600; color: #374151; margin-bottom: 2px`,i.textContent=n.previewableName?`${n.previewableName} 已渲染,但内容为空`:`组件已渲染,但内容为空`;let a=document.createElement(`div`);a.textContent=`它可能需要 props 才能显示(例如 Modal 的 open)。可以在 __previewjs__/Wrapper.tsx 里提供默认 props。`;let o=document.createElement(`button`);return o.type=`button`,o.textContent=`×`,o.setAttribute(`aria-label`,`关闭提示`),o.style.cssText=[`position: absolute`,`top: 4px`,`right: 6px`,`width: 20px`,`height: 20px`,`padding: 0`,`border: none`,`border-radius: 4px`,`background: transparent`,`color: #94a3b8`,`font-size: 14px`,`line-height: 1`,`cursor: pointer`].join(`;`),o.addEventListener(`click`,()=>{r.remove(),n.onDismiss?.()}),r.appendChild(i),r.appendChild(a),r.appendChild(o),document.body.appendChild(r),()=>r.remove()}function s(){document.getElementById(e)?.remove()}function c(){return document.getElementById(e)!==null}export{t as EMPTY_HINT_ATTRIBUTE,n as EMPTY_HINT_DELAY_MS,e as EMPTY_HINT_ID,s as clearEmptyHint,c as isEmptyHintVisible,i as isEmptyRender,a as isRootEmpty,o as renderEmptyHint,r as totalAreaOf};
|