استفاده از سنسورهای گوشی

با سنسورها می‌توانید حرکت گوشی را دریافت کنید، مقدار شتاب یا چرخش را در صفحه نمایش دهید و با تکان‌دادن گوشی یک عملکرد اجرا کنید. برای استفاده معمول به کدنویسی نیاز ندارید: عملکرد شروع سنسور دریافت را فعال می‌کند، داده در یک متغیر موقت قرار می‌گیرد و عملکرد انتخاب‌شده هنگام دریافت داده یا تشخیص تکان اجرا می‌شود.

این راهنما قابلیت‌های موجود را توضیح می‌دهد: شتاب‌سنج، شتاب حرکت بدون گرانش، ژیروسکوپ و تشخیص تکان. سنسور نور، مجاورت، قدم‌شمار و قطب‌نما فعلاً در این بخش در دسترس نیستند.

انتخاب نوع سنسور

نوع در فرم	چه چیزی دریافت می‌کنید؟	کاربرد نمونه
شتاب‌سنج (با گرانش)	شتاب سه محور، همراه با اثر گرانش	بررسی کج‌شدن گوشی یا نمایش داده حرکت
شتاب حرکت (بدون گرانش)	شتاب سه محور پس از حذف اثر گرانش	بررسی شدت حرکت گوشی
ژیروسکوپ	سرعت چرخش حول سه محور	بررسی سرعت چرخاندن گوشی
تشخیص تکان‌دادن گوشی	رویداد هنگامی که شدت شتاب حرکت از آستانه عبور کند	نمایش پیام، تغییر صفحه یا اجرای یک عملکرد با تکان

شتاب بر حسب متر بر مجذور ثانیه (m/s²) و داده ژیروسکوپ بر حسب رادیان بر ثانیه (rad/s) است. ژیروسکوپ سرعت چرخش را می‌دهد؛ خروجی آن زاویه یا جهت قطب‌نما نیست.

وقتی گوشی ثابت است، اندازه بردار شتاب‌سنج با گرانش معمولاً حدود 9.81 است؛ سهم هر محور به قرارگیری گوشی بستگی دارد. شتاب حرکت بدون گرانش و ژیروسکوپ در حالت سکون معمولاً نزدیک صفرند، ولی مقداری نوسان طبیعی است.

شروع سریع: با تکان گوشی یک پیام نشان دهید

1. صفحه موردنظر را باز کنید و تنظیمات رویداد ورود به صفحه را انتخاب کنید.
2. در انتخاب‌گر عملکردها، از دسته قابلیت‌های دستگاه، شروع سنسور را انتخاب کنید.
3. شناسه دریافت سنسور را motion قرار دهید.
4. نوع سنسور را تشخیص تکان‌دادن گوشی انتخاب کنید.
5. متغیر خروجی JSON را sensorData قرار دهید.
6. آستانه تکان را 15 و فاصله تکان‌ها را 1000 میلی‌ثانیه بگذارید.
7. در عملکرد با دریافت داده / تکان، عملکرد نمایش پیام کوتاه را انتخاب کنید و متن آن را «گوشی تکان خورد» بنویسید.
8. در عملکرد هنگام خطای سنسور، یک پیام مانند «سنسور حرکت در این دستگاه در دسترس نیست» قرار دهید.
9. پیش‌نمایش را باز کنید. با شبیه‌سازی فعال، هر یک ثانیه یک تکان تولید می‌شود و پیام را می‌بینید.
10. برای بررسی تکان واقعی، خروجی جدید اپ را روی گوشی نصب و همین صفحه را باز کنید.

به‌جای رویداد ورود می‌توانید همین عملکرد را به کلیک دکمه «شروع» وصل کنید. پس از شروع، دریافت ادامه دارد؛ کاربر لازم نیست دکمه را برای هر نمونه یا تکان دوباره بزند.

برای پایان دریافت، دکمه «توقف» بسازید و عملکرد توقف سنسور را با شناسه motion به آن وصل کنید.

تنظیمات شروع سنسور

