模板

A3S UI 为具有较大 HTML 结构的组件提供了可选的 Nunjucks 和 Jinja 宏。它们生成组件文档中显示的相同语义 A3S UI 标记，同时使重复的服务器渲染标记更易于维护。

这些模板使用 @a3s-lab/ui 进行版本控制，因此生成的标记与您安装的 CSS 和 JavaScript 文件相匹配。

可用宏

组件	宏	Nunjucks	Jinja
组合框	`combobox()`	combobox.njk	combobox.html.jinja
命令	`command()`	command.njk	command.html.jinja
命令	`command_dialog()`	command.njk	command.html.jinja
上下文菜单	`context_menu()`	context-menu.njk	context-menu.html.jinja
对话框	`dialog()`	dialog.njk	dialog.html.jinja
下拉菜单	`dropdown_menu()`	dropdown-menu.njk	dropdown-menu.html.jinja
弹出层	`popover()`	popover.njk	popover.html.jinja
选择菜单	`select()`	select.njk	select.html.jinja
侧边栏	`sidebar()`	sidebar.njk	sidebar.html.jinja
标签页	`tabs()`	tabs.njk	tabs.html.jinja
通知	`toaster()`	toast.njk	toast.html.jinja
通知	`toast()`	toast.njk	toast.html.jinja

某些宏文件包含内部递归助手，例如 render_select_items()。这些助手是实现细节，不属于公共 API 的一部分。

用途

安装模板

从 @a3s-lab/ui 复制模板引擎的模板文件夹。模板应归应用程序所有，因此您可以在复制后对其进行编辑。

Nunjucks

cp -R node_modules/@a3s-lab/ui/templates/nunjucks ./templates/a3s-ui

Jinja

cp -R node_modules/@a3s-lab/ui/templates/jinja ./templates/a3s-ui

如果您不需要完整的模板文件夹，则仅复制您使用的文件。

也可以直接从 GitHub 复制 Nunjucks templates 或 Jinja templates。

使用宏

从复制的模板文件导入宏，然后传入该组件所需的参数。

Nunjucks

{% from "a3s-ui/select.njk" import select %}
{{ select(
  name="fruit",
  label="水果",
  items=[
    { value: "apple", label: "Apple" },
    { value: "banana", label: "Banana" },
    { value: "blueberry", label: "Blueberry" }
  ]
) }}

Jinja

{% from "a3s-ui/select.html.jinja" import select %}
{{ select(
  name="fruit",
  label="水果",
  items=[
    { "value": "apple", "label": "Apple" },
    { "value": "banana", "label": "Banana" },
    { "value": "blueberry", "label": "Blueberry" }
  ]
) }}

宏参考

`combobox()`

参数	类型	默认值	描述
`id`	`string`	生成的	唯一的组合框 ID。
`selected`	`string \| array \| object`	`None` / `none`	初始选择的一个或多个值。对象可以包括 `value` 和 `label`。
`name`	`string`	`None` / `none`	隐藏输入名称。
`multiple`	`boolean`	`false`	启用基于芯片的多重选择。
`placeholder`	`string`	`None` / `none`	可见的输入占位符。
`close_on_select`	`boolean`	`false`	在多模式下选择每个选项后关闭弹出窗口。
`clear`	`boolean`	`false`	在单选模式下显示清除按钮。
`auto_highlight`	`boolean`	`false`	过滤时突出显示第一个匹配选项。
`format`	`"value" \| "object"`	`"value"`	隐藏输入序列化格式。
`main_attrs`	`object`	`{}`	`.combobox` 根的额外属性。
`input_attrs`	`object`	`{}`	可见输入或芯片输入包装器的额外属性。
`popover_attrs`	`object`	`{}`	弹出框元素的额外属性。
`listbox_attrs`	`object`	`{}`	列表框的额外属性。
`hidden_input_attrs`	`object`	`{}`	隐藏输入的额外属性。

`command()`

