docs(anchor): [anchor] anchor docs optimization (#781)

examples/sites/demos/pc/app/anchor/basic-usage-composition-api.vue

@@ -1,7 +1,7 @@
 <template>
   <tiny-switch v-model="type" true-value="line" false-value="dot"> </tiny-switch>
   当前类型：{{ type }}
-  <tiny-anchor :links="links"></tiny-anchor>
+  <tiny-anchor :links="links" :type="type"></tiny-anchor>
 </template>
 
 <script setup>

examples/sites/demos/pc/app/anchor/change-composition-api.vue

@@ -1,5 +1,5 @@
 <template>
-  <tiny-anchor :links="links" @on-change="handleChange"></tiny-anchor>
+  <tiny-anchor :links="links" @change="handleChange"></tiny-anchor>
 </template>
 
 <script setup>

examples/sites/demos/pc/app/anchor/change.vue

@@ -1,5 +1,5 @@
 <template>
-  <tiny-anchor :links="links" @on-change="handleChange"></tiny-anchor>
+  <tiny-anchor :links="links" @change="handleChange"></tiny-anchor>
 </template>
 
 <script>

examples/sites/demos/pc/app/anchor/webdoc/anchor.cn.md

@@ -4,4 +4,4 @@ title: Anchor 锚点
 
 # Anchor 锚点
 
-<div>跳转到页面指定位置。</div>
+<div>用于页内导航。</div>

examples/sites/demos/pc/app/anchor/webdoc/anchor.en.md

@@ -4,4 +4,4 @@ title: Anchor
 
 # Anchor
 
-<div>Jump to the specified position on the page.</div>
+<div>Used for intra page navigation.</div>

examples/sites/demos/pc/app/anchor/webdoc/anchor.js

@@ -6,8 +6,8 @@ export default {
       'demoId': 'basic-usage',
       'name': { 'zh-CN': '基本用法', 'en-US': 'Basic Usage' },
       'desc': {
-        'zh-CN': '属性<code>links</code>传入数据渲染',
-        'en-US': 'Attribute <code>links</code>: input data rendering'
+        'zh-CN': '通过<code>links</code>设置导航数据，<code>type</code>设置类型。',
+        'en-US': 'Set navigation data through<code>links</code>, and<code>type</code>to set the type.'
       },
       'codeFiles': ['basic-usage.vue']
     },
@@ -15,8 +15,8 @@ export default {
       'demoId': 'is-affix',
       'name': { 'zh-CN': '固定模式', 'en-US': 'Fixed mode' },
       'desc': {
-        'zh-CN': '设置属性<code>is-affix</code>为true, 让锚点不随页面滚动',
-        'en-US': 'Set the <code>is-affix</code> attribute to true so that the anchor does not scroll with the page.'
+        'zh-CN': '通过<code>is-affix</code>设置固定定位，不随页面滚动。',
+        'en-US': 'Set fixed positioning through<code>is affix</code>, without scrolling with the page.'
       },
       'codeFiles': ['is-affix.vue']
     },
@@ -24,21 +24,21 @@ export default {
       'demoId': 'set-container',
       'name': { 'zh-CN': '滚动容器', 'en-US': 'Rolling Container' },
       'desc': {
-        'zh-CN':
-          '通过<code>container-id</code>属性指定滚动容器，<code>link-click</code>监听锚点点击事件，阻止浏览器默认行为，实现单页面<code>hash</code>路由模式的页内跳转，让页面只在想要的指定容器内滚动。通过<code>mask-class</code>属性设置自定义类名，高亮显示滚动的目标元素',
-        'en-US':
-          'Use the <code>container-id</code> attribute to specify the scrolling container. <code>link-click</code> listens to anchor click events and prevents the default browser behavior. Implement intra-page redirection in single-page <code>hash</code> routing mode so that the page scrolls only in the specified container. Set the custom class name through the <code>mask-class</code> attribute to highlight the scrolling target element'
+        'zh-CN': `通过<code>container-id</code>设置滚动容器，<code>link-click</code>监听锚点点击事件，阻止浏览器默认行为，实现单页面<code>hash</code>路由模式的页内跳转，在指定容器内滚动。<br/>
+           <code>mask-class</code>设置自定义类名，高亮显示导航的目标元素。`,
+        'en-US': `By setting the scrolling container through<code>container id</code>,<code>link click</code>listens for anchor click events, prevents browser default behavior, and implements single page<code>hash</code>routing mode for page hopping, scrolling within the specified container< Br/>
+            <code>mask class</code>Set a custom class name to highlight the target element for navigation.`
       },
       'codeFiles': ['set-container.vue']
     },
     {
-      'demoId': 'on-change',
+      'demoId': 'change',
       'name': { 'zh-CN': 'change事件', 'en-US': 'change event' },
       'desc': {
-        'zh-CN': '<code>on-change</code>事件，锚点链接改变时触发回调',
-        'en-US': '<code>on-change</code> event. Callback is triggered when the anchor link changes.'
+        'zh-CN': '通过<code>change</code>监听锚点改变的事件。',
+        'en-US': '<code>change</code> event. Callback is triggered when the anchor link changes.'
       },
-      'codeFiles': ['on-change.vue']
+      'codeFiles': ['change.vue']
     }
   ],
   apis: [
@@ -49,8 +49,12 @@ export default {
         {
           'name': 'container-id',
           'type': 'string',
-          'defaultValue': 'document.body',
-          'desc': { 'zh-CN': '指定滚动容器的id值', 'en-US': 'Specify the scrolling container ID.' },
+          'defaultValue': '',
+          'desc': {
+            'zh-CN': '用于单页面 hash 路由模式时指定滚动容器的id值，不指定则默认为 HTML 文档的根节点 body 元素',
+            'en-US':
+              'When using single page hash routing mode, specify the id value of the scrolling container. If not specified, it defaults to the root node body element of the HTML document'
+          },
           'demoId': 'set-container'
         },
         {
@@ -62,11 +66,12 @@ export default {
         },
         {
           'name': 'links',
-          'type': '{ key, link, title, children }[]',
+          'type': 'ILink[]',
+          'typeAnchorName': 'ILink',
           'defaultValue': '',
           'desc': {
-            'zh-CN': '数据配置项，可通过children嵌套',
-            'en-US': 'Data configuration item, which can be nested by children.'
+            'zh-CN': '导航数据配置项，可通过children嵌套',
+            'en-US': 'Navigation data configuration items can be nested through children'
           },
           'demoId': 'basic-usage'
         },
@@ -94,29 +99,50 @@ export default {
       'events': [
         {
           'name': 'link-click',
-          'type': 'Function(arg1,arg2)',
+          'type': '(arg1: Event, arg2: {link: string, title: string}) => void',
           'defaultValue': '',
           'desc': {
-            'zh-CN':
-              '锚点点击事件, 点击后触发的回调函数;//参数arg1:点击事件对象 //参数arg2: {link: 点击锚点的链接, title: 点击节点的标题文字 }',
-            'en-US':
-              'An anchor click event, which is a callback function triggered after the anchor clicks. //Parameter arg1: click event object //Parameter arg2: {link: click anchor link, title: click node title}'
+            'zh-CN': '锚点点击事件；// 参数arg2: {link: 当前锚点链接, title: 当前锚点标题 }',
+            'en-US': 'Anchor click event; // Parameter arg2: {link: Current anchor link, title: Current anchor title}'
           },
           'demoId': 'set-container'
         },
         {
-          'name': 'on-change',
-          'type': 'Function(arg1)',
+          'name': 'change',
+          'type': '(arg1: string) => void',
           'defaultValue': '',
           'desc': {
-            'zh-CN': '监听锚点链接的改变；锚点改变后的回调函数; // 参数arg1: 当前锚点的id值',
-            'en-US':
-              'Listen to the change of the anchor link; Callback function after the anchor point is changed; //arg1: ID of the current anchor'
+            'zh-CN': '锚点链接改变事件；// 参数arg1: 当前锚点的 hash 值',
+            'en-US': 'Anchor link change event// Parameter arg1: hash value of the current anchor point'
           },
-          'demoId': 'on-change'
+          'demoId': 'change'
+        },
+        {
+          'name': 'on-change',
+          'type': '(arg: string) => void',
+          'defaultValue': '',
+          'desc': {
+            'zh-CN': '[deprecated v3.12.0废弃，v3.17.0移除；移除原因：命名规范，使用change代替]',
+            'en-US':
+              '[deprecated v3.12.0 abandoned, v3.17.0 removed; reason for removal: naming convention, use change instead]'
+          },
+          'demoId': 'change'
         }
       ],
       'slots': []
     }
+  ],
+  types: [
+    {
+      name: 'ILink',
+      type: 'interface',
+      code: `
+interface ILink {
+  key: string // 锚点的key值
+  link: string // 导航的hash值
+  title: string // 锚点标题
+  children: ILink[] // 子锚点
+}`
+    }
   ]
 }

packages/renderless/src/anchor/index.ts

@@ -54,7 +54,8 @@ const updateSkidPosition = ({ vm, state, emit }: Pick<IAnchorRenderlessParams, '
     return
   }
 
-  emit('onChange', currentLink)
+  emit('change', currentLink)
+  emit('onChange', currentLink) // deprecated 原事件onChange v3.12.0废弃，v3.17.0移除；移除原因：命名规范
 
   if (!anchorRef || !skidRef || !maskRef) {
     return