@opentiny/vue-docs 3.28.0 → 3.30.0

package/demos/pc/app/grid/filter/layout-order-filter-composition-api.vue

@@ -0,0 +1,114 @@
+<template>
+  <tiny-grid :data="tableData" @filter-change="filterChangeEvent">
+    <tiny-grid-column type="index" width="60"></tiny-grid-column>
+    <tiny-grid-column field="name" title="公司名称" :filter="nameFilter"></tiny-grid-column>
+    <tiny-grid-column field="city" title="城市" :filter="cityFilter"></tiny-grid-column>
+    <tiny-grid-column field="employees" title="员工数" :filter="employeesFilter"></tiny-grid-column>
+  </tiny-grid>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { TinyGrid, TinyGridColumn, TinyModal, TinyNumeric } from '@opentiny/vue'
+
+const cityData = [
+  { label: '福州', value: '福州' },
+  { label: '深圳', value: '深圳' },
+  { label: '中山', value: '中山' }
+]
+
+const tableData = ref([
+  {
+    id: '1',
+    name: 'GFD 科技 YX 公司',
+    city: '福州',
+    employees: 800,
+    createdDate: '2014-04-30 00:56:00'
+  },
+  {
+    id: '2',
+    name: 'WWW 科技 YX 公司',
+    city: '深圳',
+    employees: 300,
+    createdDate: '2016-07-08 12:36:22'
+  },
+  {
+    id: '3',
+    name: 'RFV 有限责任公司',
+    city: '中山',
+    employees: 1300,
+    createdDate: '2014-02-14 14:14:14'
+  },
+  {
+    id: '4',
+    name: 'TGB 科技 YX 公司',
+    city: '龙岩',
+    employees: 360,
+    createdDate: '2013-01-13 13:13:13'
+  },
+  {
+    id: '5',
+    name: 'YHN 科技 YX 公司',
+    city: '韶关',
+    employees: 810,
+    createdDate: '2012-12-12 12:12:12'
+  },
+  {
+    id: '6',
+    name: 'WSX 科技 YX 公司',
+    city: '黄冈',
+    employees: 800,
+    createdDate: '2011-11-11 11:11:11'
+  },
+  {
+    id: '7',
+    name: 'KBG 物业 YX 公司',
+    city: '赤壁',
+    employees: 400,
+    createdDate: '2016-04-30 23:56:00'
+  },
+  {
+    id: '8',
+    name: '深圳市福德宝网络技术 YX 公司',
+    city: '厦门',
+    employees: 540,
+    createdDate: '2016-06-03 13:53:25'
+  }
+])
+
+const cityFilter = ref({
+  multi: true,
+  enumable: true,
+  inputFilter: false,
+  defaultFilter: false,
+  values: cityData,
+  layout: 'enum,base'
+})
+
+const nameFilter = ref({
+  enumable: false,
+  inputFilter: true,
+  defaultFilter: false,
+  layout: 'input,base'
+})
+
+const employeesFilter = ref({
+  layout: 'extends,input,base',
+  inputFilter: {
+    component: TinyNumeric,
+    attrs: {},
+    relations: [
+      { label: '小于', value: 'lessThan' },
+      { label: '大于', value: 'greaterThan' }
+    ]
+  },
+  extends: [
+    { label: '大型企业(>500)', method: ({ value }) => value > 500 },
+    { label: '小型企业(<500)', method: ({ value }) => value < 500 }
+  ]
+})
+
+function filterChangeEvent({ filters }) {
+  TinyModal.message({ message: `筛选条件：${JSON.stringify(filters)}`, status: 'info' })
+}
+</script>

package/demos/pc/app/grid/filter/layout-order-filter.spec.ts