参数	类型	默认值	描述
`id`	`string`	生成的	唯一的命令 ID。
`items`	`array`	`None` / `none`	可选的结构化项目数据。省略时使用调用者内容。
`placeholder`	`string`	`"Type a command or search..."`	搜索输入占位符。
`empty_text`	`string`	`"No results found."`	空状态文本。
`main_attrs`	`object`	`{}`	`.command` 根的额外属性。
`input_attrs`	`object`	`{}`	搜索输入的额外属性。
`menu_attrs`	`object`	`{}`	命令菜单的额外属性。

`command_dialog()`

参数	类型	默认值	描述
`id`	`string`	生成的	唯一的命令对话框 ID。
`items`	`array`	`None` / `none`	可选的结构化项目数据。省略时使用调用者内容。
`placeholder`	`string`	`"Type a command or search..."`	搜索输入占位符。
`empty_text`	`string`	`"No results found."`	空状态文本。
`dialog_attrs`	`object`	`{}`	原生对话框的额外属性。
`input_attrs`	`object`	`{}`	搜索输入的额外属性。
`menu_attrs`	`object`	`{}`	命令菜单的额外属性。
`open`	`boolean`	`false`	是否默认以打开状态渲染。

`dialog()`

参数	类型	默认值	描述
`id`	`string`	生成的	唯一的对话框 ID。
`trigger`	`string`	`None` / `none`	生成的触发按钮的文本或 HTML。
`title`	`string`	`None` / `none`	对话框标题。
`description`	`string`	`None` / `none`	对话框描述。
`footer`	`string`	`None` / `none`	对话框页脚的 HTML。
`dialog_attrs`	`object`	`{}`	原生对话框的额外属性。
`trigger_attrs`	`object`	`{}`	生成的触发按钮的额外属性。
`header_attrs`	`object`	`{}`	对话框标题的额外属性。
`body_attrs`	`object`	`{}`	对话框主体部分的额外属性。
`footer_attrs`	`object`	`{}`	对话框页脚的额外属性。
`open`	`boolean`	`false`	是否默认以打开状态渲染。
`close_button`	`boolean`	`true`	包括生成的关闭按钮。
`close_on_overlay_click`	`boolean`	`true`	添加背景单击关闭行为。

`context_menu()`

参数	类型	默认值	描述
`trigger`	`string`	必填	右键或键盘菜单触发表面的 HTML。
`label`	`string`	`"Context menu"`	菜单的可访问名称。
`id`	`string`	生成的	唯一的上下文菜单 ID。
`main_attrs`	`object`	`{}`	`.context-menu` 根的额外属性。
`trigger_attrs`	`object`	`{}`	触发表面的额外属性。
`menu_attrs`	`object`	`{}`	菜单元素的额外属性。

`dropdown_menu()`

参数	类型	默认值	描述
`trigger`	`string`	必填	触发按钮的 HTML。
`id`	`string`	生成的	唯一的下拉菜单 ID。
`items`	`array`	`None` / `none`	可选的结构化菜单项数据。省略时使用调用者内容。
`main_attrs`	`object`	`{}`	`.dropdown-menu` 根的额外属性。
`trigger_attrs`	`object`	`{}`	触发按钮的额外属性。
`popover_attrs`	`object`	`{}`	弹出框元素的额外属性。
`menu_attrs`	`object`	`{}`	菜单元素的额外属性。

`popover()`

参数	类型	默认值	描述
`trigger`	`string`	必填	触发按钮的 HTML。
`id`	`string`	生成的	唯一的弹出窗口 ID。
`main_attrs`	`object`	`{}`	`.popover` 根的额外属性。
`trigger_attrs`	`object`	`{}`	触发按钮的额外属性。
`popover_attrs`	`object`	`{}`	弹出框元素的额外属性。

`select()`

