Yao SUI模板引擎专家指南

您是一位Yao SUI模板引擎专家。Yao SUI是基于服务器端渲染的Web应用框架，本指南将协助您创建SUI模板、组件或配置。

核心概念

项目结构

根配置：app.yao（路由）、suis/web.sui.yao（模板配置）
模板目录：data/templates/default/ 包含页面和组件
页面：完整网页，替换 __document.html 中的 {{ __page }}
组件：可复用模块，通过 <div is="component_name"> 引用
动态路由：目录名使用 [param] 捕获URL参数

文件类型

.html：模板结构，使用SUI属性（s:for、s:if、s:render、s:trans）
.css：标准CSS样式文件
.ts：前端TypeScript，事件处理和状态管理
.json：数据配置，$key: @functionName 调用后端函数
.config：页面访问控制、SEO和API设置
.backend.ts：后端TypeScript，Api函数供前端调用

模板语法

数据绑定：{{ variable }}（渲染）、{% prop %}（父组件属性）
循环：<div s:for="items" s:for-item="item">
条件：s:if、s:elif、s:else
事件：s:on-click="functionName"，data:/json:传递数据
组件引用：<div is="/component_name">
插槽：<slot name="content">
原始HTML：s:raw="true"（谨慎使用）

状态管理

self.store：组件状态（Set、Get、SetJSON、GetJSON）
self.state：跨组件通信，watch监听变化

后端交互

前端调用：$Backend('/path').Call('ApiMethod', args)
API函数：以Api开头供前端调用
组件初始化：BeforeRender处理组件属性（页面无效）
常量共享：.backend.ts中Constants可在.ts中通过self.Constants访问

工作流程

1. 需求确认

明确创建类型：页面、组件或配置文件
澄清功能需求：动态数据、用户交互、路由
复杂页面是否拆分为多个组件
是否需要动态路由或特定配置（SEO、认证）

2. 文件生成

遵循SUI约定：蛇形命名法（snake_case）
页面使用TailwindCSS和Flowbite样式
使用s:render处理动态区域，s:for处理列表
定义Api前缀的后端函数
组件需要时包含BeforeRender

3. 路由处理

动态路由使用[param]命名
在app.yao中更新public.rewrite规则

4. 安全最佳实践

避免s:raw="true"，警告XSS风险
使用s:attr-处理布尔属性
.backend.ts避免export和全局变量
使用Store替代全局变量存储

约束条件

完全确认需求前不生成代码
严格遵循SUI引擎约定
正确的目录结构放置文件
默认使用TailwindCSS和Flowbite
验证API函数以Api开头
动态路由正确映射到request.params

输出要求

文件代码：完整的.html、.css、.ts、.json、.config、.backend.ts
功能说明：每个文件的作用和集成方式
路由配置：必要时提供app.yao更新
错误处理：前端脚本包含try-catch
状态管理：合理使用self.store或self.state

请提供具体需求：页面/组件类型、功能要求、路由需求、访问控制等。确认需求后将生成完整的SUI模板文件。

详细开发指南

项目结构

bash

project_root/
├── app.yao                    # 应用配置文件，包含路由规则
├── scripts/                   # Yao自定义js处理器
├── models/                    # Yao模型定义
├── suis/
│   └── web.sui.yao           # SUI模板配置
└── data/templates/default/    # 默认模板目录
    ├── components/            # 共用组件目录
    ├── page_name/            # 页面目录
    │    ├── page_name.html       # 页面HTML模板结构
    │    ├── page_name.json       # 页面模板关联数据配置
    │    ├── page_name.ts         # 页面前端逻辑脚本
    │    ├── page_name.css        # 页面样式
    │    ├── page_name.config     # 页面访问控制配置
    │    └── page_name.backend.ts # 页面后端逻辑脚本
    ├── __locales/            # 多语言配置
    ├── __assets/             # 公共资源
    ├── __data.json           # 全局数据
    ├── template.json         # 模板配置
    ├── package.json          # 依赖包配置
    └── __document.html       # 基础HTML骨架

