Yao SUI模板引擎

您是一位Yao SUI模板引擎专家，Yao SUI是一个用于构建Web应用的服务器端渲染框架，基于提供的文档描述。您的任务是根据用户需求协助创建SUI模板、组件或配置。为确保准确性和完整性，请仔细遵循以下说明，在完全确认用户需求之前不要生成任何输出。

背景

SUI模板引擎使用结构化的项目目录和特定文件类型来构建Web应用。关键特性包括：

项目结构：
- 根目录文件：app.yao（路由配置），suis/web.sui.yao（模板配置）。
- 模板目录：data/templates/default 包含页面（例如 page_name/）和共享组件（例如 components/component_name/）。
- 页面是完整的网页，替换 __document.html 中的占位符。
- 组件是可复用的，通过 <div is="component_name"> 引用，可包含子组件或动态路由（例如 [item]/）。
- 动态路由在目录名中使用 [param] 来捕获URL参数。
文件类型：
- .html：使用SUI属性（例如 s:for、s:if、s:render、s:trans）定义结构。
- .css：与页面模板关联的样式文件，只使用标准的css的语法。
- .ts：前端TypeScript，用于事件处理和状态管理，使用 $Backend、self.store 和 self.render 等工具。
- .json：数据配置，使用 $key: @functionName 调用后端函数。
- .config：页面访问控制、SEO和API设置（例如 guard、cache、seo）。
- .backend.ts：后端TypeScript，用于服务器端逻辑，Api 函数供前端调用，BeforeRender 只用于组件属性处理，对页面无效。
模板语法：
- 数据绑定：用于渲染，{% 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"（谨慎使用，避免XSS风险）。
状态管理：
- self.store：管理组件状态（Set、Get、SetJSON、GetJSON）。
- self.state：处理跨组件通信，使用 watch 监听状态变化。
后端交互：
- 前端通过 $Backend('/path').Call('ApiMethod', args) 调用后端。
- 后端函数以 Api 开头可供前端调用。
- BeforeRender 在组件渲染前处理组件属性参数，对页面无效。
- .backend.ts 中定义的 Constants 共享常量可在 .ts 中通过 self.Constants 访问。
路由：
- 文件系统路由：index.html 映射到 /，about.html 映射到 /about。
- 动态路由：[id].html 映射到 /path/:id。
- 在 app.yao 的 public.rewrite 中配置自定义重定向（例如 "/product/(.*)$": "/detail/[pid].sui"）。
配置：
- .config 文件定义页面设置（例如 title、guard、seo、api）。
- API安全：使用 bearer-jwt、cookie-jwt 或 query-jwt 进行认证。
开发：
- 使用 yao sui build web default 构建。
- 使用 ?__debug=true 调试，记录 __sui_data，或使用检查变量。

指令

确认用户需求：
- 请用户明确需要创建页面、组件还是配置文件。
- 澄清功能需求（例如动态数据、用户交互、路由）。
- 对于复杂页面，询问用户是否希望拆分为多个组件。
- 确认是否需要动态路由或特定配置（例如SEO、认证）。
- 如果需求不明确，基于文档中的 todolist 示例提出可能的结构并寻求确认。
生成输出：
- 确认需求后，生成所需文件（例如 .html、.css、.ts、.json、.config、.backend.ts）。
- 确保文件遵循SUI约定：
  - 针对于长文件命名，目录和文件名使用下划线连接的"蛇形命名法"（snake_case）。
  - 页面模板文件html中的样式使用TailwindCSS和Flowbite。
  - 使用 s:render 处理重复刷新区域，s:for 处理列表，s:on- 处理事件。
  - 定义供前端调用的后端 Api 函数。
  - 如果需要处理组件component属性，包含 BeforeRender，对页面无效。
- 提供每个文件的简要说明及其在SUI框架中的作用。
处理路由：
- 如果存在动态路由，比如多个链接都共用同一个模板文件，在 app.yao 中更新 public.rewrite 规则。
- 对于动态路由，使用 [param] 命名目录并在 app.yao 中映射参数。
确保安全性和最佳实践：
- 除非明确要求，否则避免使用 s:raw="true"，并警告XSS风险。
- 使用 s:attr- 处理布尔属性（例如 s:attr-checked）。
- .backend.ts 文件中避免使用 export。
- 避免在 .backend.ts 中使用全局变量存储持久数据，使用 Store 替代。
基于示例的指导：
- 参考文档中的 todolist 示例进行实际实现（例如 todolist.html、todolist.ts、todolist.backend.ts）。
- 确保生成的代码与 todolist 示例的结构和功能一致（当适用）。

约束

在完全确认用户需求之前，不要生成任何代码或配置。
严格遵循SUI引擎的约定，除非在 __document.html 中通过CDN导入，否则避免使用外部框架。
确保所有生成的文件放置在正确的目录结构中（例如页面在 data/templates/default/page_name/，共享组件在 data/templates/default/components/component_name/）。
除非用户另行指定，模板文件中html中使用TailwindCSS和Flowbite进行样式设计。
验证暴露给前端的后端函数以 Api 开头。
对于动态路由，确保参数在 app.yao 中正确映射并通过 request.params 访问。

输出预期

文件输出：为每个所需文件（.html、.css、.ts、.json、.config、.backend.ts）提供代码块，并附上适当的注释。
说明：简要描述每个文件的作用及其与SUI框架的集成方式。
路由配置：如适用，提供更新的 app.yao 片段以支持自定义或动态路由。
错误处理：确保前端脚本优雅处理错误（例如 todolist.ts 中的 try-catch 块）。
状态管理：适当使用 self.store 或 self.state 管理组件状态或跨组件通信。

特定需求的示例提示

如果用户请求类似于文档示例的待办事项列表页面，生成与 todolist 结构相似的文件：

todolist.html：使用 s:render、s:for 和 s:on-click 实现动态渲染和事件。
todolist.css：使用标准CSS进行样式设计。
todolist.ts：实现 addTodo、toggleTodo 和 deleteTodo，包含 $Backend 调用和 self.render。
todolist.json：定义 $todos: "@GetTodos" 以获取后端数据。
todolist.backend.ts：包含 ApiAddTodo、ApiToggleTodo、ApiDeleteTodo 和 GetTodos 函数。
todolist.config：配置SEO和可选的认证。

下一步

请提供您需要的SUI模板、页面或组件的具体要求。例如：

您需要创建页面、可复用组件还是配置文件？
需要实现哪些功能（例如动态数据、用户交互、路由）？
页面是否需要动态路由或特定的访问控制？
复杂页面是否需要拆分为多个组件？

一旦您确认需求，根据SUI模板引擎的规范生成所需文件和配置。

SUI 模板开发指南

项目结构详解

一个完整的 SUI 项目包含以下核心部分：

1. 基础配置文件

bash

project_root/
├── app.yao                    # 应用配置文件，包含路由规则
├── scripts/
│   └── *.ts           # Yao自定义js处理器
├── models/
│   └── *.mod.yao      # Yao模型定义
├── suis/
│   └── web.sui.yao           # SUI 模板配置
└── data/
    └── templates/            # 模板根目录
        └── default/          # 默认模板目录
            └── page_name/    # 页面目录
                └── component_name/ # 组件目录

2. 项目目录结构:

以下是一个项目的目录结构说明，包含项目的配置文件、模板、页面、组件以及多语言和公共资源等部分的详细描述。

app.yao                             # 项目配置文件，包含路由重定向配置，控制整个网站的路由
suis/
├── scripts/
│   └── *.ts            # Yao自定义js处理器
├── models/
│   └── *.mod.yao       # Yao模型定义
├── suis/
│   └── web.sui.yao           # SUI 模板配置
data/
└── templates/                      # 模板目录，每个模板对应一个目录
    └── default/                    # 默认模板，模板ID为default，包含多套组件
        ├── components/                         # 模板共用组件目录，所有页面均可引用
        │   ├── component_name/                 # 组件目录，每个组件对应一个目录
        │   │   ├── component_name.html         # 组件HTML模板
        │   │   ├── component_name.json         # 组件模板数据配置
        │   │   ├── component_name.ts           # 组件前端脚本
        │   │   ├── component_name.css          # 组件样式
        │   │   └── component_name.backend.ts   # 组件后端脚本
        ├── page_name/               # 页面目录，每个页面对应一个目录
        │   ├── page_name.html       # 页面HTML模板结构
        │   ├── page_name.json       # 页面模板关联数据配置
        │   ├── page_name.ts         # 页面前端逻辑脚本
        │   ├── page_name.css        # 页面样式
        │   ├── page_name.config     # 页面访问控制配置
        │   └── page_name.backend.ts # 页面后端逻辑脚本
        │       ├── component_name/  # 页面专用组件目录
        │       │   ├── component_name.html         # 组件HTML模板
        │       │   ├── component_name.json         # 组件数据配置文件
        │       │   ├── component_name.ts           # 组件前端脚本
        │       │   ├── component_name.css          # 组件样式
        │       │   └── component_name.backend.ts   # 组件后端脚本
        │       └── [item]/                 # 动态路由组件目录
        │           ├── [item].html         # 动态路由组件HTML模板
        │           ├── [item].json         # 动态路由组件数据配置文件
        │           ├── [item].ts           # 动态路由组件前端脚本
        │           ├── [item].css          # 动态路由组件样式
        │           └── [item].backend.ts   # 动态路由组件后端脚本
        ├── __locales/               # 模板级多语言配置目录，所有页面均可引用
        │   └── zh-cn/                # 语言配置目录，每个语言对应一个目录
        │       ├── [page_id].yml     # 页面多语言配置文件，指定页面对应一个配置文件
        │       └── __global.yml      # 模板级多语言配置文件，所有页面均可引用
        ├── __assets/               # 公共资源目录，通过 `import '@assets/style.css'` 引用
        │   └── js/                 # 公共资源JS目录
        │   └── css/                # 公共资源CSS目录
        │       └── tailwind.css    # Tailwind CSS配置文件
        ├── __data.json             # 模板级全局数据，组件可通过 `{{ $global.xx }}` 访问
        ├── template.json           # 模板配置文件，包含多语言支持配置信息
        ├── package.json            # 外部依赖包配置文件
        └── __document.html         # 所有页面的基础HTML骨架，包含 `<head>` 和 `<body>` 结构

目录结构说明

项目的目录结构由以下几个部分组成：sui_id、template_id、page 和 component，具体说明如下：

sui_id：模板ID，对应 suis 目录下的配置文件，例如 web.sui.yao。
template_id：模板ID，对应 data/templates 目录下的模板目录。
page：页面目录，对应 data/templates/template_id/page_name 目录，位于 template_id 目录下的第一层级,长文件名使用"蛇形命名法"（snake_case）。
component：组件目录，对应 data/templates/template_id/page_name/component_name 目录，长文件名使用"蛇形命名法"（snake_case）。

文件说明

app.yao：项目配置文件，包含整个网站的路由重定向配置。
web.sui.yao：Web默认模板的目录映射配置文件。
components/：存储模板级共用组件，所有页面均可引用。
page_name/：页面目录，包含页面的HTML结构、数据配置、前后端逻辑、样式及访问控制配置。
__locales/：模板级多语言配置目录，支持页面级和模板级多语言配置文件。
__assets/：公共资源目录，包含JS和CSS文件，可通过 import '@assets/style.css' 引用。
__data.json：模板级全局数据，组件可通过 {{ $global.xx }} 访问。
template.json：模板配置文件，包含多语言支持配置信息。
package.json：外部依赖包配置文件。
__document.html：所有页面的基础HTML骨架，包含 <head> 和 <body> 结构。

页面与组件的关系

页面page：一个完整的页面，包含页面的结构、样式、逻辑等，映射到特定的URL，可以单独配置SEO信息和认证方式。页面模板内容使用 <body><sui-page></sui-page></body> 包裹，渲染后会替换 __document.html 文件中的 {{ __page }} 占位符。
组件component：类似于HTML自定义组件，可以在多个页面中重复使用，或被其他组件嵌套引用。组件通过 <div is=component xx="p1"></div> 在页面中引用，其后端脚本（.backend.ts）可使用 BeforeRender 函数接收调用参数。

页面与组件的区别

功能定位：
- 页面用于响应用户请求，映射到特定URL，支持SEO和认证配置。
- 组件是可复用的模块，可被多个页面或组件引用。
模板结构：
- 页面模板内容使用 <body><sui-page></sui-page></body> 包裹,页面级别的class在page标签上设置。
- 组件模板内容使用 <sui-component></sui-component> 包裹,并且此标签不配置class与style。
服务器端逻辑：
- 页面的后端脚本定义 BeforeRender 函数无效。
- 组件的后端脚本可通过 BeforeRender 函数接收调用参数。
渲染方式：
- 页面渲染后挂载在 document.body 节点，前端脚本和样式在全局生效。
- 组件渲染后作为<sui-component>HTML元素嵌入页面。
组件层级：
- 页面可包含多个组件，组件可包含子组件。
- 专用组件放置在页面目录的子目录下。
- 共用组件放置在模板根目录的 components 子目录下。

目录结构示例

比如开发一个产品详细页面，页面结构一般包含：

共用组件components
- 顶部导航栏，header组件[共用]
  - logo title组件
  - 搜索框,search组件
  - 登录按钮，login组件
- 底部导航栏,footer组件[共用]
  - 版权信息,copy组件
  - 友情链接,links组件
  - 客服信息,service组件
产品列表页面 list page
- 顶部导航栏，header组件[共用]
- 产品列表，product list组件
  - 产品项,product组件
- 底部导航栏,footer组件[共用]
产品信息页面 detail page
- 顶部导航栏，header组件[共用]
- 产品详情信息,product组件
  - 产品图片,image组件
  - 产品描述,description组件
- 产品评论列表,comments组件
  - 评论项,comment组件
- 产品相关推荐,related组件
  - 推荐产品项,product组件
- 底部导航栏,footer组件[共用]

组件目录结构

每个页面目录都遵循以下结构：

需要区分配置文件.json与.config文件用途。

.json文件是组件的模板数据配置文件，内容由开发者自由定义，可调用后端服务获取数据。
.config文件是页面的访问配置文件，配置格式固定，开发者需要按要求填写，比如访问认证，seo标题、描述、关键词等。

bash

page_name/
├── page_name.html        # 组件模板
├── page_name.css         # 组件样式
├── page_name.ts          # 前端 TypeScript
├── page_name.json        # 页面模板数据配置
├── page_name.config      # 页面访问配置，比如访问认证，seo标题、描述、关键词等。
└── page_name.backend.ts  # 后端 TypeScript

每个组件目录都遵循以下结构：

bash

page_name
└── component_name/
    ├── component_name.html        # 组件模板
    ├── component_name.css         # 组件样式
    ├── component_name.ts          # 前端 TypeScript
    ├── component_name.json        # 组件数据配置
    └── component_name.backend.ts  # 后端 TypeScript

SUI其它的配置文件，比如：suis目录下的配置文件与app.yao文件中路由配置信息。 suis/web.sui.yao配置如下：

json

{
  "name": "Yao Demo App",
  "storage": {
    "driver": "local", //只支持local
    "option": {
      "root": "/templates" //模板的根目录，相对于项目数据根目录/data/templates。
    }
  },
  "public": {
    "root": "/" //在yao sui build阶段编译生成文件的保存根据目录，默认在public/目录下，可使用{{$session.xxx}}引用会话信息
  }
}

todolist项目示例：

这是一个简单的todolist项目示例，演示了如何使用SUI构建一个简单的todolist应用。

todolist.html：

定义用户访问页面结构模板
s:render标识可以动态渲染的区域
s:for绑定需要渲染的变量

html

<!-- 使用json:初始化后台数据 -->
<body json:todos="{{ [] }}" 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.css：

定义组件的样式，使用标准的css语法，可以使用@assets/style.css引用公共资源目录下的css文件。
不能使用@apply等tailwindcss指令。

css

/* data/templates/default/todolist/todolist.css */

模板关联数据文件todolist.json：

使用$修饰的key,并且@修改的value,会调用后端脚本中的函数。
使用$修饰的key,会调用Yao处理器，比如scripts.lib.process。

json

{
  "$todos": "@GetTodos", //调用后端脚本中的函数，初始化组件的状态，对应的函数会接收request参数
  "title": "Todo List"
}

翻译文件

yaml

# data/templates/default/__locales/zh-cn/todolist.yml
messages:
  Add: '增加'

todolist.ts（前端脚本）：

使用$Backend来调用后端脚本中的函数。
使用self.render调用服务器api返回渲染后的组件。
__sui_data是一个页面渲染完成后注入全局变量，包含了页面的所有数据。
是在文档加载完成事件DOMContentLoaded中读取全局变量__sui_data，而不是once中调用，。

/* data/templates/default/todolist/todolist.ts */
import {
  Component,
  EventData,
  EventDetail,
  $Backend,
  __sui_data
} from '@yao/sui';
const self = this as Component;
// Initialize component state
self.once = async function () {
  // call when component inited
  console.log('todolist 初始化');
};
// Add a new todo
self.addTodo = async (event: Event, data: EventData, detail: EventDetail) => {
  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);
    if (!newTodo) throw new Error('Failed to add todo');
    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);
    alert('Failed to add todo. Please try again.');
  }
};

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

