docs(canvas): explain editor entry migration gates and loading lifecycles

This commit is contained in:
2026-11-12 01:26:22 +08:00
parent 450fa3f719
commit f28a2a96bf
9 changed files with 142 additions and 1 deletions
+13
View File
@@ -1,15 +1,25 @@
/**
* 公开图标资源的分片定位、格式校验与共享读取。manifest给出构建产物路径,模块级资源加载器
* 合并同分片请求并缓存解析结果;它不保存画布节点状态或私人资源授权。
*/
import manifest from "./canvas-icon-assets.json" with { type: "json" };
import { createResourceLoader } from "./resource-loader.ts";
/** React绘制可用的SVG基础形状及属性列表,不接收任意HTML/SVG字符串。 */
export type IconPaths = [string, Record<string, string | number>][];
/** Tabler统一分片,其它名字用稳定31进制散列落入96个Lucide分片;散列仅用于定位而非安全校验。 */
export function iconAsset(name: string) {
let hash = 0;
for (const char of name) hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
const key = name.startsWith("Tabler") ? "tabler" : `lucide-${hash % 96}`;
return `${manifest.root}/${manifest.assets[key as keyof typeof manifest.assets]}`;
}
// 限定基础图形标签,不提供script、foreignObject或任意节点构造能力。
const allowedTags = new Set(["path", "circle", "ellipse", "rect", "line", "polyline", "polygon"]);
// 属性名白名单配合值类型与外部引用模式检查,拒绝任意事件处理/URL内容。
const allowedAttributes = new Set(["key", "d", "cx", "cy", "r", "rx", "ry", "x", "y", "x1", "x2", "y1", "y2", "width", "height", "points", "fill", "fillRule", "clipRule", "stroke", "strokeWidth", "strokeLinecap", "strokeLinejoin", "opacity", "transform"]);
/** 校验图标名、非空且最多100项的路径数组、标签与属性形状,并拒绝url()/javascript:/data:值。
* 此处是特定分片结构验证,不宣称具有全文件字节预算或任意SVG净化能力。 */
export function validateIconShard(value: unknown): Record<string, IconPaths> {
if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid icon data");
for (const [id, paths] of Object.entries(value)) {
@@ -23,12 +33,15 @@ export function validateIconShard(value: unknown): Record<string, IconPaths> {
}
return value as Record<string, IconPaths>;
}
/** 单例分片加载器使用HTTP强缓存,响应失败或校验失败不写入成功缓存。 */
const resources = createResourceLoader(async (url, signal) => {
const response = await fetch(url, { signal, cache: "force-cache" });
if (!response.ok) throw new Error("图标加载失败");
return validateIconShard(await response.json());
});
/** 缓存命中只取指定图标路径,不发请求;未加载或分片没有该名均返回undefined。 */
export function peekIcon(name: string) { return resources.peek(iconAsset(name))?.[name]; }
/** 加入分片共享读取,取消只撤销本调用者;分片就绪但缺指定图标时给出明确错误。 */
export async function loadIcon(name: string, signal?: AbortSignal) {
const paths = (await resources.request(iconAsset(name), signal))[name];
if (!paths) throw new Error("未找到图标");