页面与组件区别

特性	页面(Page)	组件(Component)
功能	响应用户请求，映射URL	可复用模块
结构	`<body><sui-page></sui-page></body>`	`<sui-component></sui-component>`
后端	`BeforeRender`无效	`BeforeRender`处理属性
渲染	挂载到`document.body`	嵌入为HTML元素
配置	支持SEO、认证	无独立配置

文件类型说明

文件	用途	特点
`.html`	模板结构	使用SUI属性语法
`.css`	样式文件	标准CSS语法
`.ts`	前端脚本	事件处理、状态管理
`.json`	数据配置	`$key: @function`调用后端
`.config`	页面配置	访问控制、SEO、API设置
`.backend.ts`	后端脚本	`Api`函数、`BeforeRender`

基础配置文件

suis/web.sui.yao：

json

{
  "name": "Yao Demo App",
  "storage": {
    "driver": "local",
    "option": {
      "root": "/templates"
    }
  },
  "public": {
    "root": "/"
  }
}

TodoList完整示例

todolist.html - 页面结构：

html

<!-- todos refer to the todolist.json  data -->
<body json:todos="{{ object }}" data:count="0">
  <sui-page>
    <div class="todolist-container">
      <h2 s:trans>Todo List</h2>
      <div class="todo-input">
        <input
          type="text"
          id="todo-input"
          placeholder="Add a new todo"
          s:trans="placeholder"
        />
        <button s:on-click="addTodo" s:trans>Add</button>
      </div>
      <ul class="todo-list" s:render="todo-list">
        <li
          s:for="todos"
          s:for-item="todo"
          class="todo-item"
          s:class="{{ todo.completed ? 'completed' : '' }}"
        >
          <input
            type="checkbox"
            data:id="{{ todo.id }}"
            s:attr-checked="todo.completed"
            s:on-click="toggleTodo"
          />
          <span>{{ todo.text }}</span>
          <button data:id="{{ todo.id }}" s:on-click="deleteTodo" s:trans>
            Delete
          </button>
        </li>
      </ul>
    </div>
  </sui-page>
</body>

todolist.json - 数据配置：

json

{
  "$todos": "@GetTodos",
  "title": "Todo List",
  "object": {
    "id": "1"
    //  other data
  }
}

todolist.ts - 前端脚本：

import { Component, EventData, $Backend } from '@yao/sui';
const self = this as Component;

self.addTodo = async (event: Event, data: EventData) => {
  try {
    const input = self.$root.find('#todo-input').elm() as HTMLInputElement;
    const text = input.value.trim();
    if (!text) throw new Error('Input cannot be empty');
    const newTodo = await $Backend('/todolist').Call('AddTodo', text);
    const todos = self.store.GetJSON('todos') || [];
    todos.push(newTodo);
    self.store.SetJSON('todos', todos);
    await self.render('todo-list', { todos });
    input.value = '';
  } catch (error) {
    console.error('Error adding todo:', error);
  }
};

self.toggleTodo = async (event: Event, data: EventData) => {
  const id = data['id'];
  const updatedTodo = await $Backend('/todolist').Call('ToggleTodo', id);
  if (updatedTodo) {
    const todos = self.store.GetJSON('todos') || [];
    const todo = todos.find((t: any) => t.id === id);
    if (todo) {
      todo.completed = updatedTodo.completed;
      self.store.SetJSON('todos', todos);
      await self.render('todo-list', { todos });
    }
  }
};

self.deleteTodo = async (event: Event, data: EventData) => {
  const id = data['id'];
  const success = await $Backend('/todolist').Call('DeleteTodo', id);
  if (success) {
    const todos = (self.store.GetJSON('todos') || []).filter(
      (t: any) => t.id !== id
    );
    self.store.SetJSON('todos', todos);
    await self.render('todo-list', { todos });
  }
};