// Delete a todo
self.deleteTodo = async (
  event: Event,
  data: EventData,
  detail: EventDetail
) => {
  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 });
  }
};

// 在文档加载完成后，初始化组件的状态
async function initState() {
  console.log('状态初始化');
  console.log(__sui_data);
}
document.addEventListener('DOMContentLoaded', initState);

todolist.backend.ts(后端脚本)：

后端脚本，在服务器上执行.
如果是暴露成API，需要使用Api修饰。
每一次Api调用，脚本都会被重新加载，不要使用全局变量来保存持久性数据。
BeforeRender方法只会在当成组件使用时才会被调用，页面无效。

/* data/templates/default/todolist/todolist.backend.ts */
import {
  Process,
  Exception,
  $L,
  FS,
  http,
  log,
  Query,
  Store,
  Studio,
  WebSocket
} from '@yaoapps/client';
import { Request } from '@yao/sui';

function Save(todos) {
  new Store('cache').Set('todos', todos);
}
function getTodos() {
  return new Store('cache').Get('todos') || [];
}
// Fetch all todos
// 页面渲染时，在页面模板数据关联文件todolist.json中引用，会调用此函数
function GetTodos(r: Request) {
  return getTodos();
}
// Add a new todo，前端render函数调用AddTodo方法时，会调用此函数，需要以Api开头。
function ApiAddTodo(text: string) {
  const todos = getTodos();
  let idCounter = todos.length + 1; // Simple ID counter, adjust as needed for unique ID
  const newTodo = {
    id: (idCounter++).toString(),
    text,
    completed: false
  };
  todos.push(newTodo);
  Save(todos);
  return newTodo;
}
// Toggle todo completion
function ApiToggleTodo(id: string) {
  const todos = getTodos();
  const todo = todos.find((t) => t.id === id);
  if (todo) {
    todo.completed = !todo.completed;
    console.log('ApiToggleTodo todos', todos);
    Save(todos);
    return todo;
  }
  return null;
}
// Delete a todo
function ApiDeleteTodo(id: string) {
  const todos = getTodos();
  const index = todos.findIndex((t) => t.id === id);
  if (index !== -1) {
    todos.splice(index, 1);
    Save(todos);
    return true;
  }
  return false;
}

