m8-framework-mcp 1.0.0

package/docs/m8mpdoc-develop/002-/350/247/204/350/214/203/344/270/216/346/250/241/345/274/217/003.1-style-guide-a.md

@@ -0,0 +1,872 @@
+# 优先级 A 的规则：必要的 (规避错误)
+
+<div class="style-guide">
+
+## 目录和文件命名 <span class="priority-a">必要</span>
+
+**工程中的目录与组件文件一律使用 kebab-case 命名，禁止大小写混杂或使用下划线。**
+
+跨平台构建时大小写混用的路径最容易出问题，统一短横线小写可以避免在不同操作系统之间出现路径识别异常。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```
+components/UserProfile.vue
+components/Form_Item.vue
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```
+components/user-profile.vue
+components/form-item.vue
+```
+
+</div>
+
+## 模板标签与属性使用 kebab-case <span class="priority-a">必要</span>
+
+**模板内的组件标签和属性绑定全部使用 kebab-case，禁止在模板中写 PascalCase。**
+
+保持模板完全小写并用短横线连接，可以避免和原生标签、Web Component 混用时的歧义，也符合新规范的检查规则。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+<EpForm primaryType="type"></EpForm>
+<ep-input v-model="userName" primaryType="main"></ep-input>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<ep-form primary-type="type"></ep-form>
+<ep-input v-model="userName" primary-type="main"></ep-input>
+```
+
+</div>
+
+## 组件命名规范 <span class="priority-a">必要</span>
+
+**组件的定义名必须使用 PascalCase，且名称至少由两个单词组成，避免与原生元素冲突。**
+
+多单词的 PascalCase 既能确保不会和 HTML 元素同名，又与导出、自动补全保持一致。
+
+**组件名应该始终是多个单词的，根组件 `App` 以及 `<transition>`、`<component>` 之类的 Vue 内置组件除外。**
+
+这样做可以避免跟现有的以及未来的 HTML 元素相冲突，因为所有的 HTML 元素名称都是单个单词的。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```js
+export default {
+    name: 'todo',
+    // ...
+};
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```js
+export default {
+    name: 'TodoItem',
+    // ...
+};
+```
+
+</div>
+
+## 组件属性命名 <span class="priority-a">必要</span>
+
+**`defineProps` 中的属性名统一使用小驼峰，模板传参使用 kebab-case，不得混用大小写或下划线。**
+
+保持脚本与模板的命名映射清晰，避免大小写不一致导致的属性读取失败。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```vue
+<script setup>
+const props = defineProps({
+    'user-name': String,
+    MaxCount: Number
+});
+</script>
+
+<template>
+    <ep-user-card userName="codex" :MaxCount="10"></ep-user-card>
+</template>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```vue
+<script setup>
+const props = defineProps({
+    userName: {
+        type: String,
+        required: true
+    },
+    maxCount: {
+        type: Number,
+        default: 10
+    }
+});
+</script>
+
+<template>
+    <ep-user-card user-name="codex" :max-count="10"></ep-user-card>
+</template>
+```
+
+</div>
+
+## 禁止修改 Props <span class="priority-a">必要</span>
+
+**组件内部禁止直接修改通过 `defineProps` 声明的入参，必须通过事件或计算属性派生值。**
+
+直接赋值会破坏单向数据流，引发状态不同步。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```vue
+<script setup>
+const props = defineProps({ visible: Boolean });
+
+props.visible = false;
+</script>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```vue
+<script setup>
+const props = defineProps({ visible: Boolean });
+const emit = defineEmits(['update:visible']);
+
+const hide = () => emit('update:visible', false);
+</script>
+
+<template>
+    <ep-dialog :visible="visible" @close="hide"></ep-dialog>
+</template>
+```
+
+</div>
+
+## defineProps / defineEmits 规范 <span class="priority-a">必要</span>
+
+**严格按 Vue 3 官方写法使用 `defineProps` 与 `defineEmits`，事件必须显式声明后再调用。**
+
+禁止传入运行时动态值或未声明事件的 `emit`，确保类型推导与校验生效。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```vue
+<script setup>
+const props = defineProps(runtimeProps);
+
+const submit = (payload) => {
+    emit('submit', payload); // emit 未声明
+};
+</script>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{
+    modelValue: string;
+    disabled?: boolean;
+}>();
+
+const emit = defineEmits<{
+    (e: 'update:modelValue', value: string): void;
+    (e: 'submit'): void;
+}>();
+
+const submit = (payload: string) => {
+    emit('update:modelValue', payload);
+    emit('submit');
+};
+</script>
+```
+
+</div>
+
+## #组件数据 <span class="priority-a">必要</span>
+
+**组件的 `data` 必须是一个函数。**
+
+当在组件中使用 `data` property 的时候 (除了 new Vue 外的任何地方)，它的值必须是返回一个对象的函数。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```js
+export default {
+    data: {
+        foo: 'bar',
+    },
+};
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```js
+// 在单独的 vue 文件中
+export default {
+    data() {
+        return {
+            foo: 'bar',
+        };
+    },
+};
+```
+
+</div>
+
+## 计算属性禁止使用异步 <span class="priority-a">必要</span>
+
+**计算属性只能包含同步逻辑，异步请求应放到生命周期或方法中再回填结果。**
+
+异步计算属性不会按预期更新依赖，可能导致渲染时机不确定。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```vue
+<script setup>
+const totalPrice = computed(async () => {
+    const res = await fetch('/api/order');
+    return res.total;
+});
+</script>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```vue
+<script setup>
+import { onMounted, ref, computed } from 'vue';
+
+const orderTotal = ref(0);
+
+onMounted(async () => {
+    const res = await fetch('/api/order').then((r) => r.json());
+    orderTotal.value = res.total;
+});
+
+const totalPrice = computed(() => orderTotal.value);
+</script>
+```
+
+</div>
+
+## 避免重复的 key 定义 <span class="priority-a">必要</span>
+
+**`props`、`data`、`computed` 等对象内禁止出现重复的字段，避免后者覆盖前者导致逻辑混乱。**
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```vue
+<script setup>
+import { reactive } from 'vue';
+
+const props = defineProps({
+    userInfo: Object,
+    userInfo: Array
+});
+
+const state = reactive({
+    userInfo: {},
+    userInfo: []
+});
+</script>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```vue
+<script setup>
+import { reactive } from 'vue';
+
+const props = defineProps({
+    userInfo: {
+        type: Object,
+        default: () => ({})
+    }
+});
+
+const state = reactive({
+    userProfile: {}
+});
+</script>
+```
+
+</div>
+
+## 禁止未使用的组件或变量 <span class="priority-a">必要</span>
+
+**注册的组件、声明的变量或模板参数必须被实际使用，避免死代码与包体积膨胀。**
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```vue
+<script setup>
+import EpButton from './ep-button.vue';
+import EpTable from './ep-table.vue';
+import { ref } from 'vue';
+
+const count = ref(0);
+const unused = ref(true);
+</script>
+
+<template>
+    <ep-table></ep-table>
+</template>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```vue
+<script setup>
+import EpButton from './ep-button.vue';
+import EpTable from './ep-table.vue';
+import { ref } from 'vue';
+
+const count = ref(0);
+</script>
+
+<template>
+    <ep-table></ep-table>
+    <ep-button @click="count++">点击 {{ count }}</ep-button>
+</template>
+```
+
+</div>
+
+## #为 `v-for` 设置键值 <span class="priority-a">必要</span>
+
+**总是用 `key` 配合 `v-for`。**
+
+在组件上总是必须用 `key` 配合 `v-for`，以便维护内部组件及其子树的状态。甚至在元素上维护可预测的行为，比如动画中的对象固化 (object constancy)，也是一种好的做法。
+
+<details>
+
+<summary>
+  <h4>详解</h4>
+</summary>
+
+假设你有一个待办事项列表：
+
+```js
+data: function () {
+  return {
+    todos: [
+      {
+        id: 1,
+        text: '学习使用 v-for'
+      },
+      {
+        id: 2,
+        text: '学习使用 key'
+      }
+    ]
+  }
+}
+```
+
+然后你把它们按照字母顺序排序。在更新 DOM 的时候，Vue 将会优化渲染把可能的 DOM 变更降到最低。即可能删掉第一个待办事项元素，然后把它重新加回到列表的最末尾。
+
+这里的问题在于，不要删除仍然会留在 DOM 中的元素。比如你想使用 `<transition-group>` 给列表加过渡动画，或想在被渲染元素是 `<input>` 时保持聚焦。在这些情况下，为每一个项目添加一个唯一的键值 (比如 `:key="todo.id"`) 将会让 Vue 知道如何使行为更容易预测。
+
+根据我们的经验，最好*始终*添加一个唯一的键值，以便你和你的团队永远不必担心这些极端情况。也在少数对性能有严格要求的情况下，为了避免对象固化，你可以刻意做一些非常规的处理。
+
+</details>
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+<ul>
+    <li v-for="todo in todos">{{ todo.text }}</li>
+</ul>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<ul>
+    <li v-for="todo in todos" :key="todo.id">{{ todo.text }}</li>
+</ul>
+```
+
+</div>
+
+## #避免 `v-if` 和 `v-for` 用在一起 <span class="priority-a">必要</span>
+
+**永远不要把 v-if 和 v-for 同时用在同一个元素上。**
+
+一般我们在两种常见的情况下会倾向于这样做：
+
+为了过滤一个列表中的项目 (比如 `v-for="user in users" v-if="user.isActive"`)。在这种情形下，请将 `users` 替换为一个计算属性 (比如 `activeUsers`)，让其返回过滤后的列表。
+
+为了避免渲染本应该被隐藏的列表 (比如 `v-for="user in users" v-if="shouldShowUsers"`)。这种情形下，请将 `v-if` 移动至容器元素上 (比如 `ul`、`ol`)。
+
+<details>
+
+<summary>
+
+  <h4>详解</h4>
+
+</summary>
+
+当 Vue 处理指令时，`v-for` 比 `v-if` 具有更高的优先级，所以这个模板：
+
+```html
+<ul>
+    <li v-for="user in users" v-if="user.isActive" :key="user.id">{{ user.name }}</li>
+</ul>
+```
+
+将会经过如下运算：
+
+```js
+this.users.map(function (user) {
+    if (user.isActive) {
+        return user.name;
+    }
+});
+```
+
+因此哪怕我们只渲染出一小部分用户的元素，也得在每次重渲染的时候遍历整个列表，不论活跃用户是否发生了变化。
+
+通过将其更换为在如下的一个计算属性上遍历：
+
+```js
+computed: {
+  activeUsers: function () {
+    return this.users.filter(function (user) {
+      return user.isActive
+    })
+  }
+}
+```
+
+```html
+<ul>
+    <li v-for="user in activeUsers" :key="user.id">{{ user.name }}</li>
+</ul>
+```
+
+我们将会获得如下好处：
+
+-   过滤后的列表*只*会在 `users` 数组发生相关变化时才被重新运算，过滤更高效。
+-   使用 `v-for="user in activeUsers"` 之后，我们在渲染的时候*只*遍历活跃用户，渲染更高效。
+-   解耦渲染层的逻辑，可维护性 (对逻辑的更改和扩展) 更强。
+
+为了获得同样的好处，我们也可以把：
+
+```html
+<ul>
+    <li v-for="user in users" v-if="shouldShowUsers" :key="user.id">{{ user.name }}</li>
+</ul>
+```
+
+更新为：
+
+```html
+<ul v-if="shouldShowUsers">
+    <li v-for="user in users" :key="user.id">{{ user.name }}</li>
+</ul>
+```
+
+通过将 `v-if` 移动到容器元素，我们不会再对列表中的*每个*用户检查 `shouldShowUsers`。取而代之的是，我们只检查它一次，且不会在 `shouldShowUsers` 为否的时候运算 `v-for`。
+
+</details>
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+<ul>
+    <li v-for="user in users" v-if="user.isActive" :key="user.id">{{ user.name }}</li>
+</ul>
+```
+
+```html
+<ul>
+    <li v-for="user in users" v-if="shouldShowUsers" :key="user.id">{{ user.name }}</li>
+</ul>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<ul>
+    <li v-for="user in activeUsers" :key="user.id">{{ user.name }}</li>
+</ul>
+```
+
+```html
+<ul v-if="shouldShowUsers">
+    <li v-for="user in users" :key="user.id">{{ user.name }}</li>
+</ul>
+```
+
+</div>
+
+## 禁止直接使用 v-html 渲染不可信内容 <span class="priority-a">必要</span>
+
+**避免使用 `v-html` 直接渲染接口返回或用户可控的 HTML，必须经过安全过滤后再使用。**
+
+直接插入不可信内容会带来 XSS 风险。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+<template>
+    <div v-html="serverHtml"></div>
+</template>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<template>
+    <div v-html="safeHtml"></div>
+</template>
+
+<script setup>
+import { computed } from 'vue';
+import { sanitize } from '@/utils/sanitize-html';
+
+const props = defineProps({ content: String });
+const safeHtml = computed(() => sanitize(props.content || ''));
+</script>
+```
+
+</div>
+
+## #为组件样式设置作用域 <span class="priority-a">必要</span>
+
+**对于应用来说，顶级 `App` 组件和布局组件中的样式可以是全局的，但是其它所有组件都应该是有作用域的，可通过 `<style scoped>` 或 CSS Modules 实现。**
+
+这让覆写内部样式更容易：使用了常人可理解的 class 名称且没有太高的选择器优先级，而且不太会导致冲突。
+
+<details>
+<summary>
+  <h4>详解</h4>
+</summary>
+
+如果你和其他开发者一起开发一个大型工程，或有时引入三方 HTML/CSS (比如来自 Auth0)，设置一致的作用域会确保你的样式只会运用在它们想要作用的组件上。
+
+不止要使用 `scoped` attribute，使用唯一的 class 名可以帮你确保那些三方库的 CSS 不会运用在你自己的 HTML 上。比如许多工程都使用了 `button`、`btn` 或 `icon` class 名，所以即便你不使用类似 BEM 的策略，添加一个 app 专属或组件专属的前缀 (比如 `ButtonClose-icon`) 也可以提供很多保护。
+
+</details>
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```html
+<template>
+    <button class="btn btn-close">X</button>
+</template>
+
+<style>
+    .btn-close {
+        background-color: red;
+    }
+</style>
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```html
+<template>
+    <button class="button button-close">X</button>
+</template>
+
+<!-- 使用 `scoped` attribute -->
+<style scoped>
+    .button {
+        border: none;
+        border-radius: 2px;
+    }
+
+    .button-close {
+        background-color: red;
+    }
+</style>
+```
+
+</div>
+
+## 数据模型必须在 `<script setup>` 中创建 <span class="priority-a">必要</span>
+
+**数据模型的创建必须放在组件的 `<script setup>` 里完成，禁止在单独的 JS 文件里直接生成模型实例。**
+
+集中在组件内定义可以确保依赖、生命周期一致，避免被误复用或遗漏初始化。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```js
+// model.js
+export const model = Utils.definedDataModel(() => ({
+    name: '',
+    age: 0
+}));
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```vue
+<script setup>
+import { Utils } from '@epoint/ep-ui';
+
+const model = Utils.definedDataModel(() => ({
+    name: '',
+    age: 0
+}));
+</script>
+```
+
+</div>
+
+## 静态资源就近存放 <span class="priority-a">必要</span>
+
+**页面相关的图片、样式、脚本等静态资源应放在页面自身目录下，全局目录仅放通用资源。**
+
+就近存放能避免全局污染和资源冲突，也便于按需清理。
+
+<div class="style-example example-bad">
+
+### 反例：
+
+```bash
+src/assets/
+|- user-banner.png   # 仅用户页使用
+pages/user/index.vue
+```
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+```bash
+pages/user/
+|- assets/
+|  |- banner.png
+|- index.vue
+```
+
+</div>
+
+## 私有 property 名 <span class="priority-a">必要</span>
+
+**使用模块作用域保持不允许外部访问的函数的私有性。如果无法做到这一点，就始终为插件、混入等不考虑作为对外公共 API 的自定义私有 property 使用 `$_` 前缀。并附带一个命名空间以回避和其它作者的冲突 (比如 `$_yourPluginName_`)。**
+
+
+<details>
+<summary>
+  <h4>详解</h4>
+</summary>
+
+Vue 使用 `_` 前缀来定义其自身的私有 property，所以使用相同的前缀 (比如 `_update`) 有覆写实例 property 的风险。即便你检查确认 Vue 当前版本没有用到这个 property 名，也不能保证和将来的版本没有冲突。
+
+对于 `$` 前缀来说，其在 Vue 生态系统中的目的是暴露给用户的一个特殊的实例 property，所以把它用于*私有* property 并不合适。
+
+不过，我们推荐把这两个前缀结合为 `$_`，作为一个用户定义的私有 property 的约定，以确保不会和 Vue 自身相冲突。
+
+</details>
+
+<div class="style-example example-bad">
+
+### 反例：
+
+``` js
+var myGreatMixin = {
+  // ...
+  methods: {
+    update: function () {
+      // ...
+    }
+  }
+}
+```
+
+``` js
+var myGreatMixin = {
+  // ...
+  methods: {
+    _update: function () {
+      // ...
+    }
+  }
+}
+```
+
+``` js
+var myGreatMixin = {
+  // ...
+  methods: {
+    $update: function () {
+      // ...
+    }
+  }
+}
+```
+
+``` js
+var myGreatMixin = {
+  // ...
+  methods: {
+    $_update: function () {
+      // ...
+    }
+  }
+}
+```
+
+
+</div>
+<div class="style-example example-good">
+
+### 好例子：
+
+``` js
+var myGreatMixin = {
+  // ...
+  methods: {
+    $_myGreatMixin_update: function () {
+      // ...
+    }
+  }
+}
+```
+
+``` js
+// 甚至更好！
+var myGreatMixin = {
+  // ...
+  methods: {
+    publicMethod() {
+      // ...
+      myPrivateFunction()
+    }
+  }
+}
+
+function myPrivateFunction() {
+  // ...
+}
+
+export default myGreatMixin
+```
+
+</div>
+
+
+</div>
+<style>
+.priority-a {
+    color: #f44336;
+    font-size: 12px
+}
+.style-guide summary {
+    display: list-item;
+    cursor: pointer;
+    padding: 1.6em;
+    margin: -1.6em;
+    outline: none;
+}
+.style-guide details, .style-guide .style-enforcement {
+    background-color: #eee;
+}
+.style-guide details h4 {
+    display: inline-block;
+}
+.style-example, .style-guide details, .style-guide .style-enforcement {
+    border-radius: 2px;
+    margin: 1.6em 0;
+    padding: 12px;
+}
+.style-example.example-bad {
+        background: #f7e8e8;
+}
+.style-guide .style-example.example-good {
+    background: #eaedec;
+}
+</style>