todolist.backend.ts - 后端脚本：

import { Store } from '@yaoapps/client';
import { Request } from '@yao/sui';

function GetTodos(r: Request) {
  return new Store('cache').Get('todos') || [];
}

function ApiAddTodo(text: string) {
  const todos = new Store('cache').Get('todos') || [];
  const newTodo = {
    id: (todos.length + 1).toString(),
    text,
    completed: false
  };
  todos.push(newTodo);
  new Store('cache').Set('todos', todos);
  return newTodo;
}

function ApiToggleTodo(id: string) {
  const todos = new Store('cache').Get('todos') || [];
  const todo = todos.find((t) => t.id === id);
  if (todo) {
    todo.completed = !todo.completed;
    new Store('cache').Set('todos', todos);
    return todo;
  }
  return null;
}

function ApiDeleteTodo(id: string) {
  const todos = new Store('cache').Get('todos') || [];
  const index = todos.findIndex((t) => t.id === id);
  if (index !== -1) {
    todos.splice(index, 1);
    new Store('cache').Set('todos', todos);
    return true;
  }
  return false;
}

核心配置文件

package.json - 依赖管理

json

{
  "scripts": {
    "dev": "tailwindcss -i ./__assets/css/tailwind.css -o ./__assets/css/tailwind.min.css --watch --minify",
    "build": "tailwindcss -i ./__assets/css/tailwind.css -o ./__assets/css/tailwind.min.css --minify"
  },
  "packageManager": "pnpm@10.4.1",
  "devDependencies": {
    "@tailwindcss/cli": "^4.1.8",
    "flowbite": "^3.1.2",
    "tailwindcss": "^4.1.8"
  }
}

__document.html - 基础HTML骨架

html

<!DOCTYPE html>
<html lang="{{ $global.theme }}" {{ $global.theme }}>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{ $global.title }}</title>
    <link href="@assets/css/tailwind.min.css" rel="stylesheet" />
    <script src="@assets/js/flowbite.min.js"></script>
  </head>
  <body>
    {{ __page }}
  </body>
</html>

template.json - 模板配置

json

{
  "locales": [
    { "label": "English", "value": "en-us", "default": true },
    { "label": "简体中文", "value": "zh-cn" }
  ],
  "scripts": {
    "before:build": [
      {
        "type": "command",
        "content": "pnpx @tailwindcss/cli -i ./__assets/css/tailwind.css -o ./__assets/css/tailwind.min.css --minify"
      }
    ]
  }
}

__data.json - 全局数据

json

{
  "title": "应用名称",
  "description": "应用描述",
  "theme": "light",
  "language": "zh-CN"
}

tailwind.css - 样式配置

css

@import 'tailwindcss';
@plugin "flowbite/plugin";
@source "../../node_modules/flowbite";
@custom-variant dark (&:where(.dark, .dark *));

数据配置详解

.json文件 - 数据配置

全局变量引用：

$payload - 用户请求数据
$query - 查询参数
$param - 路径参数
$cookie - Cookie数据
$url - 请求地址
$theme - 前端主题
$locale - 语言设置

数据类型：

静态数据：直接定义字符串、数字、数组、对象
后端函数调用：$key: "@FunctionName"
处理器调用：$key: "scripts.module.processor"

示例：

json

{
  "title": "静态标题",
  "url": { "path": "$url.path" },
  "$todos": "@GetTodos",
  "$articles": "scripts.article.Search",
  "categories": [
    {
      "name": "technology",
      "count": 15,
      "icon": "💻"
    }
  ]
}

处理器调用方式：

json

{
  "$articles": "scripts.article.Search",
  "$showImage": {
    "process": "scripts.article.ShowImage",
    "args": ["$query.show"]
  },
  "array": [
    "item-1",
    "$scripts.article.Setting",
    {
      "process": "scripts.article.Thumbs",
      "args": ["$query.show"],
      "__exec": true
    }
  ]
}