تنظیم	مقدار پیش‌فرض فرم	توضیح
شناسه دریافت سنسور	sensor	نام دریافت برای توقف یا جایگزین‌کردن تنظیمات آن
نوع سنسور	شتاب‌سنج با گرانش	نوع داده یا رویداد موردنظر
متغیر خروجی JSON	sensorData	نام متغیر موقت خروجی؛ اختیاری است
فاصله داده‌ها	200 میلی‌ثانیه	فاصله انتشار داده پیوسته؛ بازه 50 تا 5000
آستانه تکان	15	حداقل اندازه شتاب حرکت برای تشخیص تکان؛ بازه 1 تا 100
فاصله تکان‌ها	1000 میلی‌ثانیه	حداقل فاصله بین دو رویداد تکان؛ بازه 250 تا 10000
عملکرد با دریافت داده / تکان	بدون عملکرد	پس از انتشار نمونه یا تشخیص تکان اجرا می‌شود
عملکرد هنگام خطای سنسور	بدون عملکرد	هنگام نبود سنسور، نرسیدن داده یا خطای دسترسی اجرا می‌شود
شبیه‌سازی در پیش‌نمایش	فعال	دریافت داده ساختگی در پیش‌نمایش
مقدار شبیه‌سازی x، y و z	0، 0 و 9.81	مقدار سه محور در شبیه‌سازی داده پیوسته

فاصله داده‌ها برای سه نوع داده پیوسته است؛ تشخیص تکان از آستانه و فاصله تکان‌ها استفاده می‌کند. مقدار کمتر برای فاصله داده‌ها، به‌روزرسانی بیشتری ایجاد می‌کند. برای نمایش ساده از مقدار پیش‌فرض شروع کنید.

شناسه دریافت و نام متغیر چه تفاوتی دارند؟

شناسه دریافت، مانند motion، برای مدیریت شروع و توقف است. نام متغیر، مانند sensorData، برای خواندن داده است. برای توقف، شناسه دریافت را وارد کنید، نه نام متغیر.

شناسه در محدوده همان نمونه صفحه است. شروع دوباره با شناسه یکسان، دریافت قبلی همان صفحه را جایگزین می‌کند. برای چند دریافت هم‌زمان، شناسه‌های متفاوت و متغیرهای خروجی جدا تعیین کنید؛ مثلاً accel با متغیر accelData و rotation با متغیر rotationData.

متغیر خروجی

نام متغیر باید با حرف انگلیسی یا زیرخط شروع شود و ادامه آن فقط حرف انگلیسی، عدد یا زیرخط باشد؛ مثل sensorData یا motion_data2. نقطه، فاصله و نام فارسی در نام خروجی پذیرفته نمی‌شوند. مسیرهایی مثل sensorData.x برای خواندن داده‌اند، نه نام متغیر در فرم شروع.

متغیر خروجی به‌صورت JSON در حافظه موقت ساخته یا به‌روز می‌شود و پس از بستن کامل اپ ماندگار نیست. برای جلوگیری از تداخل، نام یک متغیر موجود با کاربرد دیگر را به خروجی سنسور ندهید. اگر نام خروجی را خالی بگذارید، دریافت و عملکرد رویداد همچنان قابل استفاده‌اند، ولی داده در متغیر نوشته نمی‌شود.

داده خروجی و وضعیت‌ها

نمونه زیر فقط شکل یک داده فعال را نشان می‌دهد؛ مقدار واقعی محورهای گوشی شما متفاوت است:

{
  "status": "active",
  "sensor": "accelerometer",
  "id": "motion",
  "simulated": false,
  "timestamp": 1790769600000,
  "x": 0.12,
  "y": 0.08,
  "z": 9.79,
  "magnitude": 9.791
}

فیلد	معنی
status	وضعیت فعلی خروجی
sensor	accelerometer، userAccelerometer، gyroscope یا shake
id	شناسه دریافت
simulated	true برای داده شبیه‌سازی‌شده و false برای داده واقعی
timestamp	زمان انتشار خروجی به‌صورت میلی‌ثانیه Unix
x، y و z	مقدار سه محور دستگاه
magnitude	اندازه بردار سه محور: ریشه مجموع مربع x، y و z
error	کد خطا؛ فقط در وضعیت خطا وجود دارد

مقدار status	معنی
starting	دریافت ثبت شده و هنوز نمونه‌ای منتشر نشده است
active	یک نمونه داده یا تکان منتشر شده است
paused	دریافت فعال به‌دلیل پس‌زمینه یا پوشیده‌شدن صفحه متوقف شده است
error	دریافت با خطا مواجه شده است