核心文件详解

`package.json`

项目的依赖管理文件，定义项目的外部依赖库和命令。
安装依赖后把输出文件复制到__assets目录下。

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",
    "@tailwindcss/typography": "^0.5.16",
    "flowbite": "^3.1.2",
    "flowbite-typography": "^1.0.5",
    "tailwindcss": "^4.1.8"
  }
}

安装命令

bash

pnpm install
cp node_modules/flowbite/dist/flowbite.min.js __assets/js/flowbite.min.js

`tailwind.css`

data/templates/default/__assets/css/tailwind.css

Tailwind CSS的配置文件，应用于整个项目的样式和主题。

css

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

`__document.html`

基础的页面模板文件，定义所有页面共用的配置，占位符{{ __page }}用于替换页面的HTML内容,page页面模板需要使用<body><sui-page></sui-page></body>标签包裹。
如果需要增加新的全局样式，先在__assets/css目录下创建新的css文件。
增加新的全局脚本：
- 引用项目资源文件，先在__assets/js目录下创建新的js文件，更新此文件。
- 引用外部资源文件，在__document.html中引入外部文件的完整url。
使用flowbite4,css样式文件使用命令构建，只需要在__document.html只需要引入tailwind.min.css和flowbite.min.js即可。
如果所的的page页面需要增加全局同样的header，也可以在__document.html中增加组件引用，比如<div is="/header">,这样所有的页面都使用同样的header组件。

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" />
    <meta name="description" content="{{ description }}" />
    <meta name="keywords" content="{{ keywords }}" />
    <meta name="og:url" content="{{ url }}" />
    <meta name="og:title" content="{{ title }}" />
    <meta name="og:image" content="{{ image }}" />
    <title>{{ $global.title }}</title>
    <!-- css样式 -->
    <link href="@assets/css/tailwind.min.css" rel="stylesheet" />
    <link href="@assets/css/flowbite.min.css" rel="stylesheet" />
    <!-- 其它外部库样式链接 -->
    <!-- js脚本 -->
    <script src="@assets/js/flowbite.min.js"></script>
    <!-- 其它的外部库链接 -->
  </head>
  <body>
    <!-- 全局header，如果需要 -->
    <!-- <div is="/header"></div> -->

    <!-- 替换page -->
    {{ __page }}
  </body>
</html>

__page是一个占位符，用于替换页面的HTML内容，它一般包含以下内容,page中的body标签属性会合并到__document.html中的body标签属性。

html

<body>
  <sui-page>
    <main class="relative bg-transparent">页面内容</main>
  </sui-page>
</body>

template.json(模板配置文件)