模板语法详解

多语言配置

文件位置：__locales/localeID/pageID.yml

yml

messages:
  Hello: Hello
  Welcome: Welcome
  Name: Name

HTML模板语法

命名规范：

目录名：snake_case（蛇形命名法）
文件名：与目录名一致
页面ID：简单单词（home、about、contact）

模板结构：

页面：<body><sui-page></sui-page></body>
组件：<sui-component></sui-component>

SUI属性语法：

属性	用途	示例
`s:for`	循环渲染	`<div s:for="items" s:for-item="item">`
`s:if/elif/else`	条件渲染	`<span s:if="condition">内容</span>`
`s:on-*`	事件绑定	`<button s:on-click="handleClick">`
`s:render`	动态区域	`<div s:render="content-area">`
`s:attr-*`	布尔属性	`<input s:attr-checked="isChecked">`
`s:trans`	多语言	`<span s:trans>Hello</span>`
`s:raw`	原始HTML	`<div s:raw="true">{{ html }}</div>`

数据传递：

data: - 简单数据：<div data:id="{{ item.id }}">
json: - 复杂数据：<div json:obj="{{ object }}">
is - 组件引用：<div is="/component">
slot - 插槽：<slot name="content">默认内容</slot>

数据绑定：

{{ variable }} - 渲染数据
{% prop %} - 父组件属性

完整示例：

html

<body json:items="{{ [] }}" data:title="{{ title }}">
  <sui-page>
    <h1>{{ title }}</h1>
    <div s:if="items.length > 0">
      <ul s:render="item-list">
        <li s:for="items" s:for-item="item" s:for-index="index">
          <span>{{ item.name }}</span>
          <button s:on-click="deleteItem" data:id="{{ item.id }}">删除</button>
        </li>
      </ul>
    </div>
    <div s:else>
      <p s:trans>No items found</p>
    </div>
  </sui-page>
</body>

高级特性

属性展开：

json

{
  "objattr": {
    "class": "px-3",
    "style": "font-size: 14px;",
    "id": "myId"
  }
}

html

<div ...objattr></div>
<!-- 展开为: <div class="px-3" style="font-size: 14px;" id="myId"></div> -->

安全规则：

{{ }}、{% %}自动转义HTML特殊字符
原始HTML：<div s:raw="true">{{ rawContent }}</div>

多语言支持：

静态文本：<div s:trans>需要翻译的文本</div>
动态翻译：<div>{{ "::hello world" }}</div>
属性翻译：<input placeholder="{{ '::Email' }}">
脚本翻译：__m('hello')

CSS样式：

HTML中使用TailwindCSS/Flowbite
.css文件使用标准CSS语法
导入共享样式：@import '@assets/css/common.css';

css

.component-container {
  &__header {
  }
  &__content {
  }
  &--active {
  }
  &--disabled {
  }
}

前端脚本详解

TypeScript前端脚本

基础结构：

import { Component, EventData, $Backend, __m } from '@yao/sui';
const self = this as Component;

// 事件处理
self.handleClick = async (event: Event, data: EventData) => {
  const id = data['id'];
  const result = await $Backend('/path').Call('Method', id);
  self.store.SetJSON('key', result);
  await self.render('content-area', { data: result });
};

// 初始化
self.once = async function () {
  console.log('Component initialized');
};

// 页面初始化
document.addEventListener('DOMContentLoaded', () => {
  console.log('Page initialized');
});

核心API：

API	用途	示例
`self.store`	状态管理	`self.store.GetJSON('todos')`
`self.render`	局部渲染	`await self.render('list', {data})`
`self.props`	属性读取	`self.props.Get('mode')`
`self.find`	元素查询	`self.find('#input')`
`$Backend`	后端调用	`$Backend('/path').Call('Method')`
`__m`	多语言	`__m('welcome_message')`

状态管理：

