init

Author: maomincoding

doc/en/changeLog/index.md

@@ -4,7 +4,11 @@
 Although the version number uses the version number of Mettle, the content includes not only the updated content of Mettle, but also the updated content of other official tools in the same period.
 :::
 
-## v0.3.1 (Latest)
+## v0.5.0 (Latest)
+
+- Added two built-in properties, `$once` and `$memo`, to optimize rendering performance.
+
+## v0.3.1
 
 - Support TSX development applications. TSX provides type safety, better development experience and code maintainability in front-end projects.
 

doc/en/essentials/api/index.md

@@ -96,6 +96,8 @@ function add() {
 }
 ```
 
+The third parameter is optional. Its type is `Symbol` and is used with the built-in attribute `$memo` to indicate updated data.
+
 ## html
 
 ` html`` ` is a tag function. The syntax of the tag function is to directly follow the function name with a template string. For example, you can write HTML tags directly in the template string.

doc/en/essentials/example/index.md

@@ -631,3 +631,28 @@ export default () =>
     return () => <div style={toastStyles()}>{msg}</div>;
   });
 ```
+
+## Object to string
+
+```jsx
+function useObjToStyle(obj: any) {
+  const needUnit = (key: any) => !/[0-9]$/.test(key) && typeof obj[key] === 'number';
+
+  return Object.entries(obj)
+    .map(([key, value]) => {
+      const cssKey = key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+      const cssValue = needUnit(key) ? `${value}px` : value;
+      return `${cssKey}:${cssValue};`;
+    })
+    .join(' ');
+}
+
+let isShow = true;
+function useShowStyle() {
+  const style = {
+    display: isShow ? 'block' : 'none',
+  };
+
+  return useObjToStyle(style);
+}
+```

doc/en/essentials/usage/index.md

@@ -323,6 +323,87 @@ defineComponent(() => {
 });
 ```
 
+### $once
+
+Render the element only once, and skip future updates.
+
+```jsx
+defineComponent(() => {
+  let count = 0;
+
+  function add() {
+    setData(() => {
+      count++;
+    });
+  }
+
+  return () => (
+    <fragment>
+      <button onClick={add}>Add</button>
+      <h1 $once>{count}</h1>
+      <input value={count} />
+    </fragment>
+  );
+});
+```
+
+### $memo
+
+Cache a subtree of a template and skip the update of the subtree.
+
+This property requires an array of fixed length. The value of the first item in the array is of type `Boolean`. If the value is `false`, the update of the entire subtree will be skipped. The value of the second item in the array is of type `Symbol`, which is used with `setData`.
+
+```jsx
+defineComponent(({ setData }) => {
+  const symbol1 = Symbol();
+  let selected = 0;
+  let arr = [
+    {
+      id: '1',
+      val: 'A',
+    },
+    {
+      id: '2',
+      val: 'B',
+    },
+    {
+      id: '3',
+      val: 'C',
+    },
+  ];
+
+  function handle(event) {
+    const el = event.target;
+    const id = Number(el.dataset.id);
+    setData(
+      () => {
+        selected = id;
+      },
+      null,
+      symbol1
+    );
+    return false;
+  }
+
+  return () => (
+    <fragment>
+      <ul onClick={handle}>
+        {arr.map((todo) => (
+          <li
+            $memo={[todo.id == selected, symbol1]}
+            class={todo.id == selected ? 'danger' : ''}
+            key={todo.id}
+            data-id={todo.id}
+          >
+            {todo.val}
+          </li>
+        ))}
+      </ul>
+    </fragment>
+  );
+});
+```
+
 ## Built-in Tags
 
 ### component

doc/zh/changeLog/index.md

@@ -4,7 +4,11 @@
 版本号虽然取用的是 Mettle 的版本号，但是内容不仅仅含有 Mettle 更新的内容，还有同期的其他官方工具的更新内容。
 :::
 
-## v0.3.1 (Latest)
+## v0.5.0 (Latest)
+
+- 新增`$once`、`$memo`两个内置属性，用来优化渲染性能。
+
+## v0.3.1
 
 - 支持 TSX 开发应用，TSX 在前端项目中提供了类型安全、更好的开发体验和代码可维护性。
 

doc/zh/essentials/api/index.md

@@ -96,6 +96,8 @@ function add() {
 }
 ```
 
+第三个参数非必传，参数的类型是`Symbol`，与内置属性`$memo`搭配使用，用于标明更新的数据。
+
 ## html
 
 ` html`` `是一个标签函数，标签函数的语法是直接在函数名后跟一个模板字符串。 例如，你可以直接在模板字符串中编写 HTML 标签。

doc/zh/essentials/example/index.md

@@ -631,3 +631,28 @@ export default () =>
     return () => <div style={toastStyles()}>{msg}</div>;
   });
 ```
+
+## 对象转换为字符串
+
+```jsx
+function useObjToStyle(obj: any) {
+  const needUnit = (key: any) => !/[0-9]$/.test(key) && typeof obj[key] === 'number';
+
+  return Object.entries(obj)
+    .map(([key, value]) => {
+      const cssKey = key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+      const cssValue = needUnit(key) ? `${value}px` : value;
+      return `${cssKey}:${cssValue};`;
+    })
+    .join(' ');
+}
+
+let isShow = true;
+function useShowStyle() {
+  const style = {
+    display: isShow ? 'block' : 'none',
+  };
+
+  return useObjToStyle(style);
+}
+```

doc/zh/essentials/usage/index.md

@@ -323,6 +323,87 @@ defineComponent(() => {
 });
 ```
 
+### $once
+
+仅渲染元素一次，并跳过之后的更新。
+
+```jsx
+defineComponent(({ setData }) => {
+  let count = 0;
+
+  function add() {
+    setData(() => {
+      count++;
+    });
+  }
+
+  return () => (
+    <fragment>
+      <button onClick={add}>Add</button>
+      <h1 $once>{count}</h1>
+      <input value={count} />
+    </fragment>
+  );
+});
+```
+
+### $memo
+
+缓存一个模板的子树，跳过子树的更新。
+
+该属性需要传入一个固定长度的数组。数组第一项的值的类型为 `Boolean`，如果值为`false`，那么整个子树的更新将被跳过。数组第二项值的类型为 `Symbol`，与 `setData` 搭配使用。
+
+```jsx
+defineComponent(({ setData }) => {
+  const symbol1 = Symbol();
+  let selected = 0;
+  let arr = [
+    {
+      id: '1',
+      val: 'A',
+    },
+    {
+      id: '2',
+      val: 'B',
+    },
+    {
+      id: '3',
+      val: 'C',
+    },
+  ];
+
+  function handle(event) {
+    const el = event.target;
+    const id = Number(el.dataset.id);
+    setData(
+      () => {
+        selected = id;
+      },
+      null,
+      symbol1
+    );
+    return false;
+  }
+
+  return () => (
+    <fragment>
+      <ul onClick={handle}>
+        {arr.map((todo) => (
+          <li
+            $memo={[todo.id == selected, symbol1]}
+            class={todo.id == selected ? 'danger' : ''}
+            key={todo.id}
+            data-id={todo.id}
+          >
+            {todo.val}
+          </li>
+        ))}
+      </ul>
+    </fragment>
+  );
+});
+```
+
 ## 内置标签
 
 ### component