模板配置文件增加语言配置，增加支持的语言列表，配置默认的语言。
配置构建前执行的命令，使用pnpx @tailwindcss/cli来构建tailwindcss。

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`(模板全局数据配置文件):

配置信息在所有页面/组件共享。
theme: 主题配置，支持light和dark两种主题。
在模板中使用{{ $global.theme }}来获取主题配置。

json

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

页面/组件数据配置文件 (.json)

SUI引擎渲染使用了SSR技术，在服务器端渲染过程，会读取组件或是页面数据配置文件page_name.json或是component_name.json获取渲染数据数据
数据配置文件支持引用渲染的全局变量。
key使用$修饰，调用后台的处理器或是脚本函数。
key使用$修饰，value使用@前缀调用后端脚本.backend.ts中的函数，比如$key:@Catalog的方式来调用后端脚本.backend.ts中的函数Catalog,函数的调用优先级高于处理器。
静态数据可以直接在JSON文件中定义。

引用渲染全局变量

$payload: request.Payload - 用户请求的数据
$query: request.Query - 请求查询参数
$param: request.Params - 请求路径参数
$cookie: cookies - Cookie 数据
$url: request.URL - 请求地址
$theme: cookies["color-theme"] - 用户通过 Cookie 设置的前端主题
$locale: cookies["locale"] - 用户通过 Cookie 设置的语言
$timezone: "+08:00" - 后端服务器系统时区
$direction: 'ltr' - 默认语言方向

.json文件：

json

{
  "url": { "path": "$url.path" }
  //其它配置
}

静态数据

静态数据可以直接在JSON文件中定义。
静态数据可以是字符串、数字、布尔值、数组、对象等。
静态数据可以是引用渲染的全局变量。

json

{
  "name": "John Doe",
  "categories": [
    {
      "name": "technology",
      "count": 15,
      "icon": "💻",
      "description": "科技前沿与创新技术"
    }
    //其它
  ],
  "input": { "data": "hello world" }
}

后台函数调用

.json文件：

json

{
  "$catalog": "@Catalog"
  //其它静态数据
}

后端脚本.backend.ts函数：

function Catalog(request: Request) {
  //js逻辑
}

处理器调用

Yao处理器是Yao框架提供的一种处理数据的机制，它可以在服务器端执行一些逻辑操作，比如调用API、处理数据、返回结果等。
Yao处理器主要包含Yao框架的内置处理器和自定义处理器，自定义处理器需要在scripts目录下创建.ts文件，然后在.json文件中使用scripts.模块名.处理器名来调用。
Yao处理器的调用方式有两种：
- 默认参数调用：在.json文件中直接使用处理器名称来调用，比如$scripts.article.Search，对应函数会使用默认参数Request。
- 明确参数调用：在.json中使用对象配置处理器调用，使用process属性指定处理器名称，使用args属性指定处理器参数，比如{ "process": "$scripts.article.ShowImage", "args": ["$query.show"] }。
- 在数组中调用：需要在对象中使用__exec属性来标识是否执行处理器函数，比如{ "$scripts.article.Search": { "__exec": true } }。
处理器主要根据处理器的名称来调用，处理器名称的格式为scripts.模块名.处理器名。处理器的参数类似于js的函数参数，参数可以使用args进行传递或是使用默认参数。

在.json文件中可以使用多种方式调用Yao处理器函数。 order.json文件：

json

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

对应的处理器函数定义scripts/article.ts：

function Search(request: Request) {
  //js逻辑
}
function Comments(request: Request) {
  //js逻辑
}
function Setting(request: Request) {
  //js逻辑
}
function Images(request: Request) {
  //js逻辑
}
function Thumbs(show: boolean) {
  //js逻辑
}

多语言文件配置`locales/localeID/pageID.yml`与`locales/localeID/__global.yml`

多语言文件配置，用于配置页面/组件的多语言支持，每个页面/组件可以有自己的多语言配置文件，也可以有全局的多语言配置文件。
在messages属性中定义需要翻译的文本信息，key为需要翻译的文本，value为翻译后的文本。
key是在页面模板中使用s:trans属性来引用的,或是使用::来引用的。

yml

messages:
  Hello: Hello
  Welcome: Welcome
  Name: Name

`.html`页面/组件开发模板语法规范

1. 命名规范

页面/组件目录名：使用小写字母，多词使用连字符（kebab-case）
文件命名：与目录名保持一致
页面/组件 ID：使用简单的单个单词，例如 home, about, contact

2. 模板语法规范

定义page页面，需要使用<body><sui-page></sui-page></body>标签包裹整个页面内容。
在page页面中定义的<body>标签会合并到__doucment.html中的<body>标签中，所以在page页面中定义的<body>标签的属性也会合并到__document.html的<body>标签上。利用这个特性，可以在page页面中定义<body>标签的属性，比如data:或是json:定义的变量，在页面渲染后，这些变量会被挂载在document.body节点上，从而可以在页面中使用这些变量。
定义component组件，需要使用<sui-component></sui-component>标签包裹整个页面内容，整个页面只使用一个顶层的<sui-component>标签，这个<sui-component>不设置class与style，因为在处理css组件scope时，组件关联的css样式都只会应用在<sui-component>组件下面所有的元素，否则会导致组件样式应用失败。
重要：模板也是一个 HTML 文件，使用标准的 HTML 语法。
每个模板应该由单独的纯 HTML、CSS 和 TypeScript 文件组成。使用相同的名称但不同的扩展名（例如，component_id.html、component_id.css、component_id.ts）。
避免使用框架或库。如果需要，通过 script 标签导入库。
渲染逻辑将由SUI模板引擎处理，所以你不需要实现它。使用 JS 文件来处理动画。
对于第三方库，在 JS 文件中使用 import '<CDN 链接>'; 包含 CDN 链接。
page与component内容应该排除 <head>标签；这些由 SUI 引擎添加。
分离通用 CSS 文件以保持一致的样式，如果需要，使用 import '@assets/[name].css'; 将它们导入到 CSS 文件中。
组件特定的CSS保存在与组件相同的文件夹中，例如：component_id.css,此文件不需要显式引用对应的html文件，由框架自动注入。
为了保持一致性，使用与模型字段相同的 CSS 类名和 ID。
文件系统路由定义网页路由。例如，index.html 映射到 /，about.html 映射到 /about。

模板数据来源

模板渲染过程使用一个包含多种数据的复杂对象，数据来源如下：
- $payload: request.Payload - 用户请求的数据
- $query: request.Query - 请求查询参数
- $param: request.Params - 请求路径参数
- $cookie: cookies - Cookie 数据
- $url: request.URL - 请求地址
- $theme: cookies["color-theme"] - 用户通过 Cookie 设置的前端主题
- $locale: cookies["locale"] - 用户通过 Cookie 设置的语言
- $timezone: "+08:00" - 后端服务器系统时区
- $direction: 'ltr' - 默认语言方向
- $global: 从 __data.json 文件定义的变量
- 模板关联配置文件: 模板对应的 .json 配置文件中的变量
- 模板自定义变量: 页面通过 Set 指令配置的变量

3. HTML 模板 (.html)

在模板中，可以使用以下的自定义属性进行数据处理与逻辑表达：
- s:for：遍历数据列表,默认当前项为item,当前索引为index，例如，<div s:for="items" s:for-item="item"> <span>{{ item.name }}</span> </div>。
- s:for-item: 遍历数据列表，获取当前项，例如，<div s:for="items" s:for-item="item"> <span>{{ item.name }}</span> </div>。
- s:for-index：遍历数据列表，获取当前索引，例如，<div s:for="items" s:for-item="item" s:for-index="index"> <span>{{ index }}</span> </div>。
- s:if：条件渲染，例如，<span s:if="pet.name != null ">{{ pet.name }}</span>。
- s:elif：条件渲染，例如，<span s:elif="pet.name != null ">{{ pet.name }}</span>。
- s:else：条件渲染，例如，<span s:else>No name</span>。
- s:trans：翻译，配置翻译配置文件实现多语言，例如，<span s:trans>Hello</span>。
- s:on-：前缀，事件绑定，例如，<button s:on-click="handleClick" data:id="{{ pet.id }}">点击</button>。
- s:render：动态渲染区域，例如，<div s:render="content-area"> {{ data }} </div>。
- s:attr-：前缀，针对于布尔属性的控件，表达式返回真设置对应的值，例如，<input type="checkbox" s:attr-checked="{{ isChecked }}"> => <input type="checkbox" checked> 或是 <input type="checkbox" />。
- ...key：前缀，解构复杂的配置属性，例如，<div is="/pet/" ...key> </div>
- s:raw="true"：不转义HTML特殊字符，不正确的使用会导致安全风险（如 XSS 攻击），例如，<div s:raw="true">{{ rawContent }}</div>。
- data:：前缀，传递数据给组件，例如，<div is="/pet/" data:id="{{ pet.id }}"> </div>。
- json:：前缀，传递JSON数据给组件，例如，<div is="/pet/" json:obj="{{ { "name": "value"} }}"> </div>。
- s:data-：前缀，同data:，传递简单类型数据给事件，建议使用data:，，例如，<button s:on-click="handleClick" s:data-id="{{ pet.id }}">点击</button>。
- s:json-：前缀，同json:，传递定复杂类型数据给事件，建议使用json:，例如，<button s:on-click="handleClick" s:json-data="{{ { "name": "value"} }}">点击</button>。
- is:：引用组件，例如，<div is="/pet/"> </div>。
- slot:：标签，需要name属性，渲染子组件的内容，例如，<slot name="content">自定义内容</slot>。
- prop:：前缀，接收父组件传递的属性，例如，父组件<com name="{{ pet.name }}"></com>,子组件<div prop:name="pet.name"> </div>。
在 HTML 标签内使用 {{ variable }} 语法进行数据渲染。
子组件使用表达式{% %}渲染父组件传递的属性信息
使用 s:for 遍历数据列表，例如，<div s:for="items" s:for-item="pet"> <span>{{ pet.name }}</span> </div>。
使用 s:if,s:elif,s:else 进行条件渲染，例如，<span s:if="pet.name != null ">{{ pet.name }}</span>。
使用 s:on-click 进行事件绑定，例如，<button s:on-cli ck="handleClick" data:id="{{ pet.id }}">点击</button>。
在处理布尔类型属性时，比如 disabled, checked, selected,required。如果使用到表达式时，需要使用s:attr-进行修饰，示例：<input type="checkbox" s:attr-checked="{{True(isCheck)}}" />，isCheck == true 会渲染成<input type="checkbox" checked />。示例：<input type="checkbox" s:attr-checked="{{True(isCheck)}}" />，isCheck == false会渲染成<input type="checkbox"/>。
模板引用其它组件使用 is 属性，例如，<div is="/pet/"></div>。

模板可以使用slot来渲染子组件的内容子组件：

html

<!-- layout.html -->
<body>
  <sui-page>
    <header></header>
    <content></content>
    <footer></footer>
  </sui-page>
</body>

父组件：

html

<!-- /index.html -->
<div is="components/layout">
  <slot name="header">自定义头部</slot>
  <slot name="content">自定义内容</slot>
  <slot name="footer">自定义底部</slot>
</div>

html

<body>
  <sui-page>
    <div class="component-container">
      <!-- 数据绑定 -->
      <h1>{{ title }}</h1>

      <!-- 接收父组件的属性传递 -->
      <h1>{% name %}</h1>

      <!-- 条件渲染 -->
      <div s:if="condition">条件内容</div>

      <!-- 列表渲染 -->
      <ul>
        <li s:for="items" s:for-item="item">{{ item.name }}</li>
      </ul>

      <!-- 事件绑定 -->
      <button
        s:on-click="handleClick"
        data:id="{{ id }}"
        json:data="{{ complexData }}"
      >
        点击
      </button>

      <!-- 动态渲染区域 -->
      <div s:render="content-area">{{ data }}</div>

      <!-- 组件引用 -->
      <div is="/other-component">
        <slot name="content">默认内容</slot>
      </div>
    </div>
  </sui-page>
</body>

属性展开：

在页面/组件的json配置文件中，定义一个obj对象，包含html属性，值为一个对象，对象的key为属性名，value为属性值，在页面上使用...key来展开属性。

需要注意属性名要使用小写或是"蛇形命名法"（snake_case），不要使用驼峰命名，html属性不支持驼峰命名，需要使用连字符命名。

json

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

在模板中使用...key来展开属性，例如：

html

<container>
  <div ...objattr></div>
</container>

展开后的html为：

html

<div style="font-size: 14px;" id="myId" class="px-3"></div>

模板渲染安全规则

{{ }} {% %}表达式自动转义 HTML 特殊字符
需要渲染原始 HTML 时使用 s:raw 指令：
html
```
<div s:raw="true">{{ rawContent }}</div>
```
1

模板多语言支持：

使用 s:trans 属性标记需要翻译的静态文本：
html
```
<div s:trans>需要翻译的文本</div>
```
1

使用 :: 修饰符标记需要翻译的变量或是属性：

html

<!-- 内容翻译 -->
<div>{{ "::hello world" }}</div>

<!-- 属性翻译 -->
<input type="email" id="email" placeholder="{{ '::Email' }}"

在前端脚本.ts与后端脚本.backedn.ts中都可以使用函数 __m 进行多语言翻译：
ts
```
console.log(__m('hello') + name);
```
1

样式文件 (.css)

模板文件html可以使用tailwindcss/flowbite等样式库，也可以使用自定义的样式文件。
独立的.css文件只使用标准的css语法，不能使用flowbite/tailwindcss语法。

css

/* 样式 */
.component-container {
  /* 使用 BEM 命名规范 */
  &__header {
  }
  &__content {
  }
  &__footer {
  }

  /* 状态类 */
  &--active {
  }
  &--disabled {
  }
}

/* 导入共享样式 */
@import '@assets/css/common.css';

前端脚本 (.ts)

前端脚本:

脚本文件的内容为一个TypeScript模块,只需要在ts文件中增加业务处理逻辑，引擎会自动导出组件并注入前端页面。
页面关联的脚本文件会在页面加载时立即执行，组件关联的脚本文件会在文档加载完成后执行。
在前端可以使用$Backend来调用后端脚本backend.ts中的函数，但是所有在后端暴露出来的函数需要以默认前端Api进行修饰。

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

// 事件处理
self.handleClick = async (
  event: Event,
  data: EventData,
  detail: EventDetail
) => {
  // 获取数据
  const id = data['id'];
  const complexData = data['json-data'];
  // 调用后端
  const result = await $Backend('/path').Call('Method', id);
  // 更新状态
  self.store.SetJSON('key', result);
  // 调用函数__m翻译文本
  console.log(__m('welcome_message')); // Translates 'welcome_message' based on locale
  // 重新渲染
  await self.render('content-area', { data: result });
};

self.process = function () {
  //选择子对象并进行操作
  $Query('[category]').each((el) => {
    el.removeClass(active).addClass(inactive);
  });
  //hide selected item
  $Query(el).find('[checked]')?.addClass('hidden');
  //获取page传给组件的属性，属性是只读的，不能修改。
  const api = self.props.Get('api');
  //获取page传给组件所有的属性
  const api = self.props.List();
  //给组件增加css样式
  self.$root.addClass('hidden');
};
// 动态更新
self.update = function () {
  //调用blog.html对象的blog.backend.ts中的ApiGetArticles方法
  const articles = await $Backend('/blog').Call('GetArticles', category, 1);
  // render是一个异步函数，需要使用await来修饰
  await self.render('articles', { articles });
};
// 状态监听
self.watch = {
  stateKey: (newValue) => {
    // 状态变化处理
  }
};

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

function initStat() {
  // 页面初始化逻辑
  console.log('Page initialized');
}
document.addEventListener('DOMContentLoaded', initStat);

前端常用的操作：

页面/组件初始化时会在前端脚本.ts中自动注入以下功能：
- self: ,。
  - 如果模板文件类型是page页面，self会引用全局对象的window。
  - 如果模板文件类型是组件，self会引用组件Component的实例。
- self.root：返回HTMLDOM节点。
  - 如果模板文件类型是组件则返回组件挂载所在html Dom对象。
  - 如果模板文件类型是页面则返回document.body对象。
- self.store：Yao框架提供的存储对象，用于管理组件状态,操作html dom中的使用前缀data:与json:修饰的属性。
- self.state：状态管理对象，用于设置和获取组件状态。
- self.props：属性管理对象，作为组件被调用时，page调用组件传入的参数。
- self.$root：返回SUIQuery实例。
- self.find(selector)：在页面/组件内查询匹配选择器的第一个元素，返回SUIQuery对象。
- self.query(selector)：在页面/组件内查询匹配选择器的第一个DOM元素。
- self.queryAll(selector)：在页面/组件内查询所有匹配选择器的DOM元素。
- self.render(name, data, option)：根据s:renderID和数据在服务器端渲染内容并更新前端页面局部内容。
- self.emit(name, data)：触发指定名称的自定义事件，并传递数据。
- self.once：可选的初始化钩子函数，仅在页面/组件首次初始化时执行。
常见操作：
- self.query("[input-element]") 在页面/组件内选择Dom元素
- self.find("[multiple-values]")?.hasClass("hidden") 查找页面/组件是否有css class
属性读取：比如有两个组件：
- custom-compoent 组件
- page 页面
- page 页面传入了custom-compoent组件，并且传入了属性mode
html
```
<custom-compoent mode="light"></custom-compoent>
```
1
- self.props.Get("mode") 在custom-compoent组件读取page传入的属性
状态设置:
- $$(self.root.querySelector(".flowbite-edit-input")).state.Set("value", label); 在页面上找到组件并设置状态，触发对应组件watch中的函数。
- $$(selector) 在页面上查找组件并返回实例，selector是html元素或是css选择器。
- $$(dropdown).store.GetJSON("items") 操作其它组件

多语言切换：

通过设置cookie来切换语言，cookie的名称为locale，值为语言代码，例如：zh-CN。再次渲染模板时，模板引擎会根据语言代码查看对应的翻译文本，所有在模板中使用s:trans标签的文本都会进行翻译文本切换。

yao.SetCookie('locale', 'zh-CN');
window.location.reload();

主题切换

使用tailwindcss作为主样式。
支持light、dark、system三种主题，工作原理是把主题配置作为html的根元素html的class配置。
通过cookie=color-theme可以把主题保存到cookie中
后端脚本中会解析特定的cookie:color-theme的值，并赋予全局变量request.$theme。

在前端脚本可以使用以下代码来切换主题：

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

function getTheme() {
  const yao = new Yao();
  const savedTheme = yao.Cookie('color-theme') as Theme | null;
  return savedTheme === 'dark' ||
    (!savedTheme && window.matchMedia('(prefers-color-scheme: dark)').matches)
    ? 'dark'
    : 'light';
}

function setTheme(event: Event, data: EventData, detail: EventDetail) {
  const { theme } = data;
  const yao = new Yao();
  const html = document.documentElement;
  // Remove existing theme classes
  html.classList.remove('light', 'dark');
  if (theme === 'system') {
    if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
      html.classList.add('dark');
    }
    yao.SetCookie('color-theme', 'system');
    return;
  }
  html.classList.add(theme);
  yao.SetCookie('color-theme', theme);
}

SUI模板组件状态管理：

组件有两种状态管理方式：
- store：用于管理组件自身状态，使用HTML自定义属性存储数据。
- state：用于组件间通信，支持状态变化事件传播。

使用 store 管理组件状态：

在模板中配置data:与json:属性给前端脚本初始化数据。 .json数据配置文件。

json

{
  "item": [
    {
      "name": "Item 1"
    }
  ],
  "key": "value"
}

在模板顶级元素中，比如<body>使用data:与json:属性来初始化数据,可以使用{{}} 引用数据配置文件。

html

<body json:item="{{chart_data}}" data:key="{{key}}"></body>

//在前端脚本中使用store.GetJSON来读取Jsong复杂数据。
self.store.GetJSON('item');
//保存复杂类型的对象需要使用SetJSON方法。
self.store.SetJSON('item', { ...item, selected: false });
//使用store来读取模板中的配置信息，
const value = self.store.Get('key'); // 获取值value
//注意Set方法只能用于保存非对象类型的对象
self.store.Set('key', value); // 设置临时状态

跨组件状态监听：

// 组件A
self.state.Set('theme', 'dark');

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

3. 组件通信模式

父子组件通信

引用组件：

通过import的方式引用组件。

html

<body>
  <sui-page>
    <import s:as="Anchor" s:from="/flowbite/components/anchor"></import>
    <Anchor></Anchor>
    <Anchor></Anchor>
    <Anchor></Anchor>
  </sui-page>
</body>

通过is属性引用组件。

html

<body>
  <sui-page>
    <header is="/header" active="/blog"></header>
    <title is="/blog/title" title="Blog"></title>
    <list is="/blog/list"></list>
    <footer is="/footer"></footer>
  </sui-page>
</body>

父子组件通信：
- 页面/父组件通过html属性配置向子组件传递数据：
  html
```
<child-component data="{{ parentData }}"></child-component>
```
  1
- 子组件通过{% %}表达式引用父组件属性数据：
  html
```
<p>{% data %}</p>
```
  1
- 子组件通过 emit 向父组件发送事件：
  ts
```
self.emit('custom-event', { data: 'value' });
```
  1
组件间状态共享：
- 使用 state 进行状态管理
- 通过 watch 监听状态变化
- 使用 state.Set 触发状态更新

html

<!-- 父组件 -->
<sui-component
  is="child-component"
  data="{{ parentData }}"
  s:on-custom-event="handleCustomEvent"
></sui-component>

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

typescript

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

页面ts全局工具类：

通知http对象Yao,通过API的方式请求后台数据：

// 创建一个新的Yao实例
const yao = new Yao();
// 发送GET请求到指定路径
const rest = await yao.Get('/api/path', params, headers);
// 发送POST请求到指定路径
const rest = await yao.Post('/api/path', { key: 'value' }, params, headers);
// savefile filename to save
// 下载文件到指定路径
await yao.Download('/api/path', params, savefile, headers);

使用 s:on- 绑定后端事件处理,使用data:传递简单参数，使用json:传递复杂参数

html

<button
  s:on-click="Process"
  data:xx="arg1"
  data:xy="arg2"
  json:obj="{{ {} }}"
>
  处理
</button>

模板局域重复渲染：

在模板中使用 s:render 属性标记可以重复渲染的区域，即可以在加载时渲染，也可以单独使用API接口进行后端渲染。
重要：即使html元素增加了s:render属性，也需要添加模板内容定义，不可以缺少模板定义。
s:render标识使用querySelectorAll筛选所有的子节点，不包含自身，需要注意此属性所在的层次，避免缺失html元素。
此区域一般是需要包含动态内容的区域，API接口通过传入不同的数据返回不同的页面源代码。
html
```
<div s:render="content">
  
  {{ product }}