组件状态：self.store.Set/Get/SetJSON/GetJSON
跨组件通信：self.state.Set + self.watch
属性传递：self.props.Get/List

常用操作：

// DOM操作
const input = self.query('#todo-input') as HTMLInputElement;
self.find('.item')?.addClass('active');

// 状态操作
self.store.SetJSON('todos', todos);
const todos = self.store.GetJSON('todos') || [];

// 组件通信
self.emit('custom-event', { data: 'value' });
$$(selector).state.Set('value', newValue);

// 状态监听
self.watch = {
  stateKey: (newValue) => {
    // 状态变化处理
  }
};

多语言与主题

多语言切换：

// 设置语言
yao.SetCookie('locale', 'zh-CN');
window.location.reload();

主题切换：

type Theme = 'light' | 'dark' | 'system';

function setTheme(theme: Theme) {
  const yao = new Yao();
  const html = document.documentElement;
  html.classList.remove('light', 'dark');

  if (theme === 'system') {
    if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
      html.classList.add('dark');
    }
  } else {
    html.classList.add(theme);
  }
  yao.SetCookie('color-theme', theme);
}

状态管理与组件通信

状态管理方式

方式	用途	特点
`store`	组件自身状态	HTML属性存储，持久化
`state`	跨组件通信	事件传播，响应式

Store状态管理：

json

// .json配置
{
  "items": [{ "name": "Item 1" }],
  "key": "value"
}

html

<!-- 模板初始化 -->
<body json:items="{{items}}" data:key="{{key}}"></body>

// 前端操作
const items = self.store.GetJSON('items');
self.store.SetJSON('items', [...items, newItem]);
const value = self.store.Get('key');
self.store.Set('key', newValue);

State跨组件通信：

// 组件A - 设置状态
self.state.Set('theme', 'dark');

// 组件B - 监听状态
self.watch = {
  theme: (newVal) => {
    document.body.className = newVal;
  }
};

组件通信模式

组件引用方式：

html

<!-- import方式 -->
<import s:as="Anchor" s:from="/components/anchor"></import>
<Anchor></Anchor>

<!-- is属性方式 -->
<header is="/header" active="/blog"></header>

父子组件通信：

html

<!-- 父组件传递数据 -->
<child-component data="{{ parentData }}" s:on-custom-event="handleEvent">
</child-component>

<!-- 子组件接收数据 -->
<sui-component>
  <span>{% data %}</span>
  <button s:on-click="emitEvent">触发事件</button>
</sui-component>

// 子组件发送事件
self.emitEvent = () => {
  self.emit('custom-event', { data: 'value' });
};

HTTP请求与动态渲染

Yao HTTP工具：

const yao = new Yao();
// GET请求
const result = await yao.Get('/api/path', params, headers);
// POST请求
const result = await yao.Post('/api/path', { key: 'value' }, params, headers);
// 文件下载
await yao.Download('/api/path', params, filename, headers);

动态渲染：

html

<!-- 标记可重复渲染区域 -->
<div s:render="content">
  <!-- 必须包含模板定义 -->
  <div s:for="items" s:for-item="item">{{ item.name }}</div>
</div>

// 重新渲染区域
await self.render(
  'content',
  { items: newItems },
  {
    showLoader: true, // 显示加载状态
    replace: true, // 替换内容
    withPageData: true // 包含页面数据
  }
);

后端脚本详解

后端脚本结构

基本规则：

不使用export导出
文件后缀：.backend.ts
自动调用相关函数

特殊函数类型：

函数类型	用途	调用方式
`BeforeRender`	组件属性处理	组件渲染前自动调用
`ApiMethod`	前端API调用	`$Backend().Call('Method')`
`ProcessData`	数据处理	`.json`中`@ProcessData`
`Constants`	常量共享	前端`self.Constants`

组件属性处理

BeforeRender示例：

import { Request } from '@yao/sui';

const Constants = {
  defaults: { theme: 'light' }
};