در خروجی‌های starting، paused و error، فیلدهای x، y، z و magnitude وجود ندارند. پیش از استفاده از آن‌ها وضعیت را بررسی کنید. در حالت تشخیص تکان، اولین active با اولین تکان منتشر می‌شود؛ سکون گوشی به معنی خطا نیست.

توقف دستی یا بسته‌شدن صفحه، مقدار آخر متغیر را پاک نمی‌کند و وضعیت جدیدی به نام stopped نمی‌نویسد. بنابراین active بودن آخرین داده به‌تنهایی نشان نمی‌دهد دریافت هنوز روشن است. در صورت نیاز، وضعیت دکمه شروع/توقف را با متغیر جداگانه مدیریت کنید.

نمایش داده در صفحه

1. در ورود صفحه شروع سنسور را با نوع شتاب‌سنج (با گرانش)، شناسه motion و خروجی sensorData قرار دهید.
2. یک ویجت نمایشگر متغیر اضافه کنید و مسیر sensorData.x را نمایش دهید.
3. برای محورهای دیگر، نمایشگرهای جدا با مسیرهای sensorData.y و sensorData.z بسازید.
4. برای نمایش شدت، مسیر sensorData.magnitude و برای نمایش وضعیت، مسیر sensorData.status را استفاده کنید.
5. در پیش‌نمایش، مقدارهای شبیه‌سازی x، y و z را عوض کنید تا اتصال داده به صفحه را بررسی کنید.

در بخش‌هایی که از جایگذاری متغیر در متن پشتیبانی می‌کنند، می‌توانید از قالب زیر استفاده کنید:

شتاب محور x: {{sensorData.x}}

جزئیات خواندن مسیرهای JSON و جایگذاری متن در راهنمای متغیرها آمده است. برای این مثال، تعیین عملکرد هنگام دریافت داده ضروری نیست؛ انتشار متغیر امکان نمایش داده را فراهم می‌کند.

اجرای عملکرد براساس داده

متغیر خروجی پیش از اجرای «عملکرد با دریافت داده / تکان» به‌روز می‌شود. بنابراین شرط یا عملکرد داخلی می‌تواند همان نمونه را بخواند.

برای مثال، با نوع شتاب حرکت بدون گرانش، روی عملکرد داخلی شرط بگذارید که sensorData.magnitude از حد دلخواه بیشتر باشد؛ سپس پیام یا عملکرد دیگری اجرا کنید. اگر فقط اجرای یک عملکرد با تکان را می‌خواهید، نوع تشخیص تکان مناسب‌تر است، چون حداقل فاصله بین اجراها را هم مدیریت می‌کند.

در داده پیوسته، عملکرد ممکن است با هر نمونه مجاز اجرا شود. پیام، بازکردن صفحه یا عملیات طولانی را بدون شرط به همه نمونه‌ها وصل نکنید. تا زمانی که عملکرد قبلی تمام نشده، نمونه‌های جدید برای همان دریافت رد می‌شوند تا اجراها روی هم نیفتند.

تنظیم حساسیت تکان

• اگر تکان‌های کوچک باعث اجرا می‌شوند، آستانه تکان را بیشتر کنید؛ مثلاً از 15 به 20.
• اگر تکان معمولی تشخیص داده نمی‌شود، آستانه را کمتر کنید؛ مثلاً 10.
• اگر با یک حرکت چند بار عملکرد اجرا می‌شود، فاصله تکان‌ها را بیشتر کنید؛ مثلاً 2000 میلی‌ثانیه.
• آستانه بر اندازه شتاب بدون گرانش اعمال می‌شود. این قابلیت، عبور شدت حرکت از حد تعیین‌شده را تشخیص می‌دهد و جهت خاصی برای تکان لازم ندارد.

حساسیت مناسب به گوشی و نوع حرکت بستگی دارد؛ شبیه‌سازی فقط اتصال عملکرد را بررسی می‌کند و جای تنظیم حساسیت روی گوشی را نمی‌گیرد.

پیش‌نمایش و داده واقعی

شبیه‌سازی

گزینه شبیه‌سازی در پیش‌نمایش به‌صورت پیش‌فرض فعال است. در سه نوع داده پیوسته، مقادیر ثابت x، y و z تعیین‌شده در فرم منتشر می‌شوند. برای شبیه‌سازی گوشی ساکن با ژیروسکوپ یا شتاب بدون گرانش، هر سه مقدار را صفر قرار دهید.

