docs(canvas): explain editor entry migration gates and loading lifecycles
This commit is contained in:
@@ -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("未找到图标");
|
||||
|
||||
Reference in New Issue
Block a user