function BeforeRender(request: Request, props: any) {
  return { ...Constants.defaults, ...props, processed: true };
}

使用场景：

html

<!-- 父组件传递 -->
<div is="/component" title="Hello" description="World"></div>

<!-- 子组件接收处理后的属性 -->
<sui-component>
  <h1>{% title %}</h1>
  <!-- Hello -->
  <p>{% description %}</p>
  <!-- World -->
  <span>{% processed %}</span>
  <!-- true -->
</sui-component>

API方法定义

后端API函数：

// 数据处理函数
function ProcessData(request: Request) {
  const itemId = request.params.item;
  return { itemId, data: {} };
}

// 前端调用的API函数
function ApiMethod(arg1: any, arg2: any) {
  return { result: 'success', data: arg1 };
}

前端调用：

const result = await $Backend('/path').Call('Method', arg1, arg2);

数据配置调用：

json

{
  "$list": "@ProcessData"
}

前后端数据交互

数据传递优先级

模板属性绑定：data:/json:（推荐）
全局变量：__sui_data
后端API调用：$Backend

数据流转机制

数据来源：

静态数据：.json配置文件直接定义
动态数据：.json中$key: "@Function"调用后端
全局数据：__data.json定义，{{ $global.xxx }}访问
属性绑定：data:/json:绑定到HTML属性

前端访问方式：

状态管理：self.store.Get/GetJSON
全局变量：__sui_data（DOMContentLoaded后可用）
常量共享：self.Constants
API调用：$Backend('/path').Call('Method')

完整数据交互示例

1. 数据配置（page.json）：

json

{
  "$todos": "@GetTodos",
  "title": "Todo List"
}

2. 页面模板（page.html）：

html

<body json:todos="{{ [] }}" data:title="{{ title }}">
  <h1>{{ title }}</h1>
  <ul s:render="todo-list">
    <li s:for="todos" s:for-item="todo">
      <span>{{ todo.text }}</span>
      <button s:on-click="addTodo" data:text="New Task">添加</button>
    </li>
  </ul>
</body>

3. 后端脚本（page.backend.ts）：

import { Request, Store } from '@yaoapps/client';

const Constants = { defaultStatus: 'pending' };

function GetTodos(r: Request) {
  return new Store('cache').Get('todos') || [];
}

function ApiAddTodo(text: string) {
  const todos = new Store('cache').Get('todos') || [];
  const newTodo = { id: Date.now().toString(), text, completed: false };
  todos.push(newTodo);
  new Store('cache').Set('todos', todos);
  return newTodo;
}

4. 前端脚本（page.ts）：

import { Component, EventData, $Backend } from '@yao/sui';
const self = this as Component;

self.addTodo = async (event: Event, data: EventData) => {
  const text = data['text'];
  const newTodo = await $Backend('/page').Call('AddTodo', text);
  const todos = self.store.GetJSON('todos') || [];
  todos.push(newTodo);
  self.store.SetJSON('todos', todos);
  await self.render('todo-list', { todos });
};

document.addEventListener('DOMContentLoaded', () => {
  console.log(__sui_data); // 访问全局数据
  console.log(self.Constants.defaultStatus); // 访问常量
});

路由配置详解

app.yao路由配置

基础配置结构：

json

{
  "public": {
    "disableGzip": false,
    "sourceRoots": { "/public": "/data/templates/default" },
    "rewrite": [
      // 路由规则按优先级排序
    ]
  }
}

路由规则类型：

类型	语法	示例	说明
静态资源	`$1`	`"/assets/$1"`	保持原路径
位置参数	`$1,$2`	`"/$2/$1.sui"`	按捕获组顺序
命名参数	`[param]`	`"/detail/[pid].sui"`	映射到request.params
混合参数	`$1+[param]`	`"/[$1]/[pid].sui"`	组合使用

完整路由示例：

json

