# 应用程序运行技巧 ## 概述 * 使用 TypeScript 中的 MVU（模型-视图-更新）构建 AppRun 应用程序。 * 为了可测试性，更喜欢纯更新函数。 * 对 JSX 中嵌入的组件使用“mounted()”。 * 仅对必须加载异步数据的顶级路由页面使用 `state = async`。 ## 项目设置 ### 推荐的项目结构 web/ # 前端应用程序根目录 ├── index.html # 入口HTML文件 ├── package.json # 依赖和脚本 ├── vite.config.js # Vite配置 ├── src/ │ ├── main.tsx # 应用程序入口点（路由注册） │ ├── api.ts # REST API 客户端（可选） │ ├── styles.css # 应用样式 │ ├── tsconfig.json # TypeScript 配置 │ ├── Components/ # 可复用的UI组件 │ │ ├── Layout.tsx # 根布局容器 │ │ └── ... # 其他可复用组件 │ ├── domain/ # 业务逻辑模块（可选） │ │ └── ... # 纯函数和业务逻辑 │ ├──pages/ # 顶级页面组件 │ │ ├── Home.tsx # 示例：主页 │ │ └── ... # 其他路线页面 │ ├── types/ # TypeScript 类型定义 │ │ ├── index.ts # 共享类型 │ │ └── jsx.d.ts # JSX 类型声明 │ └── utils/ # 实用函数 └── public/ # 静态资产（可选） ### 投票配置从“vite”导入{defineConfig} 导出默认的defineConfig({ 构建：{ outDir: '距离', 空输出目录：真， }, 服务器：{ 端口：8080，开放：真实， HistoryApiFallback: true, // SPA 模式代理：{ // 代理API请求到后端 '/api': { 目标：'http://127.0.0.1:3000', 更改来源：true，安全：假 } } } }) ### 包.json { “名称”：“我的应用程序”， “版本”：“1.0.0”， “类型”：“模块”， “脚本”：{ "dev": "vite", "build": "vite 构建", "preview": "vite 预览", “检查”：“tsc --noEmit” }, “开发依赖项”：{ "apprun": "^3.38.0", “打字稿”：“^5.0.0”， "vite": "^5.0.0" } } ### TypeScript 配置 { “编译器选项”：{ “目标”：“ES2020”， “模块”：“ESNext”， "lib": ["ES2020", "DOM", "DOM.Iterable"], “jsx”：“反应”， "jsxFactory": "app.createElement", "jsxFragmentFactory": "应用程序.Fragment", "moduleResolution": "捆绑器", “resolveJsonModule”：true， “isolatedModules”：正确， “严格”：真实， “esModuleInterop”：正确， “skipLibCheck”：正确， “forceConstantCasingInFileNames”：true }, “包括”：[“src / ** / *”]， “排除”：[“node_modules”] } **AppRun 的关键设置：** * `jsx: "react"` \- 启用 JSX 语法 * `jsxFactory: "app.createElement"` \- 使用 AppRun 的 JSX 工厂 * `jsxFragmentFactory: "app.Fragment"` \- 使用 AppRun 的 Fragment 支持 * `moduleResolution: "bundler"` \- 针对 Vite 进行了优化 ### 入口点 **HTML 条目 (`index.html`):** <头> <元字符集=“UTF-8”> 我的AppRun应用 <正文>

