更新记录

1.0.0（2026-02-24）

初始版本发布

平台兼容性

uni-app(3.6.17)

UTS 手写签批插件调用文档

插件版本: v1.0 适用平台: Android (UTS)
最后更新: 2026-02-24
SDK 包名: uts.sdk.modules.zyhandwriting

1. 插件简介

本插件基于 Android 原生手写签批 SDK 封装，提供空白签批和田字格签批两种模式，适用于电子签名、合同签署、手写输入、书法练习等场景。

核心功能

2. 快速开始

2.1 引入插件

import { openBlank, openGrid } from '@/uni_modules/zy-handwriting';

2.2 基础调用

// 空白签批
openBlank({
    success: (res) => {
        console.log('图片路径:', res.imagePath);
    }
});

// 田字格签批
openGrid({
    success: (res) => {
        console.log('图片路径:', res.imagePath);
    }
});

3. API 详细文档

3.1 空白签批 openBlank

方法签名

openBlank(options: OpenBlankOptions): void

参数说明

返回值

成功回调接收 HandwritingResult 对象：

interface HandwritingResult {
    imagePath: string;  // 本地图片绝对路径
}

代码示例

openBlank({
    width: 1080,
    height: 800,
    background: "#FFFFFF",      // 白色背景
    crop: true,                 // 裁剪多余空白区域
    format: "PNG",
    themeColor: "#1890FF",      // 蓝色主题
    success: (res) => {
        this.imagePath = res.imagePath;
        uni.showToast({ title: '签名成功', icon: 'success' });
    },
    fail: (err) => {
        console.error('签名失败:', err);
        uni.showToast({ title: '已取消', icon: 'none' });
    },
    complete: () => {
        console.log('签批流程结束');
    }
});

3.2 田字格签批 openGrid

方法签名

openGrid(options: OpenGridOptions): void

参数说明

代码示例

openGrid({
    fontSize: 60,               // 字体大小
    lineLength: 10,             // 每行 10 个字
    background: "#FFFBF0",      // 米黄色背景
    crop: true,                 // 裁剪多余空白
    format: "PNG",
    themeColor: "#D4380D",      // 红色主题
    success: (res) => {
        this.imagePath = res.imagePath;
        uni.showToast({ title: '书写成功', icon: 'success' });
    },
    fail: (err) => {
        console.error('书写失败:', err);
        uni.showToast({ title: '已取消', icon: 'none' });
    }
});

4. 完整页面示例

<template>
    <view class="container">
        <view class="header">
            <text class="title">手写签批演示</text>
        </view>

        <view class="btn-group">
            <button type="primary" @click="openBlankSign">空白签名</button>
            <button type="default" @click="openGridSign">田字格书写</button>
        </view>

        <view v-if="imagePath" class="preview">
            <text class="preview-title">签批预览</text>
            <image :src="imagePath" mode="widthFix" class="preview-img" />
            <view class="action-btns">
                <button type="default" @click="clearImage" class="clear-btn">重新签批</button>
            </view>
        </view>
    </view>
</template>

<script>
    import { openBlank, openGrid } from '@/uni_modules/zy-handwriting';

    export default {
        data() {
            return {
                imagePath: ''
            };
        },
        methods: {
            // 空白签名
            openBlankSign() {
                openBlank({
                    width: 1080,
                    height: 800,
                    background: "#FFFFFF",
                    crop: true,
                    format: "PNG",
                    themeColor: "#1890FF",
                    success: (res) => {
                        this.imagePath = res.imagePath;
                        uni.showToast({ title: '签名成功', icon: 'success' });
                    },
                    fail: (err) => {
                        console.error('签名失败:', err);
                        uni.showToast({ title: '已取消', icon: 'none' });
                    }
                });
            },

            // 田字格书写
            openGridSign() {
                openGrid({
                    fontSize: 60,
                    lineLength: 10,
                    background: "#FFFBF0",
                    crop: true,
                    format: "PNG",
                    themeColor: "#D4380D",
                    success: (res) => {
                        this.imagePath = res.imagePath;
                        uni.showToast({ title: '书写成功', icon: 'success' });
                    },
                    fail: (err) => {
                        console.error('书写失败:', err);
                        uni.showToast({ title: '已取消', icon: 'none' });
                    }
                });
            },
            // 清除图片
            clearImage() {
                this.imagePath = '';
            }
        }
    };
</script>

<style scoped>
    .container {
        padding: 40rpx;
        min-height: 100vh;
        background: #F8F9FA;
    }

    .header {
        text-align: center;
        padding: 40rpx 0;
    }

    .title {
        font-size: 40rpx;
        font-weight: bold;
        color: #333;
    }

    .btn-group {
        display: flex;
        flex-direction: column;
        gap: 24rpx;
        margin: 40rpx 0;
    }

    .preview {
        margin-top: 40rpx;
        background: #FFF;
        padding: 30rpx;
        border-radius: 16rpx;
        box-shadow: 0 4rpx 20rpx rgba(0,0,0,0.08);
    }

    .preview-title {
        font-size: 32rpx;
        color: #666;
        display: block;
        margin-bottom: 20rpx;
    }

    .preview-img {
        width: 100%;
        border-radius: 8rpx;
        border: 1px solid #EEE;
    }

    .action-btns {
        display: flex;
        gap: 20rpx;
        margin-top: 30rpx;
    }
</style>

5. 错误码说明

6. 注意事项

6.1 权限配置

在 manifest.json 中确保配置以下权限：

"android": {
    "permissions": [
        "<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>",
        "<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>"
    ]
}

6.2 图片路径使用

6.3 颜色格式

background 和 themeColor 参数支持以下格式：

// 推荐格式
background: "#FFFFFF"
themeColor: "#e63f32"

// 也支持简写
background: "#FFF"
themeColor: "#F00"

6.4 参数详解

7. 常见问题

Q: 签名图片无法显示？
A: 检查 imagePath 是否为有效路径，Android 10+ 可能需要适配分区存储。

Q: 如何自定义画笔粗细？
A: 当前版本暂不支持，需联系插件作者或修改原生 SDK。

Q: 支持 iOS 吗？
A: 当前版本仅支持 Android，iOS 版本开发中。

Q: crop 参数有什么作用？
A: crop: true 时最终图片只包含手写内容区域，自动裁剪多余空白；crop: false 时保留完整画布尺寸。

Q: 田字格如何控制每行字数？
A: 通过 lineLength 参数设置，超出屏幕宽度时支持横向滚动。

8. 更新日志

9. 技术支持

温馨提示: 使用前请确保已正确配置原生 SDK 依赖和权限声明。