@@ -0,0 +1,31 @@
+import { test, expect } from '@playwright/test'
+
+test('自定义筛选项顺序 - 城市列 layout enum,base', async ({ page }) => {
+  page.on('pageerror', (exception) => expect(exception).toBeNull())
+  await page.goto('grid-filter#filter-layout-order-filter')
+
+  // 城市列：layout enum,base 仅显示枚举和清除
+  await page.getByRole('cell', { name: '城市' }).getByRole('img').first().click()
+  const filterPanel = page.locator('.tiny-grid__filter-wrapper.filter__active')
+  await filterPanel.waitFor({ state: 'visible' })
+  await filterPanel.getByTitle('福州').click()
+  await filterPanel.getByRole('button', { name: '确定' }).click()
+
+  // 筛选后应只显示福州的 1 条数据
+  await expect(page.getByRole('cell', { name: '福州' })).toHaveCount(1)
+  await expect(page.locator('.tiny-grid-body__row')).toHaveCount(1)
+})
+
+test('自定义筛选项顺序 - 员工数列 extends 快捷筛选', async ({ page }) => {
+  page.on('pageerror', (exception) => expect(exception).toBeNull())
+  await page.goto('grid-filter#filter-layout-order-filter')
+
+  // 员工数列：layout extends,input,base 点击扩展项 大型企业(>500)
+  await page.getByRole('cell', { name: '员工数' }).getByRole('img').first().click()
+  const filterPanel = page.locator('.tiny-grid__filter-wrapper.filter__active')
+  await filterPanel.waitFor({ state: 'visible' })
+  await filterPanel.getByText('大型企业(>500)').click()
+
+  // 筛选后应只显示员工数>500的行：800,1300,810,800,540 共 5 条
+  await expect(page.locator('.tiny-grid-body__row')).toHaveCount(5)
+})

package/demos/pc/app/grid/filter/layout-order-filter.vue

@@ -0,0 +1,123 @@
+<template>
+  <tiny-grid :data="tableData" @filter-change="filterChangeEvent">
+    <tiny-grid-column type="index" width="60"></tiny-grid-column>
+    <tiny-grid-column field="name" title="公司名称" :filter="nameFilter"></tiny-grid-column>
+    <tiny-grid-column field="city" title="城市" :filter="cityFilter"></tiny-grid-column>
+    <tiny-grid-column field="employees" title="员工数" :filter="employeesFilter"></tiny-grid-column>
+  </tiny-grid>
+</template>
+
+<script>
+import { TinyGrid, TinyGridColumn, TinyModal, TinyNumeric } from '@opentiny/vue'
+
+const cityData = [
+  { label: '福州', value: '福州' },
+  { label: '深圳', value: '深圳' },
+  { label: '中山', value: '中山' }
+]
+
+export default {
+  components: {
+    TinyGrid,
+    TinyGridColumn
+  },
+  data() {
+    return {
+      tableData: [
+        {
+          id: '1',
+          name: 'GFD 科技 YX 公司',
+          city: '福州',
+          employees: 800,
+          createdDate: '2014-04-30 00:56:00'
+        },
+        {
+          id: '2',
+          name: 'WWW 科技 YX 公司',
+          city: '深圳',
+          employees: 300,
+          createdDate: '2016-07-08 12:36:22'
+        },
+        {
+          id: '3',
+          name: 'RFV 有限责任公司',
+          city: '中山',
+          employees: 1300,
+          createdDate: '2014-02-14 14:14:14'
+        },
+        {
+          id: '4',
+          name: 'TGB 科技 YX 公司',
+          city: '龙岩',
+          employees: 360,
+          createdDate: '2013-01-13 13:13:13'
+        },
+        {
+          id: '5',
+          name: 'YHN 科技 YX 公司',
+          city: '韶关',
+          employees: 810,
+          createdDate: '2012-12-12 12:12:12'
+        },
+        {
+          id: '6',
+          name: 'WSX 科技 YX 公司',
+          city: '黄冈',
+          employees: 800,
+          createdDate: '2011-11-11 11:11:11'
+        },
+        {
+          id: '7',
+          name: 'KBG 物业 YX 公司',
+          city: '赤壁',
+          employees: 400,
+          createdDate: '2016-04-30 23:56:00'
+        },
+        {
+          id: '8',
+          name: '深圳市福德宝网络技术 YX 公司',
+          city: '厦门',
+          employees: 540,
+          createdDate: '2016-06-03 13:53:25'
+        }
+      ],
+      // layout 自定义顺序：枚举优先，其次输入，最后清除
+      cityFilter: {
+        multi: true,
+        enumable: true,
+        inputFilter: false,
+        defaultFilter: false,
+        values: cityData,
+        layout: 'enum,base'
+      },
+      nameFilter: {
+        enumable: false,
+        inputFilter: true,
+        defaultFilter: false,
+        layout: 'input,base'
+      },
+      // layout 自定义顺序：扩展项 + 输入 + 清除
+      employeesFilter: {
+        layout: 'extends,input,base',
+        inputFilter: {
+          component: TinyNumeric,
+          attrs: {},
+          relations: [
+            { label: '小于', value: 'lessThan' },
+            { label: '大于', value: 'greaterThan' }
+          ]
+        },
+        extends: [
+          { label: '大型企业(>500)', method: ({ value }) => value > 500 },
+          { label: '小型企业(<500)', method: ({ value }) => value < 500 }
+        ]
+      }
+    }
+  },
+  methods: {
+    filterChangeEvent({ filters }) {
+      TinyModal.message({ message: `筛选条件：${JSON.stringify(filters)}`, status: 'info' })
+    }
+  }
+}
+</script>