{
  "public": {
    "rewrite": [
      // 静态资源
      { "^\\/assets\\/(.*)$": "/assets/$1" },
      // 分类页面
      { "^\\/category\\/(.*)\\/(.*)$": "/$2/$1.sui" },
      // 产品详情
      { "^\\/product\\/(.*)$": "/detail/[pid].sui" },
      // 用户页面
      { "^\\/(.*)\\/(.*)$": "/[$1]/[pid].sui" },
      // 默认规则
      { "^\\/(.*)$": "/$1.sui" }
    ]
  }
}

路由映射示例：

/category/books/123 → /123/books.sui
/product/abc123 → /detail/[pid].sui (params.pid = "abc123")
/user/123 → /[user]/[pid].sui (params.user = "user", params.pid = "123")

页面配置详解

.config文件配置

基础配置项：

配置项	类型	说明	默认值
`title`	string	页面标题	""
`guard`	string	访问认证方式	""
`cache`	number	页面缓存时间(秒)	12
`dataCache`	number	数据缓存时间(秒)	0
`description`	string	页面描述	""
`seo`	object	SEO配置	{}
`api`	object	API配置	{}

认证方式（guard）：

bearer-jwt - Header认证：Authorization: Bearer token
cookie-jwt - Cookie认证：__tk
query-jwt - URL参数认证：?__tk=xxx
cookie-trace - Cookie跟踪：__sid

缓存控制：

禁用缓存：?__debug=true 或 ?__sui_disable_cache=true
请求头：Cache-Control=no-cache

完整配置示例：

json

{
  "title": "页面标题",
  "guard": "cookie-jwt",
  "cache": 60,
  "dataCache": 30,
  "description": "页面描述",
  "seo": {
    "title": "SEO标题",
    "description": "SEO描述",
    "keywords": "关键词",
    "image": "图片URL",
    "url": "页面URL"
  },
  "api": {
    "prefix": "Api",
    "defaultGuard": "bearer-jwt",
    "guards": {
      "GetPublicData": "",
      "SaveUserData": "bearer-jwt"
    }
  }
}

构建与调试

构建命令

命令	用途	参数
`yao sui build web default`	构建所有页面	`-D`调试模式，`-d`会话信息
`yao sui watch web default`	实时预览	监听文件变化
`yao sui trans web default`	生成多语言文件	提取翻译文本
`yao start`	启动开发服务器	本地调试

调试方法

模板调试：

输出变量：<div>{{ $env }}</div>
调试参数：?__debug=true
控制台输出：__sui_data

开发模式：

禁用缓存：-D参数
不压缩文件：调试模式自动启用

核心类型定义

// Request接口 - 后端脚本使用
export interface Request {
  method: string; // 请求方法
  payload?: Record<string, any>; // 请求数据
  query?: Record<string, string[]>; // 查询参数
  params?: Record<string, string>; // 路径参数
  headers?: Record<string, string[]>; // 请求头
  body?: any; // 请求体
  url?: URL; // 请求URL详情
  sid?: string; // 会话ID
  theme?: string; // 主题偏好
  locale?: string; // 区域设置
}

// 核心组件类型
export declare type Component = {
  root: HTMLElement; // 组件根元素
  state: ComponentState; // 状态管理
  store: ComponentStore; // 状态存储
  $root: SUIQuery; // DOM查询对象
  find: (selector: string) => SUIQuery | null; // 查找元素
  query: (selector: string) => HTMLElement | null; // 查询元素
  emit: (name: string, detail?: EventData) => void; // 触发事件
  render: (
    name: string,
    data: Record<string, any>,
    option?: RenderOption
  ) => Promise<string>; // 渲染
  once?: () => void; // 初始化钩子
  watch?: Record<string, (value?: any) => void>; // 状态监听
  Constants?: Record<string, any>; // 组件常量
};

// 状态和存储管理
export declare type ComponentState = {
  Set: (key: string, value?: any) => void;
};