در نوع تشخیص تکان، هر فاصله تعیین‌شده برای تکان‌ها یک تکان ساختگی تولید می‌شود؛ مقادیر شبیه‌سازی سه محور در این حالت استفاده نمی‌شوند. اگر عملکرد داخلی طولانی باشد، اجرای بعدی تا پایان آن انجام نمی‌شود.

داده واقعی مرورگر و خروجی اپ

برای دریافت واقعی در پیش‌نمایش، گزینه شبیه‌سازی را غیرفعال کنید. دسترسی به سنسور به دستگاه، مرورگر و محدودیت‌های دسترسی مرورگر وابسته است؛ لپ‌تاپ بدون سنسور حرکت ممکن است داده‌ای ندهد. اگر پس از شروع دریافت واقعی ظرف پنج ثانیه نمونه‌ای نرسد، خطای no_sensor_data گزارش می‌شود.

در خروجی نهایی اپ، شبیه‌سازی فعال نمی‌شود و دریافت واقعی است. پس از افزودن سنسور به اپ، خروجی جدید تهیه کنید. سخت‌افزار Android و iOS پشتیبانی می‌شود؛ خروجی وب تابع پشتیبانی مرورگر است و در خروجی دسکتاپ، دریافت واقعی فعلاً مسیر خطای پلتفرم را اجرا می‌کند.

توقف، خروج از صفحه و پس‌زمینه

• توقف مشخص: عملکرد توقف سنسور با شناسه یکسان، دریافت همان صفحه را حذف می‌کند.
• توقف همه: شناسه خالی در توقف سنسور، همه دریافت‌های همان نمونه صفحه را حذف می‌کند.
• صفحه دیگر یا پس‌زمینه: اگر صفحه فعلی پوشیده شود یا اپ به پس‌زمینه برود، دریافت موقتاً قطع می‌شود؛ با بازگشت دوباره فعال می‌شود.
• بسته‌شدن صفحه: با حذف نمونه صفحه، دریافت‌های آن پاک می‌شوند. ورود بعدی نیاز به شروع جدید دارد؛ اتصال شروع به رویداد ورود، این کار را انجام می‌دهد.
• خطا: دریافت خطادار خودکار دوباره شروع نمی‌شود. پس از رفع مشکل، عملکرد شروع سنسور را دوباره اجرا کنید.

شروع و توقف را برای همان صفحه تنظیم کنید. عملکرد توقف در صفحه دیگر، دریافت صفحه قبلی را با شناسه مشابه کنترل نمی‌کند. نام‌های متفاوت برای چند دریافت، از جایگزین‌شدن ناخواسته تنظیمات جلوگیری می‌کنند.

استفاده از JavaScript

همین قابلیت از عملکرد اجرای کد جاوااسکریپت هم در دسترس است. متد شروع، یک دریافت را ثبت می‌کند؛ منتظر اولین نمونه یا تکان نمی‌ماند.

شروع تشخیص تکان با عملکردهای نام‌دار

در لیست عملکردهای همان «اجرای کد جاوااسکریپت»، دو عملکرد بسازید: یکی با شناسه shakeAction برای نتیجه تکان و دیگری با شناسه sensorError برای پیام خطا. سپس کد زیر را وارد کنید:

const started = await AppEditor.startSensor({
  id: "motion",
  s: "shake",
  v: "sensorData",
  threshold: 15,
  cooldown: 1000,
  onEvent: "shakeAction",
  onError: "sensorError"
});

onEvent و onError رشته شناسه عملکردهای همان لیست هستند؛ تابع JavaScript به‌عنوان callback ارسال نکنید. مقدار برگشتی شروع، boolean است. true بودن آن تضمین دریافت داده نیست؛ خطای سنسور می‌تواند بعداً از مسیر onError گزارش شود.

دریافت پیوسته

await AppEditor.startSensor({
  id: "rotation",
  s: "gyroscope",
  v: "rotationData",
  ms: 200,
  sx: 0,
  sy: 0,
  sz: 0
});

برای خواندن نمونه در یک عملکرد جداگانه یا عملکرد داخلی هنگام دریافت:

const data = await AppEditor.getVar("rotationData");
if (data && data.status === "active") {
  AppEditor.showMessage("سرعت چرخش محور z: " + data.z);
}

کد خواندن را بلافاصله پس از شروع برای انتظار نمونه به کار نبرید؛ ممکن است خروجی هنوز starting باشد.

