@uxda/appkit 4.3.23 → 4.3.25

package/.cursor/rules/nutshell.mdc

@@ -0,0 +1,2166 @@
+---
+alwaysApply: true
+---
+
+# Nutshell UI 组件库使用规则 - 移动端
+
+> 基于 Vue 3 + NutUI + Taro 的移动端组件库
+> 版本：1.6.92
+> 支持：H5、微信小程序
+
+## 📚 目录
+
+- [快速开始](#快速开始)
+- [平台支持](#平台支持)
+- [基础组件](#基础组件)
+- [表单组件](#表单组件)
+- [数据展示组件](#数据展示组件)
+- [反馈组件](#反馈组件)
+- [布局组件](#布局组件)
+- [导航组件](#导航组件)
+- [通用属性](#通用属性)
+- [服务方法](#服务方法)
+- [最佳实践](#最佳实践)
+- [移动端特性](#移动端特性)
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install @uxda/nutshell
+# 或
+yarn add @uxda/nutshell
+```
+
+### H5 项目引入
+
+```javascript
+import { createApp } from 'vue'
+import Nutshell from '@uxda/nutshell/taro'
+import '@uxda/nutshell/nutshell.css'
+import '@uxda/nutshell/nutui.css' // 移动端样式
+
+const app = createApp(App)
+app.use(Nutshell)
+app.mount('#app')
+```
+
+### Taro 小程序项目引入
+
+```javascript
+// app.ts
+import { createApp } from 'vue'
+import Nutshell from '@uxda/nutshell/taro'
+
+const app = createApp({
+  // ...
+})
+
+app.use(Nutshell)
+
+export default app
+```
+
+### 按需引入组件
+
+```javascript
+import { NsButton, NsInput, NsList } from '@uxda/nutshell/components'
+```
+
+---
+
+## 平台支持
+
+Nutshell 移动端组件库支持以下平台：
+
+- ✅ H5（移动端网页）
+- ✅ 微信小程序
+- ✅ 支付宝小程序（部分）
+- ✅ 钉钉小程序（部分）
+
+### 平台检测
+
+```vue
+<script setup>
+import { usePlatform } from '@uxda/nutshell/taro'
+
+const platform = usePlatform()
+
+console.log(platform.mobile)   // 是否移动端
+console.log(platform.h5)       // 是否H5
+console.log(platform.weixin)   // 是否微信环境
+console.log(platform.android)  // 是否Android
+console.log(platform.ios)      // 是否iOS
+</script>
+```
+
+---
+
+## 基础组件
+
+### 1. Button 按钮
+
+**组件名称**: `<ns-button>`
+
+**用途**: 触发操作、提交表单、跳转页面等交互行为
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `label` | `string` | - | 按钮文字 |
+| `color` | `Color` | - | 按钮颜色 |
+| `size` | `'xs'\|'sm'\|'md'\|'lg'\|'xl'` | `'md'` | 按钮尺寸 |
+| `variant` | `'solid'\|'outlined'\|'soft'\|'plain'` | - | 按钮样式风格 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `loading` | `boolean` | `false` | 是否显示加载状态 |
+| `icon` | `string` | - | 图标名称 |
+| `block` | `boolean` | `false` | 是否块级元素（宽度100%） |
+
+**Slots**:
+
+- `default`: 按钮内容
+- `icon`: 自定义图标
+
+**示例**:
+
+```vue
+<!-- 基础用法 -->
+<ns-button label="提交" />
+
+<!-- 块级按钮 -->
+<ns-button label="立即购买" color="primary" block />
+
+<!-- 带图标 -->
+<ns-button label="分享" icon="share" />
+
+<!-- 加载状态 -->
+<ns-button label="提交中..." :loading="true" />
+
+<!-- 不同尺寸 -->
+<ns-button label="小按钮" size="sm" />
+<ns-button label="中按钮" size="md" />
+<ns-button label="大按钮" size="lg" />
+```
+
+---
+
+### 2. Icon 图标
+
+**组件名称**: `<ns-icon>`
+
+**用途**: 展示图标
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `name` | `string` | - | 图标名称 |
+| `size` | `Size\|number` | `'md'` | 图标尺寸 |
+| `fill` | `Color` | - | 图标颜色 |
+
+**示例**:
+
+```vue
+<ns-icon name="home" />
+<ns-icon name="user" size="lg" fill="primary" />
+<ns-icon name="setting" :size="24" />
+```
+
+---
+
+### 3. Avatar 头像
+
+**组件名称**: `<ns-avatar>`
+
+**用途**: 展示用户头像
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `src` | `string` | - | 头像图片地址 |
+| `size` | `Size\|number` | `'md'` | 头像尺寸 |
+| `shape` | `'circle'\|'square'` | `'circle'` | 头像形状 |
+
+**示例**:
+
+```vue
+<ns-avatar src="/avatar.jpg" />
+<ns-avatar size="lg" shape="square">用</ns-avatar>
+```
+
+---
+
+### 4. Image 图片
+
+**组件名称**: `<ns-image>`
+
+**用途**: 展示图片，支持懒加载、预览
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `src` | `string` | - | 图片地址 |
+| `width` | `string\|number` | - | 图片宽度 |
+| `height` | `string\|number` | - | 图片高度 |
+| `fit` | `'fill'\|'contain'\|'cover'\|'none'\|'scale-down'` | `'cover'` | 图片填充模式 |
+| `lazy` | `boolean` | `false` | 是否懒加载 |
+| `preview` | `boolean` | `false` | 是否支持预览 |
+
+**示例**:
+
+```vue
+<ns-image 
+  src="/photo.jpg" 
+  width="200" 
+  height="200" 
+  lazy 
+  preview 
+/>
+```
+
+---
+
+### 5. Chip 标签
+
+**组件名称**: `<ns-chip>`
+
+**用途**: 展示标签或状态
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `label` | `string` | - | 标签文字 |
+| `color` | `Color` | - | 标签颜色 |
+| `size` | `Size` | `'md'` | 标签尺寸 |
+| `closable` | `boolean` | `false` | 是否可关闭 |
+
+**示例**:
+
+```vue
+<ns-chip label="新品" color="danger" />
+<ns-chip label="热销" color="warning" />
+<ns-chip label="标签" closable @close="handleClose" />
+```
+
+---
+
+### 6. Chips 标签组
+
+**组件名称**: `<ns-chips>`
+
+**用途**: 展示多个标签
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `items` | `ChipItem[]` | `[]` | 标签数据 |
+
+**示例**:
+
+```vue
+<ns-chips 
+  :items="[
+    { text: 'JavaScript', color: 'warning' },
+    { text: 'Vue.js', color: 'success' },
+    { text: 'TypeScript', color: 'primary' }
+  ]"
+/>
+```
+
+---
+
+## 表单组件
+
+### 1. Form 表单
+
+**组件名称**: `<ns-form>`
+
+**用途**: 表单容器，用于数据收集、校验和提交
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `object` | - | 表单数据对象 |
+| `name` | `string` | - | 表单名称 |
+| `failed` | `'toast'\|'notice'\|'none'` | `'toast'` | 校验失败时的提示方式 |
+
+**Events**:
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `update:modelValue` | `(value: Record<string, any>)` | 表单数据更新 |
+
+**Methods**:
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| `validate` | `nameList?: NamePath` | `Promise<boolean>` | 触发表单验证 |
+| `resetFields` | `nameList?: NamePath[]` | - | 重置表单字段 |
+| `reset` | - | - | 重置整个表单 |
+| `clearValidate` | `nameList?: NamePath[]` | - | 移除表单校验结果 |
+
+**示例**:
+
+```vue
+<template>
+  <ns-form v-model="formData" ref="formRef">
+    <ns-input 
+      name="username" 
+      label="用户名" 
+      :rules="['required']"
+      placeholder="请输入用户名"
+    />
+    <ns-input 
+      name="phone" 
+      label="手机号" 
+      :rules="['required', 'mobile']"
+      placeholder="请输入手机号"
+    />
+    <ns-button label="提交" block @click="handleSubmit" />
+  </ns-form>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useNutshell } from '@uxda/nutshell/taro'
+
+const $n = useNutshell()
+const formRef = ref()
+const formData = ref({
+  username: '',
+  phone: ''
+})
+
+const handleSubmit = async () => {
+  const valid = await formRef.value.validate()
+  if (valid) {
+    $n.toast('提交成功', { type: 'success' })
+  }
+}
+</script>
+```
+
+---
+
+### 2. Input 输入框
+
+**组件名称**: `<ns-input>`
+
+**用途**: 单行文本输入
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `string\|number` | - | 输入值（v-model） |
+| `name` | `string` | - | 表单项名称（必填） |
+| `label` | `string` | - | 标签文字 |
+| `type` | `'text'\|'number'\|'tel'\|'password'` | `'text'` | 输入框类型 |
+| `placeholder` | `string` | - | 占位符 |
+| `maxlength` | `number` | - | 最大输入长度 |
+| `clearable` | `boolean` | `true` | 是否显示清空按钮 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `rules` | `ValidationRule[]` | - | 校验规则 |
+| `textAlign` | `'left'\|'right'\|'center'` | `'left'` | 文字对齐方向 |
+
+**Events**:
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `update:modelValue` | `(value: string\|number)` | 值更新 |
+| `change` | `(value: string\|number)` | 值改变 |
+| `blur` | `()` | 失去焦点 |
+| `focus` | `()` | 获得焦点 |
+| `enter` | `()` | 按下回车（H5） |
+
+**校验规则**:
+
+- `'required'`: 必填
+- `'numeric'`: 纯数字
+- `'email'`: 邮箱格式
+- `'id'`: 身份证号
+- `'mobile'`: 手机号
+
+**示例**:
+
+```vue
+<!-- 基础输入 -->
+<ns-input 
+  v-model="username" 
+  name="username" 
+  label="用户名" 
+  placeholder="请输入用户名"
+/>
+
+<!-- 手机号输入 -->
+<ns-input 
+  v-model="phone" 
+  name="phone" 
+  label="手机号"
+  type="tel"
+  :rules="['required', 'mobile']"
+  placeholder="请输入手机号"
+/>
+
+<!-- 密码输入 -->
+<ns-input 
+  v-model="password" 
+  name="password" 
+  label="密码"
+  type="password"
+  :rules="['required']"
+  placeholder="请输入密码"
+/>
+```
+
+---
+
+### 3. MobileInput 手机号输入
+
+**组件名称**: `<ns-mobile-input>`
+
+**用途**: 手机号输入（自动格式化为 xxx-xxxx-xxxx）
+
+**Props**: 继承自 `NsInput`，自动设置 `type="tel"` 和 `rules="['mobile']"`
+
+**示例**:
+
+```vue
+<ns-mobile-input 
+  v-model="phone" 
+  name="phone" 
+  label="手机号"
+/>
+```
+
+---
+
+### 4. IdInput 身份证号输入
+
+**组件名称**: `<ns-id-input>`
+
+**用途**: 身份证号输入
+
+**Props**: 继承自 `NsInput`，自动设置校验规则
+
+**示例**:
+
+```vue
+<ns-id-input 
+  v-model="idCard" 
+  name="idCard" 
+  label="身份证号"
+/>
+```
+
+---
+
+### 5. Textarea 多行文本框
+
+**组件名称**: `<ns-textarea>`
+
+**用途**: 多行文本输入
+
+**Props**: 继承自 `NsInput`，额外支持：
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `rows` | `number` | `3` | 行数 |
+| `autoSize` | `boolean` | `false` | 自适应高度 |
+
+**示例**:
+
+```vue
+<ns-textarea 
+  v-model="comment" 
+  name="comment" 
+  label="备注"
+  :rows="5"
+  placeholder="请输入备注"
+/>
+```
+
+---
+
+### 6. Select 下拉选择
+
+**组件名称**: `<ns-select>`
+
+**用途**: 下拉选择单个选项（移动端会弹出选择器）
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `string\|number` | - | 选中值 |
+| `name` | `string` | - | 表单项名称 |
+| `label` | `string` | - | 标签文字 |
+| `options` | `SelectOption[]` | - | 选项数据 |
+| `placeholder` | `string` | - | 占位符 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `rules` | `ValidationRule[]` | - | 校验规则 |
+
+**选项数据格式**:
+
+```typescript
+type SelectOption = {
+  text: string      // 显示文字
+  value: string | number  // 选项值
+  disabled?: boolean      // 是否禁用
+}
+```
+
+**示例**:
+
+```vue
+<template>
+  <ns-select 
+    v-model="selectedCity" 
+    name="city" 
+    label="城市"
+    :options="cityOptions"
+    placeholder="请选择城市"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const selectedCity = ref('')
+const cityOptions = [
+  { text: '北京', value: 'beijing' },
+  { text: '上海', value: 'shanghai' },
+  { text: '深圳', value: 'shenzhen' }
+]
+</script>
+```
+
+---
+
+### 7. DateSelect 日期选择
+
+**组件名称**: `<ns-date-select>`
+
+**用途**: 日期选择（移动端友好的日期选择器）
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `string` | - | 日期值（YYYY-MM-DD） |
+| `name` | `string` | - | 表单项名称 |
+| `label` | `string` | - | 标签文字 |
+| `minDate` | `Date` | - | 最小日期 |
+| `maxDate` | `Date` | - | 最大日期 |
+
+**示例**:
+
+```vue
+<ns-date-select 
+  v-model="birthDate" 
+  name="birthDate" 
+  label="出生日期"
+/>
+```
+
+---
+
+### 8. Checkbox 复选框
+
+**组件名称**: `<ns-checkbox>`
+
+**用途**: 单个复选框
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `boolean` | - | 选中状态 |
+| `label` | `string` | - | 标签文字 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+
+**示例**:
+
+```vue
+<ns-checkbox v-model="agreed" label="我已阅读并同意用户协议" />
+```
+
+---
+
+### 9. CheckboxGroup 复选框组
+
+**组件名称**: `<ns-checkbox-group>`
+
+**用途**: 多个复选框组
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `(string\|number)[]` | - | 选中值数组 |
+| `name` | `string` | - | 表单项名称 |
+| `options` | `SelectOption[]` | - | 选项数据 |
+| `max` | `number` | - | 最大可选数 |
+
+**示例**:
+
+```vue
+<ns-checkbox-group 
+  v-model="interests" 
+  name="interests"
+  :options="[
+    { text: '篮球', value: 'basketball' },
+    { text: '足球', value: 'football' },
+    { text: '游泳', value: 'swimming' }
+  ]"
+  :max="2"
+/>
+```
+
+---
+
+### 10. RadioGroup 单选框组
+
+**组件名称**: `<ns-radio-group>`
+
+**用途**: 单选框组
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `string\|number` | - | 选中值 |
+| `name` | `string` | - | 表单项名称 |
+| `options` | `SelectOption[]` | - | 选项数据 |
+| `direction` | `'horizontal'\|'vertical'` | `'vertical'` | 排列方向 |
+
+**示例**:
+
+```vue
+<ns-radio-group 
+  v-model="gender" 
+  name="gender"
+  :options="[
+    { text: '男', value: 'male' },
+    { text: '女', value: 'female' }
+  ]"
+  direction="horizontal"
+/>
+```
+
+---
+
+### 11. Switch 开关
+
+**组件名称**: `<ns-switch>`
+
+**用途**: 开关切换
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `boolean` | - | 开关状态 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `activeText` | `string` | - | 打开时的文字 |
+| `inactiveText` | `string` | - | 关闭时的文字 |
+
+**示例**:
+
+```vue
+<ns-switch 
+  v-model="enabled" 
+  active-text="开启" 
+  inactive-text="关闭"
+/>
+```
+
+---
+
+### 12. Rating 评分
+
+**组件名称**: `<ns-rating-input>`
+
+**用途**: 星级评分输入
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `number` | - | 评分值 |
+| `name` | `string` | - | 表单项名称 |
+| `count` | `number` | `5` | 星星总数 |
+| `allowHalf` | `boolean` | `false` | 是否允许半星 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+
+**示例**:
+
+```vue
+<ns-rating-input 
+  v-model="rating" 
+  name="rating"
+  :count="5"
+  allow-half
+/>
+```
+
+---
+
+### 13. Stepper 步进器
+
+**组件名称**: `<ns-stepper>`
+
+**用途**: 数字增减器
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `number` | - | 数字值 |
+| `min` | `number` | `0` | 最小值 |
+| `max` | `number` | `999` | 最大值 |
+| `step` | `number` | `1` | 步长 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `inputWidth` | `string` | `'40px'` | 输入框宽度 |
+
+**示例**:
+
+```vue
+<ns-stepper 
+  v-model="quantity" 
+  :min="1"
+  :max="99"
+  :step="1"
+/>
+```
+
+---
+
+### 14. Upload 文件上传
+
+**组件名称**: `<ns-upload>`
+
+**用途**: 文件/图片上传
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `File[]` | - | 文件列表 |
+| `accept` | `string` | `'image/*'` | 接受的文件类型 |
+| `multiple` | `boolean` | `false` | 是否支持多选 |
+| `maxSize` | `number` | - | 最大文件大小（字节） |
+| `maxCount` | `number` | `9` | 最大文件数量 |
+| `capture` | `boolean` | `false` | 是否调起摄像头 |
+
+**示例**:
+
+```vue
+<!-- 图片上传 -->
+<ns-upload 
+  v-model="images" 
+  accept="image/*"
+  :max-count="9"
+  multiple
+/>
+
+<!-- 拍照上传 -->
+<ns-upload 
+  v-model="photo" 
+  capture
+/>
+```
+
+---
+
+## 数据展示组件
+
+### 1. List 列表
+
+**组件名称**: `<ns-list>`
+
+**用途**: 展示列表数据，支持下拉刷新、上拉加载
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `data` | `any[]` | `[]` | 列表数据 |
+| `loading` | `boolean` | `false` | 是否加载中 |
+| `finished` | `boolean` | `false` | 是否加载完成 |
+| `refreshable` | `boolean` | `false` | 是否支持下拉刷新 |
+| `loadmore` | `boolean` | `false` | 是否支持上拉加载更多 |
+
+**Events**:
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `refresh` | `()` | 下拉刷新 |
+| `load` | `()` | 上拉加载更多 |
+
+**示例**:
+
+```vue
+<template>
+  <ns-list 
+    :data="items"
+    :loading="loading"
+    :finished="finished"
+    refreshable
+    loadmore
+    @refresh="handleRefresh"
+    @load="handleLoad"
+  >
+    <template #default="{ item }">
+      <div class="list-item">
+        <h3>{{ item.title }}</h3>
+        <p>{{ item.desc }}</p>
+      </div>
+    </template>
+  </ns-list>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const items = ref([])
+const loading = ref(false)
+const finished = ref(false)
+const page = ref(1)
+
+const handleRefresh = async () => {
+  page.value = 1
+  finished.value = false
+  await loadData()
+}
+
+const handleLoad = async () => {
+  page.value++
+  await loadData()
+}
+
+const loadData = async () => {
+  loading.value = true
+  try {
+    const response = await api.getList(page.value)
+    if (page.value === 1) {
+      items.value = response.data
+    } else {
+      items.value.push(...response.data)
+    }
+    finished.value = !response.hasMore
+  } finally {
+    loading.value = false
+  }
+}
+</script>
+```
+
+---
+
+### 2. Card 卡片
+
+**组件名称**: `<ns-card>`
+
+**用途**: 卡片容器
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `title` | `string` | - | 卡片标题 |
+| `padding` | `Size` | `'md'` | 内边距 |
+| `radius` | `Size` | `'md'` | 圆角大小 |
+| `shadow` | `boolean` | `false` | 是否显示阴影 |
+
+**Slots**:
+
+- `default`: 卡片内容
+- `header`: 自定义头部
+- `footer`: 底部内容
+
+**示例**:
+
+```vue
+<ns-card title="商品信息">
+  <p>商品名称：iPhone 15 Pro</p>
+  <p>价格：¥7999</p>
+  <template #footer>
+    <ns-button label="立即购买" block />
+  </template>
+</ns-card>
+```
+
+---
+
+### 3. Empty 空状态
+
+**组件名称**: `<ns-empty>`
+
+**用途**: 展示空状态
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `description` | `string` | `'暂无数据'` | 描述文字 |
+| `image` | `string` | - | 空状态图片 |
+
+**示例**:
+
+```vue
+<ns-empty description="暂无订单" />
+```
+
+---
+
+### 4. Timeline 时间轴
+
+**组件名称**: `<ns-timeline>`
+
+**用途**: 展示时间流信息
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `items` | `TimelineItem[]` | `[]` | 时间轴数据 |
+
+**示例**:
+
+```vue
+<ns-timeline 
+  :items="[
+    { time: '2024-01-01 10:00', content: '订单创建' },
+    { time: '2024-01-01 12:00', content: '商家接单' },
+    { time: '2024-01-01 14:00', content: '配送中' },
+    { time: '2024-01-01 15:30', content: '订单完成' }
+  ]"
+/>
+```
+
+---
+
+### 5. Facts 事实列表
+
+**组件名称**: `<ns-facts>`
+
+**用途**: 展示键值对信息（详情页常用）
+
+**示例**:
+
+```vue
+<ns-facts>
+  <ns-facts-item label="订单号" value="202401010001" />
+  <ns-facts-item label="下单时间" value="2024-01-01 10:00" />
+  <ns-facts-item label="支付方式" value="微信支付" />
+  <ns-facts-item label="配送地址" value="北京市朝阳区..." />
+</ns-facts>
+```
+
+---
+
+### 6. Skeleton 骨架屏
+
+**组件名称**: `<ns-skeleton>`
+
+**用途**: 加载状态占位
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `loading` | `boolean` | `true` | 是否显示骨架屏 |
+| `rows` | `number` | `3` | 骨架屏行数 |
+| `animated` | `boolean` | `true` | 是否显示动画 |
+
+**示例**:
+
+```vue
+<ns-skeleton :loading="loading" :rows="5">
+  <div v-if="!loading">
+    <!-- 实际内容 -->
+  </div>
+</ns-skeleton>
+```
+
+---
+
+### 7. Preview 图片预览
+
+**组件名称**: `<ns-preview>`
+
+**用途**: 图片预览（点击放大查看）
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `images` | `string[]` | - | 图片列表 |
+| `current` | `number` | `0` | 当前显示的图片索引 |
+
+**示例**:
+
+```vue
+<ns-preview 
+  :images="[
+    '/image1.jpg',
+    '/image2.jpg',
+    '/image3.jpg'
+  ]"
+  :current="0"
+/>
+```
+
+---
+
+### 8. Watermark 水印
+
+**组件名称**: `<ns-watermark>`
+
+**用途**: 为页面添加水印
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `content` | `string` | - | 水印文字 |
+| `rotate` | `number` | `-22` | 旋转角度 |
+| `zIndex` | `number` | `1000` | 层级 |
+
+**示例**:
+
+```vue
+<ns-watermark content="内部资料">
+  <div>页面内容</div>
+</ns-watermark>
+```
+
+---
+
+## 反馈组件
+
+### 1. Dialog 对话框
+
+**组件名称**: `<ns-dialog>`
+
+**用途**: 模态对话框
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `boolean` | - | 是否显示 |
+| `title` | `string` | - | 对话框标题 |
+| `okText` | `string` | `'确定'` | 确定按钮文字 |
+| `cancelText` | `string` | `'取消'` | 取消按钮文字 |
+| `footer` | `boolean` | `true` | 是否显示底部 |
+| `closeOnClickOverlay` | `boolean` | `true` | 点击遮罩是否关闭 |
+
+**Events**:
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `ok` | `()` | 点击确定 |
+| `close` | `()` | 关闭对话框 |
+
+**示例**:
+
+```vue
+<template>
+  <ns-button label="打开对话框" @click="visible = true" />
+  
+  <ns-dialog 
+    v-model="visible" 
+    title="提示"
+    @ok="handleOk"
+  >
+    <p>确定要执行此操作吗？</p>
+  </ns-dialog>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const visible = ref(false)
+
+const handleOk = () => {
+  // 处理确定逻辑
+  visible.value = false
+}
+</script>
+```
+
+---
+
+### 2. Sheet 底部弹出层
+
+**组件名称**: `<ns-sheet>`
+
+**用途**: 从底部弹出的操作菜单
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `boolean` | - | 是否显示 |
+| `title` | `string` | - | 标题 |
+| `items` | `SheetItem[]` | - | 菜单项 |
+
+**Events**:
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `select` | `(item: SheetItem)` | 选择菜单项 |
+
+**示例**:
+
+```vue
+<ns-sheet 
+  v-model="sheetVisible" 
+  title="选择操作"
+  :items="[
+    { text: '拍照', value: 'camera' },
+    { text: '从相册选择', value: 'album' },
+    { text: '取消', value: 'cancel' }
+  ]"
+  @select="handleSelect"
+/>
+```
+
+---
+
+### 3. Popover 气泡弹出框
+
+**组件名称**: `<ns-popover>`
+
+**用途**: 气泡式提示
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `content` | `string` | - | 显示内容 |
+| `trigger` | `'click'\|'manual'` | `'click'` | 触发方式 |
+| `placement` | `'top'\|'bottom'\|'left'\|'right'` | `'bottom'` | 弹出位置 |
+
+**示例**:
+
+```vue
+<ns-popover content="这是提示信息" placement="top">
+  <ns-button label="点击查看" />
+</ns-popover>
+```
+
+---
+
+### 4. Loading 加载
+
+**组件名称**: `<ns-loading>`
+
+**用途**: 局部加载状态
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `visible` | `boolean` | `true` | 是否显示 |
+| `tip` | `string` | - | 提示文字 |
+| `size` | `Size` | `'md'` | 加载图标大小 |
+
+**示例**:
+
+```vue
+<ns-loading :visible="loading" tip="加载中..." />
+```
+
+---
+
+### 5. Drawer 抽屉
+
+**组件名称**: `<ns-drawer>`
+
+**用途**: 从侧边滑出的抽屉面板
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `boolean` | - | 是否显示 |
+| `title` | `string` | - | 抽屉标题 |
+| `placement` | `'left'\|'right'\|'top'\|'bottom'` | `'right'` | 抽屉方向 |
+| `height` | `string` | `'60%'` | 高度（bottom/top时） |
+
+**示例**:
+
+```vue
+<ns-drawer 
+  v-model="drawerVisible" 
+  title="筛选"
+  placement="bottom"
+  height="70%"
+>
+  <!-- 筛选内容 -->
+</ns-drawer>
+```
+
+---
+
+## 布局组件
+
+### 1. Row / Column 弹性布局
+
+**组件名称**: `<ns-row>` / `<ns-column>`
+
+**用途**: Flex 布局容器
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `gap` | `Size\|number` | - | 子元素间距 |
+| `justify` | `'start'\|'center'\|'end'\|'between'\|'around'` | - | 主轴对齐方式 |
+| `align` | `'start'\|'center'\|'end'\|'stretch'` | - | 交叉轴对齐方式 |
+| `wrap` | `boolean` | `false` | 是否换行 |
+
+**示例**:
+
+```vue
+<!-- 水平排列 -->
+<ns-row gap="md" justify="between" align="center">
+  <ns-button label="按钮1" />
+  <ns-button label="按钮2" />
+  <ns-button label="按钮3" />
+</ns-row>
+
+<!-- 垂直排列 -->
+<ns-column gap="lg">
+  <ns-card title="卡片1" />
+  <ns-card title="卡片2" />
+  <ns-card title="卡片3" />
+</ns-column>
+```
+
+---
+
+### 2. Grid 网格
+
+**组件名称**: `<ns-grid>`
+
+**用途**: Grid 布局容器
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `columns` | `number` | `4` | 列数 |
+| `gap` | `Size\|number` | - | 间距 |
+
+**示例**:
+
+```vue
+<ns-grid :columns="3" gap="md">
+  <div v-for="i in 9" :key="i">
+    <ns-button :label="`按钮${i}`" block />
+  </div>
+</ns-grid>
+```
+
+---
+
+### 3. Scrollable 滚动容器
+
+**组件名称**: `<ns-scrollable>`
+
+**用途**: 可滚动区域（支持下拉刷新）
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `height` | `string` | - | 容器高度 |
+| `refreshable` | `boolean` | `false` | 是否支持下拉刷新 |
+
+**Events**:
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `refresh` | `()` | 下拉刷新 |
+| `scrollEnd` | `()` | 滚动到底部 |
+
+**示例**:
+
+```vue
+<ns-scrollable 
+  height="100vh"
+  refreshable
+  @refresh="handleRefresh"
+  @scroll-end="handleScrollEnd"
+>
+  <div v-for="item in items" :key="item.id">
+    {{ item.content }}
+  </div>
+</ns-scrollable>
+```
+
+---
+
+### 4. Divider 分割线
+
+**组件名称**: `<ns-divider>`
+
+**用途**: 分隔内容
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `dashed` | `boolean` | `false` | 是否虚线 |
+| `hairline` | `boolean` | `true` | 是否细线（0.5px） |
+
+**示例**:
+
+```vue
+<ns-divider />
+<ns-divider dashed />
+```
+
+---
+
+## 导航组件
+
+### 1. Tabbar 标签栏
+
+**组件名称**: `<ns-tabbar>`
+
+**用途**: 底部导航栏
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `string\|number` | - | 当前激活的标签 |
+| `items` | `TabbarItem[]` | - | 标签项数据 |
+| `fixed` | `boolean` | `true` | 是否固定在底部 |
+| `safeAreaInsetBottom` | `boolean` | `true` | 是否开启底部安全区适配 |
+
+**标签项数据格式**:
+
+```typescript
+type TabbarItem = {
+  text: string
+  value: string | number
+  icon?: string
+  badge?: string | number
+}
+```
+
+**示例**:
+
+```vue
+<template>
+  <ns-tabbar v-model="activeTab" :items="tabbarItems" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const activeTab = ref('home')
+const tabbarItems = [
+  { text: '首页', value: 'home', icon: 'home' },
+  { text: '分类', value: 'category', icon: 'category' },
+  { text: '购物车', value: 'cart', icon: 'cart', badge: 5 },
+  { text: '我的', value: 'mine', icon: 'user' }
+]
+</script>
+```
+
+---
+
+### 2. Tabs 标签页
+
+**组件名称**: `<ns-tabs>`
+
+**用途**: 选项卡切换
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `string\|number` | - | 当前激活的标签 |
+| `items` | `TabsItem[]` | - | 标签项数据 |
+| `variant` | `'line'\|'card'\|'button'` | `'line'` | 标签样式 |
+| `swipeable` | `boolean` | `false` | 是否开启手势滑动切换 |
+| `sticky` | `boolean` | `false` | 是否吸顶 |
+
+**示例**:
+
+```vue
+<ns-tabs 
+  v-model="activeTab" 
+  :items="[
+    { text: '全部', value: 'all' },
+    { text: '待付款', value: 'unpaid' },
+    { text: '待发货', value: 'unshipped' },
+    { text: '已完成', value: 'finished' }
+  ]"
+  swipeable
+  sticky
+>
+  <ns-tabs-item value="all">
+    <!-- 全部订单内容 -->
+  </ns-tabs-item>
+  <ns-tabs-item value="unpaid">
+    <!-- 待付款订单内容 -->
+  </ns-tabs-item>
+  <!-- ... -->
+</ns-tabs>
+```
+
+---
+
+### 3. Pagination 分页
+
+**组件名称**: `<ns-pagination>`
+
+**用途**: 分页导航（移动端简化版）
+
+**Props**:
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `number` | - | 当前页码 |
+| `total` | `number` | - | 总页数 |
+
+**示例**:
+
+```vue
+<ns-pagination 
+  v-model="currentPage"
+  :total="10"
+  @change="handlePageChange"
+/>
+```
+
+---
+
+## 通用属性
+
+### 尺寸（Size）
+
+| 值 | 说明 | 移动端常用场景 |
+|----|------|----------------|
+| `'xs'` | 超小 | 小图标、小标签 |
+| `'sm'` | 小 | 次要按钮、小卡片 |
+| `'md'` | 中等（默认） | 主按钮、标准组件 |
+| `'lg'` | 大 | 大按钮、大卡片 |
+| `'xl'` | 超大 | 重要操作按钮 |
+
+---
+
+### 颜色（Color）
+
+| 值 | 说明 | 适用场景 |
+|----|------|----------|
+| `'primary'` | 主色 | 主要操作、强调 |
+| `'success'` | 成功色 | 成功提示、完成状态 |
+| `'warning'` | 警告色 | 警告提示、待处理 |
+| `'danger'` | 危险色 | 删除、错误提示 |
+| `'info'` | 信息色 | 一般信息提示 |
+
+---
+
+## 服务方法
+
+### 1. Toast 轻提示
+
+**方法**: `$n.toast(message, options?)`
+
+**参数**:
+
+```typescript
+type ToastOptions = {
+  type?: 'info' | 'success' | 'error' | 'warning'
+  duration?: number  // 持续时间（秒），默认2秒
+  position?: 'top' | 'center' | 'bottom'
+}
+```
+
+**示例**:
+
+```javascript
+// 普通提示
+$n.toast('操作成功')
+
+// 成功提示
+$n.toast('保存成功', { type: 'success' })
+
+// 错误提示
+$n.toast('操作失败', { type: 'error' })
+
+// 长时间提示
+$n.toast('提交中，请稍候...', { duration: 5 })
+```
+
+---
+
+### 2. Loading 全局加载
+
+**方法**: 
+- `$n.loading.show(message?)` - 显示加载
+- `$n.loading.hide()` - 隐藏加载
+
+**示例**:
+
+```javascript
+// 显示加载
+$n.loading.show('加载中...')
+
+// 异步操作
+await fetchData()
+
+// 隐藏加载
+$n.loading.hide()
+```
+
+---
+
+### 3. Dialog 对话框
+
+**方法**: `$n.dialog(options)`
+
+**示例**:
+
+```javascript
+$n.dialog({
+  title: '提示',
+  content: '确定要删除吗？',
+  onOk: () => {
+    // 确定操作
+  }
+})
+```
+
+---
+
+### 4. Confirm 确认框
+
+**方法**: `$n.confirm(message, onOk)`
+
+**示例**:
+
+```javascript
+$n.confirm('确定要退出登录吗？', () => {
+  // 退出登录
+  logout()
+})
+```
+
+---
+
+### 5. Sheet 底部弹出层
+
+**方法**: `$n.sheet.open(options)`
+
+**示例**:
+
+```javascript
+$n.sheet.open({
+  title: '选择操作',
+  items: [
+    { text: '编辑', value: 'edit' },
+    { text: '删除', value: 'delete' },
+    { text: '取消', value: 'cancel' }
+  ],
+  onSelect: (item) => {
+    if (item.value === 'edit') {
+      // 编辑操作
+    }
+  }
+})
+```
+
+---
+
+## 移动端特性
+
+### 1. 安全区域适配
+
+在 iPhone X 等设备上，组件会自动适配安全区域（刘海屏、底部横条）。
+
+```vue
+<!-- Tabbar 自动适配底部安全区 -->
+<ns-tabbar 
+  :items="tabbarItems" 
+  safe-area-inset-bottom 
+/>
+```
+
+---
+
+### 2. 触摸反馈
+
+移动端组件支持触摸反馈效果，提供更好的交互体验。
+
+```vue
+<!-- 按钮支持触摸高亮 -->
+<ns-button label="点击我" />
+```
+
+---
+
+### 3. 手势操作
+
+支持常见的移动端手势：
+
+- **滑动**: Tabs 可左右滑动切换
+- **下拉刷新**: List、Scrollable 支持下拉刷新
+- **上拉加载**: List 支持上拉加载更多
+
+---
+
+### 4. 底部弹出选择器
+
+移动端的 Select、DateSelect 等组件会从底部弹出选择器，符合移动端交互习惯。
+
+```vue
+<ns-select 
+  v-model="city" 
+  :options="cityOptions"
+  placeholder="选择城市"
+/>
+<!-- 点击后从底部弹出选择器 -->
+```
+
+---
+
+### 5. 虚拟列表
+
+对于长列表，使用虚拟滚动提升性能：
+
+```vue
+<ns-list 
+  :data="longList"
+  virtual
+  :item-height="60"
+/>
+```
+
+---
+
+## 最佳实践
+
+### 1. 移动端表单设计
+
+```vue
+<template>
+  <ns-page>
+    <ns-page-header title="用户信息" />
+    
+    <ns-page-content>
+      <ns-form v-model="formData" ref="formRef">
+        <ns-input 
+          name="name" 
+          label="姓名" 
+          :rules="['required']"
+          placeholder="请输入姓名"
+        />
+        
+        <ns-mobile-input 
+          name="phone" 
+          label="手机号"
+          :rules="['required', 'mobile']"
+          placeholder="请输入手机号"
+        />
+        
+        <ns-select 
+          name="city" 
+          label="城市"
+          :options="cityOptions"
+          :rules="['required']"
+          placeholder="请选择城市"
+        />
+        
+        <ns-date-select 
+          name="birthDate" 
+          label="出生日期"
+        />
+        
+        <ns-textarea 
+          name="remark" 
+          label="备注"
+          :rows="4"
+          placeholder="请输入备注"
+        />
+      </ns-form>
+    </ns-page-content>
+    
+    <ns-page-footer>
+      <ns-button 
+        label="提交" 
+        color="primary" 
+        block 
+        @click="handleSubmit"
+      />
+    </ns-page-footer>
+  </ns-page>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useNutshell } from '@uxda/nutshell/taro'
+
+const $n = useNutshell()
+const formRef = ref()
+const formData = ref({
+  name: '',
+  phone: '',
+  city: '',
+  birthDate: '',
+  remark: ''
+})
+
+const cityOptions = [
+  { text: '北京', value: 'beijing' },
+  { text: '上海', value: 'shanghai' },
+  { text: '深圳', value: 'shenzhen' }
+]
+
+const handleSubmit = async () => {
+  const valid = await formRef.value.validate()
+  if (valid) {
+    try {
+      $n.loading.show('提交中...')
+      await api.submitForm(formData.value)
+      $n.toast('提交成功', { type: 'success' })
+      // 返回上一页或跳转
+    } catch (error) {
+      $n.toast('提交失败', { type: 'error' })
+    } finally {
+      $n.loading.hide()
+    }
+  }
+}
+</script>
+```
+
+---
+
+### 2. 移动端列表页
+
+```vue
+<template>
+  <ns-page>
+    <ns-page-header title="订单列表" />
+    
+    <ns-tabs 
+      v-model="activeTab" 
+      :items="tabItems"
+      sticky
+    >
+      <ns-tabs-item value="all">
+        <ns-list 
+          :data="orders"
+          :loading="loading"
+          :finished="finished"
+          refreshable
+          loadmore
+          @refresh="handleRefresh"
+          @load="handleLoad"
+        >
+          <template #default="{ item }">
+            <ns-card class="order-card">
+              <ns-row justify="between" align="center">
+                <h3>订单号：{{ item.orderNo }}</h3>
+                <ns-chip 
+                  :label="item.statusText" 
+                  :color="getStatusColor(item.status)"
+                />
+              </ns-row>
+              
+              <ns-divider />
+              
+              <ns-row gap="md" align="center">
+                <ns-image 
+                  :src="item.productImage" 
+                  width="80" 
+                  height="80"
+                />
+                <ns-column flex="1">
+                  <p>{{ item.productName }}</p>
+                  <p class="price">¥{{ item.price }}</p>
+                </ns-column>
+              </ns-row>
+              
+              <ns-divider />
+              
+              <ns-row justify="end" gap="sm">
+                <ns-button 
+                  label="查看详情" 
+                  size="sm"
+                  @click="viewDetail(item)"
+                />
+                <ns-button 
+                  v-if="item.canPay"
+                  label="去支付" 
+                  size="sm"
+                  color="primary"
+                  @click="goPay(item)"
+                />
+              </ns-row>
+            </ns-card>
+          </template>
+        </ns-list>
+      </ns-tabs-item>
+    </ns-tabs>
+  </ns-page>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const activeTab = ref('all')
+const orders = ref([])
+const loading = ref(false)
+const finished = ref(false)
+const page = ref(1)
+
+const tabItems = [
+  { text: '全部', value: 'all' },
+  { text: '待付款', value: 'unpaid' },
+  { text: '待发货', value: 'unshipped' },
+  { text: '已完成', value: 'finished' }
+]
+
+const handleRefresh = async () => {
+  page.value = 1
+  finished.value = false
+  await loadData()
+}
+
+const handleLoad = async () => {
+  page.value++
+  await loadData()
+}
+
+const loadData = async () => {
+  loading.value = true
+  try {
+    const response = await api.getOrders({
+      page: page.value,
+      status: activeTab.value
+    })
+    
+    if (page.value === 1) {
+      orders.value = response.data
+    } else {
+      orders.value.push(...response.data)
+    }
+    
+    finished.value = !response.hasMore
+  } finally {
+    loading.value = false
+  }
+}
+
+const getStatusColor = (status) => {
+  const colorMap = {
+    unpaid: 'warning',
+    unshipped: 'info',
+    shipped: 'primary',
+    finished: 'success'
+  }
+  return colorMap[status] || 'info'
+}
+
+const viewDetail = (order) => {
+  // 跳转到详情页
+}
+
+const goPay = (order) => {
+  // 跳转到支付页
+}
+
+onMounted(() => {
+  loadData()
+})
+</script>
+
+<style scoped>
+.order-card {
+  margin-bottom: 12px;
+}
+
+.price {
+  color: #ff4d4f;
+  font-size: 18px;
+  font-weight: bold;
+}
+</style>
+```
+
+---
+
+### 3. 移动端详情页
+
+```vue
+<template>
+  <ns-page>
+    <ns-page-header 
+      title="订单详情" 
+      back 
+      @back="goBack"
+    />
+    
+    <ns-page-content>
+      <!-- 订单状态 -->
+      <ns-card>
+        <ns-row align="center" gap="md">
+          <ns-icon name="success" size="xl" fill="success" />
+          <ns-column>
+            <h2>订单已完成</h2>
+            <p>感谢您的购买</p>
+          </ns-column>
+        </ns-row>
+      </ns-card>
+      
+      <!-- 物流信息 -->
+      <ns-card title="物流信息">
+        <ns-timeline :items="logisticsSteps" />
+      </ns-card>
+      
+      <!-- 商品信息 -->
+      <ns-card title="商品信息">
+        <ns-row gap="md" align="center">
+          <ns-image 
+            :src="order.productImage" 
+            width="80" 
+            height="80"
+          />
+          <ns-column flex="1">
+            <p>{{ order.productName }}</p>
+            <p class="price">¥{{ order.price }}</p>
+          </ns-column>
+        </ns-row>
+      </ns-card>
+      
+      <!-- 订单详情 -->
+      <ns-card title="订单详情">
+        <ns-facts>
+          <ns-facts-item 
+            label="订单号" 
+            :value="order.orderNo" 
+          />
+          <ns-facts-item 
+            label="下单时间" 
+            :value="order.createdAt" 
+          />
+          <ns-facts-item 
+            label="支付方式" 
+            :value="order.paymentMethod" 
+          />
+          <ns-facts-item 
+            label="配送地址" 
+            :value="order.address" 
+          />
+        </ns-facts>
+      </ns-card>
+    </ns-page-content>
+    
+    <ns-page-footer>
+      <ns-row gap="sm">
+        <ns-button 
+          label="联系客服" 
+          flex="1"
+          @click="contactService"
+        />
+        <ns-button 
+          label="再来一单" 
+          color="primary"
+          flex="1"
+          @click="reorder"
+        />
+      </ns-row>
+    </ns-page-footer>
+  </ns-page>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+import { useRouter } from 'vue-router'
+
+const router = useRouter()
+const order = ref({})
+const logisticsSteps = ref([])
+
+const goBack = () => {
+  router.back()
+}
+
+const contactService = () => {
+  // 联系客服
+}
+
+const reorder = () => {
+  // 再来一单
+}
+
+onMounted(async () => {
+  // 加载订单详情
+})
+</script>
+```
+
+---
+
+### 4. 性能优化建议
+
+**长列表优化**:
+
+```vue
+<!-- 使用虚拟列表 -->
+<ns-list 
+  :data="longList"
+  virtual
+  :item-height="80"
+  :buffer-size="5"
+/>
+```
+
+**图片懒加载**:
+
+```vue
+<ns-image 
+  :src="imageUrl" 
+  lazy 
+  placeholder="/loading.png"
+/>
+```
+
+**防抖处理**:
+
+```javascript
+import { debounce } from 'lodash-es'
+
+const handleSearch = debounce((keyword) => {
+  // 搜索逻辑
+}, 300)
+```
+
+---
+
+### 5. 响应式设计
+
+```vue
+<script setup>
+import { usePlatform } from '@uxda/nutshell/taro'
+
+const platform = usePlatform()
+
+// 根据屏幕宽度调整布局
+const columns = computed(() => {
+  if (platform.screen.width < 375) return 3
+  if (platform.screen.width < 414) return 4
+  return 5
+})
+</script>
+
+<template>
+  <ns-grid :columns="columns">
+    <!-- 网格内容 -->
+  </ns-grid>
+</template>
+```
+
+---
+
+### 6. 小程序特殊处理
+
+**页面高度设置**:
+
+```vue
+<style>
+/* 小程序页面高度100% */
+page {
+  height: 100%;
+}
+</style>
+```
+
+**授权处理**:
+
+```javascript
+import Taro from '@tarojs/taro'
+
+// 获取用户信息
+const getUserInfo = async () => {
+  const { authSetting } = await Taro.getSetting()
+  
+  if (!authSetting['scope.userInfo']) {
+    // 请求授权
+    await Taro.authorize({ scope: 'scope.userInfo' })
+  }
+  
+  const userInfo = await Taro.getUserInfo()
+  return userInfo
+}
+```
+
+---
+
+## 附录
+
+### 移动端尺寸规范
+
+| 元素 | 推荐尺寸 |
+|------|----------|
+| 按钮高度 | 44px - 48px |
+| 输入框高度 | 44px - 48px |
+| 列表项高度 | 不小于 44px |
+| 图标尺寸 | 24px - 32px |
+| 字体大小（正文） | 14px - 16px |
+| 字体大小（标题） | 18px - 20px |
+| 安全触摸区域 | 不小于 44px × 44px |
+
+---
+
+### 常见问题
+
+**Q: 如何处理移动端1px边框问题？**
+
+A: 组件库已内置处理，使用 `hairline` 属性可以实现0.5px细线效果。
+
+**Q: 如何适配刘海屏？**
+
+A: 使用 `safe-area-inset-bottom` 等属性自动适配安全区域。
+
+**Q: 小程序中如何使用？**
+
+A: 引入 `@uxda/nutshell/taro` 版本，详见"快速开始"章节。
+
+**Q: 如何实现下拉刷新？**
+
+A: 使用 `<ns-list>` 或 `<ns-scrollable>` 组件的 `refreshable` 属性。
+
+---
+
+## 技术支持
+
+- GitLab: http://gitlab.ddjf.local/fed/nutshell
+- 版本: 1.6.92
+- 支持平台: H5、微信小程序
+
+---
+
+**最后更新**: 2024-11-13
+