🌐 Build and Run Your First Distributed HarmonyOS App in 15 Minutes
Imagine controlling a TV from your phone with just one codebase. With HarmonyOS’s distributed capabilities, that future is now. Let’s build a cross-device clipboard app today.
🎯 What You’ll Build
A distributed clipboard app:
- Runs on both phone and tablet
- Shares text instantly across devices
- Uses HarmonyOS’s
distributedData
APIs
🧰 Step 1: Project Setup
- Create new project in DevEco Studio
- Template: Empty Feature Ability (Stage Model)
- Language: ArkTS
- Add permissions to
config.json
:
- Add permissions to
"reqPermissions": [
{ "name": "ohos.permission.DISTRIBUTED_DATASYNC" },
{ "name": "ohos.permission.DISTRIBUTED_DEVICE_MANAGER" }
]
🛠️ Step 2: Create Clipboard Logic
File: entry/src/main/ets/common/clipboard.ets
import distributedData from '@ohos.data.distributedData';
export class ClipboardService {
private kvManager;
private kvStore;
async init() {
this.kvManager = distributedData.createKVManager({
bundleName: 'com.example.clipboard',
context: getContext(this)
});
this.kvStore = await this.kvManager.getKVStore({
storeId: 'clipboard_store',
type: distributedData.StoreType.SINGLE_VERSION
});
}
async setText(value: string) {
await this.kvStore.put('shared_text', value);
}
async getText(): Promise<string> {
return await this.kvStore.get('shared_text');
}
}
🧱 Step 3: Build UI with ArkTS
File: pages/Index.ets
import { ClipboardService } from '../common/clipboard';
@Component
struct IndexPage {
@State text: string = '';
clipboard: ClipboardService = new ClipboardService();
async aboutToAppear() {
await this.clipboard.init();
this.text = await this.clipboard.getText();
}
build() {
Column() {
TextInput({ placeholder: 'Enter text', text: this.text })
.onChange(value => this.text = value)
.margin(10)
Button('Share Across Devices')
.onClick(async () => {
await this.clipboard.setText(this.text);
})
.margin(10)
Text(`Shared: ${this.text}`)
.fontSize(18)
.margin(10)
}
}
}
📱 How to Test Cross-Device Sync
- Connect two HarmonyOS virtual devices or real devices (same Wi-Fi)
- Enable “Distributed Networking” on both
- Input text on one device → check update on the other (manually trigger
getText()
or bind listener)
⚠️ Common Errors & Fixes
Issue | Cause | Solution |
---|---|---|
kvStore is undefined |
init() not awaited properly |
Ensure await this.clipboard.init() is called |
Text not syncing | Devices not paired / Wi-Fi not enabled | Enable distributed networking |
Error: permission denied | Missing reqPermissions or not granted at runtime |
Check config + prompt user to allow permissions |
Duplicate storeId error | Running same app on multiple emulators w/o cleanup | Use unique storeId or clear app cache |
📌 Summary
You’ve just built a distributed app that:
- Shares data across devices
- Uses HarmonyOS
distributedData
API - Leverages ArkTS for modern UI
🔮 Next Up…
We’ll explore HarmonyOS permission system in depth — understand how to handle camera, location, network, and more with fine-grained control.
👉 Stay tuned and star this guide if you liked it!