آموزش Node.js: میزبانی و پیکربندی محیط توسعه — بخش دوم

اپلیکیشن‌های Node.js را بسته به نیازها می‌توان در مکان‌های مختلفی میزبانی کرد. در ادامه فهرستی (غیر جامع) از گزینه‌های ممکن برای میزبانی و توزیع اپلیکیشن‌های Node.js و ایجاد دسترسی عمومی معرفی شده‌اند. این فهرست از ساده‌ترین گزینه‌های پیکربندی محیط توسعه آغاز شده و در ادامه به سمت گزینه‌های پیچیده و قوی‌تر حرکت می‌کند. برای مطالعه بخش قبلی این مجموعه مطلب آموزشی می‌توانید به لینک زیر مراجعه کنید:

• آموزش Node.js: مفاهیم مقدماتی — بخش اول

ساده‌ترین گزینه: تونل لوکال (Local Tunnel)

حتی در صورتی که یک IP دینامیک داشته باشید یا شبکه‌تان تحت NAT پیکربندی شده باشد، می‌توانید اپلیکیشن خود را روی سیستم لوکال توزیع کنید و درخواست‌ها را با استفاده از تونل لوکال مستقیماً از رایانه خودتان پاسخ دهید. این گزینه برای برخی مقاصد تست کردن، نمایش دمویی از یک محصول یا اشتراک یک اپلیکیشن با گروه معدودی از افراد مناسب است.

یک ابزار بسیار خوب برای این منظور وجود دارد که ngrok (+) نام دارد. با استفاده از ngrok می‌توان صرفاً با وارد کردن دستور زیر پورت مورد نظر را برای دسترسی اینترنت باز کرد:

ngrok PORT

بدین ترتیب یک دامنه از ngrok.io به دست می‌آورید، اما با عضویت در طرح‌های پولی این سرویس می‌توانید یک URL سفارشی و گزینه‌های امنیتی بیشتری به دست آورید. به خاطر داشته باشید که در این روش سیستم خود را برای دسترسی اینترنت باز می‌کنید. سرویس دیگری که بدین منظور می‌توان استفاده کرد localtunnel (+) است.

توزیع‌های با پیکربندی صفر

در این بخش برخی از روش‌های توزیع اپلیکیشن‌های Node.js را معرفی می‌کنیم که نیاز به هیچ پیکربندی ندارند.

Glitch: (+) یک محیط کاری و روشی برای ساخت اپلیکیشن‌ها به روشی سریع است. به طوری که این اپلیکیشن‌ها بی‌درنگ در زیردامنه مربوطه از دامنه glitch.com در دسترس قرار می‌گیرند. در حال حاضر امکان داشتن یک دامنه سفارشی وجود ندارد و همچنین چند محدودیت دیگر وجود دارند؛ اما این سرویس برای ساخت پروتوتایپ بسیار عالی است. ظاهر آن جالب است و یک محیط ساده ملال‌آور محسوب نمی‌شود. شما در این محیط می‌توانید همه قدرت Node.js، یک CDN، ذخیره‌سازی امن برای کلیدهای احراز هویت، دستورهای ایمپورت/اکسپورت گیت‌هاب و موارد دیگر را در اختیار داشته باشید.

این سرویس از سوی شرکت FogBugz و Trello (و همچنین هم‌بنیانگذار Stack Overflow) عرضه شده است. استفاده از آن برای مقاصد دمو توصیه می‌شود.

Codepen: کدپن (+) پلتفرم و جامعه‌ای جذاب است. شما می‌توانید پروژه‌ای با چندین فایل ایجاد کرده و آن را روی یک دامنه سفارشی توزیع کنید.

Serverless: روشی برای انتشار اپلیکیشن است و در آن کلاً هیچ سروری برای مدیریت کردن وجود ندارد. Serverless پارادایمی است که در آن اپلیکیشن‌ها به صورت تابع انتشار می‌یابند و به یک endpoint شبکه پاسخ می‌دهند. این پارادایم به نام FASS نیز شناخته می‌شود که اختصاری برای «Functions As A Service» (تابع به عنوان سرویس) است. لازم به اشاره است که Serverless Framework و Standard Library دو مورد از راه‌حل‌های بسیار محبوب در این زمینه به حساب می‌آیند؛ هر دوی این موارد یک لایه تجرید برای انتشار روی AWS Lambda و دیگر راه‌حل‌های FAAS مبتنی بر Azure یا Google Cloud ارائه می‌کنند.

PAAS: اختصاری برای عبارت «پلتفرم به عنوان سرویس» (Platform As A Service) است. این پلتفرم‌ها بسیاری از مواردی را که شما در زمان توزیع اپلیکیشن باید در نظر داشته باشید، بر عهده می‌گیرند و بدین ترتیب دغدغه‌های شما کاهش می‌یابد.

Zeit Now: (+) یک گزینه جذاب است. در این پلتفرم کافی است عبارت now را در ترمینال وارد کنید تا عمل توزیع اپلیکیشن اجرا شود. نسخه رایگانی از آن وجود دارد که با برخی محدودیت‌ها مواجه است؛ ولی نسخه پولی امکانات قوی‌تری دارد. با استفاده از این گزینه کلاً فراموش می‌کنید که سروری هم وجود دارد و صرفاً به توزیع اپلیکیشن می‌پردازید.

Nanobox: (+) نیز یکی از گزینه‌های میزبانی و توزیع اپلیکیشن‌های Node.js است.

Heroku: (+) یکی از گزینه‌های جالب دیگر برای توزیع اپلیکیشن‌های Node.js محسوب می‌شود.

Microsoft Azure: سرویس ابری مایکروسافت است که گزینه‌های خوبی برای توزیع اپلیکیشن‌های Node.js ارائه می‌کند.

Google Cloud Platform: پلتفرم ابری گوگل نیز ساختار جالبی برای اپلیکیشن‌های شما ارائه می‌کند. بخش مستندات (+) Node.js آن کاملاً مفید است.

سروری‌های مجازی دیگر: در این بخش برخی از شرکت‌هایی که سرورهای مجازی ارائه می‌کنند و مناسب میزبانی اپلیکیشن‌های Node.js هستند را معرفی کرده‌ایم. از جمله این شرکت‌ها می‌توان به «دیجیتال اوشن» (Digital Ocean)، «وب سرویس‌های آمازون» و Linode اشاره کرد. در مورد سرویس‌های وب آمازون به طور خاص باید به Amazon Elastic Beanstalk اشاره کرد، چون تا حدودی پیچیدگی AWS را کاهش داده است. از آنجا که این گزینه‌ها یک ماشین خالی لینوکس ارائه می‌کنند تا روی آن کار کنید، راهنمایی خاصی در مورد آن‌ها نمی‌توان ارائه کرد. در دسته سرورهای مجازی (VPS) گزینه‌های زیادی وجود دارند که می‌توان معرفی کرد و این موارد تنها شرکت‌های شاخص محسوب می‌شوند.

سرورهای فیزیکی: گزینه دیگری که می‌توان برای میزبانی اپلیکیشن Node.js استفاده کرد، این است که یک سرور فیزیکی را با نصب توزیعی از لینوکس پیکربندی کرده و به اینترنت وصل نمود.

شیوه استفاده از Node.js REPL

REPL اختصاری برای عبارت «Read-Evaluate-Print-Loop» (خواندن-ارزیابی-پرینت-حلقه) است و روشی عالی برای کاوش قابلیت‌های Node.js به طور سریع محسوب می‌شود. دستور node دستوری است که برای اجرای اسکریپت‌های Node.js استفاده می‌شود.

node script.js

اگر نام فایل را فراموش کنیم، می‌توانیم از روش REPL استفاده کنیم:

Node

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

❯ node
>

این دستور در حالت انتظار (idle) می‌ماند و منتظر وارد کردن مقدار دیگری است.

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

• دستورهای ترمینال سیستم عامل مک (macOS) — راهنمای مقدماتی
• ترمینال لینوکس و آنچه برای شروع به کار با آن باید بدانید
• آموزش خط فرمان (Command Line) ویندوز – راهنمای مقدماتی

در حالت فوق REPL منتظر می‌ماند تا نوعی کد جاوا اسکریپت را وارد کنید. برای شروع مقدار زیر را وارد کنید:

> console.log('test')
test
undefined
>

مقدار نخست یعنی test، آن خروجی است که از کنسول می‌خواهیم پرینت کند و سپس مقدار «تعریف نشده» (undefined) دریافت می‌کنیم که مقدار بازگشتی ()console.log است. اینک می‌توانیم خط جدیدی از کد جاوا اسکریپت وارد کنیم.

استفاده از tab برای تکمیل خودکار

نکته جالب در مورد REPL این است که تعاملی است. همچنان که کد را می‌نویسید؛ اگر کلید tab را بزنید، REPL تلاش خواهد کرد آن چه را که می‌نویسید تکمیل کند و با متغیری که قبلاً تعریف شده یا متغیر از قبل تعریف شده است تطبیق دهد.

کاوش اشیای جاوا اسکریپت

تلاش کنید نام کلاس جاوا اسکریپت مانند Number را وارد کنید و یک نقطه در انتهای آن وارد کرده و کلید tab را بزنید. در این زمان REPL همه مشخصه‌ها و متدهایی که روی کلاس وجود دارند را نمایش می‌دهد:

کاوش اشیای سراسری

امکان بازبینی اشیای سراسری با وارد کردن عبارت global. و فشردن کلید tab نیز وجود دارد:

متغیر خاص _

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

دستورهای نقطه (Dot)

REPL برخی دستورهای خاص دارد که همه آن‌ها با یک نقطه (Dot) شروع می‌شوند و فهرستی از آن‌ها به شرح زیر است:

• help. – این دستور راهنمای دستورهای نقطه را نمایش می‌دهد.
• editor. – امکان نوشتن کدهای چند خطی جاوا اسکریپت را به سهولت در اختیار ویرایشگر قرار می‌دهد. زمانی که در این حالت باشید با زدن کلیدهای Ctrl+D می‌توانید کدی را که نوشته‌اید اجرا کنید.
• break. – زمانی که یک عبارت چند خطی را وارد می‌کنید با تایپ دستور.break از ورودی بیشتر خارج می‌شوید و عملکردی مشابه فشردن کلیدهای Ctrl+C دارد.
• clear. – ساختار REPL را به صورت یک شیء خالی ریست می‌کند و هر عبارت چند خطی را که هم اینک وارد شده است پاک می‌سازد.
• load. – یک فایل جاوا اسکریپت را با آدرس نسبی با توجه به دایرکتوری کار فعلی بارگذاری می‌کند.
• save. – همه مواردی را که در نشست REPL وارد کرده‌اید در یک فایل ذخیره می‌کند (باید نام فایل را ذکر کنید).
• exit. – از repl خارج می‌شود (معادل فشردن دو بار کلیدهای Ctrl+C است).

REPL وقتی یک گزاره چند خطی را وارد می‌کنید، بدون نیاز به تایپ کردن دستور editor. این مسئله را می‌داند. برای نمونه، اگر شروع به تایپ کردن یک چرخه تکرار مانند زیر بکنید:

[1، 2، 3].forEach(num => {

و سپس کلید Enter را بزنید، REPL به یک خط جدید می‌رود و آن را با 3 نقطه آغاز می‌کند که نشان می‌دهد شما مشغول کار روی یک بلوک هستید.

... console.log(num)
... })

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

پذیرش آرگومان‌های خط فرمان توسط Node.js

در یک برنامه Node.js، برای دریافت آرگومان‌هایی که در خط فرمان وارد می‌شوند، می‌توانید آن‌ها را در زمان فراخوانی اپلیکیشن به صورت زیر ارسال کنید:

node app.js

آرگومان‌ها می‌توانند مستقل باشند و یا برای مثال مانند زیر کلید و مقدار داشته باشند:

node app.js Flavio

و یا به صورت زیر باشند:

node app.js name=Flavio

بدین ترتیب روش بازیابی این مقدار از کد Node.js تغییر پیدا می‌کند. روشی که برای بازیابی آن استفاده می‌کنیم، شیء process است که از متدهای درونی Node.js محسوب می‌شود. این متد یک مشخصه argv افشا می‌کند. argv آرایه‌ای است که شامل همه آرگومان‌های ارسالی از خط فرمان است. آرگومان نخست مسیر کامل دستور node است. عنصر دوم مسیر کامل فایلی است که اجرا خواهد شد. همه آرگومان‌های دیگر که از مکانی دیگر فوروارد می‌شوند در ادامه می‌آیند. می‌توان حلقه‌ای روی همه آرگومان‌ها (شامل نام فایل و مسیر node) تعریف کرد:

process.argv.forEach((val، index) => {
console.log(${index}: ${val})
})

دریافت صرفاً آرگومان‌های اضافی

می‌توان تنها آرگومان‌های اضافی را به دست آورد و به این منظور باید یک آرایه جدید که دو پارامتر نخست را حذف می‌کند ایجاد کرد:

const args = process.argv.slice(2)

اگر یک آرگومان بدون نام اندیس به صورت زیر داشته باشید:

node app.js Flavio

با استفاده از دستور زیر می‌توانید به آن دسترسی داشته باشید:

const args = process.argv.slice(2)
args[0]

در این حالت:

node app.js name=Flavio