export declare type ComponentStore = {
  Get: (key: string) => string;
  Set: (key: string, value: string) => void;
  GetJSON: (key: string) => any;
  SetJSON: (key: string, value: any) => void;
  GetData: () => Record<string, any>;
};

// 核心工具函数
export declare const $$: (selector: HTMLElement | string) => Component;
export declare function $Backend<T = any>(route?: string): SUIBackend<T>;
export declare function $Query(selector: string | HTMLElement): SUIQuery;
export declare const __sui_data: Record<string, any>;
export declare function __m(message: string): string;

// 后端API调用
export declare class SUIBackend<T = any> {
  Call(method: string, ...args: any): Promise<T>;
}

// HTTP请求工具
export declare class Yao {
  Get(path: string, params?: object, headers?: Headers): Promise<any>;
  Post(
    path: string,
    data?: object,
    params?: object,
    headers?: Headers
  ): Promise<any>;
  Download(
    path: string,
    params: object,
    savefile: string,
    headers?: Headers
  ): Promise<void>;
  Cookie(cookieName: string): string | null;
  SetCookie(cookieName: string, cookieValue: string, expireDays?: number): void;
}

总结：本指南提供了Yao SUI模板引擎的完整开发规范，包括项目结构、文件类型、模板语法、状态管理、前后端交互、路由配置等核心概念。通过TodoList示例展示了完整的开发流程，帮助开发者快速掌握SUI框架的使用方法。

Yao SUI模板引擎专家指南 ​

核心概念 ​

项目结构 ​

文件类型 ​

模板语法 ​

状态管理 ​

后端交互 ​

工作流程 ​

1. 需求确认 ​

2. 文件生成 ​

3. 路由处理 ​

4. 安全最佳实践 ​

约束条件 ​

输出要求 ​

详细开发指南 ​

项目结构 ​

页面与组件区别 ​

文件类型说明 ​

基础配置文件 ​

TodoList完整示例 ​

核心配置文件 ​

package.json - 依赖管理 ​

__document.html - 基础HTML骨架 ​

template.json - 模板配置 ​

__data.json - 全局数据 ​

tailwind.css - 样式配置 ​

数据配置详解 ​

.json文件 - 数据配置 ​

模板语法详解 ​

多语言配置 ​

HTML模板语法 ​

高级特性 ​

前端脚本详解 ​

TypeScript前端脚本 ​

多语言与主题 ​

状态管理与组件通信 ​

状态管理方式 ​

组件通信模式 ​

HTTP请求与动态渲染 ​

后端脚本详解 ​

后端脚本结构 ​

组件属性处理 ​

API方法定义 ​

前后端数据交互 ​

数据传递优先级 ​

数据流转机制 ​

完整数据交互示例 ​

路由配置详解 ​

app.yao路由配置 ​

页面配置详解 ​

.config文件配置 ​

构建与调试 ​

构建命令 ​

调试方法 ​

核心类型定义 ​

Yao SUI模板引擎专家指南

核心概念

项目结构

文件类型

模板语法

状态管理

后端交互

工作流程

1. 需求确认

2. 文件生成

3. 路由处理

4. 安全最佳实践

约束条件

输出要求

详细开发指南

项目结构

页面与组件区别

文件类型说明

基础配置文件

TodoList完整示例

核心配置文件

package.json - 依赖管理

__document.html - 基础HTML骨架

template.json - 模板配置

__data.json - 全局数据

tailwind.css - 样式配置

数据配置详解

.json文件 - 数据配置

模板语法详解

多语言配置

HTML模板语法

高级特性

前端脚本详解

TypeScript前端脚本

多语言与主题

状态管理与组件通信

状态管理方式

组件通信模式

HTTP请求与动态渲染

后端脚本详解

后端脚本结构

组件属性处理

API方法定义

前后端数据交互

数据传递优先级

数据流转机制

完整数据交互示例

路由配置详解

app.yao路由配置

页面配置详解

.config文件配置

构建与调试

构建命令

调试方法

核心类型定义