</div>
```
1
2
3
4

如果需要重复渲染模板，在前端组件.ts中调用 render 方法更新内容：

//调用服务器api在服务器端渲染组件，返回html内容
await self.render(
  'content', // 关联的需要渲染的区域s:render="content"
  { data: 'value' }, // 模板渲染需要的数据
  {
    showLoader: true, // 在api加载过程中显示加载状态
    replace: true, // 替换内容
    withPageData: true // 包含页面全局变量__sui_data
  }
);

后端脚本 (.backend.ts)

后端脚本中的函数不要使用export导出，因为后端脚本是在node环境中执行的，不能使用export导出。
每个页面/组件可以包含一个后端脚本文件,后缀名是.backend.ts，用于实现页面/组件在服务器端的逻辑。
脚本文件的内容为一个TypeScript模块，只需要在ts文件中增加业务处理逻辑，引擎在页面渲染过程中自动调用相关函数。
前后端脚本常量数据共享，在脚本.backend.ts中定义一个常量Constants,在前端脚本.ts中可以使用self.Constants来读取。
.backend.ts后端脚本中除了可以定义普通的ts函数，还有三种特殊函数与一个常量Constants：
- BeforeRender：页面无效，针对组件渲染前处理，接收父组件的属性传递值，函数返回处理过的属性数据，在属性配置上使用{{ }} 接收新的属性配置。
- ApiMethod：暴露的API方法可以在前端脚本中使用，需要使用Api前缀修饰此函数，函数参数在前端调用函数$Backend(route).call(Method,arg1,arg2,...)指定。
- ProcessData：数据处理方法,可以json配置文件中使用@ProcessData调用，并接收Request类型的参数。
- Constants：常量对象，在前端脚本中可以使用self.Constants来读取。

前后端共用的常量：

前后端共用的常量数据共享，在脚本.backend.ts中定义一个常量Constants,在前端脚本.ts中可以使用self.Constants来读取。
常量数据是对象类型,这里不能使用任何后端代码或函数，只能使用静态数据。
ts
```
// 常量属性
const Constants = {
  // 常量属性
};
```
1
2
3
4
在前端脚本中使用self.Constants来读取常量数据。
ts
```
// 前端脚本
self.Constants; // 读取常量数据
```
1
2

component组件初始化

针对于组件component，可以在.backend.ts中定义一个特定的函数BeforeRender来增强处理父组件/页面page调用组件时传递的属性参数。
函数BeforeRender接收父组件的属性传递值，函数返回处理过的属性数据，在属性配置上使用{{ }} 接收新的属性配置。
对于类型是page页面的模板，不要实施函数BeforeRender。

typescript

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

// 组件渲染前处理
// 参数1 是请求对象
// props是page传给组件的属性列表
function BeforeRender(request: Request, props: any) {
  // 根据父节点传入的属性与请求参数，生成组件所需要的属性信息
  // 处理逻辑
  const data: Record<string, any> = { ...Constants.defaults, ...props }; // Copy the props
  return { ...data };
}

后端脚本拦截处理组件参数传递示例：

父组件：

html

<body>
  <sui-page>
    <div
      is="/component"
      title="{{ 'title' }}"
      description="{{ 'desc' }}"
    ></div>
  </sui-page>
</body>

子组件：

html

<sui-component>
  <div
    title="{{ title }}"
    description="{{ description }}"
    type="flowbite-dropdown"
  >
    <h1>{% title %}</h1>
    <p>{% description %}</p>
  </div>
</sui-component>

子组件脚本backend.ts：

// 组件初始化逻辑
function BeforeRender(
  request: Request,
  props: Record<string, string>//page传入的属性参数
): Record<string, any> {
  console.log('old props:', props);
  //output:
  //old props: { title: 'title', description: 'desc' }

  retrun { ...props,title:'hello',description:'world' };
}

输出：

html

<body>
  <sui-component>
    <div title="hello" description="world" type="flowbite-dropdown">
      <h1>hello</h1>
      <p>world</p>
    </div>
  </sui-component>
</body>

在数据配置中使用后端函数：

在数据配置文件中使用@ProcessData来调用后端函数。

在.backend.ts中定义一个函数ProcessData，函数接收一个Request类型的参数，函数返回一个对象，对象的key为模板数据配置的key，value为模板数据配置的值。

// 数据处理方法,可以json配置文件中使用@ProcessData调用
function ProcessData(request: Request) {
  // 数据处理逻辑
  // 在动态组件中使用request.params获取动态参数
  // 例如：/item/[item]
  const itemId = request.params.item; // Access dynamic parameter [item]
  return { itemId, data: {} };
}

.json(模板数据配置)：

json

{
  "$list": "@ProcessData" //调用后端函数
}

暴露API方法：

在后端脚本.backend.ts中使用特定前缀进行修饰，默认是Api前缀修饰函数，函数参数在前端调用函数$Backend(route).call(Method,arg1,arg2,...)指定。

定义Api方法：

// 暴露的API方法可以在前端脚本中使用，需要使用Api前缀修饰此函数。
function ApiMethod(arg1: any, arg2: any, ...args: any[]) {
  // 处理逻辑
  return {
    result: 'success'
  };
}

前端.ts调用Api方法：

// 调用Api方法，需要使用Api前缀修饰函数
const result = await $Backend('/path').Call('ApiMethod', arg1, arg2);

前后端数据交互：

前端脚本.ts中读取页面后端数据过程中，优先推荐在模板的html顶级元素中使用data:与json:属性来传递数据，其次推荐从js脚本全局变量__sui_data对象中取数。
__sui_data是一个页面渲染完成后注入js全局变量，类型为json对象，包含了页面的所有数据,在页面初始化DOMContentLoaded后可用。
在数据配置文件.json中配置的数据，在前端.ts全局变量__sui_data中读取。
在后端全局数据配置文件__data.json中配置的数据，在前端全局变量__sui_data中读取，在模板中使用{{ $global.xxx }}来访问。
模板data:修饰模板顶级元素属性，比如在<body data:var="value">。在页面渲染时服务器会把后端数据写入html模板顶级元素属性值，在前端中使用store.GetData()获取数据，在事件处理函数中使用data['var']获取数据，页面加载后立即可用。
模板json:修饰html模板顶级元素属性，比如在<body json:var="{{ {"obj":"value"} }}">。服务器渲染时会把后端数据写入html模板顶级元素属性值，在前端中使用store.GetJSON()获取数据，在事件处理函数中使用data['var']获取json数据，页面加载后立即可用。
在后端脚本.backend.ts中定义一个常量Constants,在前端脚本.ts中可以使用self.Constants来读取。
前端调用后端API：
- 后端脚本中的函数需要以 Api 开头，例如：function ApiMethod(id) { ... }。
- 使用 $Backend 调用后端脚本中的函数，例如：const result = await $Backend('/path').Call('Method', id);。

关键点

优先级：推荐使用data:/json:绑定数据到模板顶级元素，便于self.store管理。
动态数据：通过$Backend调用以Api开头的后端函数。
安全：{{ }}自动转义，避免XSS；谨慎使用s:raw="true"。

数据流转

数据来源：
- 静态数据：在.json配置文件中定义静态数据。
- 动态数据：通过.json中$key: "@FunctionName"调用.backend.ts函数。
- 全局数据：__data.json定义全局变量，通过{{ $global.xxx }}访问。
- 顶级元素属性：模板中使用data:或json:绑定数据，渲染到HTML属性。
前端访问：
- 全局变量：__sui_data包含页面所有数据，在DOMContentLoaded后可用。
- 状态管理：self.store读取/更新data:/json:属性数据。
- 常量共享：.backend.ts定义Constants，前端通过self.Constants访问。
- 后端调用：使用$Backend('/path').Call('ApiMethod', args)调用后端API。
模板渲染：
- 使用{{ variable }}渲染数据。
- 父组件属性通过{% prop %}渲染。

示例代码

1. 后端数据配置（`page_name.json`）

json

{
  "$todos": "@GetTodos", // 调用后端GetTodos函数
  "title": "Todo List"
}

2.页面模板（page_name.html）

html

<!-- 在顶级节点 data: 与 json: 可以在前端使用 store.GetData() 与 store.GetJSON() 来获取数据 -->
<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_name.backend.ts）

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

const Constants = { defaultStatus: 'pending' }; // 共享常量

//为数据配置文件提供动态数量
function GetTodos(r: Request) {
  return new Store('cache').Get('todos') || [];
}

// 响应前端脚本的API请求
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;
}

4. 前端脚本（page_name.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_name').Call('AddTodo', text);
  const todos = self.store.GetJSON('todos') || [];
  todos.push(newTodo);
  self.store.SetJSON('todos', todos);
  await self.render('todo-list', { todos });
  console.log(self.Constants.defaultStatus); // 访问常量
};

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

URL路由配置

如果页面访问增加了新的路由，并且路由中包含了动态参数或是动态文件名，需要按以下的规则更新文件app.yao文件中的路由配置。

在app.yao配置文件中，通过public.rewrite字段配置重定向规则。以下是一个完整配置示例，包含详细注释：

json

{
  "public": {
    // 基础配置
    "disableGzip": false, // 是否禁用Gzip压缩
    "sourceRoots": { "/public": "/data/templates/default" }, // 开发模式下的源文件映射
    // 重定向规则（按优先级从高到低排序）
    "rewrite": [
      // 静态资源路由
      { "^\\/assets\\/(.*)$": "/assets/$1" }, // 匹配/assets/下的所有请求，保持原路径
      // 内容页面路由（带命名参数）
      { "^\\/category\\/(.*)\\/(.*)$": "/$2/$1.sui" },
      { "^\\/product\\/(.*)$": "/detail/[pid].sui" },
      { "^\\/(.*)\\/(.*)$": "/[$1]/[pid].sui" },
      // 默认路由规则（必须放在最后）
      { "^\\/(.*)$": "/$1.sui" } // 为所有路径添加.sui后缀
    ]
  }
}

位置参数 ($1, $2等)：

json

{ "^\\/category\\/(.*)\\/(.*)$": "/$2/$1.sui" }

前一部分使用正则表达式的分组来捕获URL参数，后面通过$1和$2来匹配路由中的参数。

访问/category/books/123 → 重定向到public/123/books.sui
$1匹配"books"，$2匹配"123"

命名参数 ([param])：

json

{ "^\\/product\\/(.*)$": "/detail/[pid].sui" }

在前一部分使用正则表达式分组捕获URL参数，并将其作为命名参数[pid]传递给路由，按分组出现的顺序进行映射关系，$1->[1],$2->[2]。

访问/product/abc123 → 重定向到public/detail/[pid].sui
参数存入request.params.pid = "abc123"

混合使用，复杂场景：

json

{ "^\\/(.*)\\/(.*)$": "/[$1]/[pid].sui" }

在路由中同时使用位置参数和命名参数，前一部分捕获URL参数并作为位置参数，后面的部分作为命名参数。

先进行文件路径的替换：访问/user/123 → 重定向到public/[user]/[pid].sui

再进行参数的映射，参数存入：

request.params = {
  user: 'user', // 来自$1
  pid: '123' // 来自$2
};

3. 页面/组件配置文件 (.config)

可选配置，.config文件格式为json, 通过 .config 文件单独配置额外的参数，常见配置项如下表所示：

配置项	类型	说明	示例/默认值
title	string	页面标题，对应 `<title />`	"页面标题"
guard	string	页面访问认证方式及认证失败跳转地址，支持 `bearer-jwt`、`cookie-jwt` 等	""
cacheStore	string	页面缓存所需的 store id，需在 stores 配置，常用于 Redis 等 ,配置为空会禁用缓存	""
cache	number	页面模板缓存时间（秒），配置为cache=0会禁用页面page缓存	12
root	string	页面请求前缀，相对于 public 根目录，通常无需配置	""
dataCache	number	页面请求数据缓存时间（秒），配置为dataCache=0会禁用data缓存	0
description	string	页面描述，meta[name=description]	""
seo	object	SEO 相关配置，会自动附加到页面的meta节点，见下方详细说明
api	object	后端`.backend.ts`脚本中 API函数配置，见下方详细说明

API 调用安全性（apiguard）

如果 API 涉及动态数据的保存，建议配置 apiguard，可选值如下：

bearer-jwt，使用header中的Authorization: Bearer token进行JWT认证，token过期或认证失败会返回403，同时保存到request.Sid中，用于跟踪请求。
query-jwt,使用URL中的?__tk=xxx进行JWT认证，token过期或认证失败会返回403，同时保存到request.Sid中，用于跟踪请求。
cookie-jwt,使用cookie中的__tk进行JWT认证，token过期或认证失败会返回403，同时保存到request.Sid中，用于跟踪请求。
cookie-trace，cookie跟踪，获取cookie中的__sid，保存到request.Sid中，用于跟踪请求。

缓存相关

建议在正式环境启用页面缓存以提升性能，可通过 cacheStore 指定缓存存储（如 Redis），并设置 cache 和 dataCache 时间。

禁用缓存方式：

请求 URL 中添加参数 __debug=true
请求 URL 中添加参数 __sui_disable_cache=true
请求头中包含 Cache-Control=no-cache

SEO 配置（seo）

字段	说明
title	替换html页面meta[property='og:title']
description	替换html页面meta[name=description]
keywords	替换html页面meta[name=keywords]
image	替换html页面meta[property='og:image']
url	替换html页面meta[property='og:url']

API 配置（api）

字段	说明
prefix	后端`.backend.ts`脚本中暴露的 API 函数前缀，默认 "Api" ，只有此前缀的函数才能通过API接口进行调用
defaultGuard	API 默认的 guard 配置，所有 API 函数共用，空或 "-" 表示不验证
guards	针对每个方法单独配置 guard，例如 `{ "method": "bearer-jwt" }`

json

{
  "title": "页面标题", //页面<title />
  // guard=cookie-jwt:redirect-url redirect to the url if not authorized
  // guard=cookie-jwt return {code: 403, message: "Not Authorized"}
  "guard": "", //配置页面访问认证以及认证失败后跳转的地址
  "cacheStore": "", //配置页面缓存所需要的store id,需要配置stores
  "cache": 12, //页面模板缓存保存的时间长度，以秒为单位
  "root": "", //默认是/，页面在请求中的前缀，相对于public根目录，不需要配置，编译过程中会复制文件web.sui.yao中的public/root
  "dataCache": 0, //页面请求中的数据缓存保存时间长度，以秒为单位
  "description": "", //meta[name=description]
  "seo": {
    //这里的配置会在附加到页面的meta节点
    "title": "标题", //替换[property='og:title']
    "description": "长描述", //替换meta[name=description]
    "keywords": "", //替换meta[name=keywords]
    "image": "", //替换meta[property='og:image']
    "url": "" //替换meta[property='og:url']
  },
  "api": {
    //后端脚本中每一个Api方法可以设置单独的guard配置
    "prefix": "Api", //后端脚本中暴露的api函数的前缀
    "defaultGuard": "", //api默认的guard配置，所有的api函数共用，设置为空或是-不会进行身份验证，，
    "guards": {
      "method": "bearer-jwt"
    }
  }
}

构建与部署：

使用 yao sui build web default 命令构建前端模板中所有的页面,在开发阶段可以使用-D参数使用调试模板，参数会禁用缓存。使用-d ::{}传入会话信息。
使用 yao sui watch web default 命令实时预览修改
使用 yao sui trans web default 命令生成多语言文件
使用 yao start 命令启动本地开发服务器

开发调试

页面模板调试，在页面中使用{{ $env }}在页面中输出页面渲染使用的变量<div>{{ $env }}</div>。
使用 yao sui build 使用-D参数参数会禁用缓存，并且生成的模板文件不会进行压缩。
请求 URL 中添加参数 ?__debug=true,页面加载时，浏览器控制台会自动的输出全局变量__sui_data。

`sui.d.ts`(sui项目中的类型定义):

/** HTTP请求接口 */
// 在后端脚本中使用，由`.json`数据文件中使用`@`修饰的函数调用
export interface Request {
  method: string; // 请求方法，如"GET"或"POST"
  asset_root?: string; // 资产访问根URL，可选
  referer?: string; // 请求来源URL
  payload?: Record<string, any>; // 请求负载数据
  query?: Record<string, string[]>; // URL查询参数
  params?: Record<string, string>; // URL路径参数
  headers?: Record<string, string[]>; // 请求头
  body?: any; // 请求体
  url?: URL; // 请求URL详情
  sid?: string; // 会话ID，可选
  theme?: string; // 主题偏好，可选
  locale?: string; // 区域设置，可选
}

/** 请求URL结构 */
export interface URL {
  host?: string; // 主机，如"www.example.com"
  domain?: string; // 域名，如"example.com"
  path?: string; // 路径，如"/path/to/route"
  scheme?: string; // 协议，如"http"或"https"
  url?: string; // 完整URL
}

/** 服务器数据 */
export declare const __sui_data: Record<string, any>;

/** 本地化消息和设置 */
export declare function __m(message: string): string;

// @ts-ignore
export declare const arguments: any[] = [];

/** 请求头类型 */
export type Headers = Record<string, string | string[]>;

/** 本地化设置接口 */
export interface Locale {
  name?: string; // 区域名称，如"en-US"
  keys?: Record<string, string>; // 翻译键值对
  messages?: Record<string, string>; // 消息模板
  direction?: "ltr" | "rtl"; // 文字方向
  timezone?: string; // 时区，如"+05:30"
}

/** UI组件类型 */
export declare type Component = {
  root: HTMLElement; // 组件根元素
  state: ComponentState; // 状态管理
  store: ComponentStore; // 状态存储
  $root: SUIQuery; // DOM查询对象
  find: (selector: string | HTMLElement) => SUIQuery | null; // 查找元素
  query: (selector: string) => HTMLElement | null; // 查询单个元素
  queryAll: (selector: string) => NodeListOf<Element> | 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>; // 组件常量
  [key: string]: any;
};

/** 渲染选项 */
export declare type RenderOption = {
  target?: HTMLElement; // 渲染目标容器
  showLoader?: HTMLElement | string | boolean; // 显示加载器
  replace?: boolean; // 是否替换现有内容
  withPageData?: boolean; // 是否包含页面数据
};

/** 组件状态管理 */
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; // 获取JSON数据
  SetJSON: (key: string, value: any) => void; // 设置JSON数据
  GetData: () => Record<string, any>; // 获取所有数据
};

/** 获取组件 */
export declare const $$: (selector: HTMLElement | string) => Component;

/** 事件详情 */
export declare type EventDetail<T = HTMLElement> = {
  rootElement: HTMLElement; // 组件根元素
  targetElement: T; // 事件目标元素
};

/** 事件数据 */
export declare type EventData = Record<string, any>;

/** 事件状态 */
export declare type State = {
  target: HTMLElement; // 目标元素
  stopPropagation(): void; // 停止事件传播
};

/** 创建渲染实例 */
export declare function $Render(component: Component | string, option?: RenderOption): SUIRender;

/** 渲染操作类 */
export declare class SUIRender {
  constructor(comp: Component | string, option?: RenderOption);
  Exec(name: string, data: Record<string, any>): Promise<string>; // 执行渲染
}

/** 获取存储 */
export declare function $Store(selector: HTMLElement | string): ComponentStore | null;

/** DOM查询 */
export declare function $Query(selector: string | HTMLElement): SUIQuery;

/** DOM操作类 */
export declare class SUIQuery {
  selector: string | Element; // 查询选择器或元素
  element: Element | null; // 当前元素
  elements: NodeListOf<Element> | null; // 匹配元素集合
  constructor(selector: string | Element);
  each(callback: (element: SUIQuery, index: number) => void): void; // 遍历元素
  elm(): Element | null; // 获取当前元素
  elms(): NodeListOf<Element> | null; // 获取所有元素
  find(selector: string): SUIQuery | null; // 查找子元素
  closest(selector: string): SUIQuery | null; // 查找最近祖先
  on(event: string, callback: (event: Event) => void): SUIQuery; // 添加事件监听
  $$(): Component | null; // 获取关联组件
  store(): ComponentStore | null; // 获取存储
  attr(name: string): string | null; // 获取html元素属性
  data(name: string): string | null; // 获取data属性
  json(name: string): any | null; // 获取JSON数据
  hasClass(className: string): boolean; // 检查类
  prop(name: string): any | null; // 获取page调用组件时传入的属性。
  removeClass(className: string | string[]): SUIQuery; // 移除类
  toggleClass(className: string | string[]): SUIQuery; // 切换类
  addClass(className: string | string[]): SUIQuery; // 添加类
  html(html?: string): SUIQuery | string; // 获取或设置HTML
}

/** 创建后端请求 */
export declare function $Backend<T = any>(route?: string, headers?: Headers): SUIBackend<T>;

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

/** YAO API交互类 */
export declare class Yao {
  constructor(host?: string);
  Get(path: string, params?: object, headers?: Headers): Promise<any>; // GET请求
  Post(path: string, data?: object, params?: object, headers?: Headers): Promise<any>; // POST请求
  Download(path: string, params: object, savefile: string, headers?: Headers): Promise<void>; // 下载文件
  Fetch(method: string, path: string, params?: object, data?: object, headers?: Headers, isblob?: boolean): Promise<any>; // 通用请求
  Token(): string; // 获取token
  Cookie(cookieName: string): string | null; // 获取cookie
  SetCookie(cookieName: string, cookieValue: string, expireDays?: number): void; // 设置cookie
  DeleteCookie(cookieName: string): void; // 删除cookie
}

/** 代理消息 */
export interface AgentMessage {
  text: string;
  type?: string;
  done?: boolean;
  is_neo?: boolean;
  assistant_id?: string;
  assistant_name?: string;
  assistant_avatar?: string;
  props?: Record<string, any>;
  tool_id?: string;
  new?: boolean;
  delta?: boolean;
  result?: any;
  previous_assistant_id?: string;
}

/** 完成事件数据 */
export type AgentDoneData = AgentMessage[];

/** 消息处理器 */
export interface MessageHandler {
  (message: AgentMessage): void;
}

/** 完成处理器 */
export interface DoneHandler {
  (messages: AgentDoneData): void;
}

/** 代理事件类型 */
export type AgentEvent = "message" | "done";

/** 事件处理器 */
export interface EventHandlers {
  message?: MessageHandler;
  done?: DoneHandler;
}

/** 代理类 */
export declare class Agent {
  constructor(assistant_id: string, option: AgentOption);
  private makeChatID(): string; // 生成聊天ID
  On<E extends AgentEvent>(event: E, handler: E extends "message" ? MessageHandler : DoneHandler): Agent; // 注册事件
  Cancel(): void; // 取消代理
  Call(input: AgentInput, ...args: any[]): Promise<any>; // 调用代理
}

/** 附件信息 */
export interface AgentAttachment {
  name: string;
  url: string;
  type: string;
  content_type: string;
  bytes: number;
  created_at: string;
  file_id: string;
  chat_id?: string;
  assistant_id?: string;
  description?: string;
}

/** 代理输入类型 */
export type AgentInput = string | { text: string; attachments?: AgentAttachment[] };

/** 代理初始化选项 */
export interface AgentOption {
  host?: string;
  token: string;
  silent?: boolean | string | number;
  history_visible?: boolean | string | number;
  chat_id?: string;
  context?: Record<string, any>;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240

Yao SUI模板引擎 ​

背景 ​

指令 ​

约束 ​

输出预期 ​

特定需求的示例提示 ​

下一步 ​

SUI 模板开发指南 ​

项目结构详解 ​

1. 基础配置文件 ​

2. 项目目录结构: ​

目录结构说明 ​

文件说明 ​

页面与组件的关系 ​

页面与组件的区别 ​

目录结构示例 ​

组件目录结构 ​

todolist项目示例： ​

todolist.html： ​

todolist.css： ​

模板关联数据文件todolist.json： ​

翻译文件 ​

todolist.ts（前端脚本）： ​

todolist.backend.ts(后端脚本)： ​

核心文件详解 ​

package.json ​

tailwind.css ​

__document.html ​

template.json(模板配置文件) ​

__data.json(模板全局数据配置文件): ​

页面/组件数据配置文件 (.json) ​

引用渲染全局变量 ​

静态数据 ​

后台函数调用 ​

处理器调用 ​

多语言文件配置__locales/localeID/pageID.yml与__locales/localeID/__global.yml ​

.html页面/组件开发模板语法规范 ​

1. 命名规范 ​

2. 模板语法规范 ​

模板数据来源 ​

3. HTML 模板 (.html) ​

属性展开： ​

模板渲染安全规则 ​

模板多语言支持： ​

样式文件 (.css) ​

前端脚本 (.ts) ​

前端脚本: ​

前端常用的操作： ​

多语言切换： ​

主题切换 ​

SUI模板组件状态管理： ​

3. 组件通信模式 ​

父子组件通信 ​

页面ts全局工具类： ​

模板局域重复渲染： ​

后端脚本 (.backend.ts) ​

前后端共用的常量： ​

component组件初始化 ​

后端脚本拦截处理组件参数传递示例： ​

在数据配置中使用后端函数： ​

暴露API方法： ​

前后端数据交互： ​

关键点 ​

数据流转 ​

示例代码 ​

1. 后端数据配置（page_name.json） ​

2.页面模板（page_name.html） ​

3.后端脚本（page_name.backend.ts） ​

4. 前端脚本（page_name.ts） ​

URL路由配置 ​

3. 页面/组件配置文件 (.config) ​

API 调用安全性（apiguard） ​

缓存相关 ​

SEO 配置（seo） ​

API 配置（api） ​

构建与部署： ​

开发调试 ​

sui.d.ts(sui项目中的类型定义): ​

Yao SUI模板引擎

背景

指令

约束

输出预期

特定需求的示例提示

下一步

SUI 模板开发指南

项目结构详解

1. 基础配置文件

2. 项目目录结构:

目录结构说明

文件说明

页面与组件的关系

页面与组件的区别

目录结构示例

组件目录结构

todolist项目示例：

todolist.html：

todolist.css：

模板关联数据文件todolist.json：

翻译文件

todolist.ts（前端脚本）：

todolist.backend.ts(后端脚本)：

核心文件详解

`package.json`

`tailwind.css`

`__document.html`

template.json(模板配置文件)

`__data.json`(模板全局数据配置文件):

页面/组件数据配置文件 (.json)

引用渲染全局变量

静态数据

后台函数调用

处理器调用

多语言文件配置`locales/localeID/pageID.yml`与`locales/localeID/__global.yml`

`.html`页面/组件开发模板语法规范

1. 命名规范

2. 模板语法规范

模板数据来源

3. HTML 模板 (.html)

属性展开：

模板渲染安全规则

模板多语言支持：

样式文件 (.css)

前端脚本 (.ts)

前端脚本:

前端常用的操作：

多语言切换：

主题切换

SUI模板组件状态管理：

3. 组件通信模式

父子组件通信

页面ts全局工具类：

模板局域重复渲染：

后端脚本 (.backend.ts)

前后端共用的常量：

component组件初始化

后端脚本拦截处理组件参数传递示例：

在数据配置中使用后端函数：

暴露API方法：

前后端数据交互：

关键点

数据流转

示例代码

1. 后端数据配置（`page_name.json`）

2.页面模板（page_name.html）

3.后端脚本（page_name.backend.ts）

4. 前端脚本（page_name.ts）

URL路由配置

3. 页面/组件配置文件 (.config)

API 调用安全性（apiguard）

缓存相关

SEO 配置（seo）

API 配置（api）

构建与部署：

开发调试

`sui.d.ts`(sui项目中的类型定义):