package/demos/pc/app/grid/toolbar/custom-toolbar.spec.js

@@ -3,6 +3,6 @@ import { test, expect } from '@playwright/test'
 test('工具栏自定义插槽', async ({ page }) => {
   page.on('pageerror', (exception) => expect(exception).toBeNull())
   await page.goto('grid-toolbar#toolbar-custom-toolbar')
-  await expect(page.getByRole('textbox', { name: '请输入公司名称' })).toBeVisible()
+  await expect(page.getByRole('searchbox', { name: '请输入公司名称' })).toBeVisible()
   await expect(page.getByRole('button', { name: '取消全选' })).toBeVisible()
 })

package/demos/pc/app/grid/webdoc/grid-filter.js

@@ -4,126 +4,175 @@ export default {
   demos: [
     {
       demoId: 'filter-default-filter',
-      name: { 'zh-CN': '过滤', 'en-US': 'Filter' },
+      name: { 'zh-CN': '基础筛选', 'en-US': 'Basic Filter' },
       desc: {
         'zh-CN': `
         <div class="tip custom-block">
           <p class="custom-block-title">filter 配置</p>
-          <p>通过自定义的 <code>filter</code> 的作用域插槽自定义筛选的规则，可以配置项：
+          <p>通过 <code>filter</code> 属性配置列筛选。配置项及对应关系：
             <ul>
-              <li>multi 设置在显示枚举选项功能是否为多选，仅在 enumable:true 下有效。</li>
-              <li>enumable 设置在过滤面板中显示枚举选项。</li>
-              <li>inputFilter 设置在过滤面板中显示输入筛选的项。</li>
-              <li>defaultFilter 设置在过滤面板中显示默认的筛选条件。</li>
-              <li>values 设置在显示枚举选项功能 (enumable) 下制定静态数据源。</li>
-              <li>label 设置枚举数据的显示值属性字段，默认'label'。</li>
-              <li>value 设置枚举数据的实际值属性字段，默认'value'。</li>
+              <li><strong>layout</strong> 筛选项显示顺序，默认 <code>input,enum,default,extends,base</code>。各取值与下方配置一一对应：<code>input</code>→inputFilter，<code>enum</code>→enumable，<code>default</code>→defaultFilter，<code>extends</code>→extends，<code>base</code>→清除选项，<code>simple</code>→simpleFilter（与其它 layout 项互斥）。</li>
+              <li><strong>inputFilter</strong> 输入筛选。true 使用默认 input；传入对象可配置 <code>component</code>、<code>relations</code>、<code>relation</code>、<code>attrs</code>。</li>
+              <li><strong>enumable</strong> 是否显示枚举选项。需 layout 包含 enum 或 simple 时生效。</li>
+              <li><strong>multi</strong> 枚举是否为多选，仅在 enumable 为 true 时有效，默认 true。</li>
+              <li><strong>values</strong> 枚举数据源。数组或 <code>(params)=>Promise</code>；不传则从表格数据自动提取。</li>
+              <li><strong>label</strong> / <strong>value</strong> 枚举项显示值和实际值的字段名，默认 label、value。用于 values 数据结构的字段映射。</li>
+              <li><strong>defaultFilter</strong> 是否显示空/非空筛选。需 layout 包含 default。</li>
+              <li><strong>extends</strong> 扩展快捷筛选项数组，每项含 <code>label</code>、<code>value?</code>、<code>method</code>。需 layout 包含 extends。</li>
+              <li><strong>condition</strong> 初始筛选条件，如 <code>condition.value</code> 设置默认选中、<code>condition.relation</code> 设置默认关系。</li>
+              <li><strong>simpleFilter</strong> 简化版配置，需 <code>layout:'simple'</code>。含 <code>isDatetime</code>（日期范围）、<code>selectAll</code>（全选）、<code>datetimeConfig</code>（isDatetime 时必填）、<code>searchConfig</code>（非日期时可选，为枚举列表加搜索框）。</li>
+              <li><strong>method</strong> 自定义筛选方法，用于 <code>#filter</code> 插槽完全自定义时实现筛选逻辑。</li>
+              <li><strong>attrs</strong> 过滤面板根节点属性，如 id、class 等。</li>
+              <li><strong>dataset</strong> 数据源配置，用于异步获取枚举选项。</li>
+              <li><strong>filter-popper-options</strong> 设置过滤面板弹出层配置项。</li>
             </ul>
           </p>
         </div>
         `,
         'en-US':
-          '<div class="tip custom-block"><p class="custom-block-title">filter Configuration</p>\n<p>Customize filtering rules based on the scope slot of the customized <code>filter</code>.\nConfigurable items:\nMulti specifies whether to select multiple enumeration options. This parameter is valid only when enable:true is selected. \nenumable Sets the display of enumeration options in the filter panel. \ninputFilter Sets the display of the input filtered items in the filter panel. \ndefaultFilter Sets the default filter criteria to be displayed in the filter panel. \nvalues specifies the static data source under the display enumeration option function (enumable). \nlabel Sets the display value attribute field of enumerated data. The default value is label. \nvalue Sets the actual value attribute field of the enumerated data. The default value is\'value\'. </p>\n</div>\n'
+          '<div class="tip custom-block"><p class="custom-block-title">filter Configuration</p><p>Configure column filtering via <code>filter</code> prop. Options and constraints: <code>layout</code> - filter order (default: input,enum,default,extends,base). Each value maps to: input→inputFilter, enum→enumable, default→defaultFilter, extends→extends, base→clear, simple→simpleFilter (exclusive). <code>inputFilter</code> - true or {component, relations, relation, attrs}. <code>enumable</code> - show enum options (requires enum or simple in layout). <code>multi</code> - enum multi-select when enumable. <code>values</code> - array or (params)=>Promise; auto-extract from table if omitted. <code>label</code>/<code>value</code> - field mapping for values. <code>defaultFilter</code> - empty/non-empty (requires default in layout). <code>extends</code> - shortcut items [{label, value?, method}]. <code>condition</code> - initial filter state. <code>simpleFilter</code> - for layout:simple (isDatetime, selectAll, datetimeConfig, searchConfig). <code>method</code> - custom filter logic for #filter slot. <code>attrs</code>, <code>dataset</code>.</p></div>'
       },
       codeFiles: ['filter/default-filter.vue']
     },
+    {
+      demoId: 'filter-layout-order-filter',
+      name: { 'zh-CN': '自定义筛选项顺序', 'en-US': 'Custom Layout Order' },
+      desc: {
+        'zh-CN':
+          '<p>通过 <code>layout</code> 自定义筛选项的显示顺序和组合。默认值为 <code>input,enum,default,extends,base</code>。可选项：<code>input</code> 输入筛选、<code>enum</code> 枚举选择、<code>default</code> 空/非空、<code>extends</code> 扩展项、<code>base</code> 清除操作、<code>simple</code> 简化版。</p>',
+        'en-US':
+          '<p>Use <code>layout</code> to customize the display order and combination of filter items. Default value is <code>input,enum,default,extends,base</code>. Options: <code>input</code>, <code>enum</code>, <code>default</code>, <code>extends</code>, <code>base</code>, <code>simple</code>.</p>'
+      },
+      codeFiles: ['filter/layout-order-filter.vue']
+    },
+    {
+      demoId: 'filter-label-value-filter',
+      name: { 'zh-CN': 'label/value 字段映射', 'en-US': 'Label/Value Field Mapping' },
+      desc: {
+        'zh-CN':
+          '<p>通过 <code>label</code> 和 <code>value</code> 配置枚举数据的显示值和实际值字段，适配后端返回的 code/name 等不同字段结构。默认分别为 <code>label</code> 和 <code>value</code>。</p>',
+        'en-US':
+          '<p>Use <code>label</code> and <code>value</code> to configure the display and actual value fields for enum data, adapting to different field structures such as code/name from backend. Defaults are <code>label</code> and <code>value</code>.</p>'
+      },
+      codeFiles: ['filter/filter-label-value.vue']
+    },
     {
       demoId: 'filter-dynamic-filter',
-      name: { 'zh-CN': '动态改变筛选项', 'en-US': 'Filter' },
+      name: { 'zh-CN': '动态改变筛选项', 'en-US': 'Dynamic Filter Options' },
       desc: {
-        'zh-CN': `<p>通过改变自定义的 <code>filter</code> 自定义筛选的规则中的 <code>values</code> 数组，或者将 <code>values</code> 定义成方法可以动态的返回筛选项。`,
-        'en-US': ''
+        'zh-CN':
+          '<p>通过修改 <code>filter.values</code> 数组或在 <code>values</code> 中传入函数，可动态改变或异步加载筛选项。</p>',
+        'en-US':
+          '<p>Dynamically update or async load filter options by mutating <code>filter.values</code> or passing a function that returns a Promise.</p>'
       },
       codeFiles: ['filter/dynamic-filter.vue']
     },
     {
       demoId: 'filter-simple-filter',
-      name: { 'zh-CN': '简化版筛选 - 单选/多选菜单', 'en-US': 'Custom Parameter' },
+      name: { 'zh-CN': '简化版筛选 - 单选/多选菜单', 'en-US': 'Simple Filter - Single/Multi Select' },
       desc: {
         'zh-CN':
-          '<p>通过 <code>layout</code> 设置需要使用的筛选项为<code>simple</code>,其中<code>layout</code>可选项包括<code>input,enum,default,extends,base,simple</code> 。</p>\n',
-        'en-US': '<p>Add custom parameters by <code>params</code>.</p>\n'
+          '<p>设置 <code>layout: "simple"</code> 启用简化版筛选。支持 <code>selectAll</code> 全选、<code>searchConfig</code> 搜索框。适用于管理侧规范的紧凑筛选面板。</p>',
+        'en-US':
+          '<p>Set <code>layout: "simple"</code> for compact filter panel. Supports <code>selectAll</code> and <code>searchConfig</code> for search box in enum list.</p>'
       },
       codeFiles: ['filter/simple-filter.vue']
     },
     {
       demoId: 'filter-simple-date-filter',
-      name: { 'zh-CN': '简化版筛选 - 时间日期菜单', 'en-US': 'Advanced Filter Settings' },
+      name: { 'zh-CN': '简化版筛选 - 日期范围', 'en-US': 'Simple Filter - Date Range' },
       desc: {
         'zh-CN':
-          '<p>通过 <code>layout</code> 设置需要使用的筛选项为<code>simple</code>,其中<code>layout</code>可选项包括<code>input,enum,default,extends,base,simple</code>。</p>\n',
+          '<p>设置 <code>layout: "simple"</code> 且 <code>simpleFilter.isDatetime: true</code>，使用 <code>datetimeConfig</code> 配置日期范围选择器，支持 min、max、startDate、endDate 等。</p>',
         'en-US':
-          '<p>You can use <code>inputFilter</code> to configure custom components and conditions for the input filter area, and use <code>extends</code> to add a shortcut filter list</p>\n'
+          '<p>Set <code>layout: "simple"</code> with <code>simpleFilter.isDatetime: true</code>. Configure date range picker via <code>datetimeConfig</code> (min, max, startDate, endDate).</p>'
       },
       codeFiles: ['filter/simple-date-filter.vue']
     },
     {
       demoId: 'filter-simple-default-value-filter',
-      name: { 'zh-CN': '筛选面板默认选中值', 'en-US': 'Set Column Filtering Rules' },
+      name: { 'zh-CN': '筛选默认选中值', 'en-US': 'Filter Default Selected Value' },
       desc: {
-        'zh-CN': '<p>通过 <code>condition.value</code>可以配置筛选默认的选中值。</p>\n',
-        'en-US': '<p>Set the column filtering rule through the <code>filter</code> attribute</p>\n'
+        'zh-CN': '<p>通过 <code>filter.condition.value</code> 配置筛选的默认选中值，表格初始化时即应用该筛选条件。</p>',
+        'en-US':
+          '<p>Set default selected filter values via <code>filter.condition.value</code>. The filter is applied on table init.</p>'
       },
       codeFiles: ['filter/simple-default-value-filter.vue']
     },
+    {
+      demoId: 'filter-input-custom-component',
+      name: { 'zh-CN': '自定义输入组件', 'en-US': 'Custom Input Component' },
+      desc: {
+        'zh-CN':
+          '<p>通过 <code>inputFilter.component</code> 传入自定义组件，实现非标准输入（如范围输入：左最小值、右最大值）。自定义组件需支持 <code>modelValue</code> + <code>update:modelValue</code>，或配置 <code>model</code> 指定字段名。配合 <code>relations[].method</code> 实现自定义筛选逻辑。</p>',
+        'en-US':
+          '<p>Pass custom component via <code>inputFilter.component</code> for non-standard input (e.g. range: min + max). Component must support <code>modelValue</code> + <code>update:modelValue</code>, or configure <code>model</code>. Use <code>relations[].method</code> for custom filter logic.</p>'
+      },
+      codeFiles: ['filter/input-filter-custom-component.vue']
+    },
     {
       demoId: 'filter-advanced-filter',
-      name: { 'zh-CN': '过滤高级设置', 'en-US': 'Custom Filter' },
+      name: { 'zh-CN': '高级筛选', 'en-US': 'Advanced Filter' },
       desc: {
         'zh-CN':
-          '<p>通过 <code>inputFilter</code> 可以给 <code>input</code> 过滤区域配置自定义组件与条件，通过 <code>extends</code> 可以增加快捷过滤列表。</p>',
-        'en-US': '<p>Set additional parameters through the <code>params</code> attribute</p>\n'
+          '<p>通过 <code>inputFilter.component</code> 配置自定义输入组件（如 TinyNumeric、TinyDatePicker）；<code>inputFilter.relations</code> 自定义筛选关系；<code>extends</code> 添加快捷筛选项。</p>',
+        'en-US':
+          '<p>Use <code>inputFilter.component</code> for custom input (e.g. TinyNumeric, TinyDatePicker); <code>inputFilter.relations</code> for filter relations; <code>extends</code> for shortcut filter items.</p>'
       },
       codeFiles: ['filter/advanced-filter.vue']
     },
     {
       demoId: 'filter-custom-filter',
-      name: { 'zh-CN': '列筛选规则', 'en-US': 'Server Filter' },
+      name: { 'zh-CN': '自定义筛选插槽', 'en-US': 'Custom Filter Slot' },
       desc: {
-        'zh-CN': '<p>通过 <code>filter</code> 属性设置列筛选规则。</p>\n',
+        'zh-CN':
+          '<p>通过 <code>#filter</code> 插槽完全自定义筛选面板 UI。插槽参数提供 <code>context</code>，可调用 <code>commitFilter</code>、<code>resetFilter</code>、<code>clearFilter</code> 等方法。需配合 <code>filter.method</code> 实现筛选逻辑。</p>',
         'en-US':
-          '<p>Configure remote-filter to enable server-side filtering. The server-side filtering invokes the fetch-data table for query. The filter-change event is triggered after the server-side filtering.\nThe <code>services/getGridMockData</code> service in this example needs to be implemented. The example simulates the data returned by a remote service \n</p>\n'
+          '<p>Fully customize filter panel via <code>#filter</code> slot. Slot provides <code>context</code> with <code>commitFilter</code>, <code>resetFilter</code>, <code>clearFilter</code>. Configure <code>filter.method</code> for filter logic.</p>'
       },
       codeFiles: ['filter/custom-filter.vue']
     },
     {
       demoId: 'filter-server-filter',
-      name: { 'zh-CN': '服务端过滤', 'en-US': 'Enter the default filtering options.' },
+      name: { 'zh-CN': '服务端过滤', 'en-US': 'Server-side Filtering' },
       desc: {
         'zh-CN':
-          '<p>配置 remote-filter 开启服务端过滤，服务端过滤会调用表格 fetch-data 进行查询，filter-change 服务端过滤后触发的事件\n该示例中的 <code>services/getGridMockData</code> 服务需要自行实现，示例模拟了远程服务返回的数据。\n</p>\n',
+          '<p>配置 <code>remote-filter</code> 开启服务端过滤。筛选时会调用表格 <code>fetch-data</code> 的 api，并将 filters 参数传入，筛选完成后触发 <code>filter-change</code> 事件。</p>',
         'en-US':
-          '<p>Set the default input filtering options through the <code>inputFilter.relation</code> attribute. \n Enter the built-in options for filtering: <code>equals</code>, <code>unequal</code>, <code>greaterThan</code>, <code>lessThan</code>, <code>equalToGreaterThan</code>, <code>equalToLessThan</code>, <code>contains</code>, <code>startwith</code>, <code>endwith</code>; Custom options can also be configured. \n When configuring custom options, you need to configure the filtering method through the <code>inputFilter.method</code> attribute. </p>\n'
+          '<p>Enable server-side filtering with <code>remote-filter</code>. Filter triggers <code>fetch-data</code> api with filters param, then fires <code>filter-change</code> event.</p>'
       },
       codeFiles: ['filter/server-filter.vue']
     },
     {
       demoId: 'server-filter-default',
-      name: { 'zh-CN': '服务端过滤默认选中值', 'en-US': 'Server-side filtering default selected value' },
+      name: { 'zh-CN': '服务端过滤默认选中值', 'en-US': 'Server Filter Default Value' },
       desc: {
         'zh-CN':
-          '<p>配置 remote-filter 开启服务端过滤后，表格初始化时，如果设置了 <code>auto-load</code> 会在表格列初始化钱调用 <code>handleFetch</code>，因此此时无法获取到过滤参数，如果需要设置服务端过滤默认选中值，需将 <code>auto-load</code> 设置为 false 且手动调用一次 <code>handleFetch</code> 方法。</p>\n',
+          '<p>服务端过滤下，若需设置默认选中值，需将 <code>auto-load</code> 设为 false，在列初始化后手动调用 <code>handleFetch</code>。否则 <code>handleFetch</code> 在列初始化前执行，无法获取筛选参数。</p>',
         'en-US':
-          '<p>Set the default input filtering options through the <code>inputFilter.relation</code> attribute. \n Enter the built-in options for filtering: <code>equals</code>, <code>unequal</code>, <code>greaterThan</code>, <code>lessThan</code>, <code>equalToGreaterThan</code>, <code>equalToLessThan</code>, <code>contains</code>, <code>startwith</code>, <code>endwith</code>; Custom options can also be configured. \n When configuring custom options, you need to configure the filtering method through the <code>inputFilter.method</code> attribute. </p>\n'
+          '<p>For server filter with default value, set <code>auto-load</code> to false and manually call <code>handleFetch</code> after init. Otherwise handleFetch runs before columns ready and cannot get filter params.</p>'
       },
       codeFiles: ['filter/server-filter-default.vue']
     },
     {
       demoId: 'filter-default-relation',
-      name: { 'zh-CN': '输入过滤的默认选项', 'en-US': '' },
+      name: { 'zh-CN': '输入过滤默认选项', 'en-US': 'Input Filter Default Relation' },
       desc: {
         'zh-CN':
-          '<p>通过属性 <code>inputFilter.relation</code> 配置输入过滤的默认选项。\n输入过滤的内置选项：<code>equals</code>，<code>unequal</code>，<code>greaterThan</code>，<code>lessThan</code>，<code>equalToGreaterThan</code>，<code>equalToLessThan</code>，<code>contains</code>，<code>startwith</code>，<code>endwith</code>；也可以配置自定义选项。\n配置自定义选项的同时要配置过滤方法，通过属性 <code>inputFilter.method</code> 配置。</p>\n',
-        'en-US': ''
+          '<p>通过 <code>inputFilter.relation</code> 配置输入筛选的默认关系。内置值：<code>equals</code>、<code>contains</code>、<code>startwith</code>、<code>greaterThan</code> 等。自定义 <code>relations</code> 时，可通过 <code>method</code> 配置筛选逻辑。</p>',
+        'en-US':
+          '<p>Set default relation via <code>inputFilter.relation</code>. Built-in: equals, contains, startwith, greaterThan, etc. For custom relations, configure <code>method</code> for filter logic.</p>'
       },
       codeFiles: ['filter/default-relation.vue']
     },
     {
       demoId: 'filter-request-service-reload-filter',
-      name: { 'zh-CN': '重载数据时不清除过滤', 'en-US': '' },
+      name: { 'zh-CN': '重载时保持筛选', 'en-US': 'Keep Filter on Reload' },
       desc: {
-        'zh-CN': `<p>在调用 <code>handleFetch('reload')</code> 重载表格数据时，默认会清除表格筛选。配置 <code>fetchData.reloadConfig.filter</code> 为 <code>true</code> 可以在重载时保持表格筛选。</p>`,
-        'en-US': ''
+        'zh-CN':
+          '<p>调用 <code>handleFetch("reload")</code> 时默认会清除筛选。设置 <code>fetchData.reloadConfig.filter: true</code> 可在重载后保留当前筛选条件。</p>',
+        'en-US':
+          '<p>By default, <code>handleFetch("reload")</code> clears filters. Set <code>fetchData.reloadConfig.filter: true</code> to preserve filters on reload.</p>'
       },
       codeFiles: ['filter/request-service-reload-filter.vue']
     }

package/demos/pc/app/guide/show-close-composition-api.vue

@@ -0,0 +1,77 @@
+<template>
+  <div>
+    <tiny-button plain class="show-close-btn" @click="stepStart">新手引导显示关闭按钮</tiny-button>
+    <tiny-guide :show-step="showStep" :dom-data="domData" :show-close="true"></tiny-guide>
+
+    <tiny-button plain class="hide-close-btn" style="margin-top: 20px" @click="stepStartWithoutClose"
+      >新手引导隐藏关闭按钮</tiny-button
+    >
+    <tiny-guide :show-step="showStepWithoutClose" :dom-data="domDataWithoutClose" :show-close="false"></tiny-guide>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { TinyGuide, TinyButton } from '@opentiny/vue'
+
+const showStep = ref(false)
+const showStepWithoutClose = ref(false)
+
+const domData = ref([
+  {
+    title: '新手引导标题 1',
+    text: '这里是可以关闭的新手引导，点击右上角的关闭按钮可直接退出引导',
+    domElement: '.show-close-btn',
+    button: [
+      {
+        text: '下一步',
+        action: 'next'
+      }
+    ]
+  },
+  {
+    title: '新手引导标题 2',
+    text: '这个引导步骤展示了关闭按钮功能',
+    domElement: '.show-close-btn',
+    button: [
+      {
+        text: '完成',
+        action: 'complete'
+      }
+    ]
+  }
+])
+
+const domDataWithoutClose = ref([
+  {
+    title: '新手引导标题 1',
+    text: '这里是不显示关闭按钮的新手引导，无法通过关闭按钮退出引导',
+    domElement: '.hide-close-btn',
+    button: [
+      {
+        text: '下一步',
+        action: 'next'
+      }
+    ]
+  },
+  {
+    title: '新手引导标题 2',
+    text: '这个引导没有关闭按钮，只能通过底部按钮操作',
+    domElement: '.hide-close-btn',
+    button: [
+      {
+        text: '完成',
+        action: 'complete'
+      }
+    ]
+  }
+])
+
+function stepStart() {
+  showStep.value = !showStep.value
+}
+
+function stepStartWithoutClose() {
+  showStepWithoutClose.value = !showStepWithoutClose.value
+}
+</script>

package/demos/pc/app/guide/show-close.spec.ts

@@ -0,0 +1,37 @@
+import { test, expect } from '@playwright/test'
+
+test('关闭按钮', async ({ page }) => {
+  page.on('pageerror', (exception) => expect(exception).toBeNull())
+  await page.goto('guide#show-close')
+
+  // 测试显示关闭按钮的引导
+  const showCloseBtn = page.locator('.show-close-btn')
+  const guideWithClose = page.locator('.shepherd-element').first()
+
+  await showCloseBtn.click()
+  await expect(guideWithClose).toBeVisible()
+
+  // 检查关闭按钮是否存在
+  const closeBtn = guideWithClose.locator('.shepherd-cancel-icon')
+  await expect(closeBtn).toBeVisible()
+
+  // 点击关闭按钮关闭引导
+  await closeBtn.click()
+  await expect(guideWithClose).toBeHidden()
+
+  // 测试隐藏关闭按钮的引导
+  const hideCloseBtn = page.locator('.hide-close-btn')
+  const guideWithoutClose = page.locator('.shepherd-element').first() // 第二个引导也是第一个shepherd-element
+
+  await hideCloseBtn.click()
+  await expect(guideWithoutClose).toBeVisible()
+
+  // 验证关闭按钮不存在
+  const closeBtnHidden = guideWithoutClose.locator('.shepherd-cancel-icon')
+  await expect(closeBtnHidden).toBeHidden()
+
+  // 通过完成按钮关闭引导
+  const completeBtn = page.getByRole('button', { name: '下一步' })
+  await completeBtn.click()
+  await expect(guideWithoutClose).toBeHidden()
+})