پارامترهای متد شروع

پارامتر	توضیح
id	شناسه دریافت؛ در صورت حذف sensor
s	accelerometer، userAccelerometer، gyroscope یا shake؛ پیش‌فرض accelerometer
v	نام خروجی JSON؛ اگر ارسال نشود، متغیری نوشته نمی‌شود
ms	فاصله داده پیوسته؛ پیش‌فرض 200 میلی‌ثانیه
threshold	آستانه تکان؛ پیش‌فرض 15
cooldown	فاصله تکان‌ها؛ پیش‌فرض 1000 میلی‌ثانیه
onEvent	شناسه عملکرد هنگام داده یا تکان؛ اختیاری
onError	شناسه عملکرد هنگام خطا؛ اختیاری
sim	شبیه‌سازی پیش‌نمایش؛ پیش‌فرض فعال، false برای داده واقعی مرورگر
sx، sy و sz	مقدار شبیه‌سازی؛ پیش‌فرض به‌ترتیب 0، 0 و 9.81

توقف از کد

کد زیر را در عملکرد جداگانه، مثل کلیک دکمه توقف، قرار دهید:

await AppEditor.stopSensor({id: "motion"});

برای توقف همه دریافت‌های همان صفحه:

await AppEditor.stopSensor({});

اگر توقف را بلافاصله پس از شروع در همان کد اجرا کنید، دریافت قبل از استفاده لغو می‌شود. توقف مقدار true برمی‌گرداند حتی اگر شناسه موردنظر دریافت فعالی نداشته باشد؛ این مقدار، تأیید وجود یک سنسور فعال نیست.

خطاها و رفع مشکل

کد خطا در متغیر خروجی	معنی	اقدام پیشنهادی
unsupported_platform	دریافت واقعی در این پلتفرم پشتیبانی نمی‌شود	در پیش‌نمایش شبیه‌سازی را فعال کنید؛ دریافت واقعی را روی گوشی بررسی کنید
sensor_unavailable	سنسور یا دسترسی آن در دسترس نیست	نوع سنسور، سخت‌افزار و دسترسی‌های دستگاه یا مرورگر را بررسی کنید
sensor_disconnected	جریان داده سنسور پایان یافته است	با عملکرد شروع، دریافت را دوباره فعال کنید
no_sensor_data	طی پنج ثانیه نمونه واقعی نرسیده است	پشتیبانی دستگاه و مرورگر را بررسی و دریافت را دوباره شروع کنید

در پیش‌نمایش بدون حرکت پیام تکان می‌بینم: شبیه‌سازی فعال است؛ این رفتار برای بررسی اتصال عملکرد طراحی شده است.

مقدارهای پیش‌نمایش تغییر نمی‌کنند: داده پیوسته شبیه‌سازی ثابت است. مقادیر x، y و z را تغییر دهید و شروع را دوباره اجرا کنید یا از داده واقعی استفاده کنید.

محورهای خروجی خالی‌اند: status را بررسی کنید. پیش از اولین نمونه، هنگام توقف موقت و هنگام خطا، محورهای نمونه وجود ندارند.

شتاب‌سنج در حالت سکون صفر نیست: نوع با گرانش انتخاب شده است. برای شتاب ناشی از حرکت، نوع بدون گرانش را انتخاب کنید.

دکمه توقف اثری ندارد: شناسه شروع و توقف و صفحه‌ای که عملکرد روی آن اجرا می‌شود را مقایسه کنید. برای توقف دریافت motion، نام متغیر sensorData را وارد نکنید.

عملکرد هنگام داده اجرا نمی‌شود: اتصال عملکرد داخلی و شرط آن را بررسی کنید. در حالت تکان، شدت حرکت باید از آستانه بگذرد. اگر عملکرد قبلی هنوز در حال اجرا باشد، نمونه‌های بعدی رد می‌شوند. در JavaScript هم شناسه عملکرد باید در لیست همان عملکرد تعریف شده باشد.

دو سنسور داده یکدیگر را تغییر می‌دهند: برای هر دریافت شناسه و نام خروجی جدا انتخاب کنید.

راهنماهای مرتبط

• شروع سنسور
• توقف سنسور
• متغیرها و مسیرهای JSON
• رویدادهای صفحه و ویجت
• شرط‌ها
• اجرای کد جاوااسکریپت