From 9bdf4c32d0cde455bec3491f643eb7bcebc2e487 Mon Sep 17 00:00:00 2001
From: 07akioni <07akioni2@gmail.com>
Date: Sun, 17 Apr 2022 17:46:43 +0800
Subject: [PATCH] docs: add controlled & uncontorlled part

---
 .../controlled-uncontrolled/enUS/index.md     | 33 +++++++++++++++++++
 .../controlled-uncontrolled/zhCN/index.md     | 33 +++++++++++++++++++
 demo/routes/debug-route-mixin.js              |  0
 demo/routes/routes.js                         | 10 ++++++
 demo/store/menu-options.js                    |  5 +++
 5 files changed, 81 insertions(+)
 create mode 100644 demo/pages/docs/controlled-uncontrolled/enUS/index.md
 create mode 100644 demo/pages/docs/controlled-uncontrolled/zhCN/index.md
 delete mode 100644 demo/routes/debug-route-mixin.js

diff --git a/demo/pages/docs/controlled-uncontrolled/enUS/index.md b/demo/pages/docs/controlled-uncontrolled/enUS/index.md
new file mode 100644
index 000000000..22c58faf5
--- /dev/null
+++ b/demo/pages/docs/controlled-uncontrolled/enUS/index.md
@@ -0,0 +1,33 @@
+<!--anchor:on-->
+
+# Controlled manner & uncontrolled manner
+
+A component's manner can be controlled or uncontrolled. Uncontrolled manner means you only listen to its change but not controll its value. Controlled manner means you controll the component's value.
+
+## Uncontrolled manner
+
+In this situation, you don't set `<n-input />`'s `value` but only listen to its change. Component's value will be controlled by itself.
+
+```html
+<n-input @update:value="handleUpdateValue" />
+```
+
+## Controlled manner
+
+In the situation, you listen to component's value & change at the same time. If you don't update `value`, component's value won't be changed. Its value is controlled by you.
+
+```html
+<n-input :value="value" @update:value="handleUpdateValue" />
+```
+
+### `v-model`
+
+A component with `v-model` works in controlled manner, since `v-model` is the same as `:model-value` and `@update:model-value`.
+
+## Uncontrolled manner in naive-ui
+
+Different library has different behavior on how to distinguish controlled or uncontrlled manner. In naive-ui, if `value` is `undefined` or not passed, it will be uncontrolled. That is to say, if you set a component's value to `undefined` won't clear it but transform it from controlled manner to uncontrolled manner. If you need to clear it, at most time you can use `null`.
+
+### Not only `value`
+
+Any props pair like `xxx` & `@update:xxx` can work both in controlled manner or uncontrolled manner.
diff --git a/demo/pages/docs/controlled-uncontrolled/zhCN/index.md b/demo/pages/docs/controlled-uncontrolled/zhCN/index.md
new file mode 100644
index 000000000..8a04ab5c0
--- /dev/null
+++ b/demo/pages/docs/controlled-uncontrolled/zhCN/index.md
@@ -0,0 +1,33 @@
+<!--anchor:on-->
+
+# 受控模式与非受控模式
+
+一个组件的行为可以分为受控模式和非受控模式两种。非受控模式指的是只监听组件的变化，而不去控制组件的 value，受控模式指的是控制组件的值。
+
+## 非受控模式
+
+在这种情况下，你不去控制 `<n-input />` 的 `value`，而只能监听它的变化，组件值的变化由组件自身控制。
+
+```html
+<n-input @update:value="handleUpdateValue" />
+```
+
+## 受控模式
+
+在这种情况下，你既监听了组件的变化，然后也控制了组件的值。如果你不更新 `value`，那么组件组件的值不会改变，组件值的变化由你控制。
+
+```html
+<n-input :value="value" @update:value="handleUpdateValue" />
+```
+
+### `v-model`
+
+`v-model` 控制的组件在受控模式下，因为 `v-model` 等同于 `:model-value` 和 `@update:model-value` 的组合。
+
+## naive-ui 中的受控模式
+
+不同的组件库区分受控与非受控模式的区别是不同的。在 naive-ui 中，只要 `value` 是 `undefined` 或者根本没有传，那么组件的值会是非受控的。也就是说你将一个组件的值设为 `undefined` 并不能清空它，只会改变它的控制模式。一般情况下清空可以使用 `null`。
+
+### 不止 `value`
+
+任何 `xxx` 与 `@update:xxx` 的属性对都可以有受控和非受控模式。
diff --git a/demo/routes/debug-route-mixin.js b/demo/routes/debug-route-mixin.js
deleted file mode 100644
index e69de29bb..000000000
diff --git a/demo/routes/routes.js b/demo/routes/routes.js
index 241e21a96..6fe775ada 100644
--- a/demo/routes/routes.js
+++ b/demo/routes/routes.js
@@ -67,6 +67,11 @@ export const enDocRoutes = [
   {
     path: 'style-position',
     component: () => import('../pages/docs/style-position/enUS/index.md')
+  },
+  {
+    path: 'controlled-uncontrolled',
+    component: () =>
+      import('../pages/docs/controlled-uncontrolled/enUS/index.md')
   }
 ]
 
@@ -139,6 +144,11 @@ export const zhDocRoutes = [
   {
     path: 'style-position',
     component: () => import('../pages/docs/style-position/zhCN/index.md')
+  },
+  {
+    path: 'controlled-uncontrolled',
+    component: () =>
+      import('../pages/docs/controlled-uncontrolled/zhCN/index.md')
   }
 ]
 
diff --git a/demo/store/menu-options.js b/demo/store/menu-options.js
index d579ed589..c62169f29 100644
--- a/demo/store/menu-options.js
+++ b/demo/store/menu-options.js
@@ -106,6 +106,11 @@ export function createDocumentationMenuOptions ({ lang, theme, mode }) {
           en: 'Common Issues',
           zh: '常见问题',
           path: '/common-issues'
+        },
+        {
+          en: 'Controlled & Uncontrolled',
+          zh: '受控与非受控',
+          path: '/controlled-uncontrolled'
         }
       ]
     },