[args[0 به صورت name=Flavio است و باید آن را تجزیه کنید. بهترین روش برای انجام این کار استفاده از کتابخانه minimist (+) است که متدهایی برای کار با آرگومان‌ها ارائه کرده است:

const args = require('minimist')(process.argv.slice(2))

args['name'] //Flavio

دریافت خروجی در خط فرمان با Node.js

روش پرینت موارد مختلف در کنسول خط فرمان با استفاده از Node.js، از یک متد ابتدایی console.log تا سناریوهای پیچیده‌تر متفاوت است.

خروجی ابتدایی با ماژول console

Node.js یک ماژول console دارد که روش‌های مفید زیادی برای تعامل با خط فرمان ارائه کرده است. این ماژول اساساً همان شیء console است که قبلاً در مرورگر دیده‌ایم. ساده‌ترین و پراستفاده‌ترین متد ()console.log نام دارد که یک رشته ارسالی را در کنسول پرینت می‌کند. اگر یک شیء ارسال شود، کنسول آن را به صورت رشته رندر می‌کند. امکان ارسال متغیرهای چندگانه به console.log به صورت زیر وجود دارد:

const x = 'x'
const y = 'y'
console.log(x، y)

در این حالت Node.js هر دوی آن‌ها را پرینت می‌کند. امکان قالب‌بندی عبارت‌ها در حالت pretty با ارسال متغیرها و یک قید قالب‌بندی مانند مثال زیر نیز وجود دارد:

console.log('My%s has%d years'، 'cat'، 2)

در کد فوق موارد زیر را باید توضیح دهیم:

• s% یک متغیر را به صورت رشته قالب‌بندی می‌کند.
• d% یا i% یک متغیر را به صورت یک عدد صحیح قالب‌بندی می‌کند.
• f% یک متغیر را به صورت عدد اعشاری قالب‌بندی می‌کند.
• o% یک بازنمایی از شیء را پرینت می‌کند.

مثال:

console.log('%O'، Number)

پاکسازی کنسول

دستور ()console.clear، کنسول را پاک می‌کند (البته رفتار آن وابسته به نوع کنسول مورد استفاده است).

شمارش عناصر

()console.count یک متد کارآمد است. این کد را در نظر بگیرید:

const x = 1
const y = 2
const z = 3

console.count(
   'The value of x is ' + x + ' and has been checked.. how many times?'
)

console.count(
   'The value of x is ' + x + ' and has been checked.. how many times?'
)

console.count(
   'The value of y is ' + y + ' and has been checked.. how many times?'
)

اتفاقی که در کد فوق می‌افتد این است که count تعداد دفعاتی که یک رشته پرینت می‌شود را می‌شمارد و تعداد را نیز پس از آن پرینت می‌کند. بدین ترتیب در مثال زیر تعداد سیب‌ها و پرتقال‌ها را می‌شماریم:

const oranges = ['orange'، 'orange']
const apples = ['just one apple']
oranges.forEach(fruit => {
   console.count(fruit)
})
apples.forEach(fruit => {
   console.count(fruit)   
})

پرینت رد پشته

ممکن است مواردی وجود داشته باشند که پرینت «رد پشته فراخوانی» (call stack trace) یک تابع مفید باشد و به یافتن پاسخ این پرسش کمک کند که: «چطور به این بخش از کد رسیده‌ایم؟»

پرینت رد پشته با استفاده از دستور ()console.trace به صورت زیر ممکن است:

const function2 = () => console.trace()
const function1 = () => function2()
function1()

این دستور رد پشته را پرینت می‌کند. برای نمونه اگر کد فوق را در Node REPL وارد کنیم، نتیجه زیر به دست می‌آید:

Trace
   at function2 (repl:1:33)
   at function1 (repl:1:25)
   at repl:1:1
   at ContextifyScript.Script.runInThisContext (vm.js:44:33)
   at REPLServer.defaultEval (repl.js:239:29)
   at bound (domain.js:301:14)
   at REPLServer.runBound [as eval] (domain.js:314:12)
   at REPLServer.onLine (repl.js:440:10)
   at emitOne (events.js:120:20)
   at REPLServer.emit (events.js:210:7)

محاسبه زمان صرف شده

می‌توان میزان زمانی که یک تابع طول کشیده اجرا شود را با استفاده از ()time و ()timeEnd به راحتی محاسبه کرد:

1 2 3 4 5 6 7 8

const doSomething = () => console.log('test') const measureDoingSomething = () => {   console.time('doSomething()')   //do something, and measure the time it takes   doSomething()   console.timeEnd('doSomething()') } measureDoingSomething()

stdout و stderr

همان‌طور که دیدیم console.log برای پرینت کردن پیام‌ها در کنسول کاملاً عالی است. این کار خروجی استاندارد یا stdout نام دارد. console.error در استریم stderr پرینت می‌کند. این مقدار در کنسول ظاهر می‌شود؛ اما در لاگ خطا قابل مشاهده است.

رنگی کردن خروجی

می‌توان خروجی متن را در کنسول با استفاده از یک دنباله escape رنگی کرد. دنباله escape به مجموعه‌ای از کاراکترها گفته می‌شود که برای مثال مانند زیر یک رنگ را شناسایی می‌کنند:

console.log('\x1b[33m%s\x1b[0m'، 'hi!')

این کد را می‌توان در Node REPL امتحان کرد و خروجی کار یک عبارت !hi با رنگ زرد خواهد بود.

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

این کتابخانه با دستور npm install chalk نصب می‌شود و به صورت زیر می‌توانید از آن استفاده کنید:

const chalk = require('chalk')
console.log(chalk.yellow('hi!'))

استفاده از chalk.yellow نسبت به تلاش برای به‌ خاطرسپاری کدهای escape بسیار آسان‌تر است و کد نیز خوانایی بیشتری پیدا می‌کند.

ایجاد یک نوار پیشرفت

Progress (+) نام یک پکیج جالب است که برای ایجاد نوار پیشرفت در کنسول استفاده می‌شود. آن را با استفاده از دستور زیر می‌توانید نصب کنید:

npm install progress

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

1 2 3 4 5 6 7 8

const ProgressBar = require('progress') const bar = new ProgressBar(':bar', { total: 10 }) const timer = setInterval(() => {   bar.tick()   if (bar.complete) {     clearInterval(timer)   } }, 100)

پذیرش ورودی از خط فرمان در Node.js

شاید تاکنون از خود پرسیده باشید چگونه می‌توان یک برنامه CLI در Node.js را به صورت تعاملی درآورد؟

Node از نسخه 7 خود به بعد ماژول readline (+) را برای اجرای کارهایی مانند دریافت ورودی از استریم قابل خواندن مانند استریم process.stdin عرضه کرده است که در طی اجرای برنامه Node همان ورودی ترمینال است و به صورت هر بار یک خط ورودی را دریافت می‌کند.

1 2 3 4 5 6 7 8

const readline = require('readline').createInterface({   input: process.stdin,   output: process.stdout }) readline.question(`What's your name?`, (name) => {   console.log(`Hi ${name}!`)   readline.close() })

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

متد ()question نخستین پارامتر (یک سؤال) را نمایش می‌دهد و منتظر ورودی کاربر می‌ماند. این متد در زمان فشرده شدن کلید enter یک تابع callback فراخوانی می‌کند. در این تابع callback اینترفیس readline را می‌بندیم.

readline چند متد دیگر نیز دارد که توصیه می‌کنیم مستندات آن‌ها را در صفحه‌ای که پیش‌تر معرفی کردیم بررسی کنید. اگر نیاز دارید که یک رمز عبور را الزام کنید، بهتر است آن را اینک مطرح کنید، اما آن را با استفاده از کاراکترهای * نمایش دهید. ساده‌ترین روش برای این کار، استفاده از پکیج readline-sync است که بر اساس API شباهت زیادی به readline دارد و این کار را به صورت خودکار انجام می‌دهد. این پکیج را می‌توان با استفاده از دستور زیر نصب کرد:

npm install inquirer

سپس کد فوق را به صورت زیر بازنویسی می‌کنیم:

1 2 3 4 5 6 7 8 9

const inquirer = require('inquirer') var questions = [{   type: 'input',   name: 'name',   message: "What's your name?", }] inquirer.prompt(questions).then(answers => {   console.log(`Hi ${answers['name']}!`) })

فایل Inquirer.js امکان انجام کارهای زیادی مانند پرسیدن سؤالات چندگانه، ارائه دکمه‌های رادیویی، تأییدیه‌ها و مواردی از این دست را می‌دهد.

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

ارائه کارکردهای یک فایل Node.js با استفاده از اکسپورت

Node.js یک سیستم ماژول داخلی با نام module.exports دارد که امکان استفاده از API داخلی و افشای داده‌ها به فایل دیگر در همان اپلیکیشن و یا حتی اپلیکیشن‌های دیگر را می‌دهد.

هر فایل Node.js می‌تواند کارکردهای افشا شده از سوی فایل‌های Node.js دیگر را ایمپورت کند. زمانی که می‌خواهید چیزی را برای استفاده خود ایمپورت کنید، باید از دستور زیر استفاده کنید:

const library = require('./library')

از دستور فوق می‌توان برای ایمپورت کردن کارکردهای افشا شده در فایل library.js که در پوشه کنونی قرار دارند استفاده کرد. در این فایل، هر کارکرد پیش از آن که بتواند از سوی فایل‌های دیگر ایمپورت شود، باید افشا شود. هر شیء یا متغیر تعریف شده در این فایل به صورت پیش‌فرض خصوصی است و در معرض دسترسی دنیای خارجی قرار ندارد. برای افشای یک کارکرد باید از API با نام module.exports استفاده کنیم که از سوی سیستم ماژول Node.js ارائه شده است.

ماژول exports

هنگامی که یک شیء یا تابع را به صورت یک مشخصه exports انتساب می‌دهید، این همان چیزی است که افشا می‌شود. بدین ترتیب می‌توان آن را در بخش‌های دیگر اپلیکیشن یا حتی اپلیکیشن‌های دیگر نیز ایمپورت کرد. این کار به دو روش قابل اجرا است. روش نخست این است که یک شیء را به module.exports انتساب می‌دهیم. module.exports به صورت آماده مصرف از سوی سیستم ماژول ارائه شده است و کار اکسپورت فایل را به آن شیء تبدیل می‌کند.

1 2 3 4 5 6 7

const car = {   brand: 'Ford',   model: 'Fiesta' } module.exports = car //..in the other file const car = require('./car')

روش دوم برای افزودن شیء اکسپورت شده به صورت یک مشخصه exports است. بدین ترتیب امکان اکسپورت شیءها، تابع‌ها یا داده‌های چندگانه وجود دارد:

1 2 3 4 5

const car = {   brand: 'Ford',   model: 'Fiesta' } exports.car = car

روش مستقیم نیز به صورت زیر است:

1 2 3 4

exports.car = {   brand: 'Ford',   model: 'Fiesta' }

در فایل دیگر نیز باید با ارجاع دادن به مشخصه ایمپورت خودتان از آن استفاده کنید:

1 2	const items = require('./items') items.car

روش دیگر نیز چنین است:

1	const car = require('./items').car

شاید بپرسید فرق بین module.exports و exports چیست؟ حالت نخست آن «شیء» را که به آن اشاره می‌کند افشا می‌کند. حالت دوم مشخصه‌های شیء مورد اشاره را افشا می‌کند. بدین ترتیب به پایان بخش دوم سری مقالات آموزش Node.js می‌رسیم. در بخش بعدی در مورد npm و روش نصب پکیج‌ها صحبت خواهیم کرد.

https://blog.faradars.org/node-js-tutorial-part-2/

آموزش ساخت یک اپلیکیشن آیفون (بخش چهارم) — به زبان ساده

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

برای مطالعه قسمت قبلی این مجموعه مطلب آموزشی می‌توانید روی این لینک کلیک کنید.

عنوان آیتم ناوبری

به Xcode بروید و گزینه Main.storyboard را اگر انتخاب نشده است، انتخاب کنید. طوری اسکرول کنید که صحنه News پدیدار باشد. روی آیتم ناوبری در صحنه News کلیک کنید تا انتخاب شود. اگر پنل Document Outline نیز در حالت نمایش است در این زمان خواهید دید که Navigation Item در آنجا نیز انتخاب شده است. در روی بوم نیز چنین وضعیتی وجود دارد.

اگر پنل Inspector در سمت راست فعال نباشد، روی دکمه انتهای سمت راست نوار ابزار کلیک کنید تا پدیدار شود. اینک می‌توانید Attributes Inspector را ببینید. اگر چنین نیست روی آیکون چهارم بالای پنل Inspector کلیک کنید تا به آن سوییچ شود.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

پنل Attributes Inspector همه خصوصیت‌های موجود (گاهی مشخصه نیز نامیده می‌شود) را برای شیء انتخاب شده کنونی نمایش می‌دهد. شما می‌توانید اغلب این موارد را تغییر دهید. در این مورد باید یک عنوان برای آیتم ناوبری انتخاب شده وارد کنیم.

در فیلد title در پنل Attributes Inspector عبارت News را وارد کرده و روی Return کلیک کنید. آیتم ناوبری روی بوم و همچنین بخش «دورنمای سند» اینک باید عنوانی به صورت News داشته باشد.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

نوار ناوبری

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

در کنترلر ناوبری برای صحنه News یک بار روی نوار ناوبری کلیک کنید تا انتخاب شود.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

همان طور که می‌بینید خصوصیت‌های زیادی برای نوار ناوبری وجود دارد. در حال حاضر ما تنها چند مورد از آن‌ها را بررسی می‌کنیم. روی منوی بازشدنی کنار Bar Text کلیک و گزینه custom را انتخاب کنید.

تغییر رنگ نوار ناوبری

Xcode گزینه «انتخاب رنگ» (Color Picker) را نمایش می‌دهد.

در نوار ابزار این بخش انتخاب رنگ، برگه Color Sliders که دارای آیکون اسلایدر و گزینه دوم از سمت چپ است را انتخاب کنید. در منوی بازشونده گزینه RGB Sliders را انتخاب کنید. مقدار رنگ را به صورت مقادیر زیر تعیین کنید:

• red = 208
• green = 16
• blue = 18

میزان «مات بودن» (Opacity) را نیز برابر با 100% تنظیم کنید. اینک می‌بینید که رنگ پس‌زمینه نوار ناوبری روی بوم تغییر یافته است.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

در این مرحله بخش انتخاب کننده رنگ را ببندید. اکنون که نوار ناوبری تیره داریم، متن تیره‌رنگ عنوان آیتم ناوبری و متن «نوار وضعیت» (Status Bar) کنتراست مناسبی ندارند. ما باید از Xcode بخواهیم که با نوار ناوبری به صورت یک شیء تیره رفتار کند تا رنگ این عناوین به صورت سفید درآید.

به این منظور منوی بازشدنی Style را برای نوار ناوبری به صورت Black تنظیم کنید. همزمان سبک عناوین بزرگ را انتخاب کنید تا با ظاهرتصویر ابتدای مقاله اول این سری که می‌خواهیم ایجاد کنیم مطابقت داشته باشد. در ادامه کادر انتخاب Prefers Large Titles را فعال کنید.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

اگر اپلیکیشن خود را به مثابه یک لِگو تصور کنیم، تنها کاری که انجام داده‌ایم این است که رنگ و ارتفاع نوار ناوبری را تغییر داده‌ایم. ساختار بلوک‌ها و لایه‌ها همچنان همان است. نوار ناوبری Large Titles باعث می‌شود که عناوین آیتم‌های ناوبری به جای مرکز در سمت چپ قرار بگیرند.

سلول نمای جدولی

در صحنه News می‌توان یک سلول خالی منفرد را زیر هدر بخش Prototype Cells مشاهده کرد. در ادامه می‌خواهیم محتوایی برای این بخش تعیین کنیم.

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

زمانی که سلول را به طرز صحیحی انتخاب کردید، همانند تصویر زیر باید عبارت Table View Cell را در بخش فوقانی Attributes Inspector ببینید.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

ما می‌خواهیم کاربر بتواند روی این سلول در صحنه News کلیک کند تا مقاله خبری مرتبط را در صحنه‌ای دیگر با جزییات بیشتر مشاهده کند. کاربر مورد نظر برای انجام این کار به نوعی راهنمایی نیاز دارد که به وی اشاره کنیم امکان تپ کردن روی سلول را دارد. استاندارد این کار «disclosure indicator» است که یک پیکان خاکستری با نوک اشاره کننده به سمت راست در سمت راست سلول است.

بدین ترتیب به سادگی می‌توان به سلول اعلام کرد که یک نشانگر disclosure را نمایش دهد و سلول می‌داند که باید یک «نمای فرعی» (subview) به نام accessory view در سمت راست سلول اضافه کند.

در بخش Attributes Inspector منوی بازشدنی Accessory را از مقدار None به Disclosure Indicator تغییر دهید.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

نشانگر Disclosure

این سلول هم اینک یک نشانگر Disclosure دارد که همان پیکان خاکستری است که به سمت راست اشاره می‌کند. به طور مشابه سلول نمای جدولی، چهار گزینه style دارد که به صورت خودکار نماهای فرعی برچسب را در سلول اضافه می‌کنند. سبک subtitle دو برچسب را به عنوان نمای فرعی در سمت چپ اضافه می‌کند.

در این زمان باید منوی بازشدنی Style را به صورت Subtitle تنظیم کنید. بدین ترتیب خواهید دید که برچسب‌های متنی خالی در سلول ظاهر می‌شوند. در صورتی که Content View را باز کنید، می‌بینید که در بخش دورنمای سند نیز این موارد قابل مشاهده هستند.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

روی برچسب Title در سلول دو بار کلیک کنید. اینک می‌بینید که برچسب با نوشته Label به صورت عنوان در پنل نمایش می‌یابد.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

اینک باید متن برچسب را تغییر دهیم. به این منظور می‌توانیم هم در بوم روی آن کلیک کنیم و هم در پنل Attributes inspector این کار را انجام دهیم. متن برچسب را از Title به Lego Block Chain تغییر دهید. این تیتر در واقع عنوان مقاله خبری خیالی ما است.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

به طور مشابه، متن برچسب Subtitle را انتخاب کرده و برخی جزییات را برای مقاله خبری اضافه کنید.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

نمای جدولی استاتیک

اگر اپلیکیشن خودمان را در این مرحله اجرا کنیم، سلول‌ها علی‌رغم این که عناوین و تیترهای مختلفی را در آن‌ها وارد کرده‌ایم، همچنان خالی مشاهده می‌شوند. دلیل این امر آن است که نمای جدولی هم اینک روی حالت «پروتوتایپ‌های دینامیک» (dynamic prototypes) تنظیم شده است. این بدان معنی است که نمای جدولی انتظار دارد مقادیر هر سلول به صورت دینامیک و احتمالاً از طریق ارتباط با یک سرور خبری پر شوند. ما در حال حاضر هیچ کد یا حتی سروری در این زمینه نداریم و از این رو قصد داریم جدول را به صورت محتوای استاتیک تنظیم کنیم.

به این منظور در صحنه News یک بار روی ناحیه خاکستری Table View —Prototype Content پایین سلول کلیک کنید. اینک پنل Attributes Inspector باید عنوان Table View را نمایش دهد. منوی بازشدنی Content را از Dynamic Prototypes به Static Cells تغییر دهید.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

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

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

یک بار روی سلول سوم کلیک کنید. با بررسی این که دستگیره انتخاب در لبه انتهایی سلول سوم مشاهده می‌شود و این که عنوان پنل Attributes Inspector به صورت Table View Cell درآمده است، مطمئن شوید که این سلول انتخاب شده است.

جهت نمایش تصویر در ابعاد اصلی روی آن کلیک کنید.

این سلول را با فشردن کلید Delete کیبورد، حذف کنید.

نتیجه نهایی

اپلیکیشن را اجرا کنید تا آنچه را تا به اینجا طراحی کرده‌ایم، مشاهده کنید.

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

کامیت کردن تغییرات

برای کامیت کردن تغییرات همانند دفعات قبل مراحل زیر را اجرا می‌کنیم:

1. از منوی Source Control گزینه Commit Changes را انتخاب کنید.
2. یک توضیح مانند آنچه در ادامه آمده است، برای کامیت وارد کنید:

News: customised attributes in navigation bar، navigation item، table view and cells.

3. روی دکمه Commit کلیک کنید.

جمع‌بندی

در این بخش از سری مقالات راهنمای ساخت اپلیکیشن آیفون که قسمت چهارم آن است از پنل Attributes Inspector برای سفارشی‌سازی نوار ناوبری، آیتم ناوبری، نمای جدولی و سلول‌های آن استفاده کردیم. هر گونه سؤال یا دیدگاه مرتبط با این نوشته را می‌توانید در بخش نظرات با ما در میان بگذارید. در بخش بعدی بحث ناوبری اپلیکیشن خود را تکمیل می‌کنیم. برای مطالعه بخش بعدی روی لینک زیر کلیک کنید:

https://blog.faradars.org/build-iphone-app-tutorial-4/

دیباگ کردن Node.js با ویژوال استودیو کد — راهنمای کاربردی

واقعیت این است که دیباگ کردن Node.js همواره کار دشواری است. اگر تاکنون فرصت کدنویسی یک پروژه در Node.js را داشته‌اید، می‌دانید که یافتن منشأ خطا در این نوع کدها و در نتیجه دیباگ Node.js پیچیدگی و دردسر فراوانی به همراه دارد.

برخلاف کدهای جاوا اسکریپت که در مرورگر دیباگ می‌شوند و یا کدهای جاوا که با استفاده از یک IDE قوی مانند IntelliJ بررسی می‌شوند، در Node.js امکان تعیین «نقاط توقف» (breakpoint) در نقاط دلخواه، رفرش کردن صفحه یا راه‌اندازی مجدد کامپایلر و بررسی گام به گام کد، ارزیابی توابع و یافتن متغیر عوض شده یا مفقود وجود ندارد. همین ناتوانی است که موجب دشواری دیباگ کدهای Node.js شده است.

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

گزینه‌های دیباگ کردن Node.js

چند روش برای دیباگ برنامه‌های مشکل‌دار Node.js وجود دارد که در ادامه آن‌ها را فهرست‌بندی کرده‌ایم و لینک‌های مربوطه را نیز در صورت نیاز به مطالعه بیشتر ارائه کرده‌ایم.

()Console.log

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

معادل این ابزار در جاوا ()System.out.println و در پایتون ()print نام دارد. ابزار یاد شده ساده‌ترین روش برای پیاده‌سازی دیباگ است و همچنین سریع‌ترین روش برای آلوده کردن کدهای تمیز به خطوطی از اطلاعات اضافی محسوب می‌شود. به هر حال این روش در برخی موارد به یافتن و اصلاح خطا کمک می‌کند.

مستندات Node.js

مستندات Node.js نیز درک کرده است که دیباگ کردن کدها کار آسانی نیست و از این رو یک مرجع کارآمد (+) برای کمک به شروع دیباگ ارائه کرده است.

این ابزار مفید است؛ اما اگر صادقانه سخن بگوییم رمزگشایی از آن به جز برای کسانی که تجربه زیادی در کدنویسی دارند کار دشواری محسوب می‌شود. بدین ترتیب ممکن است به سرعت در دام مباحثی چون UUID-ها، وب‌سوکت‌ها و «عوارض امنیتی» بیافتید و دچار سرگیجه شوید. در واقع بهتر بود که در این زمینه از روش غیر پیچیده‌تری استفاده می‌شد.

Chrome DevTools

بخش ابزارهای توسعه‌دهنده در مرورگر کروم امکان دیباگ کردن کدهای Node.js را فراهم می‌سازد که به ظاهر روش ساده‌ای محسوب می‌شود، اما اگر می‌خواهید این روش را بیازمایید، ممکن است متوجه شوید که نیم ساعت سپری شده است و هنوز نتوانسته‌اید پنجره DevTools را به برنامه Node وصل کنید. به هر حال به نظر می‌رسد استفاده از Chrome DevTools برای دیباگ کدهای Node.js پیچیده‌تر از آن است که باید باشد.

JetBrains

JetBrains  یکی از شرکت‌های محبوب توسعه نرم‌افزار است که IDE-هایی مانند IntelliJ و WebStorm را عرضه کرده است. این شرکت اکوسیستم جالبی از افزونه‌ها برای ابزارهای خود ارائه کرده است.

به لطف جامعه گسترده کاربران JetBrains، مقالات زیادی در حوزه‌های متفاوت و از جمله دیباگ کردن کدهای Node.js نوشته شده است. اما این مورد نیز همچون مستندات Node و Chrome DevTools آسان نیست. کاربر در این روش باید پیکربندی‌های زیادی انجام دهد، پردازش‌های اجرایی را الحاق کند و همچنین «ترجیحات» (Preferences) را به مقدار زیادی پیکربندی کند تا WebStorm آماده دیباگ کردن شود.

ویژوال استودیو کد (Visual Studio Code)

این گزینه یکی از ساده‌ترین روش‌های دیباگ کردن کدهای Node.js را ارائه کرده است. هر کسی که VS Code را یک بار تجربه کرده، عاشق آن شده است.

VS Code کاری را که هیچ کدام از گزینه‌های دیگر در خصوص دیباگ کردن کدهای Node.js موفق به انجام نشدند، اجرایی کرده و آن را به فرایندی کاملاً ساده تبدیل کرده است. دیباگ کردن با استفاده از VS Code چنان ساده است که هر کسی می‌تواند آن را به سرعت راه‌اندازی و اجرا کند و مهم نیست که چه میزان از آشنایی با IDE-ها، Node و یا برنامه‌نویسی دارد.

تنظیم ویژوال استودیو کد برای دیباگ کردن کدهای Node.js

در این بخش اقدام به تنظیم VS Code و دیباگ کردن Node.js می‌کنیم. به این منظور، می‌بایست قبلاً VS Code را دانلود (+) و نصب کرده باشید. بنابراین در ادامه شروع به تنظیم آن می‌کنیم.

در نرم‌افزار VS Code به بخش Preferences > Settings بروید و در کادر جستجو عبارت node debug را وارد کنید. زیر برگه Extensions یک اکستنشن با عنوان «Node debug» ظاهر می‌شود. در اینجا روی کادر نخست Debug > Node: Auto Attach کلیک کرده و منوی بازشدنی را روی on تنظیم کنید. اینک آماده شروع به کار هستیم.

جهت مشاهده تصویر در اندازه اصلی روی آن کلیک کنید.

اکنون به فایل پروژه Node.js خود بروید و با کلیک کردن روی سمت چپ فایل در هر جایی که دوست دارید برخی نقاط توقف را تنظیم کنید. سپس در ترمینال عبارت node –inspect <FILE NAME> را وارد کنید تا عملکرد آن را مشاهده کنید.

جهت مشاهده تصویر در ابعاد اصلی روی آن کلیک کنید.

دیباگ با VS Code در عمل

اگر به یک پروژه Node.js نیاز دارید که این موارد را تست کنید می‌توانید این پروژه (+) را دانلود کنید. این پروژه جهت تست کردن شکل‌های مختلف استریم کردن مقادیر بالایی از داده در Node ساخته شده است؛ اما در این دموی ما نیز به خوبی کار می‌کند. زمانی که کلید Enter را بزنید. بخش انتهایی ترمینال VS Code به رنگ نارنجی در می‌آید تا نشان دهد که در حالت دیباگ هستید. کنسول نیز پیامی را مبنی بر الحاق دیباگر (‘Debugger Attached’) نمایش می‌دهد.

جهت مشاهده تصویر در ابعاد اصلی روی آن کلیک کنید.

زمانی که این وضعیت را مشاهده کردید، بدانید که موفق به دیباگ کردن کدهای Node.js در VS Code شده‌اید.

تنظیم نقاط توقف

اینک می‌توانید نقاط توقف را در گوشه پایین-چپ صفحه مشاهده کنید. امکان فعال و غیرفعال کردن آن‌ها نیز با انتخاب کادر مربوطه وجود دارد. بدین ترتیب امکان اجرای خط به خط کد و گزینه‌های step over ،step in ،restart و غیره، همانند زمانی که با استفاده از دکمه Play کوچک در مرورگر اجرا می‌کردید وجود خواهد داشت. به این منظور باید از دکمه‌های بخش میانی و بالای IDE استفاده کنید. VS Code نقاط توقف و خطی را که کد در آن متوقف شده است هایلایت می‌کند تا پیگیری فرایند کار، آسان باشد.

جهت مشاهده تصویر در ابعاد اصلی روی آن کلیک کنید.

زمانی که با استفاده از دکمه‌های فوق از یک نقطه توقف به نقطه توقف بعدی حرکت می‌کنید می‌توانید ببینید که برنامه موارد console.log را در کنسول دیباگ در بخش تحتانی ویژوال استودیو کد پرینت می‌کند و با حرکت به سمت جلو با رنگ زرد هایلایت می‌شود.

جهت مشاهده تصویر در ابعاد اصلی روی آن کلیک کنید.

همان طور که می‌بینید هر چه در برنامه پیش می‌رویم مواردی که در کنسول دیباگ به نمایش در می‌آیند افزایش می‌یابند و در طی این مسیر می‌توان اشیا و تابع‌ها را در دامنه محلی با استفاده از ابزارهای گوشه چپ-بالای VS Code دقیقاً همانند روش بررسی موارد مشابه در مرورگر بررسی کرد.

نتیجه‌گیری

دیباگ کردن Node.js به لطف VS Code دیگر مانند گذشته دشوار نیست و لازم نیست 500 بار ()console.log را در کد خود تکرار کنیم تا بفهمیم که باگ کجا هست. گزینه Debug > Node ویژوال استودیو کد به کمک روش الحاق خودکار پردازش این وضعیت را دگرگون ساخته است.

https://blog.faradars.org/easiest-way-to-debug-node-js-with-vscode/

بوکه (Bokeh) — از صفر تا صد

«بوکه» (Bokeh)، کتابخانه‌ای برای بصری‌سازی تعاملی داده‌ها است. برخلاف دیگر کتابخانه‌های موجود برای بصری‌سازی داده‌ها در «زبان برنامه‌نویسی پایتون»، مانند «مَت‌پلات‌لیب» (Matplotlib) و «سی‌بورن» (Seaborn)، بوکه گرافیک‌های خود را با استفاده از «اچ‌تی‌ام‌ال» (HTML) و «جاوا اسکریپت» (JavaScript) رندر می‌کند. این موضوع موجب شده تا بوکه به گزینه‌ای مناسب برای ساخت دشبوردها و اپلیکیشن‌های مبتنی بر وب مبدل شود. به طور کلی باید گفت، کتابخانه بوکه ابزاری قدرتمند برای اکتشاف و درک داده‌ها یا ساخت نمودارهای زیبا برای پروژه‌ها و گزارش‌ها است. هدف از این راهنما آن است که روش کار با کتابخانه بوکه با بهره‌گیری از مجموعه داده‌های جهان واقعی، آموزش داده شود. سرفصل‌های زیر در این مطلب ارائه شده‌اند.

• تبدیل داده‌ها به بصری‌سازی با استفاده از کتابخانه Bokeh
• سفارشی‌سازی و مرتب‌سازی بصری‌سازی‌ها
• افزودن قابلیت تعامل به بصری‌سازی‌ها

از داده تا بصری‌سازی

ساخت خروجی‌های بصری با استفاده از کتابخانه بوکه (Bokeh) شامل گام‌های زیر می‌شود:

• آماده‌سازی داده‌ها
• تعیین محل بصری‌سازی‌ها (روش رندر)
• انتخاب اَشکال (Figures)
• کار با داده‌ها و ترسیم آن‌ها
• سازمان‌دهی قالب‌ها
• پیش‌نمایش و ذخیره خروجی‌ها

اکنون، هر یک از مراحل بیان شده در بالا، همراه با جزئیات بیشتر مورد بررسی قرار می‌گیرد.

آماده‌سازی داده‌ها

بصری‌سازی داده‌ها همیشه با داده‌های ورودی آغاز می‌شود. در این گام معمولا از کتابخانه‌های «پیش‌پردازش» (Preprocessing)داده‌ها مانند «پانداس» (Pandas) و «نام‌پای» (NumPy) استفاده می‌شود و طی آن، گام‌های مورد نیاز برای تبدیل داده‌ها به فرم مناسب برای انجام پردازش‌ها، برداشته می‌شود.

تعیین محل بصری‌سازی‌ها

در این گام، چگونگی تولید و نمایش بصری‌سازی‌ها، به وسیله کاربر تعیین می‌شود. در این راهنما، دو گزینه متداولی که بوکه در این راستا فراهم می‌کند ارائه شده‌اند که عبارتند از: تولید یک فایل HTML استاتیک و رندر کردن بصری‌سازی‌ها به صورت خطی در «ژوپیتر نوت‌بوک» (Jupyter Notebook).

انتخاب اَشکال

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

کار با داده‌ها و ترسیم آن‌ها

اکنون، از قابلیت رندر کردن بوکه برای شکل دادن به داده‌ها استفاده می‌شود. در این فاز، باید از انعطاف‌پذیری موجود برای ترسیم داده‌ها از پایه با استفاده از اشکال و نشانه‌گرهای متعدد موجود استفاده کرد؛ همه این موارد به سادگی قابل سفارشی‌سازی هستند. این عملکرد، آزادی فوق‌العاده‌ای را جهت ارائه داده‌ها در اختیار کاربر قرار می‌دهد. علاوه بر موارد بیان شده، بوکه دارای توابع توکاری برای ساخت چیزهایی مانند «نمودار میله‌ای تجمعی» (Stacked Bar Charts) و قابلیت‌هایی برای ساخت بصری‌سازی‌های پیشرفته‌تر مانند گراف‌های شبکه و نقشه‌ها است.

سازمان‌دهی قالب

بوکه، برای افرادی که نیاز به بیش از یک تصویر برای تشریح داده‌های خود دارند نیز ابزاری مناسب محسوب می‌شود. این کتابخانه، نه فقط گزینه‌های «قالب» (layout) شبکه مانند استاندارد را فراهم می‌کند، بلکه این امکان را برای کاربر فراهم می‌کند تا به سادگی بصری‌سازی‌ها را  با تنها با چند خط کد در یک قالب قرار دهد. علاوه بر آن، نمودارها را می‌توان به سرعت به یکدیگر لینک کرد؛ بنابراین، انتخاب یکی از نمودارها، بر کلیه نمودارهای دیگر (هر ترکیبی از دیگر گزینه‌ها) نیز تاثیرگذار است.

پیش‌نمایش و ذخیره خروجی‌ها

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31

"""Bokeh Visualization Template   This template is a general outline for turning your data into a visualization using Bokeh. """ # Data handling import pandas as pd import numpy as np   # Bokeh libraries from bokeh.io import output_file, output_notebook from bokeh.plotting import figure, show from bokeh.models import ColumnDataSource from bokeh.layouts import row, column, gridplot from bokeh.models.widgets import Tabs, Panel   # Prepare the data   # Determine where the visualization will be rendered output_file('filename.html')  # Render to static HTML, or output_notebook()  # Render inline in a Jupyter Notebook   # Set up the figure(s) fig = figure()  # Instantiate a figure() object   # Connect to and draw the data   # Organize the layout   # Preview and save show(fig)  # See what I made, and save if I like it

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

ساخت اولین تصویر با کتابخانه بوکه

راهکارهای متعددی برای ارائه خروجی بصری از داده‌ها در کتابخانه «بوکه» (Bokeh) وجود دارد. در این راهنما، گزینه‌های معرفی شده در زیر مورد استفاده قرار می‌گیرند.

• (‘output_file(‘filename.html: بصری‌سازی‌ها را روی یک فایل HTML استاتیک می‌نویسد.
• ()output_notebook بصری‌سازی‌ها را به طور مستقیم در «ژوپیتر نوت‌بوک» رندر می‌کند.

شایان ذکر است که هیچ یک از دو تابع بالا بصری‌سازی‌ها را به کاربر نمایش نمی‌دهند. در واقع این اتفاق مادامی که ()show فراخوانی نشده نمی‌افتد. اگرچه، این توابع اطمینان حاصل می‌کنند که در صورت فراخوانی ()show، بصری‌سازی‌ها به گونه‌ای نمایش داده می‌شود که کاربر تمایل دارد. با فراخوانی هم‌زمان ()output_file و ()output_notebook در یک اجرای واحد، بصری‌سازی هم روی فایل HTML استاتیک و هم روی نوت‌بوک به صورت توکار انجام می‌شود. اگر به هر دلیلی کاربر چند دستور ()output_file را به طور هم‌زمان اجرا کند، تنها آخرین دستور برای رندر کردن مورد استفاده قرار می‌گیرد. اکنون، فرصت خوبی فراهم شده تا کد اولیه در ()figure پیش‌فرض بوکه با استفاده از ()output_file نوشته شود.

1 2 3 4 5 6 7 8 9 10 11 12 13

# Bokeh Libraries from bokeh.io import output_file from bokeh.plotting import figure, show   # The figure will be rendered in a static HTML file called output_file_test.html output_file('output_file_test.html',             title='Empty Bokeh Figure')   # Set up a generic figure() object fig = figure()   # See what it looks like show(fig)

برای مشاهده تصویر با ابعاد اصلی روی آن کلیک کنید.

همانطور که مشهود است، یک پنجره جدید مرورگر باز شده که به آن Empty Bokeh Figure و empty figure گفته می‌شود. آنچه در تصویر مشهود نیست و در پشت صحنه به وقوع می‌پیوندد، ساخته شدن فایلی با نام output_file_test.html در پوشه کاری جاری کاربر است. اگر کاربر قصد داشته باشد که قطعه کدی مشابه با ()output_notebook را به جای ()output_file اجرا کند، با این فرض که Jupyter Notebook در حال اجرا است می‌تواند از قطعه کد زیر استفاده کند.

1 2 3 4 5 6 7 8 9 10 11 12

# Bokeh Libraries from bokeh.io import output_notebook from bokeh.plotting import figure, show   # The figure will be right in my Jupyter Notebook output_notebook()   # Set up a generic figure() object fig = figure()   # See what it looks like show(fig)

برای مشاهده تصویر در ابعاد اصلی روی آن کلیک کنید.

همانطور که مشهود است، نتایج مشابه هستند و صرفا رندر کردن در محل‌های متفاوتی به وقوع پیوسته است. اطلاعات بیشتر پیرامون ()output_file و ()output_notebook در مستندات رسمی بوکه (+) موجود است. نکته شایان توجه آن است که گاهی هنگام رندر کردن چندین بصری‌سازی به ترتیب، مشاهده می‌شود که رندرهای قبلی مربوط به اجراهای پیشین پاک نشده‌اند. در صورت مواجه شدن با چنین شرایطی، می‌توان کد زیر را «وارد» (Import) و در میان اجراها اجرا کرد.

1 2 3 4 5

# Import reset_output (only needed once) from bokeh.plotting import reset_output   # Use reset_output() between subsequent show() calls, as needed reset_output()

پیش از ادامه دادن این مطلب، لازم به ذکر است که بوکه به طور پیش‌فرض با یک جعبه ابزار از پیش بارگذاری شده می‌آید. اطلاعات بیشتر پیرامون این جعبه ابزار و چگونگی پیکربندی آن در بخش افزودن تعامل، در پایان این راهنما ارائه شده است.

آماده‌سازی اولین شکل برای داده‌ها

اکنون که چگونگی ساخت و نمایش یک تصویر کلی بوکه هم در مرورگر و هم در ژوپیتر نوت‌بوک آموزش داده شد، زمان آن رسیده تا بیشتر پیرامون چگونگی پیکربنی شی ()figure توضیح داده شود. شی ()figure فقط پایه بصری‌سازی داده‌ها نیست، بلکه شیئی است که ابزارهای بوکه برای بصری‌سازی داده‌ها را قفل‌گشایی می‌کند. figure در بوکه یک زیرکلاس از «Bokeh Plot Object» است که پارامترهای زیادی را برای پیکربندی عناصر زیبایی‌شناختی شکل فراهم می‌کند. برای درک بهتر این مطلب، در ادامه زشت‌ترین تصویر ممکن با قطعه کد زیر ساخته می‌شود.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

# Bokeh Libraries from bokeh.io import output_notebook from bokeh.plotting import figure, show   # The figure will be rendered inline in my Jupyter Notebook output_notebook()   # Example figure fig = figure(background_fill_color='gray',              background_fill_alpha=0.5,              border_fill_color='blue',              border_fill_alpha=0.25,              plot_height=300,              plot_width=500,              h_symmetry=True,              x_axis_label='X Label',              x_axis_type='datetime',              x_axis_location='above',              x_range=('2018-01-01', '2018-06-30'),              y_axis_label='Y Label',              y_axis_type='linear',              y_axis_location='left',              y_range=(0, 100),              title='Example Figure',              title_location='right',              toolbar_location='below',              tools='save')   # See what it looks like show(fig)

هنگامی که شی ()figure معرفی شد، می‌توان آن را پیکربندی کرد. اکنون، فرض می‌شود که کاربر می‌خواهد خطوط شبکه‌ای را حذف کند. برای این کار می‌توان از قطعه کد زیر استفاده کرد.

1 2 3 4 5

# Remove the gridlines from the figure() object fig.grid.grid_line_color = None   # See what it looks like show(fig)

مشخصات خطوط شبکه‌ای از طریق خصیصه grid شکل در دسترس هستند. در این مثال، تنظیم grid_line_color روی None، به شکل موثری همه خطوط شبکه‌ای را به صورت یکباره حذف می‌کند.

نکته: اگر کاربر در نوت‌بوک یا «محیط توسعه یکپارچه» (Integrated Development Environment | IDE) با قابلیت «تکمیل خودکار» (auto-complete) کار می‌کند، می‌تواند از مزایای قابل توجه آن استفاده کند. ()figure دارای عناصر قابل سفارشی‌سازی متعددی است و قابلیت تکمیل خودکار برای کشف گزینه‌های موجود برای سفارشی‌سازی بسیار مفید محسوب می‌شود.

در صورتی که محیط توسعه مورد استفاده کاربر دارای قابلیت تکمیل خودکار نیست، انجام یک جست‌و‌جوی سریع، با کلیدواژه Bokeh و آنچه که کاربر قصد دارد انجام دهد، معمولا او را به مسیر صحیحی هدایت می‌کند. مطالب بسیار زیادی برای آموزش دادن در همین رابطه وجود دارند، اما ورود بیش از حد به جزئیات، این مطلب را از هدف اصلی آن دور می‌کند. برای مطالعه بیشتر در این رابطه، می‌توان از موارد زیر استفاده کرد.

• Bokeh Plot Class (+): سوپرکلاسی از شی ()figure است که شکل‌ها از آن خصیصه‌های زیادی را به ارث می‌برند.
• The Figure Class (+): محل خوبی برای پیدا کردن جزئیات بیشتر پیرامون آرگومان‌های شی ()figure است.

در ادامه، برخی از گزینه‌های سفارشی‌سازی خاصی که فراگیری آن‌ها ارزشمند است بیان شده‌اند.

• Text Properties (+): همه خصیصه‌های مربوط به تغییر استایل، سایز، رنگ و دیگر موارد مربوط به «قلم» (Font) در این قسمت تحت پوشش قرار می‌گیرند.
• TickFormatters (+): اشیا توکاری هستند که برای قالب‌بندی محورها استفاده می‌شوند. نحو مورد استفاده برای انجام این کار، مشابه با نحو پایتون برای قالب‌بندی رشته‌ها است.

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

ترسیم داده‌ها با Glyphs

یک شکل خالی، مساله جذاب و قابل توجهی نیست؛ بنابراین در ادمه به بررسی glyphs که بلوک سازنده بصری‌سازی‌های Bokeh است پرداخته می‌شود. glyph یک شکل گرافیکی برداری‌سازی شده یا «نشانگری» (Marker) است که برای ارائه داده‌ها در اشکالی مانند یک دایره یا مربع مورد استفاده قرار می‌گیرد. مثال‌های بیشتر در این رابطه در گالری بوکه (+) موجود هستند. پس از ساخت شکل، باید به دسته‌ای از متدهای قابل پیکربندی glyph دسترسی داده شود. اکنون، کار با یک مثال بسیار پایه‌ای آغاز می‌شود که طی آن چندین نقطه روی یک دستگاه مختصات x-y ترسیم می‌شوند.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

# Bokeh Libraries from bokeh.io import output_file from bokeh.plotting import figure, show   # My x-y coordinate data x = [1, 2, 1] y = [1, 1, 2]   # Output the visualization directly in the notebook output_file('first_glyphs.html', title='First Glyphs')   # Create a figure with no toolbar and axis ranges of [0,3] fig = figure(title='My Coordinates',              plot_height=300, plot_width=300,              x_range=(0, 3), y_range=(0, 3),              toolbar_location=None)   # Draw the coordinates as circles fig.circle(x=x, y=y,            color='green', size=10, alpha=0.5)   # Show plot show(fig)

پس از معرفی ()figure، می‌توان دید که چگونه می‌توان از آن برای ترسیم داده‌ها در دستگاه مختصات x-y با استفاده از glyph‌های circle سفارشی‌سازی شده استفاده کرد. در ادامه برخی از دسته‌های glyph معرفی شده‌اند.

• Marker شامل اشکالی مانند دایره، لوزی، مربع و مثلث است و برای ساخت بصری‌سازی‌هایی مانند «نمودارهای نقطه‌ای» (Scatter chart)و «نمودار حبابی» (Bubble chart) مفید محسوب می‌شود.
• Line مواردی مانند اشکال تک‌خطی، خطی پله‌ای و چندخطی را شامل می‌شود که می‌توان از آن‌ها برای ساخت نمودارهای خطی استفاده کرد.
• Bar/Rectangle اشکالی هستند که برای ساخت نمودارهای میله‌ای سنتی یا پشته‌ای (hbar)، ستونی (vbar)، آبشاری و  «گانت» (gantt)مورد استفاده قرار می‌گیرند.

glyph‌ها را می‌توان ترکیب کرد تا قابلیت‌های لازم برای بصری‌سازی تامین شوند. اکنون فرض می‌شود که هدف ساخت تصویری است که تعداد کلمات نوشته شده در هر روز برای ساخت این راهنما را با یک خط نشانگر روند رشد تعداد کلمات (روزانه و تجمعی) نشان دهد.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36

import numpy as np   # Bokeh libraries from bokeh.io import output_notebook from bokeh.plotting import figure, show   # My word count data day_num = np.linspace(1, 10, 10) daily_words = [450, 628, 488, 210, 287, 791, 508, 639, 397, 943] cumulative_words = np.cumsum(daily_words)   # Output the visualization directly in the notebook output_notebook()   # Create a figure with a datetime type x-axis fig = figure(title='My Tutorial Progress',              plot_height=400, plot_width=700,              x_axis_label='Day Number', y_axis_label='Words Written',              x_minor_ticks=2, y_range=(0, 6000),              toolbar_location=None)   # The daily words will be represented as vertical bars (columns) fig.vbar(x=day_num, bottom=0, top=daily_words,          color='blue', width=0.75,          legend='Daily')   # The cumulative sum will be a trend line fig.line(x=day_num, y=cumulative_words,          color='gray', line_width=1,          legend='Cumulative')   # Put the legend in the upper left corner fig.legend.location = 'top_left'   # Let's check it out show(fig)

برای ترکیب ستون‌ها و خط‌ها در شکل، این موارد با استفاده از شی ()figure ساخته شده‌اند. علاوه بر آن، می‌توان مشاهده کرد که با تنظیمات legend برای هر glyph چگونه می‌توان راهنمای نمودار را به صورت یکپارچه ترسیم کرد. راهنمای نقشه نیز با تخصیص «top_left» به «fig.legend.location» به گوشه بالا و سمت راست نمودار انتقال داده می‌شود.

نگاهی کوتاه به داده‌ها

کتابخانه بصری‌سازی بوکه فرصت خوبی را برای کار با داده‌های گوناگون فراهم می‌کند. جذابیت Bokeh در آن است که تقریبا پیاده‌سازی هر ایده بصری‌سازی با آن امکان دارد و این موضوع فقط به چگونگی استفاده از ابزارهایی که در اختیار کاربر قرار داده بستگی دارد. در مثالی که در ادامه به آن پرداخته می‌شود از مجموعه داده‌های عمومی Kaggle که مربوط به ۷۲ فصل از مسابقات بسکتبال اتحادیه ملی بسکتبال آمریکا ( the National Basketball Association’s (NBA) 2017-18 season) هستند، استفاده شده است.

• 2017-18_playerBoxScore.csv (+): آمارهای بازیکنان به صورت بازی به بازی
• 2017-18_teamBoxScore.csv (+): آمارهای تیم به صورت بازی به بازی
• 2017-18_standings.csv (+): جدول رده‌بندی و امتیازات روزانه

پس از دانلود مجموعه داده، با استفاده از قطعه کدی که در ادامه آمده، داده‌ها در دیتافریم کتابخانه «پانداس» (Pandas) خوانده می‌شوند.

1 2 3 4 5 6

import pandas as pd   # Read the csv files player_stats = pd.read_csv('2017-18_playerBoxScore.csv', parse_dates=['gmDate']) team_stats = pd.read_csv('2017-18_teamBoxScore.csv', parse_dates=['gmDate']) standings = pd.read_csv('2017-18_standings.csv', parse_dates=['stDate'])

این قطعه کد داده‌ها را از سه فایل CSV خوانده و به صورت خودکار ستون‌های داده‌ را به صورت اشیا datetime تفسیر می‌کند. اکنون زمان آن رسیده که روی داده‌های واقعی کار شود.

استفاده از شی ColumnDataSource

در مثال بالا از لیست‌های پایتون و آرایه‌های «نام‌پای» (Numpy Arrays) برای نمایش داده‌ها استفاده شده است. کتابخانه «بوکه» (Bokeh) برای مدیریت این نوع داده‌ها به خوبی تجهیز شده است. اگرچه، هنگامی که بحث داده‌ها در پایتون می‌شود، احتمال استفاده از دیکشنری‌ها و دیتافریم‌های پانداس نیز وجود دارد، به ویژه اگر داده‌ها از یک فایل یا منبع داده خارجی خوانده می‌شوند. Bokeh برای کار با این ساختارهای داده پیچیده‌تر توانمند و حتی دارای توابع توکاری برای مدیریت آن‌ها است؛ به عنوان مثالی از این توابع می‌توان به ColumnDataSource اشاره کرد.

اکنون، امکان دارد این پرسش مطرح شود که «اگر Bokeh دارای رابطی برای کار با داده‌ها به صورت مستقیم است چرا از ColumnDataSource استفاده شود؟». اولا، هنگامی که به یک لیست، آرایه یا دیتافریم به طور مستقیم ارجاع داده می‌شود، بوکه در پشت صحنه به هر حال آن را به یک ColumnDataSource تبدیل می‌کند. دوم و مهم‌تر آنکه، ColumnDataSource پیاده‌سازی قابلیت‌های تعاملی بوکه را ساده‌تر می‌سازد.

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

• Python dict: «کلیدها» (keys)، اسامی مرتبط با توالی‌های مربوطه هستند (لیست‌ها، آرایه‌ها و به همین ترتیب).
• DataFrame پانداس: ستون‌های DataFrame، اسامی مرجع برای ColumnDataSource هستند.
• groupby در پانداس: ستون‌های ColumnDataSource را به شکل دیده شده با فراخوانی ()groupby.describe ارجاع می‌دهند.

اکنون، کار با بصری‌سازی مسابقات برای جایگاه اول در NBA’s Western Conference in 2017-18 برای مدافع قهرمانی یعنی تیم Golden State Warriors و رقیب آن Houston Rockets آغاز می‌شود. رکوردهای روزانه پیروزی-شکست برای این دو تیم در یک دیتافریم با نام west_top_2 ذخیره شده است.

1 2 3 4 5 6 7 8 9 10

>>> west_top_2 = (standings[(standings['teamAbbr'] == 'HOU') | (standings['teamAbbr'] == 'GS')] ...               .loc[:, ['stDate', 'teamAbbr', 'gameWon']] ...               .sort_values(['teamAbbr','stDate'])) >>> west_top_2.head()         stDate teamAbbr  gameWon 9   2017-10-17       GS        0 39  2017-10-18       GS        0 69  2017-10-19       GS        0 99  2017-10-20       GS        1 129 2017-10-21       GS        1

از اینجا می‌توان این DataFrame را در دو شی ColumnDataSource بارگذاری و مسابقه را بصری‌سازی کرد.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

# Bokeh libraries from bokeh.plotting import figure, show from bokeh.io import output_file from bokeh.models import ColumnDataSource   # Output to file output_file('west-top-2-standings-race.html',             title='Western Conference Top 2 Teams Wins Race')   # Isolate the data for the Rockets and Warriors rockets_data = west_top_2[west_top_2['teamAbbr'] == 'HOU'] warriors_data = west_top_2[west_top_2['teamAbbr'] == 'GS']   # Create a ColumnDataSource object for each team rockets_cds = ColumnDataSource(rockets_data) warriors_cds = ColumnDataSource(warriors_data)   # Create and configure the figure fig = figure(x_axis_type='datetime',              plot_height=300, plot_width=600,              title='Western Conference Top 2 Teams Wins Race, 2017-18',              x_axis_label='Date', y_axis_label='Wins',              toolbar_location=None)   # Render the race as step lines fig.step('stDate', 'gameWon',          color='#CE1141', legend='Rockets',          source=rockets_cds) fig.step('stDate', 'gameWon',          color='#006BB6', legend='Warriors',          source=warriors_cds)   # Move the legend to the upper left corner fig.legend.location = 'top_left'   # Show the plot show(fig)

چگونگی ارجاع داده شدن اشیای ColumnDataSource هنگام ساخت دو خط قابل توجه است. اسامی ستون اصلی به سادگی به عنوان پارامترهای ورودی پاس داده می‌شوند و مشخص می‌شود که کدام ColumnDataSource با خصیصه source مورد استفاده قرار بگیرد. بصری‌سازی‌ها نشانگر وجود مسابقات تنگاتنگی در این فصل و همچنین، حاکی از تاثیر قابل توجه Warriors در میانه فصل هستند. اگرچه، یک بیت لغزش در فصل پیش امکان بالا رفتن را برای Rockets فراهم کرده و در نهایت از مدافعان قهرمانی پایان فصل، به عنوان تیم اول پیشی گرفته است.

نکته: در بوکه، می‌توان رنگ‌ها را بر اساس اسم، مقدار پایه ۱۶ (hex value)، یا کد رنگ RGB تعیین کرد. برای بصری‌سازی بالا، دو رنگ برای خطوط مربوطه تعیین شده‌اند که نشانگر دو تیم هستند. به جای استفاده از اسامی رنگ‌های CSS، کاربر ممکن است بخواهد که با استفاده از رنگ‌های رسمی تیم‌ها به صورت کدهای هگزادسیمال جلوه زیبایی به خروجی‌ها ببخشد. در عین حال، می‌توان از تاپل‌هایی که کدهای رنگ RGB را نشان می‌دهند (۲۰۶، ۱۷، ۶۵) برای Rockets و کدهای (۰، ۱۰۷ و ۱۸۲) برای Warriors استفاده کرد.

بوکه لیست مفیدی از اسامی رنگ‌های CSS که بر اساس فام اصلی آن‌ها دسته‌بندی شده‌اند را ارائه می‌کند. همچنین، می‌توان از سایت‌های متعددی که برای یافتن کدهای رنگی به صورت CSS ،RGB و hex وجود دارند، استفاده کرد. اشیای ColumnDataSource می‌توانند کاری بیش از ارجاع‌دهی به ستون‌های DataFrame انجام دهند. شی ColumnDataSource دارای سه فیلتر توکار است که می‌توانند برای ساخت نمایش‌هایی از داده‌ها با استفاده از شی CDSView مورد استفاده قرار بگیرند؛ این سه فیلتر در ادامه معرفی شده‌اند.

• GroupFilter کار فیلتر کردن ColumnDataSource را با استفاده از لیستی از اندیس‌های صحیح (Integer) انجام می‌دهد.
• IndexFilter که ColumnDataSource را با استفاده از لیستی از شاخص‌های صحیح فیلتر می‌کند.
• BooleanFilter امکان استفاده از لیستی از مقادیر boolean را با سطرهای True که انتخاب شده‌اند فراهم می‌کند.

در مثال پیشین، دو شی ColumnDataSource ساخته شدند که هر یک از آن‌ها زیرمجموعه‌ای از دیتافریم west_top_2 هستند. مثال بعدی، خروجی مشابهی را از یک ColumnDataSource بر پایه west_top_2 با استفاده از GroupFilter می‌سازد که دیدی از داده‌ها فراهم می‌کند.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

# Bokeh libraries from bokeh.plotting import figure, show from bokeh.io import output_file from bokeh.models import ColumnDataSource, CDSView, GroupFilter   # Output to file output_file('west-top-2-standings-race.html',             title='Western Conference Top 2 Teams Wins Race')   # Create a ColumnDataSource west_cds = ColumnDataSource(west_top_2)   # Create views for each team rockets_view = CDSView(source=west_cds,                        filters=[GroupFilter(column_name='teamAbbr', group='HOU')]) warriors_view = CDSView(source=west_cds,                         filters=[GroupFilter(column_name='teamAbbr', group='GS')])   # Create and configure the figure west_fig = figure(x_axis_type='datetime',                   plot_height=300, plot_width=600,                   title='Western Conference Top 2 Teams Wins Race, 2017-18',                   x_axis_label='Date', y_axis_label='Wins',                   toolbar_location=None)   # Render the race as step lines west_fig.step('stDate', 'gameWon',               source=west_cds, view=rockets_view,               color='#CE1141', legend='Rockets') west_fig.step('stDate', 'gameWon',               source=west_cds, view=warriors_view,               color='#006BB6', legend='Warriors')   # Move the legend to the upper left corner west_fig.legend.location = 'top_left'   # Show the plot show(west_fig)

چگونگی پاس دادن GroupFilter به CDSView در یک لیست قابل توجه است. این کار، امکان ترکیب چندین فیلتر با یکدیگر را برای ایزوله کردن داده‌هایی که از ColumnDataSource مورد نیاز هستند فراهم می‌کند. Western Conference به عنوان مسابقاتی مهیج پایان یافت که رقابت‌های آن حقیقتا تنگاتنگ برگزار شده بودند. این رقابت‌ها در ادامه به صورت بصری ارائه خواهند شد. بنابراین، در ادامه به موضوع بعدی یعنی layout‌ها پرداخته خواهد شد.

سازمان‌دهی بصری‌سازی‌های متعدد با Layout‌ها

جدول رده‌بندی Eastern Conference به دو دسته از رقابت‌ها در بخش آتلانتیک تقسیم می‌شود که عبارتند از: Boston Celtics و Toronto Raptors. پیش از تکرار گام‌هایی که برای ساخت west_top_2 مورد استفاده قرار گرفتند، بهتر است یکبار دیگر ColumnDataSource با استفاده از آنچه پیش‌تر توضیح داده شد مورد آزمون قرار بگیرد. در این مثال، چگونگی خوراک دادن کل DataFrame به یک ColumnDataSource و ساخت نمایش‌هایی برای ایزوله کردن داده‌های مرتبط، بیان خواهد شد.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

# Bokeh libraries from bokeh.plotting import figure, show from bokeh.io import output_file from bokeh.models import ColumnDataSource, CDSView, GroupFilter   # Output to file output_file('east-top-2-standings-race.html',             title='Eastern Conference Top 2 Teams Wins Race')   # Create a ColumnDataSource standings_cds = ColumnDataSource(standings)   # Create views for each team celtics_view = CDSView(source=standings_cds,                       filters=[GroupFilter(column_name='teamAbbr',                                            group='BOS')]) raptors_view = CDSView(source=standings_cds,                       filters=[GroupFilter(column_name='teamAbbr',                                            group='TOR')])   # Create and configure the figure east_fig = figure(x_axis_type='datetime',            plot_height=300, plot_width=600,            title='Eastern Conference Top 2 Teams Wins Race, 2017-18',            x_axis_label='Date', y_axis_label='Wins',            toolbar_location=None)   # Render the race as step lines east_fig.step('stDate', 'gameWon',               color='#007A33', legend='Celtics',               source=standings_cds, view=celtics_view) east_fig.step('stDate', 'gameWon',               color='#CE1141', legend='Raptors',               source=standings_cds, view=raptors_view)   # Move the legend to the upper left corner east_fig.legend.location = 'top_left'   # Show the plot show(east_fig)

ColumnDataSource قادر به ایزوله کردن داده‌های مرتبط در یک دیتافریم ۵، ۰۴۰ در ۳۹ بدون سختی قابل توجه و تنها با چند خط کد «پانداس» (Pandas) است. با نگاه به بصری‌سازی‌ها، می‌توان مشاهده کرد که رقابت‌های Eastern Conference دارای هیچ مشکلی نیستند. پس از آنکه Celtics نتوانستند میادین را به خوبی حفظ کنند، Raptors‌ها همه راه را بازگشتند تا بر رقیب خود غلبه کرده و فصل را با پنج برد بیشتر به اتمام برسانند. با دو بصری‌سازی آماده، زمان آن رسیده تا این نمودارها در کنار هم قرار داده شوند و تحلیل‌هایی روی آن‌ها صورت پذیرد. مشابه با عملکرد subplot در «مَت‌پِلات‌لیب» ( Matplotlib)، بوکه نیز دارای توابع column، row و gridplot در ماژول bokeh.layouts است. این توابع می‌توانند به صورت عمومی‌تر با عنوان layout دسته‌بندی شوند. استفاده از این layout‌ها کار سختی نیست. اگر هدف، قرار دادن دو بصری‌سازی در پیکربندی عمودی باشد می‌توان به صورت زیر عمل کرد.

1 2 3 4 5 6 7 8 9 10 11

# Bokeh library from bokeh.plotting import figure, show from bokeh.io import output_file from bokeh.layouts import column   # Output to file output_file('east-west-top-2-standings-race.html',             title='Conference Top 2 Teams Wins Race')   # Plot the two visualizations in a vertical configuration show(column(west_fig, east_fig))

تنها با تغییر column با row در قطعه کد بالا، می‌توان به طور مشابه دو نمودار را به صورت افقی در کنار هم قرار داد.

نکته: برای افرادی که همراه با مطالعه این مطلب در تلاش برای نوشتن کدهای خودشان هستند، در ادامه نکاتی پیرامون خطایی که امکان دارد با آن مواجه شوند ارائه می‌شود. این خطا ممکن است ضمن دسترسی به west_fig و east_fig در مثالی که در ادامه ارائه شده رخ دهد. خطای مذکور، چیزی شبیه آنچه در زیر آمده، خواهد بود.

1	WARNING:bokeh.core.validation.check:W-1004 (BOTH_CHILD_AND_ROOT): Models should not be a document root...

این تنها یکی از خطاهای متعددی است که به عنوان ماژول اعتبارسنجی بوکه به وقوع می‌پیوندند که در آن W-1004 هشداری پیرامون استفاده مجدد از west_fig و east_fig در یک layout جدید است. برای اجتناب از این خطاها، همانطور که مثال‌ها تست می‌شوند، قطعه کدی که هر لایه را نمایش می‌دهد به صورت زیر آغاز می‌شود:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54

# Bokeh libraries from bokeh.plotting import figure, show from bokeh.models import ColumnDataSource, CDSView, GroupFilter   # Create a ColumnDataSource standings_cds = ColumnDataSource(standings)   # Create the views for each team celtics_view = CDSView(source=standings_cds,                       filters=[GroupFilter(column_name='teamAbbr',                                            group='BOS')])   raptors_view = CDSView(source=standings_cds,                       filters=[GroupFilter(column_name='teamAbbr',                                            group='TOR')])   rockets_view = CDSView(source=standings_cds,                       filters=[GroupFilter(column_name='teamAbbr',                                            group='HOU')]) warriors_view = CDSView(source=standings_cds,                       filters=[GroupFilter(column_name='teamAbbr',                                            group='GS')])   # Create and configure the figure east_fig = figure(x_axis_type='datetime',                   plot_height=300,                   x_axis_label='Date',                   y_axis_label='Wins',                   toolbar_location=None)   west_fig = figure(x_axis_type='datetime',                   plot_height=300,                   x_axis_label='Date',                   y_axis_label='Wins',                   toolbar_location=None)   # Configure the figures for each conference east_fig.step('stDate', 'gameWon',               color='#007A33', legend='Celtics',               source=standings_cds, view=celtics_view) east_fig.step('stDate', 'gameWon',               color='#CE1141', legend='Raptors',               source=standings_cds, view=raptors_view)   west_fig.step('stDate', 'gameWon', color='#CE1141', legend='Rockets',               source=standings_cds, view=rockets_view) west_fig.step('stDate', 'gameWon', color='#006BB6', legend='Warriors',               source=standings_cds, view=warriors_view)   # Move the legend to the upper left corner east_fig.legend.location = 'top_left' west_fig.legend.location = 'top_left'   # Layout code snippet goes here!

انجام این کار موجب نوسازی مولفه‌های مرتبط برای رندر کردن بصری‌سازی‌ها و حصول اطمینان از این موضوع می‌شود که هیچ هشداری مورد نیاز نیست. به جای استفاده از column یا row، کاربر ممکن است بخواهد که از gridplot استفاده کند. یک تفاوت کلیدی gridplot با دیگر موارد آن است که به طور خودکار نوار ابزار را در سراسر شکل‌های (Figures) فرزند تحکیم می‌کند. همانطور که مشهود است، در gridplot به جای آنکه یک تاپل به عنوان ورودی به آن داده شود، نیازمند لیستی از لیست‌ها است که در آن هر زیر لیست یک سطر از شبکه را نشان می‌دهد:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

# Bokeh libraries from bokeh.io import output_file from bokeh.layouts import gridplot   # Output to file output_file('east-west-top-2-gridplot.html',             title='Conference Top 2 Teams Wins Race')   # Reduce the width of both figures east_fig.plot_width = west_fig.plot_width = 300   # Edit the titles east_fig.title.text = 'Eastern Conference' west_fig.title.text = 'Western Conference'   # Configure the gridplot east_west_gridplot = gridplot([[west_fig, east_fig]],                               toolbar_location='right')   # Plot the two visualizations in a horizontal configuration show(east_west_gridplot)

در نهایت، gridplot امکان انتقال مقادیر None را فراهم می‌کند که به صورت زیرنمودارهای خالی تفسیر می‌شوند. از این رو، اگر کاربر قصد قرار دادن یک placeholder برای دو نمودار اضافه‌تر را داشته باشد، می‌تواند به صورت زیر عمل کند.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

# Bokeh libraries from bokeh.io import output_file from bokeh.layouts import gridplot   # Output to file output_file('east-west-top-2-gridplot.html',             title='Conference Top 2 Teams Wins Race')   # Reduce the width of both figures east_fig.plot_width = west_fig.plot_width = 300   # Edit the titles east_fig.title.text = 'Eastern Conference' west_fig.title.text = 'Western Conference'   # Plot the two visualizations with placeholders east_west_gridplot = gridplot([[west_fig, None], [None, east_fig]],                               toolbar_location='right')   # Plot the two visualizations in a horizontal configuration show(east_west_gridplot)

برای مشاهده تصویر در ابعاد اصلی روی لینک زیر کلیک کنید.

اگر کاربر قصد جابه‌جایی میان بصری‌سازی‌ها در سایز کامل آن‌ها را بدون پایین کشیدن آن‌ها برای متناسب شدن در کنار یا بر فراز هم داشته باشد، یک گزینه خوب tabbed layout است. یک tabbed layout شامل دو تابع ویجت Bokeh است: ()Tab و ()Panel از زیرماژول bokeh.models.widgets. همچون استفاده از ()gridplot، ساخت یک tabbed layout نیز کار ساده‌ای به حساب می‌آید.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

# Bokeh Library from bokeh.io import output_file from bokeh.models.widgets import Tabs, Panel   # Output to file output_file('east-west-top-2-tabbed_layout.html',             title='Conference Top 2 Teams Wins Race')   # Increase the plot widths east_fig.plot_width = west_fig.plot_width = 800   # Create two panels, one for each conference east_panel = Panel(child=east_fig, title='Eastern Conference') west_panel = Panel(child=west_fig, title='Western Conference')   # Assign the panels to Tabs tabs = Tabs(tabs=[west_panel, east_panel])   # Show the tabbed layout show(tabs)

اولین گام، ساخت یک ()Panel برای هر tab است. این موضوع ممکن است کمی گیج‌کننده به نظر برسد، در واقع باید به تابع ()Tabs به عنوان مکانیزمی که Tab‌های جداگانه ساخته شده با ()Panel را سازمان‌دهی می‌کند نگریست. هر ()Panel یک فرزند را به عنوان ورودی دریافت می‌کند که می‌تواند یک ()figure یا layout تنها باشد. (باید به خاطر داشت که layout یک نام عمومی برای column ،row یا gridplot است.) پس از آنکه پنل‌ها سرهم شدند، می‌توان آن‌ها را به ()Tabs در یک لیست انتقال داد. اکنون که چگونگی دسترسی، ترسیم و سازمان‌دهی داده‌ها مشخص شد، زمان آن رسیده که معجزه بوکه را روی داده‌های واقعی دید: تعامل!

افزودن تعامل

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

Bokeh یک کتابخانه بصری‌سازی تعاملی است که مرورگرهای مدرن را برای ارائه، هدف قرار می‌دهد.

در این بخش، چهار راهکاریی که می‌توان با استفاده از آن‌ها تعامل را به بصری‌سازی‌ها افزود بیان شده‌اند.

• پیکربندی نوار ابزار
• انتخاب نقاط داده
• افزودن اقدام شناور
• پیوند دادن محورها و انتخاب‌ها
• برجسته کردن داده‌ها با استفاده از legend

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

پیکربندی نوار ابزار

چنانکه پیش‌تر در بخش «ساخت شکل اولیه» بیان شد، ()figure پیش‌فرض بوکه با یک نوار ابزار عرضه می‌شود. نوار ابزار پیش‌فرض با ابزارهایی که در ادامه بیان شده‌اند ارائه می‌شود (از چپ به راست).

• Pan
• Box Zoom
• Wheel Zoom
• Save
• Reset

نوار ابزار را می‌توان با پاس دادن toolbar_location=None هنگام معرفی یک شی ()figure حذف کرد و یا با پاس دادن هر یک از گزینه‌های above، below، left یا right تغییر مکان داد. علاوه بر آن، نوار ابزار را می‌توان برای در بر گرفتن هر ترکیبی از ابزارهایی که کاربر تمایل دارد پیکربندی کرد. بوکه ۱۰ ابزار اختصاصی در ۱۸ دسته ارائه می کند که در زیر بیان شده‌اند.

• Pan/Drag: box_select, box_zoom, lasso_select, pan, xpan, ypan, resize_select
• Click/Tap: poly_select, tap
• Scroll/Pinch: wheel_zoom, xwheel_zoom, ywheel_zoom
• Actions: undo, redo, reset, save
• Inspectors: crosshair, hover

انتخاب نقاط داده

پیاده‌سازی رفتار انتخاب به سادگی افزودن چند کلیدواژه خاص هنگام اعلام glyph‌ها است. دومین مثال، یک نمودار پراکندگی می‌سازد که تعداد کل ضربات سه امتیازی را نسبت به درصد ضربات ساخته شده (برای بازیکنانی با دستکم ۱۰۰ ضربه سه امتیازی) نمایش می‌دهد. داده‌ها را می‌توان از دیتافریم player_stats تجمیع کرد.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

# Find players who took at least 1 three-point shot during the season three_takers = player_stats[player_stats['play3PA'] > 0]   # Clean up the player names, placing them in a single column three_takers['name'] = [f'{p["playFNm"]} {p["playLNm"]}'                         for _, p in three_takers.iterrows()]   # Aggregate the total three-point attempts and makes for each player three_takers = (three_takers.groupby('name')                             .sum()                             .loc[:,['play3PA', 'play3PM']]                             .sort_values('play3PA', ascending=False))   # Filter out anyone who didn't take at least 100 three-point shots three_takers = three_takers[three_takers['play3PA'] >= 100].reset_index()   # Add a column with a calculated three-point percentage (made/attempted) three_takers['pct3PM'] = three_takers['play3PM'] / three_takers['play3PA']

در ادامه نمونه‌ای از دیتافریم‌های حاصل شده را می‌توان مشاهده کرد.

1	>>> three_takers.sample(5)

 name play3PA play3PM pct3PM
229 Corey Brewer 110 31 0.281818
78 Marc Gasol 320 109 0.340625
126 Raymond Felton 230 81 0.352174
127 Kristaps Porziņģis 229 90 0.393013
66 Josh Richardson 336 127 0.377976

اکنون، فرض می‌شود که کاربر قصد انتخاب گروهی از بازیکنان را در توزیع دارد و در این راستا رنگ glyph‌ها که نشانگر بازیکنان انتخاب نشده هستند را خاموش می‌کند.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

# Bokeh Libraries from bokeh.plotting import figure, show from bokeh.io import output_file from bokeh.models import ColumnDataSource, NumeralTickFormatter   # Output to file output_file('three-point-att-vs-pct.html',             title='Three-Point Attempts vs. Percentage')   # Store the data in a ColumnDataSource three_takers_cds = ColumnDataSource(three_takers)   # Specify the selection tools to be made available select_tools = ['box_select', 'lasso_select', 'poly_select', 'tap', 'reset']   # Create the figure fig = figure(plot_height=400,              plot_width=600,              x_axis_label='Three-Point Shots Attempted',              y_axis_label='Percentage Made',              title='3PT Shots Attempted vs. Percentage Made (min. 100 3PA), 2017-18',              toolbar_location='below',              tools=select_tools)   # Format the y-axis tick labels as percentages fig.yaxis[0].formatter = NumeralTickFormatter(format='00.0%')   # Add square representing each player fig.square(x='play3PA',            y='pct3PM',            source=three_takers_cds,            color='royalblue',            selection_color='deepskyblue',            nonselection_color='lightgray',            nonselection_alpha=0.3)   # Visualize show(fig)

کاربر ابتدا باید ابزارهای انتخابی که می‌خواهد در دسترس باشند را تعیین کند. در مثال بالا، box_select، lasso_select، poly_select و tap (به علاووه دکمه reset) در لیستی که select_tools نامیده می‌شود تعریف شده‌اند. هنگامی که شکل تعریف شد، نوار ابزار در موقعیت below در نمودار قرار می‌گیرد و لیست به tools برای در دسترس قرار دادن ابزارهای انتخاب شده در بالا انتقال داده می‌شود. هر بازیکن در ابتدا با یک مربع به رنگ آبی تیره نمایش داده می‌شود، اما پیکربندی‌های بیان شده در زیر هنگامی که یک بازیکن یا بازیکنان انتخاب می‌شوند تنظیم شده است.

• تبدیل کردن بازیکنان انتخاب شده به آبی آسمانی
• تغییر glyph‌های همه بازیکنان انتخاب نشده به رنگ خاکستری روشن (lightgray) با شفافیت ۰.۳

تنها با چند تغییر سریع، بصری‌سازی اکنون به چیزی مانند تصویر زیر مبدل شده است.

افزودن Hover

ابزار ()HoverTool اندکی با ابزارهای انتخاب شده در بالا متفاوت و دارای مشخصه‌هایی و به ویژه tooltips است. ابتدا، می‌توان یک tooltip را با ساخت لیستی از تاپل‌ها که حاوی توصیف‌ها و ارجاعات به ColumnDataSource هستند ساخت. این لیست به عنوان ورودی به ()HoverTool انتقال داده شده و سپس به سادگی با استفاده از ()add_tools به شکل افزوده شده است. در ادامه، آنچه به وقوع پیوسته قابل مشاهده است.

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

# Format the tooltip tooltips = [             ('Player','@name'),             ('Three-Pointers Made', '@play3PM'),             ('Three-Pointers Attempted', '@play3PA'),             ('Three-Point Percentage','@pct3PM{00.0%}'),            ]   # Configure a renderer to be used upon hover hover_glyph = fig.circle(x='play3PA', y='pct3PM', source=three_takers_cds,                          size=15, alpha=0,                          hover_fill_color='black', hover_alpha=0.5)   # Add the HoverTool to the figure fig.add_tools(HoverTool(tooltips=tooltips, renderers=[hover_glyph]))   # Visualize show(fig)

این کار با ساخت یک glyph کاملا جدید انجام می‌شود، در این مثال، از دایره‌ها به جای مربع استفاده شده که به hover_glyph تخصیص داده شده‌اند. توجه به این نکته لازم است که شفافیت اولیه برابر با صفر تعیین شده، بنابراین تا هنگامی که نشانگر موس آن را لمس نکند، به صورت شفاف است. مشخصه‌هایی که برای hover ظاهر می‌شوند با تنظیم hover_alpha برابر با ۰.۵ در امتداد hover_fill_color تنظیم می‌شوند. اکنون، هنگام Hover کردن روی مارکرهای گوناگون، دایره کوچک مشکی روی مربع اصلی ظاهر می‌شود.

پیوند دادن محورها و انتخاب‌ها

پیوند دادن، فرآیند همگام‌سازی عناصر از بصری‌سازی‌های گوناگون درون یک قالب است. برای مثال، ممکن است کاربر بخواهد که محورهای چند نمودار را برای اطمینان از اینکه اگر روی آن‌ها بزرگنمایی شود روی دیگری منعکس می‌شوند به یکدیگر پیوند دهد. برای این مثال، بصری‌سازی‌ها قادر به Pan کردن (اسکرول افقی) به بخش‌های مختلف از برنامه تیم و آزمودن وضعیت آمارهای بازی‌های گوناگون هستند. آمارها به وسیله نمودار در یک ()gridplot نمایش داده می‌شوند. داده‌ها از دیتافریم team_stats قابل گردآوری هستند. در ادامه، تیم Philadelphia 76ers به عنوان تیم مورد علاقه انتخاب می‌شود.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

# Isolate relevant data phi_gm_stats = (team_stats[(team_stats['teamAbbr'] == 'PHI') &                            (team_stats['seasTyp'] == 'Regular')]                 .loc[:, ['gmDate',                          'teamPTS',                          'teamTRB',                          'teamAST',                          'teamTO',                          'opptPTS',]]                 .sort_values('gmDate'))   # Add game number phi_gm_stats['game_num'] = range(1, len(phi_gm_stats)+1)   # Derive a win_loss column win_loss = [] for _, row in phi_gm_stats.iterrows():       # If the 76ers score more points, it's a win     if row['teamPTS'] > row['opptPTS']:         win_loss.append('W')     else:         win_loss.append('L')   # Add the win_loss data to the DataFrame phi_gm_stats['winLoss'] = win_loss

در ادامه، نتایج پنج بازی اول 76ers آورده شده است.

1	>>> phi_gm_stats.head()

 gmDate teamPTS teamTRB teamAST teamTO opptPTS game_num winLoss
10 2017-10-18 115 48 25 17 120 1 L
39 2017-10-20 92 47 20 17 102 2 L
52 2017-10-21 94 41 18 20 128 3 L
80 2017-10-23 97 49 25 21 86 4 W
113 2017-10-25 104 43 29 16 105 5 L

کار با وارد کردن (Import) کتابخانه‌های لازم بوکه، مشخص کردن پارامترهای خروجی و خواندن داده‌ها در ColumnDataSource آغاز می‌شود.

1 2 3 4 5 6 7 8 9 10 11 12

# Bokeh Libraries from bokeh.plotting import figure, show from bokeh.io import output_file from bokeh.models import ColumnDataSource, CategoricalColorMapper, Div from bokeh.layouts import gridplot, column   # Output to file output_file('phi-gm-linked-stats.html',                 title='76ers Game Log')   # Store the data in a ColumnDataSource gm_stats_cds = ColumnDataSource(phi_gm_stats)

هر بازی به وسیله یک ستون ارائه می‌شود و اگر نتیجه بُرد بود سبز و اگر باخت بود قرمز رنگ می‌شود. برای انجام این کار، CategoricalColorMapper بوکه، می‌تواند برای نگاشت مقادیر داده به رنگ‌های تعیین شده مورد استفاده قرار بگیرد.

1 2 3

# Create a CategoricalColorMapper that assigns a color to wins and losses win_loss_mapper = CategoricalColorMapper(factors = ['W', 'L'],                                          palette=['green', 'red'])

برای این بررسی موردی، لیستی که مقادیر داده دسته‌ای را نگاشت می‌کند به factors و لیستی با رنگ‌های مورد نظر به palette پاس داده می‌شود. چهار آمار برای بصری‌سازی در یک gridplot دو در دو وجود دارد که عبارتند از امتیازها (point)، پاس‌های منجر به گل (assist)، ریباندها (rebounds) و گردش‌ها (turnovers). در ساخت چهار شکل و پیکربندی نمودارهای مربوط به آن‌ها، افزونگی زیادی در ویژگی‌ها وجود دارد. بنابراین، برای ساده کردن کد از یک حلقه for استفاده می‌شود.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

# Create a dict with the stat name and its corresponding column in the data stat_names = {'Points': 'teamPTS',               'Assists': 'teamAST',               'Rebounds': 'teamTRB',               'Turnovers': 'teamTO',}   # The figure for each stat will be held in this dict stat_figs = {}   # For each stat in the dict for stat_label, stat_col in stat_names.items():       # Create a figure     fig = figure(y_axis_label=stat_label,                  plot_height=200, plot_width=400,                  x_range=(1, 10), tools=['xpan', 'reset', 'save'])       # Configure vbar     fig.vbar(x='game_num', top=stat_col, source=gm_stats_cds, width=0.9,              color=dict(field='winLoss', transform=win_loss_mapper))       # Add the figure to stat_figs dict     stat_figs[stat_label] = fig

همانطور که مشهود است، تنها پارامترهایی که نیاز به تنظیم داشتند y-axis-label شکل و داده‌هایی که top را در vbar دیکته می‌کند هستند. این مقادیر به راحتی در یک dict ذخیره می‌شوند که در آن تکرار به منظور ساخت شکل برای هر آمار انجام می‌شود. همچنین، می‌توان پیاده‌سازی CategoricalColorMapper در پیکربندی glyph مربوط به vbar را مشاهده کرد. خصوصیت رنگ یک ٰdict را با فیلد درون ColumnDataSource پاس می‌دهد تا نگاشت شود؛ بدین شکل، نام CategoricalColorMapper در بالا ساخته شده است. دید اولیه فقط ۱۰ بازی اول از فصل 76ers را نشان می‌دهد، بنابراین، نیاز به راهی برای اسکرول افقی (pan horizontally) برای کاوش در کل بازی‌های این فصل است. بدین ترتیب، پیکربندی نوار ابزار امکان لازم برای داشتن یک ابزار xpan که قابلیت Pan کردن از طریق نمودار را بدون داشتن هرگونه نگرانی پیرامون چولگی تصادفی در نمایش در طول محور عمودی دارد، فراهم می‌کند. اکنون که شکل ساخته شد، gridplot را می‌توان با ارجاع به اشکالی از dict ساخته شده در بالا راه‌اندازی کرد.

1 2 3

# Create layout grid = gridplot([[stat_figs['Points'], stat_figs['Assists']],                 [stat_figs['Rebounds'], stat_figs['Turnovers']]])

پیوند دادن محورهای چهار نمودار به سادگی تنظیم کردن x_range برای کلیه اشکال به صورت مساوی با یکدیگر است.

1 2 3 4 5

# Link together the x-axes stat_figs['Points'].x_range = \     stat_figs['Assists'].x_range = \     stat_figs['Rebounds'].x_range = \     stat_figs['Turnovers'].x_range

برای افزودن نوار عنوان به بصری‌سازی، می‌توان این کار را روی شکل امتیازها انجام داد، اما در صورت انجام چنین کاری، فضای شکل محدود می‌شود. بنابراین، یک ترفند خوب استفاده از قابلیت‌های Bokeh برای تفسیر HTML جهت درج عنصر Div محسوب می‌شود که شامل اطلاعات عنوان است. پس از آنکه ساخته شد، به سادگی می‌توان آن را با ()gridplot در قالب column ترکیب کرد.

1 2 3 4 5 6 7 8 9 10

# Add a title for the entire visualization using Div html = """<h3>Philadelphia 76ers Game Log</h3> <b><i>2017-18 Regular Season</i> <br> </b><i>Wins in green, losses in red</i> """ sup_title = Div(text=html)   # Visualize show(column(sup_title, grid))

کنار هم قرار دادن همه قسمت‌ها منجر به ساخت شکل زیر می‌شود.

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

# Isolate relevant data phi_gm_stats_2 = (team_stats[(team_stats['teamAbbr'] == 'PHI') &                              (team_stats['seasTyp'] == 'Regular')]                   .loc[:, ['gmDate',                            'team2P%',                            'team3P%',                            'teamPTS',                            'opptPTS']]                   .sort_values('gmDate'))   # Add game number phi_gm_stats_2['game_num'] = range(1, len(phi_gm_stats_2) + 1)   # Derive a win_loss column win_loss = [] for _, row in phi_gm_stats_2.iterrows():       # If the 76ers score more points, it's a win     if row['teamPTS'] > row['opptPTS']:         win_loss.append('W')     else:         win_loss.append('L')   # Add the win_loss data to the DataFrame phi_gm_stats_2['winLoss'] = win_loss

شکلی که داده‌ها به نظر می‌رسند:

1 2 3 4 5 6 7

>>> phi_gm_stats_2.head()         gmDate  team2P%  team3P%  teamPTS  opptPTS  game_num winLoss 10  2017-10-18   0.4746   0.4286      115      120         1       L 39  2017-10-20   0.4167   0.3125       92      102         2       L 52  2017-10-21   0.4138   0.3333       94      128         3       L 80  2017-10-23   0.5098   0.3750       97       86         4       W 113 2017-10-25   0.5082   0.3333      104      105         5       L

کد لازم برای ساخت بصری‌سازی‌ها به صورت زیر است:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46

# Bokeh Libraries from bokeh.plotting import figure, show from bokeh.io import output_file from bokeh.models import ColumnDataSource, CategoricalColorMapper, NumeralTickFormatter from bokeh.layouts import gridplot   # Output inline in the notebook output_file('phi-gm-linked-selections.html',             title='76ers Percentages vs. Win-Loss')   # Store the data in a ColumnDataSource gm_stats_cds = ColumnDataSource(phi_gm_stats_2)   # Create a CategoricalColorMapper that assigns specific colors to wins and losses win_loss_mapper = CategoricalColorMapper(factors = ['W', 'L'], palette=['Green', 'Red'])   # Specify the tools toolList = ['lasso_select', 'tap', 'reset', 'save']   # Create a figure relating the percentages pctFig = figure(title='2PT FG % vs 3PT FG %, 2017-18 Regular Season',                 plot_height=400, plot_width=400, tools=toolList,                 x_axis_label='2PT FG%', y_axis_label='3PT FG%')   # Draw with circle markers pctFig.circle(x='team2P%', y='team3P%', source=gm_stats_cds,               size=12, color='black')   # Format the y-axis tick labels as percenages pctFig.xaxis[0].formatter = NumeralTickFormatter(format='00.0%') pctFig.yaxis[0].formatter = NumeralTickFormatter(format='00.0%')   # Create a figure relating the totals totFig = figure(title='Team Points vs Opponent Points, 2017-18 Regular Season',                 plot_height=400, plot_width=400, tools=toolList,                 x_axis_label='Team Points', y_axis_label='Opponent Points')   # Draw with square markers totFig.square(x='teamPTS', y='opptPTS', source=gm_stats_cds, size=10,               color=dict(field='winLoss', transform=win_loss_mapper))   # Create layout grid = gridplot([[pctFig, totFig]])   # Visualize show(grid)

این نمایش خوبی از قدرت موجود در استفاده از ColumnDataSource است. تا هنگامی که رندر کننده glyph (در این مثال، glyphs «دایره» (circle) برای درصدها و «مربع» (square) برای شکست‌ها و پیروزی‌ها) ColumnDataSource مشابهی را به اشتراک می‌گذارند، انتخاب‌ها به صورت پیش‌فرض به یکدیگر لینک می‌شوند. در شکل زیر نمایش آنچه بیان شد به صورت بصری ارائه شده و همانطور که مشهود است آنچه در نمودار یک سمت تصویر انتخاب می‌شود در سمت دیگر نیز منعکس می‌شود.

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

برجسته‌سازی داده‌ها با استفاده از Legend

این گام ما را به آخرین مثال تعاملی در این راهنما هدایت می‌کند: legend‌های تعاملی. در بخش «ترسیم داده‌ها با Glyph‌ها» مشهود بود که پیاده‌سازی یک legend هنگام ساخت نمودار چقدر آسان است. با استفاده از legend افزودن تعامل صرفا با تخصیص یک click_policy انجام‌پذیر خواهد بود. با استفاده از یک خط کد، می‌توان توانایی hide یا mute کردن داده‌ها را با بهره‌گیری از legend ایجاد کرد. در این مثال، می‌توان دو نمودار پراکندگی یکسان را دید که امتیازها و ریباندهای بازی به بازی برای James و Kevin Durant را مقایسه می‌کنند. تنها تفاوت آن‌ها در این است که یکی از hide به عنوان click_policy خود و دیگری از mute برای این منظور استفاده می‌کند. اولین گام برای پیکربندی خروجی و راه‌اندازی داده‌ها ساخت چشم‌اندازی برای هر بازیکن از دیتافریم player_stats است.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

# Bokeh Libraries from bokeh.plotting import figure, show from bokeh.io import output_file from bokeh.models import ColumnDataSource, CDSView, GroupFilter from bokeh.layouts import row   # Output inline in the notebook output_file('lebron-vs-durant.html',             title='LeBron James vs. Kevin Durant')   # Store the data in a ColumnDataSource player_gm_stats = ColumnDataSource(player_stats)   # Create a view for each player lebron_filters = [GroupFilter(column_name='playFNm', group='LeBron'),                   GroupFilter(column_name='playLNm', group='James')] lebron_view = CDSView(source=player_gm_stats,                       filters=lebron_filters)   durant_filters = [GroupFilter(column_name='playFNm', group='Kevin'),                   GroupFilter(column_name='playLNm', group='Durant')] durant_view = CDSView(source=player_gm_stats,                       filters=durant_filters)

پیش از ساخت شکل، پارامترهای متداول در شکل، مارکرها و داده‌ها را می‌توان در دیکشنری‌ها تلفیق و استفاده مجدد کرد. این کار نه تنها از «افزونگی» (redundancy) در گام‌های بعدی جلوگیری می‌کند، بلکه راه ساده‌ای برای پیچش این پارامترها در صورت نیاز فراهم می‌کند.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

# Consolidate the common keyword arguments in dicts common_figure_kwargs = {     'plot_width': 400,     'x_axis_label': 'Points',     'toolbar_location': None, } common_circle_kwargs = {     'x': 'playPTS',     'y': 'playTRB',     'source': player_gm_stats,     'size': 12,     'alpha': 0.7, } common_lebron_kwargs = {     'view': lebron_view,     'color': '#002859',     'legend': 'LeBron James' } common_durant_kwargs = {     'view': durant_view,     'color': '#FFC324',     'legend': 'Kevin Durant' }

اکنون که مشخصه‌های گوناگون تنظیم شدند، دو نمودار پراکندگی را می‌توان به شیوه خلاصه‌تری ساخت که کد آن در زیر آمده است.

1 2 3 4 5 6 7 8 9 10 11 12

# Create the two figures and draw the data hide_fig = figure(**common_figure_kwargs,                   title='Click Legend to HIDE Data',                   y_axis_label='Rebounds') hide_fig.circle(**common_circle_kwargs, **common_lebron_kwargs) hide_fig.circle(**common_circle_kwargs, **common_durant_kwargs)   mute_fig = figure(**common_figure_kwargs, title='Click Legend to MUTE Data') mute_fig.circle(**common_circle_kwargs, **common_lebron_kwargs,                 muted_alpha=0.1) mute_fig.circle(**common_circle_kwargs, **common_durant_kwargs,                 muted_alpha=0.1)

توجه به این نکته لازم است که mute_fig دارای یک پارامتر افزوده با عنوان muted_alpha است. این پارامتر شفافیت مارکرها را هنگامی که mute به عنوان click_policy مورد استفاده قرار می‌گیرد تعیین می‌کند. در نهایت، click_policy برای هر تصویر تنظیم و در پیکربندی افقی نمایش داده می‌شود.

1 2 3 4 5 6

# Add interactivity to the legend hide_fig.legend.click_policy = 'hide' mute_fig.legend.click_policy = 'mute'   # Visualize show(row(hide_fig, mute_fig))

هنگامی که legend در موقعیت خود قرار گرفت، تمام آنچه نیاز است تخصیص دادن hide یا mute به مشخصه click_policy شکل است. این کار موجب می‌شود legend پایه‌ای به یک legend تعاملی مبدل شود. شایان توجه است که به ویژه برای mute، مشخصه‌های اضافی برای muted_alpha در glyph‌های circle مربوطه برای LeBron James و Kevin Durant تنظیم شده‌اند. این کار، جلوه‌های بصری مشتق شده از تعامل‌های legend را دیکته می‌کند.

نتیجه‌گیری

در این راهنما چگونگی پیکربندی اسکریپت‌های پایتون با بهره‌گیری از کتابخانه بوکه، به منظور رندر کردن یک فایل HTML استاتیک یا نوت‌بوک ژوپیتر مورد بررسی قرار گرفت. همچنین، چگونگی نمونه‌سازی و سفارشی‌سازی شی ()figure، ساخت بصری‌سازی‌ها با استفاده از glyph‌ها، دسترسی و فیلتر داده‌ها با ColumnDataSource، سازمان‌دهی نمودارها در لایوت‌های شبکه‌ای و tab شده و همچنین، افزودن اشکال گوناگونی از تعامل شامل انتخاب، hover کردن، پیوند دادن و افزودن Legend‌های تعاملی آموزش داده شد.

https://blog.faradars.org/bokeh-from-zero-to-hero/

ساخت اپلیکیشن ضبط صدا با کاتلین (Kotlin) — به زبان ساده

فریمورک مالتی‌مدیا در اندروید از ضبط و پخش صدا نیز پشتیبانی می‌کند. در این مطلب مراحل ساخت یک اپلیکیشن ضبط صدا را بررسی می‌کنیم که قابلیت ضبط کردن صدا و ذخیره‌سازی آن در حافظه داخلی دستگاه اندرویدی را دارد. این کار با استفاده از MediaRecorder که از سوی SDK اندروید ارائه شده است صورت می‌گیرد. همچنین با روش تقاضای آنی «دسترسی‌های کاربر» (User Permissions) و شیوه کار با حافظه داخلی یک دستگاه اندرویدی آشنا خواهیم شد.

ایجاد رابط کاربری (UI)

ابتدا باید رابط کاربری اپلیکیشن ضبط صدای خودمان را بسازیم. این رابط از یک طرح‌بندی ساده با 3 دکمه تشکیل یافته است که برای آغاز، مکث/ ازسرگیری و توقف ضبط صدا استفاده می‌شوند.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48

<?xml version="1.0" encoding="utf-8"?> <RelativeLayout         xmlns:android="http://schemas.android.com/apk/res/android"         xmlns:tools="http://schemas.android.com/tools"         android:layout_width="match_parent" android:layout_height="match_parent"         tools:context=".MainActivity">       <TextView             android:id="@+id/textview_sound_recorder_heading"             android:layout_width="wrap_content"             android:layout_height="wrap_content"             android:text="Sound Recorder"             android:layout_centerHorizontal="true"             android:textSize="32dp"             android:textStyle="bold"             android:textColor="#000"             android:layout_marginTop="32dp"     />       <Button             android:id="@+id/button_start_recording"             android:layout_width="wrap_content"             android:layout_height="wrap_content"             android:text="Start"             android:layout_alignParentBottom="true"             android:layout_marginLeft="32dp"             android:layout_marginBottom="32dp"             android:layout_centerVertical="true"/>       <Button             android:id="@+id/button_pause_recording"             android:layout_width="wrap_content"             android:layout_height="wrap_content"             android:text="Pause"             android:layout_alignParentBottom="true"             android:layout_centerHorizontal="true"             android:layout_marginBottom="32dp"/>       <Button             android:id="@+id/button_stop_recording"             android:layout_width="wrap_content"             android:layout_height="wrap_content"             android:text="Stop"             android:layout_alignParentBottom="true"             android:layout_alignParentRight="true"             android:layout_marginBottom="32dp"             android:layout_marginRight="32dp"/> </RelativeLayout>

تقاضای مجوزهای مورد نیاز

پس از ایجاد رابط کاربری می‌توانیم با استفاده از MediaRecorder شروع به ساخت اپلیکیشن خود بکنیم. اما قبل از آن باید مجوز دسترسی‌های مورد نیاز خود برای ضبط صدا و استفاده از حافظه داخلی را از کاربر بخواهیم. این کار با چند خط کد ساده در فایل AndroidManifest.xml ممکن است:

1 2	<uses-permission android:name="android.permission.RECORD_AUDIO"/> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

همچنین پیش از استفاده عملی از MediaRecorder لازم است که بررسی کنیم آیا کاربر واقعاً مجوز دسترسی‌ها را ارائه کرده است یا نه؛ این کار را در فایل MainActivity.kt انجام می‌دهیم:

1 2 3 4 5 6

if (ContextCompat.checkSelfPermission(this,       Manifest.permission.RECORD_AUDIO) != PackageManager.PERMISSION_GRANTED && ContextCompat.checkSelfPermission(this,       Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED) {   val permissions = arrayOf(android.Manifest.permission.RECORD_AUDIO, android.Manifest.permission.WRITE_EXTERNAL_STORAGE, android.Manifest.permission.READ_EXTERNAL_STORAGE)   ActivityCompat.requestPermissions(this, permissions,0) }

نکته: این خطوط کد در ادامه به فراخوانی OnClickListener در دکمه start_recording انتقال خواهند یافت تا بتوانیم مطمئن باشیم که MediaRecorder بدون در اختیار داشتن دسترسی‌های لازم شروع به کار نمی‌کند.

ضبط و ذخیره‌سازی صدا

پس از تهیه مقدمات کار اینک نوبت آن رسیده است که به صورت عملی اقدام به ضبط و ذخیره‌سازی صدا بکنیم.

افزودن OnClickListeners

ابتدا باید یک OnClickListeners به دکمه‌های خود اضافه کنیم تا مطمئن شویم که به رویدادهای اجرا شده از سوی کاربر پاسخ می‌دهند. همان طور که پیش‌تر گفتیم وجود مجوز دسترسی‌های صحیح را پیش از افزودن فراخوانی OnClickListener به دکمه start_recording بررسی می‌کنیم.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

button_start_recording.setOnClickListener {     if (ContextCompat.checkSelfPermission(this,             Manifest.permission.RECORD_AUDIO) != PackageManager.PERMISSION_GRANTED && ContextCompat.checkSelfPermission(this,             Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED) {         val permissions = arrayOf(android.Manifest.permission.RECORD_AUDIO, android.Manifest.permission.WRITE_EXTERNAL_STORAGE, android.Manifest.permission.READ_EXTERNAL_STORAGE)         ActivityCompat.requestPermissions(this, permissions,0)     } else {         startRecording()     } }   button_stop_recording.setOnClickListener{     stopRecording() }   button_pause_recording.setOnClickListener {     pauseRecording() }

پیکربندی MediaRecorder

سپس باید یک مسیر برای خروجی تعریف کرده و شروع به پیکربندی MediaRecorder خودمان کنیم.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

private var output: String? = null private var mediaRecorder: MediaRecorder? = null private var state: Boolean = false private var recordingStopped: Boolean = false   override fun onCreate(savedInstanceState: Bundle?) {     super.onCreate(savedInstanceState)     setContentView(R.layout.activity_main)       output = Environment.getExternalStorageDirectory().absolutePath + "/recording.mp3"     mediaRecorder = MediaRecorder()          mediaRecorder?.setAudioSource(MediaRecorder.AudioSource.MIC)     mediaRecorder?.setOutputFormat(MediaRecorder.OutputFormat.MPEG_4)     mediaRecorder?.setAudioEncoder(MediaRecorder.AudioEncoder.AAC)     mediaRecorder?.setOutputFile(output) }

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

ضبط و ذخیره‌سازی صوت

کد مورد استفاده برای آغاز به کار MediaRecorder در رویداد OnClickListener برای دکمه start_recording قرار می‌گیرد:

1 2 3 4 5 6 7 8 9 10 11 12

private fun startRecording() {     try {         mediaRecorder?.prepare()         mediaRecorder?.start()         state = true         Toast.makeText(this, "Recording started!", Toast.LENGTH_SHORT).show()     } catch (e: IllegalStateException) {         e.printStackTrace()     } catch (e: IOException) {         e.printStackTrace()     } }

همان طور که مشاهده می‌کنید ما باید تابع prepare را پیش از آن که اقدام به ضبط صدا بکنیم، فراخوانی کرده باشیم. همچنین آن را درون بلوک try-catch جاسازی کرده‌ایم تا مطمئن شویم که اپلیکیشن هنگامی که تابع prepares ناموفق باشد، از کار نمی‌افتد.

متد OnClickListeners دکمه Stop کاملاً شبیه به آن متدی است که در بخش قبل تعریف کردیم.

1 2 3 4 5 6 7 8 9

private fun stopRecording(){     if(state){         mediaRecorder?.stop()         mediaRecorder?.release()         state = false     }else{         Toast.makeText(this, "You are not recording right now!", Toast.LENGTH_SHORT).show()     } }

در کد فوق بررسی می‌کنیم که آیا MediaRecorder در حال حاضر و پیش از توقف عملی recording در حال اجرا است یا نه، چون اپلیکیشن در زمانی که متد stop هنگام عدم ضبط صدا فراخوانی شود، ممکن است موجب از کار افتادن برنامه شود. پس از آن متغیر state را به حالت false تغییر می‌دهیم تا مانع این بشویم که کاربر مجدداً روی دکمه stop بزند.

سپس باید OnClickListener را برای دکمه pause/resume تعریف کنیم.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

@SuppressLint("RestrictedApi", "SetTextI18n") @TargetApi(Build.VERSION_CODES.N) private fun pauseRecording() {     if(state) {         if(!recordingStopped){             Toast.makeText(this,"Stopped!", Toast.LENGTH_SHORT).show()             mediaRecorder?.pause()             recordingStopped = true             button_pause_recording.text = "Resume"         }else{             resumeRecording()         }     } }   @SuppressLint("RestrictedApi", "SetTextI18n") @TargetApi(Build.VERSION_CODES.N) private fun resumeRecording() {     Toast.makeText(this,"Resume!", Toast.LENGTH_SHORT).show()     mediaRecorder?.resume()     button_pause_recording.text = "Pause"     recordingStopped = false }

ما در این دو متد بررسی می‌کنیم که آیا MediaRecorder در حال اجرا است یا نه. اگر چنین باشد فرایند ضبط صدا را متوقف می‌کنیم و متن دکمه را به resume تغییر می‌دهیم. اگر دکمه دوباره کلیک شود فرایند ضبط صدا را از نقطه‌ای که باقی مانده بود از سر می‌گیریم.

در نهایت ما می‌توانیم ضبط صدا را آغاز کرده و با باز کردن فایل recording.mp3 که در حافظه داخلی دستگاه ذخیره شده است به آن گوش دهیم.

کد کامل اپلیکیشن ضبط صدا در کاتلین: MainActivity.kt

در ادامه کد منبع کامل اپلیکیشن ابتدایی ضبط صدا را مشاهده می‌کنید:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103

package com.example.android.soundrecorder   import android.Manifest import android.annotation.SuppressLint import android.annotation.TargetApi import android.content.pm.PackageManager import android.media.MediaRecorder import android.os.Build import android.support.v7.app.AppCompatActivity import android.os.Bundle import android.os.Environment import android.support.v4.app.ActivityCompat import android.support.v4.content.ContextCompat import android.widget.Toast import kotlinx.android.synthetic.main.activity_main.* import java.io.IOException   class MainActivity : AppCompatActivity() {       private var output: String? = null     private var mediaRecorder: MediaRecorder? = null     private var state: Boolean = false     private var recordingStopped: Boolean = false       override fun onCreate(savedInstanceState: Bundle?) {         super.onCreate(savedInstanceState)         setContentView(R.layout.activity_main)           mediaRecorder = MediaRecorder()         output = Environment.getExternalStorageDirectory().absolutePath + "/recording.mp3"           mediaRecorder?.setAudioSource(MediaRecorder.AudioSource.MIC)         mediaRecorder?.setOutputFormat(MediaRecorder.OutputFormat.MPEG_4)         mediaRecorder?.setAudioEncoder(MediaRecorder.AudioEncoder.AAC)         mediaRecorder?.setOutputFile(output)           button_start_recording.setOnClickListener {             if (ContextCompat.checkSelfPermission(this,                     Manifest.permission.RECORD_AUDIO) != PackageManager.PERMISSION_GRANTED && ContextCompat.checkSelfPermission(this,                     Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED) {                 val permissions = arrayOf(android.Manifest.permission.RECORD_AUDIO, android.Manifest.permission.WRITE_EXTERNAL_STORAGE, android.Manifest.permission.READ_EXTERNAL_STORAGE)                 ActivityCompat.requestPermissions(this, permissions,0)             } else {                 startRecording()             }         }           button_stop_recording.setOnClickListener{             stopRecording()         }           button_pause_recording.setOnClickListener {             pauseRecording()         }     }       private fun startRecording() {         try {             mediaRecorder?.prepare()             mediaRecorder?.start()             state = true             Toast.makeText(this, "Recording started!", Toast.LENGTH_SHORT).show()         } catch (e: IllegalStateException) {             e.printStackTrace()         } catch (e: IOException) {             e.printStackTrace()         }     }       @SuppressLint("RestrictedApi", "SetTextI18n")     @TargetApi(Build.VERSION_CODES.N)     private fun pauseRecording() {         if(state) {             if(!recordingStopped){                 Toast.makeText(this,"Stopped!", Toast.LENGTH_SHORT).show()                 mediaRecorder?.pause()                 recordingStopped = true                 button_pause_recording.text = "Resume"             }else{                 resumeRecording()             }         }     }       @SuppressLint("RestrictedApi", "SetTextI18n")     @TargetApi(Build.VERSION_CODES.N)     private fun resumeRecording() {         Toast.makeText(this,"Resume!", Toast.LENGTH_SHORT).show()         mediaRecorder?.resume()         button_pause_recording.text = "Pause"         recordingStopped = false     }       private fun stopRecording(){         if(state){             mediaRecorder?.stop()             mediaRecorder?.release()             state = false         }else{             Toast.makeText(this, "You are not recording right now!", Toast.LENGTH_SHORT).show()         }     } }

بررسی فایل صدا

پس از ضبط کردن صدا باید به حافظه داخلی دستگاه اندرویدی خود بروید تا بتوانید به فایل ضبط شده گوش بدهید. اگر در مورد مسیر این کار مطمئن نیستید، مراحل کار را در ادامه توضیح داده‌ایم:

1. اپلیکیشن file را روی دستگاه اندرویدی خود باز کنید.
2. به بخش local بروید.
3. به دنبال فایلی با نام recording.mp3 بگردید.

سخن پایانی

بدین ترتیب به پایان این راهنما با موضوع اپلیکیشن مقدماتی ضبط صدا در کاتلین رسیدیم. اینک شما با طرز کار MediaRecorder آشنا شده‌اید و می‌دانید که چگونه می‌توانید به صورت همزمان تقاضای دسترسی بکنید و چرا این کار مهم است. همچنین نکاتی را در مورد حافظه داخلی دستگاه اندرویدی و شیوه ذخیره‌سازی داده‌ها در آن آموختید. نسخه پیشرفته‌تری از این اپلیکیشن که مجهز به امکانات بیشتری مانند پخش صدای ضبط شده با استفاده از MediaPlayer است را می‌توانید در این ریپوی گیت‌هاب (+) مشاهده کنید.

https://blog.faradars.org/create-an-android-sound-recorder-with-kotlin/