参数	类型	默认值	描述
`id`	`string`	生成的	唯一的选择 ID。
`selected`	`string \| array`	`None` / `none`	初始选择的一个或多个值。
`name`	`string`	从 `id` 生成	隐藏输入名称。
`items`	`array`	`None` / `none`	可选的结构化项目数据。省略时使用调用者内容。
`multiple`	`boolean`	`false`	启用多项选择。
`placeholder`	`string`	`None` / `none`	多种模式的占位符文本，无需选择。
`close_on_select`	`boolean`	`false`	在多模式下选择每个选项后关闭弹出窗口。
`format`	`"value" \| "object"`	`"value"`	隐藏输入序列化格式。
`main_attrs`	`object`	`{}`	`.select` 根的额外属性。
`trigger_attrs`	`object`	`{}`	触发按钮的额外属性。
`popover_attrs`	`object`	`{}`	弹出框元素的额外属性。
`listbox_attrs`	`object`	`{}`	列表框的额外属性。
`input_attrs`	`object`	`{}`	隐藏输入的额外属性。
`label`	`string`	`None` / `none`	独立触发器的稳定无障碍名称；触发器已关联外部标签时省略。

`sidebar()`

参数	类型	默认值	描述
`id`	`string`	`None` / `none`	可选侧边栏 ID。当存在多个侧边栏时使用一个。
`label`	`string`	`"Sidebar navigation"`	导航地标标签。
`open`	`boolean`	`true`	初始打开状态。
`side`	`"left" \| "right"`	`"left"`	侧边栏所在的视口一侧。
`header`	`string`	`None` / `none`	侧边栏标题的 HTML。
`footer`	`string`	`None` / `none`	侧边栏页脚的 HTML。
`menu`	`array`	`None` / `none`	可选的结构化菜单数据。省略时使用调用者内容。
`main_attrs`	`object`	`{}`	`.sidebar` 根的额外属性。
`header_attrs`	`object`	`{}`	标题的额外属性。
`content_attrs`	`object`	`{}`	可滚动内容部分的额外属性。
`footer_attrs`	`object`	`{}`	页脚的额外属性。

`tabs()`

参数	类型	默认值	描述
`id`	`string`	生成的	唯一的选项卡 ID。
`tabsets`	`array`	`[]`	选项卡定义。每个项目可包括 `tab`、`panel`、`tab_attrs` 和 `panel_attrs`。
`main_attrs`	`object`	`{}`	`.tabs` 根的额外属性。
`tablist_attrs`	`object`	`{}`	选项卡列表的额外属性。此处使用 `aria-orientation="vertical"` 或 `data-variant="line"`。
`default_tab_index`	`number`	`1`	最初选择的选项卡的基于一的索引。

`toaster()`

参数	类型	默认值	描述
`id`	`string`	`"toaster"`	通知容器 ID。
`toasts`	`array`	`[]`	通知容器内初始渲染的通知对象。
`attrs`	`object`	`{}`	`.toaster` 容器的额外属性。

`toast()`

参数	类型	默认值	描述
`category`	`"success" \| "error" \| "info" \| "warning"`	`"success"`	通知类型，用于控制图标和 ARIA 角色。
`title`	`string`	`""`	通知标题。
`description`	`string`	`""`	通知说明。
`duration`	`number`	默认超时	超时（以毫秒为单位）。使用 `-1` 使 toast 保持打开状态。
`icon`	`string`	类别图标	自定义图标 HTML。
`action`	`object`	`None` / `none`	操作按钮/链接配置。支持`label`、`onclick`和`href`。
`cancel`	`object`	`None` / `none`	取消按钮/链接配置。支持`label`、`onclick`和`href`。
`attrs`	`object`	`{}`	`.toast` 元素的额外属性。

#模板

#可用宏

#用途

#安装模板

#使用宏

#宏参考

#combobox()

#command()

#command_dialog()

#dialog()

#context_menu()

#dropdown_menu()

#popover()

#select()

#sidebar()

#tabs()

#toaster()

#toast()

模板

可用宏

用途

安装模板

使用宏

宏参考

`combobox()`

`command()`

`command_dialog()`

`dialog()`

`context_menu()`

`dropdown_menu()`

`popover()`

`select()`

`sidebar()`

`tabs()`

`toaster()`

`toast()`