<脚本类型=“模块”src=“src/main.tsx”> **应用程序入口（`src/main.tsx`）：** 从“apprun”导入应用程序；从'./components/Layout'导入布局；从 './pages/Home' 导入主页；从 './pages/About' 导入关于；导入'./styles.css'; app.render('#root', ); app.addComponents('#pages', { '/'：首页， '/关于'：关于， }); **布局组件（`src/components/Layout.tsx`）：** 从“apprun”导入应用程序；导出默认 () => (

）； ### 样式选项 **选项 1：普通 CSS** /* src/styles.css */ ：根{ --颜色主色：#007bff； --颜色文本：#333； --间距单位：8px； } 身体{ 字体系列：system-ui、-apple-system、sans-serif；颜色：var(--颜色文本)；保证金：0；填充：0； } **选项 2：Tailwind CSS v4** 安装 Tailwind v4： npm install -D tailwindcss@next @tailwindcss/vite@next 更新`vite.config.js`：从“vite”导入{defineConfig} 从“@tailwindcss/vite”导入 tailwindcss 导出默认的defineConfig({ 插件：[tailwindcss()]， // ...其他配置 }) 在 `src/styles.css` 中导入： @导入“tailwindcss”；在组件中的使用：

你好世界

**选项 3：CSS 模块** 从 './MyComponent.module.css' 导入样式；导出默认 () => (

你好

）； ### API 客户端模式 // src/api.ts const API_BASE_URL = '/api'; 接口 RequestOptions 扩展 RequestInit { 参数？：记录<字符串，字符串>； } 异步函数请求( 端点：字符串，选项：请求选项 = {} ): 承诺 { const { params, ...fetchOptions } = 选项; 让 url = `${API_BASE_URL}${endpoint}`; 如果（参数）{ const query = new URLSearchParams(params).toString(); url += `?${query}`; } const 响应 = 等待获取（url，{ 标题：{ '内容类型'：'应用程序/json'， ...fetchOptions.headers， }, ...获取选项， }); 如果（！response.ok）{ const error =等待response.json().catch(() => ({})); 抛出新错误(error.message || `HTTP ${response.status}`); } 返回response.json(); } 导出常量 API = { 获取：（端点：字符串，参数？：记录<字符串，字符串>）=> 请求 (端点, { 方法: 'GET', 参数 }), 帖子：（端点：字符串，数据？：未知）=> 请求（端点，{ 方法：'POST'，正文：JSON.stringify（数据）， }), put：（端点：字符串，数据？：未知）=> 请求（端点，{ 方法：'放置'，正文：JSON.stringify（数据）， }), 删除：（端点：字符串）=> 请求 (端点, { 方法: '删除' }), }; 导出默认api； ### 快速入门 # 1.创建项目 npm create vite@latest my-apprun-app -- --template vanilla-ts cd my-apprun-app # 2.安装AppRun npm 安装 npm安装-D apprun # 3. 配置 TypeScript（使用上述设置更新 tsconfig.json） # 4. 重命名入口文件 mv src/main.ts src/main.tsx # 5. 创建基本的应用程序结构 #（添加布局、页面、组件如上所示） # 6. 运行开发服务器 npm 运行开发 # 7. 为生产而构建 npm 运行构建 npm 运行预览 ### 为什么选择 Vite + AppRun？ **为什么选择：** * 通过即时 HMR 快速开发 * 使用 Rollup 优化构建 * 一流的 TypeScript 支持 * 最低配置 **为什么选择AppRun：** * 轻量级（gzip 压缩后约 7KB） * 简单的MVU模式 * 直接 DOM 更新（无虚拟 DOM） * 完整的 TypeScript 支持 * 内置路由 ## 组件模式 - 决策树 1. **Manages state + user interactions?** → Stateful Class Component 2. **弹出/模态/叠加？** → 模态组件（使用 `mounted()`） 3. **仅从 props 中显示？** → 功能组件 4. **10+ events needing type safety?** → Typed Events Pattern ## 有状态类组件 **Structure Order:** Imports → Interfaces → Helpers → Actions → Component 从 'apprun' 导入 { app, Component }; 接口 Props { 数据？：任意； } 导出接口状态{ 加载：布尔值；错误：字符串|无效的; 成功消息？：字符串； // ... 特定字段 } const getStateFromProps = (props: Props): State => ({ /* ... */ }); export const saveData = async function* (state: State): AsyncGenerator { // 验证 if (!state.data.name.trim()) { yield { ...state, error: '需要名称' }; 返回; } // 正在加载产量{ ...状态，加载：true，错误：null }; // API调用尝试{ 等待 api.save(state.data); yield { ...state, loading: false, successMessage: 'Saved!' }; app.run('数据已保存'); } catch（错误：任何）{ yield { ...state, loading: false, error: error.message }; } }; export default class MyComponent extends Component { 声明道具：Readonly; mounted = (props: Props): State => getStateFromProps(props); 视图=（状态：状态）=> { if (state.loading) return

正在加载...

; if (state.error) return

{state.error}

; 返回（ <表格> <输入$bind =“数据.name”/> <按钮 $onclick={[saveData]} 禁用={state.loading}>保存）； }; } **View Pattern:** Guard clauses → Early returns → Main content ## 模态组件 **CRITICAL:** Must use `mounted()` (embedded in JSX), not `state = async` export default class Modal extends Component { 声明道具：Readonly; mounted = (props: Props): State => getStateFromProps(props); 视图=（状态：状态）=>（

e.stopPropagation()}> <按钮onclick={closeModal}>× {/*内容*/}

）； } **Requirements:** Close button + backdrop click + stopPropagation ## 功能组件导出接口 Props { 数据：数据类型[]； onItemClick?: (项目: DataType) => void; } export default function DisplayComponent({ data, onItemClick }: Props) { if (!data?.length) return

没有项目

; 返回（

onItemClick?.(item)}>{item.name}

