@_tc/template-core 0.2.0-bate.1 → 0.2.0-bate.2

package/AGENT_README.md

@@ -367,10 +367,13 @@ import '@_tc/template-core/fe/tailwind_ui.css'
 
 ```ts
 import {
+  clearRafTimer,
   api,
   get,
   post,
   request,
+  rafSetInterval,
+  rafSetTimeout,
   schemaEventBus,
   schemaStore,
   useSchemaStore,
@@ -401,6 +404,7 @@ import { Button, DataTable, Form, Input, Modal, Select } from '@_tc/template-cor
 常用前端能力：
 
 - 请求方法：`api`、`request`、`get`、`post`、`put`、`patch`、`del`。
+- RAF 计时器：`rafSetTimeout`、`rafSetInterval`、`rafClearTimeout`、`rafClearInterval`、`clearRafTimer`。
 - 请求类型：`BaseResponse`、`PageParams`、`PageResponse`、`RequestConfig`、`ResponseConfig`、`AxiosError`。
 - 请求 header：自动添加 `s_t`、`s_sign`、`projk`；存在短 token 时添加 `Authorization: Bearer ${token}`。
 - 本地 key：短 token 是 `localStorage.auth_token`，项目 key 是 `localStorage.p_J_k`；刷新 token header 默认名是 `RT`。
@@ -410,6 +414,7 @@ import { Button, DataTable, Form, Input, Modal, Select } from '@_tc/template-cor
 - 多语言：`i18nStore.getState().addResources()`，配置文案可写 `$i18n::...`。
 - 主题：`ThemeSwitch` 会同步根节点 `dark` class 和 `localStorage`。
 - `Input type="password"` 会自动显示密码显隐按钮；`allowClear` 不作用于密码输入。
+- RAF 计时器只在浏览器环境可用，不适合 Node 侧调用。
 
 不要直接依赖 `frontend/src/...`、`packages/react/ui/...` 这类包内部路径。
 

package/cjs/app/controller/view.js

@@ -1 +1 @@
-const e=require(`../../packages/common/string/index.js`);var t=e=>JSON.stringify(e).replace(/</g,`\\u003c`).replace(/>/g,`\\u003e`).replace(/&/g,`\\u0026`).replace(/\u2028/g,`\\u2028`).replace(/\u2029/g,`\\u2029`),n=(n=>class{async renderPage(r,i){let a=r.path;if(n.extends.localCacheHtmlEtag.keepFreshFEBuildKey(),a.includes(`${n.options.apiPrefix}/`))await i();else{n.extends.logger.log(` - render page: `+r.params.page);try{let i=r.query.projk;Array.isArray(i)&&(i=e.joinStr(...i));let a={projKey:i??``,name:n.options?.name??``,env:n.envs.get(),basePath:t(`${n.options.pageBasePage}${r.params.page}`),projKeyJson:t(String(r.query.projk??``)),signKey:t(n.config.signKey),options:t(n.options)},o=n.extends.renderView(`${r.params.page}.entry.tpl`,r,a),s=e.joinStr(a.basePath,a.name,a.env,a.projKey);if(!n.extends.localCacheHtmlEtag.hasEtag(s)){let e=n.extends.crypto.hmacSign(o);n.extends.localCacheHtmlEtag.setEtag(s,e)}let c=n.extends.localCacheHtmlEtag.getEtag(s);c||console.log(`---- etag 缓存异常 请检查服务 ----`),r.etag=c??Date.now()+``}catch(e){console.log(`-------------- render view error --------------`),console.log(e),n.extends.generateErrorMessage(`template not found`,{status:404,showError:!0,code:0})}}}});module.exports=n;
+const e=require(`../../packages/common/string/index.js`);var t=e=>JSON.stringify(e).replace(/</g,`\\u003c`).replace(/>/g,`\\u003e`).replace(/&/g,`\\u0026`).replace(/\u2028/g,`\\u2028`).replace(/\u2029/g,`\\u2029`),n=(n=>class{async renderPage(r,i){let a=r.path;if(n.extends.localCacheHtmlEtag.keepFreshFEBuildKey(),a.includes(`${n.options.apiPrefix}/`))await i();else{n.extends.logger.log(` - render page: `+r.params.page);try{let i=r.query.projk;Array.isArray(i)&&(i=e.joinStr(...i));let a={projKey:i??``,name:n.options?.name??``,env:n.envs.get(),basePath:t(`${n.options.pageBasePage}${r.params.page}`),projKeyJson:t(String(r.query.projk??``)),signKey:t(n.config.signKey),options:t(n.options)},o=n.extends.renderView(`${r.params.page}.entry.tpl`,r,a),s=e.joinStr(a.basePath,a.name,a.env,a.projKey);if(!n.extends.localCacheHtmlEtag.hasEtag(s)){let e=n.extends.crypto.hmacSign(o);n.extends.localCacheHtmlEtag.setEtag(s,e)}let c=n.extends.localCacheHtmlEtag.getEtag(s);if(c||console.log(`---- etag 缓存异常 请检查服务 ----`),r.etag=c??Date.now()+``,r.fresh){r.status=304;return}}catch(e){console.log(`-------------- render view error --------------`),console.log(e),n.extends.generateErrorMessage(`template not found`,{status:404,showError:!0,code:0})}}}});module.exports=n;

package/esm/app/controller/view.js

@@ -23,7 +23,10 @@ var t = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u003e
 					n.extends.localCacheHtmlEtag.setEtag(s, e);
 				}
 				let c = n.extends.localCacheHtmlEtag.getEtag(s);
-				c || console.log("---- etag 缓存异常 请检查服务 ----"), r.etag = c ?? Date.now() + "";
+				if (c || console.log("---- etag 缓存异常 请检查服务 ----"), r.etag = c ?? Date.now() + "", r.fresh) {
+					r.status = 304;
+					return;
+				}
 			} catch (e) {
 				console.log("-------------- render view error --------------"), console.log(e), n.extends.generateErrorMessage("template not found", {
 					status: 404,

package/fe/frontend/src/common/rafTimer.d.ts

@@ -0,0 +1,7 @@
+export type RafTimerId = number;
+export type RafTimerCallback<Args extends unknown[] = []> = (...args: Args) => void;
+export declare const rafSetTimeout: <Args extends unknown[]>(callback: RafTimerCallback<Args>, delay?: number, ...args: Args) => RafTimerId;
+export declare const rafClearTimeout: (timerId: RafTimerId) => void;
+export declare const rafSetInterval: <Args extends unknown[]>(callback: RafTimerCallback<Args>, delay?: number, ...args: Args) => RafTimerId;
+export declare const rafClearInterval: (timerId: RafTimerId) => void;
+export declare const clearRafTimer: (timerId: RafTimerId) => void;

package/fe/frontend/src/common/rafTimer.js

@@ -0,0 +1,144 @@
+//#region frontend/src/common/rafTimer.ts
+var rafTimers = /* @__PURE__ */ new Map();
+var rafTimerSeed = 0;
+/**
+* 统一修正延迟时间，避免传入 undefined 或负数。
+*
+* @param delay 原始延迟时间。
+* @returns 不小于 0 的延迟时间。
+*/
+var normalizeDelay = (delay) => Math.max(0, delay ?? 0);
+/**
+* 确认当前环境支持 requestAnimationFrame。
+*/
+var assertRafAvailable = () => {
+	if (typeof requestAnimationFrame === "undefined" || typeof cancelAnimationFrame === "undefined") throw new Error("raf timer requires requestAnimationFrame and can only run in a browser environment.");
+};
+/**
+* 创建唯一的计时器 id。
+*
+* @returns 新的计时器 id。
+*/
+var createTimerId = () => {
+	rafTimerSeed += 1;
+	return rafTimerSeed;
+};
+/**
+* 删除并取消指定计时器。
+*
+* 步骤：
+* 1. 根据 id 查找计时器状态。
+* 2. 如果计时器不存在，直接结束。
+* 3. 取消下一帧回调，并从缓存中移除计时器。
+*
+* @param timerId 要取消的计时器 id。
+*/
+var deleteTimer = (timerId) => {
+	const timer = rafTimers.get(timerId);
+	if (!timer) return;
+	cancelAnimationFrame(timer.frameId);
+	rafTimers.delete(timerId);
+};
+/**
+* 每一帧执行一次的调度函数。
+*
+* 步骤：
+* 1. 读取当前计时器状态。
+* 2. 对比当前时间和起始时间/上次执行时间，判断是否到达延迟。
+* 3. timeout 到点后执行一次并删除计时器。
+* 4. interval 到点后执行回调，并更新上次执行时间。
+* 5. 如果计时器仍然存在，继续注册下一帧。
+*
+* @param timerId 当前计时器 id。
+* @param currentTime requestAnimationFrame 传入的当前时间戳。
+*/
+var tick = (timerId, currentTime) => {
+	const timer = rafTimers.get(timerId);
+	if (!timer) return;
+	if (timer.type === "timeout" ? currentTime - timer.startTime >= timer.delay : currentTime - timer.lastRunTime >= timer.delay) {
+		if (timer.type === "timeout") {
+			rafTimers.delete(timerId);
+			timer.callback();
+			return;
+		}
+		timer.lastRunTime = currentTime;
+		timer.callback();
+	}
+	if (rafTimers.has(timerId)) timer.frameId = requestAnimationFrame((nextTime) => tick(timerId, nextTime));
+};
+/**
+* 创建 requestAnimationFrame 计时器。
+*
+* 步骤：
+* 1. 检查当前运行环境是否支持 requestAnimationFrame。
+* 2. 创建计时器 id，并记录起始时间。
+* 3. 保存计时器类型、延迟、回调和帧 id 等状态。
+* 4. 注册第一帧调度。
+* 5. 将计时器状态写入缓存，并返回计时器 id。
+*
+* @param type 计时器类型。
+* @param callback 到点后执行的回调函数。
+* @param delay 延迟或间隔时间，单位毫秒。
+* @param args 传给回调函数的参数。
+* @returns 计时器 id。
+*/
+var createRafTimer = (type, callback, delay, args) => {
+	assertRafAvailable();
+	const timerId = createTimerId();
+	const startTime = performance.now();
+	const timer = {
+		type,
+		delay: normalizeDelay(delay),
+		callback: () => callback(...args ?? []),
+		startTime,
+		lastRunTime: startTime,
+		frameId: 0
+	};
+	timer.frameId = requestAnimationFrame((currentTime) => tick(timerId, currentTime));
+	rafTimers.set(timerId, timer);
+	return timerId;
+};
+/**
+* 使用 requestAnimationFrame 驱动，在指定延迟后执行一次回调。
+*
+* @param callback 延迟结束后执行的回调函数。
+* @param delay 延迟时间，单位毫秒，默认 0。
+* @param args 传给回调函数的参数。
+* @returns 计时器 id，可通过 rafClearTimeout 或 clearRafTimer 取消。
+*/
+var rafSetTimeout = (callback, delay, ...args) => createRafTimer("timeout", callback, delay, args);
+/**
+* 取消 rafSetTimeout 创建的计时器。
+*
+* @param timerId rafSetTimeout 返回的计时器 id。
+*/
+var rafClearTimeout = (timerId) => {
+	deleteTimer(timerId);
+};
+/**
+* 使用 requestAnimationFrame 驱动，按指定间隔重复执行回调。
+*
+* @param callback 每次间隔结束后执行的回调函数。
+* @param delay 间隔时间，单位毫秒，默认 0。
+* @param args 传给回调函数的参数。
+* @returns 计时器 id，可通过 rafClearInterval 或 clearRafTimer 取消。
+*/
+var rafSetInterval = (callback, delay, ...args) => createRafTimer("interval", callback, delay, args);
+/**
+* 取消 rafSetInterval 创建的计时器。
+*
+* @param timerId rafSetInterval 返回的计时器 id。
+*/
+var rafClearInterval = (timerId) => {
+	deleteTimer(timerId);
+};
+/**
+* 取消本模块创建的任意 requestAnimationFrame 计时器。
+*
+* @param timerId rafSetTimeout 或 rafSetInterval 返回的计时器 id。
+*/
+var clearRafTimer = (timerId) => {
+	deleteTimer(timerId);
+};
+//#endregion
+export { clearRafTimer, rafClearInterval, rafClearTimeout, rafSetInterval, rafSetTimeout };

package/fe/frontend/src/index.d.ts

@@ -6,6 +6,8 @@ export * from "./components/index";
 export type { FormFieldSchema, SchemaFormComponentsMap, SchemaFormNamespace, SelectProps } from "../../packages/react/ui/index";
 export { api, del, get, patch, post, put, request } from "./common/request";
 export type { AxiosError, BaseResponse, PageParams, PageResponse, RequestConfig, ResponseConfig } from "./common/request";
+export { clearRafTimer, rafClearInterval, rafClearTimeout, rafSetInterval, rafSetTimeout } from "./common/rafTimer";
+export type { RafTimerCallback, RafTimerId } from "./common/rafTimer";
 export * from "./defaultPages/SchemaPage/data/eventInfo";
 export { merge } from "./defaultPages/SchemaPage/utils/permissions";
 export * from "./exportStore";

package/fe/frontend/src/index.js

@@ -10,6 +10,7 @@ import { schemaEventBus } from "./stores/schemaEventBus.js";
 import { schemaStore, useSchemaStore } from "./stores/schemaStore.js";
 import "./exportStore.js";
 import { initApp } from "./main.js";
+import { clearRafTimer, rafClearInterval, rafClearTimeout, rafSetInterval, rafSetTimeout } from "./common/rafTimer.js";
 import AsyncSelect_default from "./components/AsyncSelect/index.js";
 import LanguageSwitch_default from "./components/LanguageSwitch/index.js";
 import { themeSwitchStorageKey } from "./components/ThemeSwitch/ThemeSwitch.js";
@@ -17,4 +18,4 @@ import ThemeSwitch_default from "./components/ThemeSwitch/index.js";
 import "./components/index.js";
 import { eventsInfo } from "./defaultPages/SchemaPage/data/eventInfo.js";
 import { merge } from "./defaultPages/SchemaPage/utils/permissions.js";
-export { AsyncSelect_default as AsyncSelect, FreezeState, HeaderView, LanguageSwitch_default as LanguageSwitch, ThemeSwitch_default as ThemeSwitch, api, apiFreezerStore, del, eventsInfo, generateRouter, get, getAuthToken, i18n, i18nStore, initApp, localKeyMap, merge, modeStore, patch, post, put, request, schemaEventBus, schemaStore, setAuthToken, themeSwitchStorageKey, useApiFreezer, useModeStore, useSchemaStore };
+export { AsyncSelect_default as AsyncSelect, FreezeState, HeaderView, LanguageSwitch_default as LanguageSwitch, ThemeSwitch_default as ThemeSwitch, api, apiFreezerStore, clearRafTimer, del, eventsInfo, generateRouter, get, getAuthToken, i18n, i18nStore, initApp, localKeyMap, merge, modeStore, patch, post, put, rafClearInterval, rafClearTimeout, rafSetInterval, rafSetTimeout, request, schemaEventBus, schemaStore, setAuthToken, themeSwitchStorageKey, useApiFreezer, useModeStore, useSchemaStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_tc/template-core",
-  "version": "0.2.0-bate.1",
+  "version": "0.2.0-bate.2",
   "description": "A full-stack TypeScript admin framework powered by Koa, React, and Vite - monorepo root",
   "types": "./types/index.d.ts",
   "exports": {