docs(agents): add design references
This commit is contained in:
@@ -0,0 +1,50 @@
|
||||
---
|
||||
name: arco-vue-controlled-values
|
||||
description: "Arco Design Vue 受控与非受控值模式。用于判断何时使用 `v-model`、命名 `v-model:*`、默认属性和组件内部状态。"
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# 受控值模式
|
||||
|
||||
在 Vue 中要先明确状态归属：业务代码需要读取、提交、持久化或联动的值，应由父级状态控制；仅用于组件初始展示的值，可以交给组件内部维护。
|
||||
|
||||
## 使用 v-model 受控
|
||||
|
||||
当父级状态拥有当前值时，使用 `v-model`。
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { ref } from 'vue';
|
||||
|
||||
const keyword = ref('');
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<a-input v-model="keyword" allow-clear />
|
||||
</template>
|
||||
```
|
||||
|
||||
弹窗可见性、抽屉可见性、选中项等状态通常使用命名双向绑定。
|
||||
|
||||
```vue
|
||||
<a-modal v-model:visible="visible" title="确认">
|
||||
内容
|
||||
</a-modal>
|
||||
```
|
||||
|
||||
## 使用默认状态
|
||||
|
||||
当组件只需要一个初始值，父级代码不需要响应每次变化时，使用文档中声明的 `default-*` 属性。
|
||||
|
||||
```vue
|
||||
<a-tabs default-active-key="overview">
|
||||
<a-tab-pane key="overview" title="概览" />
|
||||
<a-tab-pane key="detail" title="详情" />
|
||||
</a-tabs>
|
||||
```
|
||||
|
||||
## 判断规则
|
||||
|
||||
- 表单字段、筛选条件、弹窗可见性、选中项、分页状态，以及会被提交或持久化的值，优先使用 `v-model`。
|
||||
- 静态示例或纯局部交互状态，可以使用 `default-*`。
|
||||
- 同一个状态不要同时使用 `v-model` 和对应的 `default-*` 属性，避免状态来源不一致。
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: arco-vue-form-patterns
|
||||
description: "Arco Design Vue 表单模式。用于 `a-form`、`a-form-item`、`field`、`model`、校验规则、动态字段、提交成功或失败，以及弹窗内表单。"
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# 表单模式
|
||||
|
||||
完整表单 API 参考 [form.md](../components/data-entry/form.md)。
|
||||
|
||||
## 基础组合式表单
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { reactive } from 'vue';
|
||||
import { Message } from '@arco-design/web-vue';
|
||||
|
||||
const form = reactive({
|
||||
username: '',
|
||||
role: '',
|
||||
});
|
||||
|
||||
const rules = {
|
||||
username: [{ required: true, message: '请输入用户名' }],
|
||||
role: [{ required: true, message: '请选择角色' }],
|
||||
};
|
||||
|
||||
const handleSubmit = (values: unknown) => {
|
||||
Message.success('提交成功');
|
||||
console.log(values);
|
||||
};
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<a-form :model="form" :rules="rules" layout="vertical" @submit-success="handleSubmit">
|
||||
<a-form-item field="username" label="用户名">
|
||||
<a-input v-model="form.username" placeholder="请输入用户名" />
|
||||
</a-form-item>
|
||||
<a-form-item field="role" label="角色">
|
||||
<a-select v-model="form.role" :options="['admin', 'user']" placeholder="请选择角色" />
|
||||
</a-form-item>
|
||||
<a-button type="primary" html-type="submit">提交</a-button>
|
||||
</a-form>
|
||||
</template>
|
||||
```
|
||||
|
||||
## 使用要点
|
||||
|
||||
- `:model` 始终绑定到同一个响应式对象，避免字段分散在多个来源。
|
||||
- `a-form-item` 使用 `field` 标识字段路径，不使用 `name`。
|
||||
- 提交按钮使用 `html-type="submit"`，并在表单上监听 `@submit-success` 和 `@submit-failed`。
|
||||
- 简单表单可将校验规则放在模型附近；复杂表单可抽到组合函数中统一维护。
|
||||
- 嵌套对象和动态字段使用 Form 文档支持的字段路径，例如 `people[1].id`。
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
name: arco-vue-modal-patterns
|
||||
description: "Arco Design Vue 弹窗与反馈模式。用于 `a-modal`、`v-model:visible`、确认流程、弹窗表单、Message、Notification 和 Drawer。"
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# 弹窗与反馈模式
|
||||
|
||||
详细 API 参考 [modal.md](../components/feedback/modal.md)、[drawer.md](../components/feedback/drawer.md) 和 [message.md](../components/feedback/message.md)。
|
||||
|
||||
## 受控弹窗
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { ref } from 'vue';
|
||||
|
||||
const visible = ref(false);
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<a-button type="primary" @click="visible = true">打开</a-button>
|
||||
<a-modal v-model:visible="visible" title="编辑">
|
||||
<p>内容</p>
|
||||
</a-modal>
|
||||
</template>
|
||||
```
|
||||
|
||||
## 弹窗内表单
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { reactive, ref } from 'vue';
|
||||
import { Message } from '@arco-design/web-vue';
|
||||
|
||||
const visible = ref(false);
|
||||
const form = reactive({ name: '' });
|
||||
|
||||
const handleBeforeOk = async () => {
|
||||
if (!form.name) {
|
||||
Message.error('请输入名称');
|
||||
return false;
|
||||
}
|
||||
Message.success('保存成功');
|
||||
return true;
|
||||
};
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<a-modal v-model:visible="visible" title="编辑" :on-before-ok="handleBeforeOk">
|
||||
<a-form :model="form" layout="vertical">
|
||||
<a-form-item field="name" label="名称" required>
|
||||
<a-input v-model="form.name" />
|
||||
</a-form-item>
|
||||
</a-form>
|
||||
</a-modal>
|
||||
</template>
|
||||
```
|
||||
|
||||
## 使用要点
|
||||
|
||||
- 弹窗和抽屉的可见性使用 `v-model:visible`。
|
||||
- 异步确认、表单校验、关闭拦截使用文档中的 `on-before-ok` 或关闭前钩子。
|
||||
- 轻量结果反馈使用 `Message`；需要标题、正文或更复杂内容时使用 `Notification`。
|
||||
- `Message` 和 `Notification` 是全局服务 API，不是 `<a-message>` 或 `<a-notification>` 组件标签。
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: arco-vue-responsive-design
|
||||
description: "Arco Design Vue 响应式布局模式。用于响应式 Grid、页面布局、表单、仪表盘和移动端友好的组件组合。"
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# 响应式布局
|
||||
|
||||
优先使用 Arco Vue 的 Grid 和 Layout 组件表达响应式页面结构。
|
||||
|
||||
## 响应式栅格
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<a-row :gutter="[16, 16]">
|
||||
<a-col :xs="24" :sm="12" :lg="8">
|
||||
<a-card title="指标 A">...</a-card>
|
||||
</a-col>
|
||||
<a-col :xs="24" :sm="12" :lg="8">
|
||||
<a-card title="指标 B">...</a-card>
|
||||
</a-col>
|
||||
<a-col :xs="24" :sm="24" :lg="8">
|
||||
<a-card title="指标 C">...</a-card>
|
||||
</a-col>
|
||||
</a-row>
|
||||
</template>
|
||||
```
|
||||
|
||||
## 使用要点
|
||||
|
||||
- Grid 能表达的布局优先使用 `xs`、`sm`、`md`、`lg`、`xl`、`xxl` 属性，不必额外编写媒体查询。
|
||||
- 窄屏表单优先使用纵向布局，降低标签和输入框互相挤压的概率。
|
||||
- 小屏表格需要保留可用性，可使用横向滚动、隐藏次要列，或改成卡片和列表展示。
|
||||
- 仪表盘、表格和重复卡片应设置稳定尺寸，避免加载态和数据变化造成布局跳动。
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
name: arco-vue-table-patterns
|
||||
description: "Arco Design Vue 表格模式。用于 `a-table`、列配置、数据源、行选择、分页、远程加载、插槽、排序和筛选。"
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# 表格模式
|
||||
|
||||
完整表格 API 参考 [table.md](../components/data-display/table.md)。
|
||||
|
||||
## 基础表格
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const columns = [
|
||||
{ title: '名称', dataIndex: 'name' },
|
||||
{ title: '状态', dataIndex: 'status', slotName: 'status' },
|
||||
{ title: '操作', slotName: 'actions' },
|
||||
];
|
||||
|
||||
const data = [
|
||||
{ key: '1', name: '任务 A', status: 'running' },
|
||||
{ key: '2', name: '任务 B', status: 'done' },
|
||||
];
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<a-table :columns="columns" :data="data" row-key="key">
|
||||
<template #status="{ record }">
|
||||
<a-tag :color="record.status === 'done' ? 'green' : 'blue'">
|
||||
{{ record.status }}
|
||||
</a-tag>
|
||||
</template>
|
||||
<template #actions="{ record }">
|
||||
<a-button type="text" size="small">查看 {{ record.name }}</a-button>
|
||||
</template>
|
||||
</a-table>
|
||||
</template>
|
||||
```
|
||||
|
||||
## 远程数据
|
||||
|
||||
- 将分页、筛选、排序状态放在本地响应式状态中。
|
||||
- 用一个请求函数统一拉取数据，在 `onMounted` 和表格变更事件中复用。
|
||||
- 请求中给表格设置加载状态，避免重复操作和空白反馈。
|
||||
- 不要在每次渲染时重新创建列配置；列应定义一次，或由稳定输入计算得到。
|
||||
Reference in New Issue
Block a user