）； } **Pattern:** Destructure → Guard clauses → Main render ## 类型化事件模式 **负载规则：** 1. 单值 → `payload: string` |调用：`$onclick={['delete', id]}` 2. 多个值 → `payload: { id: string;名称：字符串 }` |调用：`$onclick={['edit', { id, name }]}` 3. 无有效负载 → `有效负载：void` |调用：`$onclick="保存"` 4. 输入事件 → `payload: { target: { value: string } }` // 类型/events.ts 导出类型 MyEvents = | { name: '保存';有效负载：无效} | { name: '删除';有效负载：字符串} | { 名称: '编辑';有效负载：{ id：字符串；名称：字符串 } }; 导出类型 MyEventName = MyEvents['name']; // 组件类 MyComponent 扩展 Component { 覆盖更新= myHandlers； } // 处理程序（OBJECT 格式，而不是数组）导出 const myHandlers: Update = { 保存：（状态）：状态=>（{...状态，保存：true}），删除：（状态，id：字符串）：状态=>（{ ...状态， items: state.items.filter(i => i.id !== id) }), 编辑：（状态，{id，名称}：{id：字符串；名称：字符串}）：状态=>（{ ...状态，编辑：{ id，名称 } }) }; **stopPropagation：** 添加事件作为最后一个参数 'click-item': (state, id: string, e?: Event): State => { e?.stopPropagation(); 返回 { ...状态，选择：id }; } ## 事件指令 ### AppRun 指令（触发更新处理程序）指令|使用案例|示例 ---|---|--- `$bind="字段"` |双向绑定（首选表单）| `<输入$bind =“名称”/>` `$bind="nested.field"` |嵌套属性 | `` `$onclick="操作"` |弦动作| `<按钮 $onclick="保存"/>` `$onclick={['action', data]}` |带参数的操作 | ` ## 关键规则 ### 状态初始化组件类型 |使用 |示例 ---|---|--- JSX 嵌入式 | `安装()` | `mounted = (props) => getStateFromProps(props)` 顶级路由| `状态 = 异步` | `state = async () => { const data = wait api.fetch();返回{数据}； }` **❌切勿混合使用** `mounted()` 和 `state = async` ### 状态更新 **返回状态触发重新渲染：** * 不可变（推荐）：`return { ...state, field: value }` * 可变（允许）：`state.field = value;返回状态` * 仅副作用：不返回（不重新渲染） ### 必需的状态属性接口状态{ 加载：布尔值； // 对于异步操作错误：字符串|无效的; // 对于错误消息成功消息？：字符串； // 成功反馈 // ... 特定字段 } ### 深度克隆 // 嵌套对象更新返回{ ...状态，用户：{ ...状态.用户，简介：{ ...状态.用户.个人资料，姓名 } } }; ## 反模式 **❌不要：** // 不要将 $onclick 与调用 app.run 的箭头函数一起使用 $onclick={() => app.run('action')} // 不要忘记异步中的错误处理异步函数 save() { 等待 api.save(); } // 没有 try-catch！ // 当 $bind 可用时不要使用手动输入 $oninput={(e) => setState({ ...state, field: e.target.value })} // 不要对 JSX 嵌入式组件使用 state = async 模态类扩展组件 { state = async () => { /* 错误 */ }; } // 不要忘记防御性编程 messages.map() // 消息可能未定义 - 使用 messages?.map() // 不要对更新处理程序使用数组格式 update = [['event', handler]] // 错误 - 使用对象格式 // 不要直接改变状态状态.count++； // 错误 ## 路由、链接和组件注册本节介绍 AppRun 应用程序如何处理路由、页面导航和组件注册。 ### 概述该应用程序使用AppRun的内置路由系统，无需任何外部路由器库。路由以声明方式定义，导航使用标准 HTML 锚标记或编程方法。 ### 1\.组件注册路由集中注册在“main.tsx”中：从“apprun”导入应用程序；从'./components/Layout'导入布局；从 './pages/Home' 导入主页；从 './pages/World' 导入世界； app.render('#root', ); app.addComponents('#pages', { '/'：首页， '/世界'：世界， // '/Agent': 代理, // 注释掉 // '/Settings': 设置, // 注释掉 }); **它是如何工作的：** * **`app.render('#root',)`**：将顶级布局组件渲染到`#root` DOM元素中 * **`app.addComponents('#pages', {...})`** : 注册路由到组件的映射 * 键：路线路径（例如，`'/'`、`'/World'`） * 值：组件类（例如，`Home`、`World`） * 组件被渲染到布局中定义的`#pages`容器中 ### 2\.布局容器 Layout 组件为路由页面提供渲染容器： // web/src/components/Layout.tsx 导出默认 () =>

* 具有全宽、全高容器的最小包装器 * `#pages` div 是动态渲染路由组件的地方 * AppRun根据当前路线自动交换组件 ### 3\.页面链接（声明性导航）该应用程序使用**标准 HTML 锚标记**进行导航： **来自家庭组件的示例：** // 导航到一个特定的世界 <按钮类名=“btn btn-primary”> 输入{世界名称} **世界组件示例：** // 导航回到首页

应用技能

包含技能